copilot

package module
v0.1.19 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 27, 2026 License: MIT Imports: 17 Imported by: 0

README

Copilot CLI SDK for Go

A Go SDK for programmatic access to the GitHub Copilot CLI.

Note: This SDK is in technical preview and may change in breaking ways.

Installation

go get github.com/github/copilot-sdk/go

Quick Start

package main

import (
    "fmt"
    "log"

    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    // Create client
    client := copilot.NewClient(&copilot.ClientOptions{
        LogLevel: "error",
    })

    // Start the client
    if err := client.Start(); err != nil {
        log.Fatal(err)
    }
    defer client.Stop()

    // Create a session
    session, err := client.CreateSession(&copilot.SessionConfig{
        Model: "gpt-5",
    })
    if err != nil {
        log.Fatal(err)
    }
    defer session.Destroy()

    // Set up event handler
    done := make(chan bool)
    session.On(func(event copilot.SessionEvent) {
        if event.Type == "assistant.message" {
            if event.Data.Content != nil {
                fmt.Println(*event.Data.Content)
            }
        }
        if event.Type == "session.idle" {
            close(done)
        }
    })

    // Send a message
    _, err = session.Send(copilot.MessageOptions{
        Prompt: "What is 2+2?",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Wait for completion
    <-done
}

API Reference

Client
  • NewClient(options *ClientOptions) *Client - Create a new client
  • Start() error - Start the CLI server
  • Stop() []error - Stop the CLI server (returns array of errors, empty if all succeeded)
  • ForceStop() - Forcefully stop without graceful cleanup
  • CreateSession(config *SessionConfig) (*Session, error) - Create a new session
  • ResumeSession(sessionID string) (*Session, error) - Resume an existing session
  • ResumeSessionWithOptions(sessionID string, config *ResumeSessionConfig) (*Session, error) - Resume with additional configuration
  • ListSessions() ([]SessionMetadata, error) - List all sessions known to the server
  • DeleteSession(sessionID string) error - Delete a session permanently
  • GetState() ConnectionState - Get connection state
  • Ping(message string) (*PingResponse, error) - Ping the server

ClientOptions:

  • CLIPath (string): Path to CLI executable (default: "copilot" or COPILOT_CLI_PATH env var)
  • CLIUrl (string): URL of existing CLI server (e.g., "localhost:8080", "http://127.0.0.1:9000", or just "8080"). When provided, the client will not spawn a CLI process.
  • Cwd (string): Working directory for CLI process
  • Port (int): Server port for TCP mode (default: 0 for random)
  • UseStdio (bool): Use stdio transport instead of TCP (default: true)
  • LogLevel (string): Log level (default: "info")
  • AutoStart (*bool): Auto-start server on first use (default: true). Use Bool(false) to disable.
  • AutoRestart (*bool): Auto-restart on crash (default: true). Use Bool(false) to disable.
  • Env ([]string): Environment variables for CLI process (default: inherits from current process)

ResumeSessionConfig:

  • Tools ([]Tool): Tools to expose when resuming
  • Provider (*ProviderConfig): Custom model provider configuration
Session
  • Send(options MessageOptions) (string, error) - Send a message
  • On(handler SessionEventHandler) func() - Subscribe to events (returns unsubscribe function)
  • Abort() error - Abort the currently processing message
  • GetMessages() ([]SessionEvent, error) - Get message history
  • Destroy() error - Destroy the session
Helper Functions
  • Bool(v bool) *bool - Helper to create bool pointers for AutoStart/AutoRestart options

Image Support

The SDK supports image attachments via the Attachments field in MessageOptions. You can attach images by providing their file path:

_, err = session.Send(copilot.MessageOptions{
    Prompt: "What's in this image?",
    Attachments: []copilot.Attachment{
        {
            Type: "file",
            Path: "/path/to/image.jpg",
        },
    },
})

Supported image formats include JPG, PNG, GIF, and other common image types. The agent's view tool can also read images directly from the filesystem, so you can also ask questions like:

_, err = session.Send(copilot.MessageOptions{
    Prompt: "What does the most recent jpg in this directory portray?",
})
Tools

Expose your own functionality to Copilot by attaching tools to a session.

Use DefineTool for type-safe tools with automatic JSON schema generation:

type LookupIssueParams struct {
    ID string `json:"id" jsonschema:"Issue identifier"`
}

lookupIssue := copilot.DefineTool("lookup_issue", "Fetch issue details from our tracker",
    func(params LookupIssueParams, inv copilot.ToolInvocation) (any, error) {
        // params is automatically unmarshaled from the LLM's arguments
        issue, err := fetchIssue(params.ID)
        if err != nil {
            return nil, err
        }
        return issue.Summary, nil
    })

session, _ := client.CreateSession(&copilot.SessionConfig{
    Model: "gpt-5",
    Tools: []copilot.Tool{lookupIssue},
})
Using Tool struct directly

For more control over the JSON schema, use the Tool struct directly:

lookupIssue := copilot.Tool{
    Name:        "lookup_issue",
    Description: "Fetch issue details from our tracker",
    Parameters: map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "id": map[string]interface{}{
                "type":        "string",
                "description": "Issue identifier",
            },
        },
        "required": []string{"id"},
    },
    Handler: func(invocation copilot.ToolInvocation) (copilot.ToolResult, error) {
        args := invocation.Arguments.(map[string]interface{})
        issue, err := fetchIssue(args["id"].(string))
        if err != nil {
            return copilot.ToolResult{}, err
        }
        return copilot.ToolResult{
            TextResultForLLM: issue.Summary,
            ResultType:       "success",
            SessionLog:       fmt.Sprintf("Fetched issue %s", issue.ID),
        }, nil
    },
}

session, _ := client.CreateSession(&copilot.SessionConfig{
    Model: "gpt-5",
    Tools: []copilot.Tool{lookupIssue},
})

When the model selects a tool, the SDK automatically runs your handler (in parallel with other calls) and responds to the CLI's tool.call with the handler's result.

Streaming

Enable streaming to receive assistant response chunks as they're generated:

package main

import (
    "fmt"
    "log"

    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    client := copilot.NewClient(nil)

    if err := client.Start(); err != nil {
        log.Fatal(err)
    }
    defer client.Stop()

    session, err := client.CreateSession(&copilot.SessionConfig{
        Model:     "gpt-5",
        Streaming: true,
    })
    if err != nil {
        log.Fatal(err)
    }
    defer session.Destroy()

    done := make(chan bool)

    session.On(func(event copilot.SessionEvent) {
        if event.Type == "assistant.message_delta" {
            // Streaming message chunk - print incrementally
            if event.Data.DeltaContent != nil {
                fmt.Print(*event.Data.DeltaContent)
            }
        } else if event.Type == "assistant.reasoning_delta" {
            // Streaming reasoning chunk (if model supports reasoning)
            if event.Data.DeltaContent != nil {
                fmt.Print(*event.Data.DeltaContent)
            }
        } else if event.Type == "assistant.message" {
            // Final message - complete content
            fmt.Println("\n--- Final message ---")
            if event.Data.Content != nil {
                fmt.Println(*event.Data.Content)
            }
        } else if event.Type == "assistant.reasoning" {
            // Final reasoning content (if model supports reasoning)
            fmt.Println("--- Reasoning ---")
            if event.Data.Content != nil {
                fmt.Println(*event.Data.Content)
            }
        }
        if event.Type == "session.idle" {
            close(done)
        }
    })

    _, err = session.Send(copilot.MessageOptions{
        Prompt: "Tell me a short story",
    })
    if err != nil {
        log.Fatal(err)
    }

    <-done
}

When Streaming: true:

  • assistant.message_delta events are sent with DeltaContent containing incremental text
  • assistant.reasoning_delta events are sent with DeltaContent for reasoning/chain-of-thought (model-dependent)
  • Accumulate DeltaContent values to build the full response progressively
  • The final assistant.message and assistant.reasoning events contain the complete content

Note: assistant.message and assistant.reasoning (final events) are always sent regardless of streaming setting.

Infinite Sessions

By default, sessions use infinite sessions which automatically manage context window limits through background compaction and persist state to a workspace directory.

// Default: infinite sessions enabled with default thresholds
session, _ := client.CreateSession(&copilot.SessionConfig{
    Model: "gpt-5",
})

// Access the workspace path for checkpoints and files
fmt.Println(session.WorkspacePath())
// => ~/.copilot/session-state/{sessionId}/

// Custom thresholds
session, _ := client.CreateSession(&copilot.SessionConfig{
    Model: "gpt-5",
    InfiniteSessions: &copilot.InfiniteSessionConfig{
        Enabled:                       copilot.Bool(true),
        BackgroundCompactionThreshold: copilot.Float64(0.80), // Start compacting at 80% context usage
        BufferExhaustionThreshold:     copilot.Float64(0.95), // Block at 95% until compaction completes
    },
})

// Disable infinite sessions
session, _ := client.CreateSession(&copilot.SessionConfig{
    Model: "gpt-5",
    InfiniteSessions: &copilot.InfiniteSessionConfig{
        Enabled: copilot.Bool(false),
    },
})

When enabled, sessions emit compaction events:

  • session.compaction_start - Background compaction started
  • session.compaction_complete - Compaction finished (includes token counts)

Transport Modes

stdio (Default)

Communicates with CLI via stdin/stdout pipes. Recommended for most use cases.

client := copilot.NewClient(nil) // Uses stdio by default
TCP

Communicates with CLI via TCP socket. Useful for distributed scenarios.

Environment Variables

  • COPILOT_CLI_PATH - Path to the Copilot CLI executable

License

MIT

Documentation

Overview

Package copilot provides a Go SDK for interacting with the GitHub Copilot CLI.

The copilot package enables Go applications to communicate with the Copilot CLI server, create and manage conversation sessions, and integrate custom tools.

Basic usage: 

client := copilot.NewClient(nil)
if err := client.Start(); err != nil {
    log.Fatal(err)
}
defer client.Stop()

session, err := client.CreateSession(&copilot.SessionConfig{
    Model: "gpt-4",
})
if err != nil {
    log.Fatal(err)
}

session.On(func(event copilot.SessionEvent) {
    if event.Type == "assistant.message" {
        fmt.Println(event.Data.Content)
    }
})

session.Send(copilot.MessageOptions{Prompt: "Hello!"})

Package copilot provides a Go SDK for interacting with the GitHub Copilot CLI.

Index

Constants

View Source 
const SdkProtocolVersion = 2

SdkProtocolVersion is the SDK protocol version. This must match the version expected by the copilot-agent-runtime server.

Variables

This section is empty.

Functions

func Bool 

func Bool(v bool) *bool

Bool returns a pointer to the given bool value. Use for setting AutoStart or AutoRestart: AutoStart: Bool(false)

func Float64 added in v0.1.18 

func Float64(v float64) *float64

Float64 returns a pointer to the given float64 value. Use for setting thresholds: BackgroundCompactionThreshold: Float64(0.80)

func GetSdkProtocolVersion 

func GetSdkProtocolVersion() int

GetSdkProtocolVersion returns the SDK protocol version.

Types

type Attachment 

type Attachment struct {
	DisplayName string          `json:"displayName"`
	Path        *string         `json:"path,omitempty"`
	Type        AttachmentType  `json:"type"`
	FilePath    *string         `json:"filePath,omitempty"`
	Selection   *SelectionClass `json:"selection,omitempty"`
	Text        *string         `json:"text,omitempty"`
}

type AttachmentType added in v0.1.15 

type AttachmentType string
const (
	Directory AttachmentType = "directory"
	File      AttachmentType = "file"
	Selection AttachmentType = "selection"
)

type AzureProviderOptions 

type AzureProviderOptions struct {
	// APIVersion is the Azure API version. Defaults to "2024-10-21".
	APIVersion string `json:"apiVersion,omitempty"`
}

AzureProviderOptions contains Azure-specific provider configuration

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client manages the connection to the Copilot CLI server and provides session management.

The Client can either spawn a CLI server process or connect to an existing server. It handles JSON-RPC communication, session lifecycle, tool execution, and permission requests.

Example: 

// Create a client with default options (spawns CLI server using stdio)
client := copilot.NewClient(nil)

// Or connect to an existing server
client := copilot.NewClient(&copilot.ClientOptions{
    CLIUrl: "localhost:3000",
})

if err := client.Start(); err != nil {
    log.Fatal(err)
}
defer client.Stop()

func NewClient 

func NewClient(options *ClientOptions) *Client

NewClient creates a new Copilot CLI client with the given options.

If options is nil, default options are used (spawns CLI server using stdio). The client is not connected after creation; call Client.Start to connect.

Example: 

// Default options
client := copilot.NewClient(nil)

// Custom options
client := copilot.NewClient(&copilot.ClientOptions{
    CLIPath:  "/usr/local/bin/copilot",
    LogLevel: "debug",
})

func (*Client) CreateSession 

func (c *Client) CreateSession(config *SessionConfig) (*Session, error)

CreateSession creates a new conversation session with the Copilot CLI.

Sessions maintain conversation state, handle events, and manage tool execution. If the client is not connected and AutoStart is enabled, this will automatically start the connection.

The config parameter is optional; pass nil for default settings.

Returns the created session or an error if session creation fails.

Example: 

// Basic session
session, err := client.CreateSession(nil)

// Session with model and tools
session, err := client.CreateSession(&copilot.SessionConfig{
    Model: "gpt-4",
    Tools: []copilot.Tool{
        {
            Name:        "get_weather",
            Description: "Get weather for a location",
            Handler:     weatherHandler,
        },
    },
})

func (*Client) DeleteSession added in v0.1.19 

func (c *Client) DeleteSession(sessionID string) error

DeleteSession permanently deletes a session and all its conversation history.

The session cannot be resumed after deletion. If the session is in the local sessions map, it will be removed.

Example: 

if err := client.DeleteSession("session-123"); err != nil {
    log.Fatal(err)
}

func (*Client) ForceStop 

func (c *Client) ForceStop()

ForceStop forcefully stops the CLI server without graceful cleanup.

Use this when Client.Stop fails or takes too long. This method:

  • Clears all sessions immediately without destroying them
  • Force closes the connection
  • Kills the CLI process (if spawned by this client)

Example: 

// If normal stop hangs, force stop
done := make(chan struct{})
go func() {
    client.Stop()
    close(done)
}()

select {
case <-done:
    // Stopped successfully
case <-time.After(5 * time.Second):
    client.ForceStop()
}

func (*Client) GetAuthStatus added in v0.1.15 

func (c *Client) GetAuthStatus() (*GetAuthStatusResponse, error)

GetAuthStatus returns current authentication status

func (*Client) GetState 

func (c *Client) GetState() ConnectionState

GetState returns the current connection state of the client.

Possible states: StateDisconnected, StateConnecting, StateConnected, StateError.

Example: 

if client.GetState() == copilot.StateConnected {
    session, err := client.CreateSession(nil)
}

func (*Client) GetStatus added in v0.1.15 

func (c *Client) GetStatus() (*GetStatusResponse, error)

GetStatus returns CLI status including version and protocol information

func (*Client) ListModels added in v0.1.15 

func (c *Client) ListModels() ([]ModelInfo, error)

ListModels returns available models with their metadata

func (*Client) ListSessions added in v0.1.19 

func (c *Client) ListSessions() ([]SessionMetadata, error)

ListSessions returns metadata about all sessions known to the server.

Returns a list of SessionMetadata for all available sessions, including their IDs, timestamps, and optional summaries.

Example: 

sessions, err := client.ListSessions()
if err != nil {
    log.Fatal(err)
}
for _, session := range sessions {
    fmt.Printf("Session: %s\n", session.SessionID)
}

func (*Client) Ping 

func (c *Client) Ping(message string) (*PingResponse, error)

Ping sends a ping request to the server to verify connectivity.

The message parameter is optional and will be echoed back in the response. Returns a PingResponse containing the message and server timestamp, or an error.

Example: 

resp, err := client.Ping("health check")
if err != nil {
    log.Printf("Server unreachable: %v", err)
} else {
    log.Printf("Server responded at %d", resp.Timestamp)
}

func (*Client) ResumeSession 

func (c *Client) ResumeSession(sessionID string) (*Session, error)

ResumeSession resumes an existing conversation session by its ID using default options.

This is a convenience method that calls Client.ResumeSessionWithOptions with nil config.

Example: 

session, err := client.ResumeSession("session-123")

func (*Client) ResumeSessionWithOptions 

func (c *Client) ResumeSessionWithOptions(sessionID string, config *ResumeSessionConfig) (*Session, error)

ResumeSessionWithOptions resumes an existing conversation session with additional configuration.

This allows you to continue a previous conversation, maintaining all conversation history. The session must have been previously created and not deleted.

Example: 

session, err := client.ResumeSessionWithOptions("session-123", &copilot.ResumeSessionConfig{
    Tools: []copilot.Tool{myNewTool},
})

func (*Client) Start 

func (c *Client) Start() error

Start starts the CLI server (if not using an external server) and establishes a connection.

If connecting to an external server (via CLIUrl), only establishes the connection. Otherwise, spawns the CLI server process and then connects.

This method is called automatically when creating a session if AutoStart is true (default).

Returns an error if the server fails to start or the connection fails.

Example: 

client := copilot.NewClient(&copilot.ClientOptions{AutoStart: boolPtr(false)})
if err := client.Start(); err != nil {
    log.Fatal("Failed to start:", err)
}
// Now ready to create sessions

func (*Client) Stop 

func (c *Client) Stop() []error

Stop stops the CLI server and closes all active sessions.

This method performs graceful cleanup:

  1. Destroys all active sessions
  2. Closes the JSON-RPC connection
  3. Terminates the CLI server process (if spawned by this client)

Returns an array of errors encountered during cleanup. An empty slice indicates all cleanup succeeded.

Example: 

errors := client.Stop()
for _, err := range errors {
    log.Printf("Cleanup error: %v", err)
}

type ClientOptions 

type ClientOptions struct {
	// CLIPath is the path to the Copilot CLI executable (default: "copilot")
	CLIPath string
	// Cwd is the working directory for the CLI process (default: "" = inherit from current process)
	Cwd string
	// Port for TCP transport (default: 0 = random port)
	Port int
	// UseStdio enables stdio transport instead of TCP (default: true)
	UseStdio bool
	// CLIUrl is the URL of an existing Copilot CLI server to connect to over TCP
	// Format: "host:port", "http://host:port", or just "port" (defaults to localhost)
	// Examples: "localhost:8080", "http://127.0.0.1:9000", "8080"
	// Mutually exclusive with CLIPath, UseStdio
	CLIUrl string
	// LogLevel for the CLI server
	LogLevel string
	// AutoStart automatically starts the CLI server on first use (default: true).
	// Use Bool(false) to disable.
	AutoStart *bool
	// AutoRestart automatically restarts the CLI server if it crashes (default: true).
	// Use Bool(false) to disable.
	AutoRestart *bool
	// Env is the environment variables for the CLI process (default: inherits from current process)
	Env []string
}

ClientOptions configures the CopilotClient

type CompactionTokensUsed added in v0.1.15 

type CompactionTokensUsed struct {
	CachedInput float64 `json:"cachedInput"`
	Input       float64 `json:"input"`
	Output      float64 `json:"output"`
}

type ConnectionState 

type ConnectionState string

ConnectionState represents the client connection state 

const (
	StateDisconnected ConnectionState = "disconnected"
	StateConnecting   ConnectionState = "connecting"
	StateConnected    ConnectionState = "connected"
	StateError        ConnectionState = "error"
)

type ContextClass added in v0.1.15 

type ContextClass struct {
	Branch     *string `json:"branch,omitempty"`
	Cwd        string  `json:"cwd"`
	GitRoot    *string `json:"gitRoot,omitempty"`
	Repository *string `json:"repository,omitempty"`
}

type ContextUnion added in v0.1.15 

type ContextUnion struct {
	ContextClass *ContextClass
	String       *string
}

func (*ContextUnion) MarshalJSON added in v0.1.15 

func (x *ContextUnion) MarshalJSON() ([]byte, error)

func (*ContextUnion) UnmarshalJSON added in v0.1.15 

func (x *ContextUnion) UnmarshalJSON(data []byte) error

type CustomAgentConfig 

type CustomAgentConfig struct {
	// Name is the unique name of the custom agent
	Name string `json:"name"`
	// DisplayName is the display name for UI purposes
	DisplayName string `json:"displayName,omitempty"`
	// Description of what the agent does
	Description string `json:"description,omitempty"`
	// Tools is the list of tool names the agent can use (nil for all tools)
	Tools []string `json:"tools,omitempty"`
	// Prompt is the prompt content for the agent
	Prompt string `json:"prompt"`
	// MCPServers are MCP servers specific to this agent
	MCPServers map[string]MCPServerConfig `json:"mcpServers,omitempty"`
	// Infer indicates whether the agent should be available for model inference
	Infer *bool `json:"infer,omitempty"`
}

CustomAgentConfig configures a custom agent

type Data added in v0.1.15 

type Data struct {
	Context                         *ContextUnion            `json:"context"`
	CopilotVersion                  *string                  `json:"copilotVersion,omitempty"`
	Producer                        *string                  `json:"producer,omitempty"`
	SelectedModel                   *string                  `json:"selectedModel,omitempty"`
	SessionID                       *string                  `json:"sessionId,omitempty"`
	StartTime                       *time.Time               `json:"startTime,omitempty"`
	Version                         *float64                 `json:"version,omitempty"`
	EventCount                      *float64                 `json:"eventCount,omitempty"`
	ResumeTime                      *time.Time               `json:"resumeTime,omitempty"`
	ErrorType                       *string                  `json:"errorType,omitempty"`
	Message                         *string                  `json:"message,omitempty"`
	Stack                           *string                  `json:"stack,omitempty"`
	InfoType                        *string                  `json:"infoType,omitempty"`
	NewModel                        *string                  `json:"newModel,omitempty"`
	PreviousModel                   *string                  `json:"previousModel,omitempty"`
	HandoffTime                     *time.Time               `json:"handoffTime,omitempty"`
	RemoteSessionID                 *string                  `json:"remoteSessionId,omitempty"`
	Repository                      *Repository              `json:"repository,omitempty"`
	SourceType                      *SourceType              `json:"sourceType,omitempty"`
	Summary                         *string                  `json:"summary,omitempty"`
	MessagesRemovedDuringTruncation *float64                 `json:"messagesRemovedDuringTruncation,omitempty"`
	PerformedBy                     *string                  `json:"performedBy,omitempty"`
	PostTruncationMessagesLength    *float64                 `json:"postTruncationMessagesLength,omitempty"`
	PostTruncationTokensInMessages  *float64                 `json:"postTruncationTokensInMessages,omitempty"`
	PreTruncationMessagesLength     *float64                 `json:"preTruncationMessagesLength,omitempty"`
	PreTruncationTokensInMessages   *float64                 `json:"preTruncationTokensInMessages,omitempty"`
	TokenLimit                      *float64                 `json:"tokenLimit,omitempty"`
	TokensRemovedDuringTruncation   *float64                 `json:"tokensRemovedDuringTruncation,omitempty"`
	EventsRemoved                   *float64                 `json:"eventsRemoved,omitempty"`
	UpToEventID                     *string                  `json:"upToEventId,omitempty"`
	CurrentTokens                   *float64                 `json:"currentTokens,omitempty"`
	MessagesLength                  *float64                 `json:"messagesLength,omitempty"`
	CompactionTokensUsed            *CompactionTokensUsed    `json:"compactionTokensUsed,omitempty"`
	Error                           *ErrorUnion              `json:"error"`
	MessagesRemoved                 *float64                 `json:"messagesRemoved,omitempty"`
	PostCompactionTokens            *float64                 `json:"postCompactionTokens,omitempty"`
	PreCompactionMessagesLength     *float64                 `json:"preCompactionMessagesLength,omitempty"`
	PreCompactionTokens             *float64                 `json:"preCompactionTokens,omitempty"`
	Success                         *bool                    `json:"success,omitempty"`
	SummaryContent                  *string                  `json:"summaryContent,omitempty"`
	TokensRemoved                   *float64                 `json:"tokensRemoved,omitempty"`
	Attachments                     []Attachment             `json:"attachments,omitempty"`
	Content                         *string                  `json:"content,omitempty"`
	Source                          *string                  `json:"source,omitempty"`
	TransformedContent              *string                  `json:"transformedContent,omitempty"`
	TurnID                          *string                  `json:"turnId,omitempty"`
	Intent                          *string                  `json:"intent,omitempty"`
	ReasoningID                     *string                  `json:"reasoningId,omitempty"`
	DeltaContent                    *string                  `json:"deltaContent,omitempty"`
	MessageID                       *string                  `json:"messageId,omitempty"`
	ParentToolCallID                *string                  `json:"parentToolCallId,omitempty"`
	ToolRequests                    []ToolRequest            `json:"toolRequests,omitempty"`
	TotalResponseSizeBytes          *float64                 `json:"totalResponseSizeBytes,omitempty"`
	APICallID                       *string                  `json:"apiCallId,omitempty"`
	CacheReadTokens                 *float64                 `json:"cacheReadTokens,omitempty"`
	CacheWriteTokens                *float64                 `json:"cacheWriteTokens,omitempty"`
	Cost                            *float64                 `json:"cost,omitempty"`
	Duration                        *float64                 `json:"duration,omitempty"`
	Initiator                       *string                  `json:"initiator,omitempty"`
	InputTokens                     *float64                 `json:"inputTokens,omitempty"`
	Model                           *string                  `json:"model,omitempty"`
	OutputTokens                    *float64                 `json:"outputTokens,omitempty"`
	ProviderCallID                  *string                  `json:"providerCallId,omitempty"`
	QuotaSnapshots                  map[string]QuotaSnapshot `json:"quotaSnapshots,omitempty"`
	Reason                          *string                  `json:"reason,omitempty"`
	Arguments                       interface{}              `json:"arguments"`
	ToolCallID                      *string                  `json:"toolCallId,omitempty"`
	ToolName                        *string                  `json:"toolName,omitempty"`
	MCPServerName                   *string                  `json:"mcpServerName,omitempty"`
	MCPToolName                     *string                  `json:"mcpToolName,omitempty"`
	PartialOutput                   *string                  `json:"partialOutput,omitempty"`
	ProgressMessage                 *string                  `json:"progressMessage,omitempty"`
	IsUserRequested                 *bool                    `json:"isUserRequested,omitempty"`
	Result                          *Result                  `json:"result,omitempty"`
	ToolTelemetry                   map[string]interface{}   `json:"toolTelemetry,omitempty"`
	AgentDescription                *string                  `json:"agentDescription,omitempty"`
	AgentDisplayName                *string                  `json:"agentDisplayName,omitempty"`
	AgentName                       *string                  `json:"agentName,omitempty"`
	Tools                           []string                 `json:"tools"`
	HookInvocationID                *string                  `json:"hookInvocationId,omitempty"`
	HookType                        *string                  `json:"hookType,omitempty"`
	Input                           interface{}              `json:"input"`
	Output                          interface{}              `json:"output"`
	Metadata                        *Metadata                `json:"metadata,omitempty"`
	Name                            *string                  `json:"name,omitempty"`
	Role                            *Role                    `json:"role,omitempty"`
}

type DeleteSessionRequest added in v0.1.19 

type DeleteSessionRequest struct {
	SessionID string `json:"sessionId"`
}

DeleteSessionRequest is the request for session.delete

type DeleteSessionResponse added in v0.1.19 

type DeleteSessionResponse struct {
	Success bool    `json:"success"`
	Error   *string `json:"error,omitempty"`
}

DeleteSessionResponse is the response from session.delete

type End added in v0.1.19 

type End struct {
	Character float64 `json:"character"`
	Line      float64 `json:"line"`
}

type ErrorClass added in v0.1.15 

type ErrorClass struct {
	Code    *string `json:"code,omitempty"`
	Message string  `json:"message"`
	Stack   *string `json:"stack,omitempty"`
}

type ErrorUnion added in v0.1.15 

type ErrorUnion struct {
	ErrorClass *ErrorClass
	String     *string
}

func (*ErrorUnion) MarshalJSON added in v0.1.15 

func (x *ErrorUnion) MarshalJSON() ([]byte, error)

func (*ErrorUnion) UnmarshalJSON added in v0.1.15 

func (x *ErrorUnion) UnmarshalJSON(data []byte) error

type GetAuthStatusResponse added in v0.1.15 

type GetAuthStatusResponse struct {
	IsAuthenticated bool    `json:"isAuthenticated"`
	AuthType        *string `json:"authType,omitempty"`
	Host            *string `json:"host,omitempty"`
	Login           *string `json:"login,omitempty"`
	StatusMessage   *string `json:"statusMessage,omitempty"`
}

GetAuthStatusResponse is the response from auth.getStatus

type GetModelsResponse added in v0.1.15 

type GetModelsResponse struct {
	Models []ModelInfo `json:"models"`
}

GetModelsResponse is the response from models.list

type GetStatusResponse added in v0.1.15 

type GetStatusResponse struct {
	Version         string `json:"version"`
	ProtocolVersion int    `json:"protocolVersion"`
}

GetStatusResponse is the response from status.get

type InfiniteSessionConfig added in v0.1.18 

type InfiniteSessionConfig struct {
	// Enabled controls whether infinite sessions are enabled (default: true)
	Enabled *bool
	// BackgroundCompactionThreshold is the context utilization (0.0-1.0) at which
	// background compaction starts. Default: 0.80
	BackgroundCompactionThreshold *float64
	// BufferExhaustionThreshold is the context utilization (0.0-1.0) at which
	// the session blocks until compaction completes. Default: 0.95
	BufferExhaustionThreshold *float64
}

InfiniteSessionConfig configures infinite sessions with automatic context compaction and workspace persistence. When enabled, sessions automatically manage context window limits through background compaction and persist state to a workspace directory.

type JSONRPCClient 

type JSONRPCClient struct {
	// contains filtered or unexported fields
}

JSONRPCClient is a minimal JSON-RPC 2.0 client for stdio transport

func NewJSONRPCClient 

func NewJSONRPCClient(stdin io.WriteCloser, stdout io.ReadCloser) *JSONRPCClient

NewJSONRPCClient creates a new JSON-RPC client

func (*JSONRPCClient) Notify 

func (c *JSONRPCClient) Notify(method string, params map[string]interface{}) error

Notify sends a JSON-RPC notification (no response expected)

func (*JSONRPCClient) Request 

func (c *JSONRPCClient) Request(method string, params map[string]interface{}) (map[string]interface{}, error)

Request sends a JSON-RPC request and waits for the response

func (*JSONRPCClient) SetNotificationHandler 

func (c *JSONRPCClient) SetNotificationHandler(handler NotificationHandler)

SetNotificationHandler sets the handler for incoming notifications

func (*JSONRPCClient) SetRequestHandler 

func (c *JSONRPCClient) SetRequestHandler(method string, handler RequestHandler)

SetRequestHandler registers a handler for incoming requests from the server

func (*JSONRPCClient) Start 

func (c *JSONRPCClient) Start()

Start begins listening for messages in a background goroutine

func (*JSONRPCClient) Stop 

func (c *JSONRPCClient) Stop()

Stop stops the client and cleans up

type JSONRPCError 

type JSONRPCError struct {
	Code    int                    `json:"code"`
	Message string                 `json:"message"`
	Data    map[string]interface{} `json:"data,omitempty"`
}

JSONRPCError represents a JSON-RPC error response

func (*JSONRPCError) Error 

func (e *JSONRPCError) Error() string

type JSONRPCNotification 

type JSONRPCNotification struct {
	JSONRPC string                 `json:"jsonrpc"`
	Method  string                 `json:"method"`
	Params  map[string]interface{} `json:"params"`
}

JSONRPCNotification represents a JSON-RPC 2.0 notification

type JSONRPCRequest 

type JSONRPCRequest struct {
	JSONRPC string                 `json:"jsonrpc"`
	ID      json.RawMessage        `json:"id"`
	Method  string                 `json:"method"`
	Params  map[string]interface{} `json:"params"`
}

JSONRPCRequest represents a JSON-RPC 2.0 request

type JSONRPCResponse 

type JSONRPCResponse struct {
	JSONRPC string                 `json:"jsonrpc"`
	ID      json.RawMessage        `json:"id,omitempty"`
	Result  map[string]interface{} `json:"result,omitempty"`
	Error   *JSONRPCError          `json:"error,omitempty"`
}

JSONRPCResponse represents a JSON-RPC 2.0 response

type ListSessionsResponse added in v0.1.19 

type ListSessionsResponse struct {
	Sessions []SessionMetadata `json:"sessions"`
}

ListSessionsResponse is the response from session.list

type MCPLocalServerConfig 

type MCPLocalServerConfig struct {
	Tools   []string          `json:"tools"`
	Type    string            `json:"type,omitempty"` // "local" or "stdio"
	Timeout int               `json:"timeout,omitempty"`
	Command string            `json:"command"`
	Args    []string          `json:"args"`
	Env     map[string]string `json:"env,omitempty"`
	Cwd     string            `json:"cwd,omitempty"`
}

MCPLocalServerConfig configures a local/stdio MCP server

type MCPRemoteServerConfig 

type MCPRemoteServerConfig struct {
	Tools   []string          `json:"tools"`
	Type    string            `json:"type"` // "http" or "sse"
	Timeout int               `json:"timeout,omitempty"`
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers,omitempty"`
}

MCPRemoteServerConfig configures a remote MCP server (HTTP or SSE)

type MCPServerConfig 

type MCPServerConfig map[string]interface{}

MCPServerConfig can be either MCPLocalServerConfig or MCPRemoteServerConfig Use a map[string]interface{} for flexibility, or create separate configs

type MessageOptions 

type MessageOptions struct {
	// Prompt is the message to send
	Prompt string
	// Attachments are file or directory attachments
	Attachments []Attachment
	// Mode is the message delivery mode (default: "enqueue")
	Mode string
}

MessageOptions configures a message to send

type Metadata added in v0.1.15 

type Metadata struct {
	PromptVersion *string                `json:"promptVersion,omitempty"`
	Variables     map[string]interface{} `json:"variables,omitempty"`
}

type ModelBilling added in v0.1.15 

type ModelBilling struct {
	Multiplier float64 `json:"multiplier"`
}

ModelBilling contains model billing information

type ModelCapabilities added in v0.1.15 

type ModelCapabilities struct {
	Supports ModelSupports `json:"supports"`
	Limits   ModelLimits   `json:"limits"`
}

ModelCapabilities contains model capabilities and limits

type ModelInfo added in v0.1.15 

type ModelInfo struct {
	ID           string            `json:"id"`
	Name         string            `json:"name"`
	Capabilities ModelCapabilities `json:"capabilities"`
	Policy       *ModelPolicy      `json:"policy,omitempty"`
	Billing      *ModelBilling     `json:"billing,omitempty"`
}

ModelInfo contains information about an available model

type ModelLimits added in v0.1.15 

type ModelLimits struct {
	MaxPromptTokens        *int               `json:"max_prompt_tokens,omitempty"`
	MaxContextWindowTokens int                `json:"max_context_window_tokens"`
	Vision                 *ModelVisionLimits `json:"vision,omitempty"`
}

ModelLimits contains model limits

type ModelPolicy added in v0.1.15 

type ModelPolicy struct {
	State string `json:"state"`
	Terms string `json:"terms"`
}

ModelPolicy contains model policy state

type ModelSupports added in v0.1.15 

type ModelSupports struct {
	Vision bool `json:"vision"`
}

ModelSupports contains model support flags

type ModelVisionLimits added in v0.1.15 

type ModelVisionLimits struct {
	SupportedMediaTypes []string `json:"supported_media_types"`
	MaxPromptImages     int      `json:"max_prompt_images"`
	MaxPromptImageSize  int      `json:"max_prompt_image_size"`
}

ModelVisionLimits contains vision-specific limits

type NotificationHandler 

type NotificationHandler func(method string, params map[string]interface{})

NotificationHandler handles incoming notifications

type PermissionHandler 

type PermissionHandler func(request PermissionRequest, invocation PermissionInvocation) (PermissionRequestResult, error)

PermissionHandler executes a permission request The handler should return a PermissionRequestResult. Returning an error denies the permission.

type PermissionInvocation 

type PermissionInvocation struct {
	SessionID string
}

PermissionInvocation provides context about a permission request

type PermissionRequest 

type PermissionRequest struct {
	Kind       string                 `json:"kind"`
	ToolCallID string                 `json:"toolCallId,omitempty"`
	Extra      map[string]interface{} `json:"-"` // Additional fields vary by kind
}

PermissionRequest represents a permission request from the server

type PermissionRequestResult 

type PermissionRequestResult struct {
	Kind  string        `json:"kind"`
	Rules []interface{} `json:"rules,omitempty"`
}

PermissionRequestResult represents the result of a permission request

type PingResponse 

type PingResponse struct {
	Message         string `json:"message"`
	Timestamp       int64  `json:"timestamp"`
	ProtocolVersion *int   `json:"protocolVersion,omitempty"`
}

PingResponse is the response from a ping request

type ProviderConfig 

type ProviderConfig struct {
	// Type is the provider type: "openai", "azure", or "anthropic". Defaults to "openai".
	Type string `json:"type,omitempty"`
	// WireApi is the API format (openai/azure only): "completions" or "responses". Defaults to "completions".
	WireApi string `json:"wireApi,omitempty"`
	// BaseURL is the API endpoint URL
	BaseURL string `json:"baseUrl"`
	// APIKey is the API key. Optional for local providers like Ollama.
	APIKey string `json:"apiKey,omitempty"`
	// BearerToken for authentication. Sets the Authorization header directly.
	// Use this for services requiring bearer token auth instead of API key.
	// Takes precedence over APIKey when both are set.
	BearerToken string `json:"bearerToken,omitempty"`
	// Azure contains Azure-specific options
	Azure *AzureProviderOptions `json:"azure,omitempty"`
}

ProviderConfig configures a custom model provider

type QuotaSnapshot added in v0.1.15 

type QuotaSnapshot struct {
	EntitlementRequests              float64    `json:"entitlementRequests"`
	IsUnlimitedEntitlement           bool       `json:"isUnlimitedEntitlement"`
	Overage                          float64    `json:"overage"`
	OverageAllowedWithExhaustedQuota bool       `json:"overageAllowedWithExhaustedQuota"`
	RemainingPercentage              float64    `json:"remainingPercentage"`
	ResetDate                        *time.Time `json:"resetDate,omitempty"`
	UsageAllowedWithExhaustedQuota   bool       `json:"usageAllowedWithExhaustedQuota"`
	UsedRequests                     float64    `json:"usedRequests"`
}

type Repository added in v0.1.15 

type Repository struct {
	Branch *string `json:"branch,omitempty"`
	Name   string  `json:"name"`
	Owner  string  `json:"owner"`
}

type RequestHandler 

type RequestHandler func(params map[string]interface{}) (map[string]interface{}, *JSONRPCError)

RequestHandler handles incoming server requests and returns a result or error

type Result added in v0.1.15 

type Result struct {
	Content         string  `json:"content"`
	DetailedContent *string `json:"detailedContent,omitempty"`
}

type ResumeSessionConfig 

type ResumeSessionConfig struct {
	// Tools exposes caller-implemented tools to the CLI
	Tools []Tool
	// Provider configures a custom model provider
	Provider *ProviderConfig
	// OnPermissionRequest is a handler for permission requests from the server
	OnPermissionRequest PermissionHandler
	// Streaming enables streaming of assistant message and reasoning chunks.
	// When true, assistant.message_delta and assistant.reasoning_delta events
	// with deltaContent are sent as the response is generated.
	Streaming bool
	// MCPServers configures MCP servers for the session
	MCPServers map[string]MCPServerConfig
	// CustomAgents configures custom agents for the session
	CustomAgents []CustomAgentConfig
	// SkillDirectories is a list of directories to load skills from
	SkillDirectories []string
	// DisabledSkills is a list of skill names to disable
	DisabledSkills []string
}

ResumeSessionConfig configures options when resuming a session

type Role added in v0.1.15 

type Role string
const (
	Developer Role = "developer"
	System    Role = "system"
)

type SelectionClass added in v0.1.19 

type SelectionClass struct {
	End   End   `json:"end"`
	Start Start `json:"start"`
}

type Session 

type Session struct {
	// SessionID is the unique identifier for this session.
	SessionID string
	// contains filtered or unexported fields
}

Session represents a single conversation session with the Copilot CLI.

A session maintains conversation state, handles events, and manages tool execution. Sessions are created via Client.CreateSession or resumed via Client.ResumeSession.

The session provides methods to send messages, subscribe to events, retrieve conversation history, and manage the session lifecycle. All methods are safe for concurrent use.

Example usage: 

session, err := client.CreateSession(copilot.SessionConfig{
    Model: "gpt-4",
})
if err != nil {
    log.Fatal(err)
}
defer session.Destroy()

// Subscribe to events
unsubscribe := session.On(func(event copilot.SessionEvent) {
    if event.Type == "assistant.message" {
        fmt.Println("Assistant:", event.Data.Content)
    }
})
defer unsubscribe()

// Send a message
messageID, err := session.Send(copilot.MessageOptions{
    Prompt: "Hello, world!",
})

func NewSession 

func NewSession(sessionID string, client *JSONRPCClient, workspacePath string) *Session

NewSession creates a new session wrapper with the given session ID and client.

Note: This function is primarily for internal use. Use Client.CreateSession to create sessions with proper initialization.

func (*Session) Abort 

func (s *Session) Abort() error

Abort aborts the currently processing message in this session.

Use this to cancel a long-running request. The session remains valid and can continue to be used for new messages.

Returns an error if the session has been destroyed or the connection fails.

Example: 

// Start a long-running request in a goroutine
go func() {
    session.Send(copilot.MessageOptions{
        Prompt: "Write a very long story...",
    })
}()

// Abort after 5 seconds
time.Sleep(5 * time.Second)
if err := session.Abort(); err != nil {
    log.Printf("Failed to abort: %v", err)
}

func (*Session) Destroy 

func (s *Session) Destroy() error

Destroy destroys this session and releases all associated resources.

After calling this method, the session can no longer be used. All event handlers and tool handlers are cleared. To continue the conversation, use Client.ResumeSession with the session ID.

Returns an error if the connection fails.

Example: 

// Clean up when done
if err := session.Destroy(); err != nil {
    log.Printf("Failed to destroy session: %v", err)
}

func (*Session) GetMessages 

func (s *Session) GetMessages() ([]SessionEvent, error)

GetMessages retrieves all events and messages from this session's history.

This returns the complete conversation history including user messages, assistant responses, tool executions, and other session events in chronological order.

Returns an error if the session has been destroyed or the connection fails.

Example: 

events, err := session.GetMessages()
if err != nil {
    log.Printf("Failed to get messages: %v", err)
    return
}
for _, event := range events {
    if event.Type == "assistant.message" {
        fmt.Println("Assistant:", event.Data.Content)
    }
}

func (*Session) On 

func (s *Session) On(handler SessionEventHandler) func()

On subscribes to events from this session.

Events include assistant messages, tool executions, errors, and session state changes. Multiple handlers can be registered and will all receive events. Handlers are called synchronously in the order they were registered.

The returned function can be called to unsubscribe the handler. It is safe to call the unsubscribe function multiple times.

Example: 

unsubscribe := session.On(func(event copilot.SessionEvent) {
    switch event.Type {
    case "assistant.message":
        fmt.Println("Assistant:", event.Data.Content)
    case "session.error":
        fmt.Println("Error:", event.Data.Message)
    }
})

// Later, to stop receiving events:
unsubscribe()

func (*Session) Send 

func (s *Session) Send(options MessageOptions) (string, error)

Send sends a message to this session and waits for the response.

The message is processed asynchronously. Subscribe to events via Session.On to receive streaming responses and other session events.

Parameters:

  • options: The message options including the prompt and optional attachments.

Returns the message ID of the response, which can be used to correlate events, or an error if the session has been destroyed or the connection fails.

Example: 

messageID, err := session.Send(copilot.MessageOptions{
    Prompt: "Explain this code",
    Attachments: []copilot.Attachment{
        {Type: "file", Path: "./main.go"},
    },
})
if err != nil {
    log.Printf("Failed to send message: %v", err)
}

func (*Session) SendAndWait 

func (s *Session) SendAndWait(options MessageOptions, timeout time.Duration) (*SessionEvent, error)

SendAndWait sends a message to this session and waits until the session becomes idle.

This is a convenience method that combines Session.Send with waiting for the session.idle event. Use this when you want to block until the assistant has finished processing the message.

Events are still delivered to handlers registered via Session.On while waiting.

Parameters:

  • options: The message options including the prompt and optional attachments.
  • timeout: How long to wait for completion. Defaults to 60 seconds if zero. Controls how long to wait; does not abort in-flight agent work.

Returns the final assistant message event, or nil if none was received. Returns an error if the timeout is reached or the connection fails.

Example: 

response, err := session.SendAndWait(copilot.MessageOptions{
    Prompt: "What is 2+2?",
}, 0) // Use default 60s timeout
if err != nil {
    log.Printf("Failed: %v", err)
}
if response != nil {
    fmt.Println(*response.Data.Content)
}

func (*Session) WorkspacePath added in v0.1.18 

func (s *Session) WorkspacePath() string

WorkspacePath returns the path to the session workspace directory when infinite sessions are enabled. Contains checkpoints/, plan.md, and files/ subdirectories. Returns empty string if infinite sessions are disabled.

type SessionConfig 

type SessionConfig struct {
	// SessionID is an optional custom session ID
	SessionID string
	// Model to use for this session
	Model string
	// ConfigDir overrides the default configuration directory location.
	// When specified, the session will use this directory for storing config and state.
	ConfigDir string
	// Tools exposes caller-implemented tools to the CLI
	Tools []Tool
	// SystemMessage configures system message customization
	SystemMessage *SystemMessageConfig
	// AvailableTools is a list of tool names to allow. When specified, only these tools will be available.
	// Takes precedence over ExcludedTools.
	AvailableTools []string
	// ExcludedTools is a list of tool names to disable. All other tools remain available.
	// Ignored if AvailableTools is specified.
	ExcludedTools []string
	// OnPermissionRequest is a handler for permission requests from the server
	OnPermissionRequest PermissionHandler
	// Streaming enables streaming of assistant message and reasoning chunks.
	// When true, assistant.message_delta and assistant.reasoning_delta events
	// with deltaContent are sent as the response is generated.
	Streaming bool
	// Provider configures a custom model provider (BYOK)
	Provider *ProviderConfig
	// MCPServers configures MCP servers for the session
	MCPServers map[string]MCPServerConfig
	// CustomAgents configures custom agents for the session
	CustomAgents []CustomAgentConfig
	// SkillDirectories is a list of directories to load skills from
	SkillDirectories []string
	// DisabledSkills is a list of skill names to disable
	DisabledSkills []string
	// InfiniteSessions configures infinite sessions for persistent workspaces and automatic compaction.
	// When enabled (default), sessions automatically manage context limits and persist state.
	InfiniteSessions *InfiniteSessionConfig
}

SessionConfig configures a new session

type SessionCreateResponse 

type SessionCreateResponse struct {
	SessionID string `json:"sessionId"`
}

SessionCreateResponse is the response from session.create

type SessionEvent 

type SessionEvent struct {
	Data      Data             `json:"data"`
	Ephemeral *bool            `json:"ephemeral,omitempty"`
	ID        string           `json:"id"`
	ParentID  *string          `json:"parentId"`
	Timestamp time.Time        `json:"timestamp"`
	Type      SessionEventType `json:"type"`
}

func UnmarshalSessionEvent added in v0.1.15 

func UnmarshalSessionEvent(data []byte) (SessionEvent, error)

func (*SessionEvent) Marshal added in v0.1.15 

func (r *SessionEvent) Marshal() ([]byte, error)

type SessionEventHandler 

type SessionEventHandler func(event SessionEvent)

SessionEventHandler is a callback for session events

type SessionEventType added in v0.1.15 

type SessionEventType string
const (
	Abort                      SessionEventType = "abort"
	AssistantIntent            SessionEventType = "assistant.intent"
	AssistantMessage           SessionEventType = "assistant.message"
	AssistantMessageDelta      SessionEventType = "assistant.message_delta"
	AssistantReasoning         SessionEventType = "assistant.reasoning"
	AssistantReasoningDelta    SessionEventType = "assistant.reasoning_delta"
	AssistantTurnEnd           SessionEventType = "assistant.turn_end"
	AssistantTurnStart         SessionEventType = "assistant.turn_start"
	AssistantUsage             SessionEventType = "assistant.usage"
	HookEnd                    SessionEventType = "hook.end"
	HookStart                  SessionEventType = "hook.start"
	PendingMessagesModified    SessionEventType = "pending_messages.modified"
	SessionCompactionComplete  SessionEventType = "session.compaction_complete"
	SessionCompactionStart     SessionEventType = "session.compaction_start"
	SessionError               SessionEventType = "session.error"
	SessionHandoff             SessionEventType = "session.handoff"
	SessionIdle                SessionEventType = "session.idle"
	SessionInfo                SessionEventType = "session.info"
	SessionModelChange         SessionEventType = "session.model_change"
	SessionResume              SessionEventType = "session.resume"
	SessionSnapshotRewind      SessionEventType = "session.snapshot_rewind"
	SessionStart               SessionEventType = "session.start"
	SessionTruncation          SessionEventType = "session.truncation"
	SessionUsageInfo           SessionEventType = "session.usage_info"
	SubagentCompleted          SessionEventType = "subagent.completed"
	SubagentFailed             SessionEventType = "subagent.failed"
	SubagentSelected           SessionEventType = "subagent.selected"
	SubagentStarted            SessionEventType = "subagent.started"
	SystemMessage              SessionEventType = "system.message"
	ToolExecutionComplete      SessionEventType = "tool.execution_complete"
	ToolExecutionPartialResult SessionEventType = "tool.execution_partial_result"
	ToolExecutionProgress      SessionEventType = "tool.execution_progress"
	ToolExecutionStart         SessionEventType = "tool.execution_start"
	ToolUserRequested          SessionEventType = "tool.user_requested"
	UserMessage                SessionEventType = "user.message"
)

type SessionGetMessagesResponse 

type SessionGetMessagesResponse struct {
	Events []SessionEvent `json:"events"`
}

SessionGetMessagesResponse is the response from session.getMessages

type SessionMetadata added in v0.1.19 

type SessionMetadata struct {
	SessionID    string  `json:"sessionId"`
	StartTime    string  `json:"startTime"`
	ModifiedTime string  `json:"modifiedTime"`
	Summary      *string `json:"summary,omitempty"`
	IsRemote     bool    `json:"isRemote"`
}

SessionMetadata contains metadata about a session

type SessionSendResponse 

type SessionSendResponse struct {
	MessageID string `json:"messageId"`
}

SessionSendResponse is the response from session.send

type SourceType added in v0.1.15 

type SourceType string
const (
	Local  SourceType = "local"
	Remote SourceType = "remote"
)

type Start added in v0.1.19 

type Start struct {
	Character float64 `json:"character"`
	Line      float64 `json:"line"`
}

type SystemMessageAppendConfig 

type SystemMessageAppendConfig struct {
	// Mode is optional, defaults to "append"
	Mode string `json:"mode,omitempty"`
	// Content provides additional instructions appended after SDK-managed sections
	Content string `json:"content,omitempty"`
}

SystemMessageAppendConfig is append mode: use CLI foundation with optional appended content.

type SystemMessageConfig 

type SystemMessageConfig struct {
	Mode    string `json:"mode,omitempty"`
	Content string `json:"content,omitempty"`
}

SystemMessageConfig represents system message configuration for session creation. Use SystemMessageAppendConfig for default behavior, SystemMessageReplaceConfig for full control. In Go, use one struct or the other based on your needs.

type SystemMessageReplaceConfig 

type SystemMessageReplaceConfig struct {
	// Mode must be "replace"
	Mode string `json:"mode"`
	// Content is the complete system message (required)
	Content string `json:"content"`
}

SystemMessageReplaceConfig is replace mode: use caller-provided system message entirely. Removes all SDK guardrails including security restrictions.

type Tool 

type Tool struct {
	Name        string
	Description string // optional
	Parameters  map[string]interface{}
	Handler     ToolHandler
}

Tool describes a caller-implemented tool that can be invoked by Copilot

func DefineTool 

func DefineTool[T any, U any](name, description string, handler func(T, ToolInvocation) (U, error)) Tool

DefineTool creates a Tool with automatic JSON schema generation from a typed handler function. The handler receives typed arguments (automatically unmarshaled from JSON) and the raw ToolInvocation. The handler can return any value - strings pass through directly, other types are JSON-serialized.

Example: 

type GetWeatherParams struct {
    City string `json:"city" jsonschema:"city name"`
    Unit string `json:"unit" jsonschema:"temperature unit (celsius or fahrenheit)"`
}

tool := copilot.DefineTool("get_weather", "Get weather for a city",
    func(params GetWeatherParams, inv copilot.ToolInvocation) (any, error) {
        return fmt.Sprintf("Weather in %s: 22°%s", params.City, params.Unit), nil
    })

type ToolBinaryResult 

type ToolBinaryResult struct {
	Data        string `json:"data"`
	MimeType    string `json:"mimeType"`
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
}

ToolBinaryResult represents binary payloads returned by tools.

type ToolHandler 

type ToolHandler func(invocation ToolInvocation) (ToolResult, error)

ToolHandler executes a tool invocation. The handler should return a ToolResult. Returning an error marks the tool execution as a failure.

type ToolInvocation 

type ToolInvocation struct {
	SessionID  string
	ToolCallID string
	ToolName   string
	Arguments  interface{}
}

ToolInvocation describes a tool call initiated by Copilot

type ToolRequest added in v0.1.15 

type ToolRequest struct {
	Arguments  interface{}      `json:"arguments"`
	Name       string           `json:"name"`
	ToolCallID string           `json:"toolCallId"`
	Type       *ToolRequestType `json:"type,omitempty"`
}

type ToolRequestType added in v0.1.15 

type ToolRequestType string
const (
	Custom   ToolRequestType = "custom"
	Function ToolRequestType = "function"
)

type ToolResult 

type ToolResult struct {
	TextResultForLLM    string                 `json:"textResultForLlm"`
	BinaryResultsForLLM []ToolBinaryResult     `json:"binaryResultsForLlm,omitempty"`
	ResultType          string                 `json:"resultType"`
	Error               string                 `json:"error,omitempty"`
	SessionLog          string                 `json:"sessionLog,omitempty"`
	ToolTelemetry       map[string]interface{} `json:"toolTelemetry,omitempty"`
}

ToolResult represents the result of a tool invocation.

Source Files

View all Source files

Directories

Path Synopsis
e2e
testharness

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.