copilot

package module
v0.1.29 Latest Latest
Warning

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

 Go to latest Published: Feb 27, 2026 License: MIT Imports: 20 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

Run the Sample

Try the interactive chat sample (from the repo root):

cd go/samples
go run chat.go

Quick Start

package main

import (
	"context"
    "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(context.Background()); err != nil {
        log.Fatal(err)
    }
    defer client.Stop()

    // Create a session
    session, err := client.CreateSession(context.Background(), &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(context.Background(), copilot.MessageOptions{
        Prompt: "What is 2+2?",
    })
    if err != nil {
        log.Fatal(err)
    }

    // Wait for completion
    <-done
}

Distributing your application with an embedded GitHub Copilot CLI

The SDK supports bundling, using Go's embed package, the Copilot CLI binary within your application's distribution. This allows you to bundle a specific CLI version and avoid external dependencies on the user's system.

Follow these steps to embed the CLI:

  1. Run go get -tool github.com/github/copilot-sdk/go/cmd/bundler. This is a one-time setup step per project.
  2. Run go tool bundler in your build environment just before building your application.

That's it! When your application calls copilot.NewClient without a CLIPath nor the COPILOT_CLI_PATH environment variable, the SDK will automatically install the embedded CLI to a cache directory and use it for all operations.

API Reference

Client
  • NewClient(options *ClientOptions) *Client - Create a new client
  • Start(ctx context.Context) error - Start the CLI server
  • Stop() error - Stop the CLI server
  • ForceStop() - Forcefully stop without graceful cleanup
  • CreateSession(config *SessionConfig) (*Session, error) - Create a new session
  • ResumeSession(sessionID string, config *ResumeSessionConfig) (*Session, error) - Resume an existing session
  • ResumeSessionWithOptions(sessionID string, config *ResumeSessionConfig) (*Session, error) - Resume with additional configuration
  • ListSessions(filter *SessionListFilter) ([]SessionMetadata, error) - List sessions (with optional filter)
  • DeleteSession(sessionID string) error - Delete a session permanently
  • GetState() ConnectionState - Get connection state
  • Ping(message string) (*PingResponse, error) - Ping the server
  • GetForegroundSessionID(ctx context.Context) (*string, error) - Get the session ID currently displayed in TUI (TUI+server mode only)
  • SetForegroundSessionID(ctx context.Context, sessionID string) error - Request TUI to display a specific session (TUI+server mode only)
  • On(handler SessionLifecycleHandler) func() - Subscribe to all lifecycle events; returns unsubscribe function
  • OnEventType(eventType SessionLifecycleEventType, handler SessionLifecycleHandler) func() - Subscribe to specific lifecycle event type

Session Lifecycle Events:

// Subscribe to all lifecycle events
unsubscribe := client.On(func(event copilot.SessionLifecycleEvent) {
    fmt.Printf("Session %s: %s\n", event.SessionID, event.Type)
})
defer unsubscribe()

// Subscribe to specific event type
unsubscribe := client.OnEventType(copilot.SessionLifecycleForeground, func(event copilot.SessionLifecycleEvent) {
    fmt.Printf("Session %s is now in foreground\n", event.SessionID)
})

Event types: SessionLifecycleCreated, SessionLifecycleDeleted, SessionLifecycleUpdated, SessionLifecycleForeground, SessionLifecycleBackground

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)
  • GitHubToken (string): GitHub token for authentication. When provided, takes priority over other auth methods.
  • UseLoggedInUser (*bool): Whether to use logged-in user for authentication (default: true, but false when GitHubToken is provided). Cannot be used with CLIUrl.

SessionConfig:

  • Model (string): Model to use ("gpt-5", "claude-sonnet-4.5", etc.). Required when using custom provider.
  • ReasoningEffort (string): Reasoning effort level for models that support it ("low", "medium", "high", "xhigh"). Use ListModels() to check which models support this option.
  • SessionID (string): Custom session ID
  • Tools ([]Tool): Custom tools exposed to the CLI
  • SystemMessage (*SystemMessageConfig): System message configuration
  • Provider (*ProviderConfig): Custom API provider configuration (BYOK). See Custom Providers section.
  • Streaming (bool): Enable streaming delta events
  • InfiniteSessions (*InfiniteSessionConfig): Automatic context compaction configuration
  • OnUserInputRequest (UserInputHandler): Handler for user input requests from the agent (enables ask_user tool). See User Input Requests section.
  • Hooks (*SessionHooks): Hook handlers for session lifecycle events. See Session Hooks section.

ResumeSessionConfig:

  • Tools ([]Tool): Tools to expose when resuming
  • ReasoningEffort (string): Reasoning effort level for models that support it
  • Provider (*ProviderConfig): Custom API provider configuration (BYOK). See Custom Providers section.
  • Streaming (bool): Enable streaming delta events
Session
  • Send(ctx context.Context, options MessageOptions) (string, error) - Send a message
  • On(handler SessionEventHandler) func() - Subscribe to events (returns unsubscribe function)
  • Abort(ctx context.Context) error - Abort the currently processing message
  • GetMessages(ctx context.Context) ([]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(context.Background(), 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(context.Background(), 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(context.Background(), &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]any{
        "type": "object",
        "properties": map[string]any{
            "id": map[string]any{
                "type":        "string",
                "description": "Issue identifier",
            },
        },
        "required": []string{"id"},
    },
    Handler: func(invocation copilot.ToolInvocation) (copilot.ToolResult, error) {
        args := invocation.Arguments.(map[string]any)
        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(context.Background(), &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 (
	"context"
    "fmt"
    "log"

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

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

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

    session, err := client.CreateSession(context.Background(), &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(context.Background(), 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(context.Background(), &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(context.Background(), &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(context.Background(), &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)

Custom Providers

The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own Key), including local providers like Ollama. When using a custom provider, you must specify the Model explicitly.

ProviderConfig:

  • Type (string): Provider type - "openai", "azure", or "anthropic" (default: "openai")
  • BaseURL (string): API endpoint URL (required)
  • APIKey (string): API key (optional for local providers like Ollama)
  • BearerToken (string): Bearer token for authentication (takes precedence over APIKey)
  • WireApi (string): API format for OpenAI/Azure - "completions" or "responses" (default: "completions")
  • Azure.APIVersion (string): Azure API version (default: "2024-10-21")

Example with Ollama:

session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
    Model: "deepseek-coder-v2:16b", // Required when using custom provider
    Provider: &copilot.ProviderConfig{
        Type:    "openai",
        BaseURL: "http://localhost:11434/v1", // Ollama endpoint
        // APIKey not required for Ollama
    },
})

Example with custom OpenAI-compatible API:

session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
    Model: "gpt-4",
    Provider: &copilot.ProviderConfig{
        Type:    "openai",
        BaseURL: "https://my-api.example.com/v1",
        APIKey:  os.Getenv("MY_API_KEY"),
    },
})

Example with Azure OpenAI:

session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
    Model: "gpt-4",
    Provider: &copilot.ProviderConfig{
        Type:    "azure",  // Must be "azure" for Azure endpoints, NOT "openai"
        BaseURL: "https://my-resource.openai.azure.com",  // Just the host, no path
        APIKey:  os.Getenv("AZURE_OPENAI_KEY"),
        Azure: &copilot.AzureProviderOptions{
            APIVersion: "2024-10-21",
        },
    },
})

Important notes:

  • When using a custom provider, the Model parameter is required. The SDK will return an error if no model is specified.
  • For Azure OpenAI endpoints (*.openai.azure.com), you must use Type: "azure", not Type: "openai".
  • The BaseURL should be just the host (e.g., https://my-resource.openai.azure.com). Do not include /openai/v1 in the URL - the SDK handles path construction automatically.

User Input Requests

Enable the agent to ask questions to the user using the ask_user tool by providing an OnUserInputRequest handler:

session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
    Model: "gpt-5",
    OnUserInputRequest: func(request copilot.UserInputRequest, invocation copilot.UserInputInvocation) (copilot.UserInputResponse, error) {
        // request.Question - The question to ask
        // request.Choices - Optional slice of choices for multiple choice
        // request.AllowFreeform - Whether freeform input is allowed (default: true)

        fmt.Printf("Agent asks: %s\n", request.Question)
        if len(request.Choices) > 0 {
            fmt.Printf("Choices: %v\n", request.Choices)
        }

        // Return the user's response
        return copilot.UserInputResponse{
            Answer:      "User's answer here",
            WasFreeform: true, // Whether the answer was freeform (not from choices)
        }, nil
    },
})

Session Hooks

Hook into session lifecycle events by providing handlers in the Hooks configuration:

session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
    Model: "gpt-5",
    Hooks: &copilot.SessionHooks{
        // Called before each tool execution
        OnPreToolUse: func(input copilot.PreToolUseHookInput, invocation copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
            fmt.Printf("About to run tool: %s\n", input.ToolName)
            // Return permission decision and optionally modify args
            return &copilot.PreToolUseHookOutput{
                PermissionDecision: "allow", // "allow", "deny", or "ask"
                ModifiedArgs:       input.ToolArgs, // Optionally modify tool arguments
                AdditionalContext:  "Extra context for the model",
            }, nil
        },

        // Called after each tool execution
        OnPostToolUse: func(input copilot.PostToolUseHookInput, invocation copilot.HookInvocation) (*copilot.PostToolUseHookOutput, error) {
            fmt.Printf("Tool %s completed\n", input.ToolName)
            return &copilot.PostToolUseHookOutput{
                AdditionalContext: "Post-execution notes",
            }, nil
        },

        // Called when user submits a prompt
        OnUserPromptSubmitted: func(input copilot.UserPromptSubmittedHookInput, invocation copilot.HookInvocation) (*copilot.UserPromptSubmittedHookOutput, error) {
            fmt.Printf("User prompt: %s\n", input.Prompt)
            return &copilot.UserPromptSubmittedHookOutput{
                ModifiedPrompt: input.Prompt, // Optionally modify the prompt
            }, nil
        },

        // Called when session starts
        OnSessionStart: func(input copilot.SessionStartHookInput, invocation copilot.HookInvocation) (*copilot.SessionStartHookOutput, error) {
            fmt.Printf("Session started from: %s\n", input.Source) // "startup", "resume", "new"
            return &copilot.SessionStartHookOutput{
                AdditionalContext: "Session initialization context",
            }, nil
        },

        // Called when session ends
        OnSessionEnd: func(input copilot.SessionEndHookInput, invocation copilot.HookInvocation) (*copilot.SessionEndHookOutput, error) {
            fmt.Printf("Session ended: %s\n", input.Reason)
            return nil, nil
        },

        // Called when an error occurs
        OnErrorOccurred: func(input copilot.ErrorOccurredHookInput, invocation copilot.HookInvocation) (*copilot.ErrorOccurredHookOutput, error) {
            fmt.Printf("Error in %s: %s\n", input.ErrorContext, input.Error)
            return &copilot.ErrorOccurredHookOutput{
                ErrorHandling: "retry", // "retry", "skip", or "abort"
            }, nil
        },
    },
})

Available hooks:

  • OnPreToolUse - Intercept tool calls before execution. Can allow/deny or modify arguments.
  • OnPostToolUse - Process tool results after execution. Can modify results or add context.
  • OnUserPromptSubmitted - Intercept user prompts. Can modify the prompt before processing.
  • OnSessionStart - Run logic when a session starts or resumes.
  • OnSessionEnd - Cleanup or logging when session ends.
  • OnErrorOccurred - Handle errors with retry/skip/abort strategies.

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{
    OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
    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

View Source 
var PermissionHandler = struct {
	// ApproveAll approves all permission requests.
	ApproveAll PermissionHandlerFunc
}{
	ApproveAll: func(_ PermissionRequest, _ PermissionInvocation) (PermissionRequestResult, error) {
		return PermissionRequestResult{Kind: "approved"}, nil
	},
}

PermissionHandler provides pre-built OnPermissionRequest implementations.

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.

func String added in v0.1.24 

func String(v string) *string

String returns a pointer to the given string value. Use for setting optional string parameters in RPC calls.

Types

type AgentMode added in v0.1.24 

type AgentMode string
const (
	Autopilot   AgentMode = "autopilot"
	Interactive AgentMode = "interactive"
	Plan        AgentMode = "plan"
	Shell       AgentMode = "shell"
)

type Attachment 

type Attachment struct {
	DisplayName   *string         `json:"displayName,omitempty"`
	LineRange     *LineRange      `json:"lineRange,omitempty"`
	Path          *string         `json:"path,omitempty"`
	Type          AttachmentType  `json:"type"`
	FilePath      *string         `json:"filePath,omitempty"`
	Selection     *SelectionClass `json:"selection,omitempty"`
	Text          *string         `json:"text,omitempty"`
	Number        *float64        `json:"number,omitempty"`
	ReferenceType *ReferenceType  `json:"referenceType,omitempty"`
	State         *string         `json:"state,omitempty"`
	Title         *string         `json:"title,omitempty"`
	URL           *string         `json:"url,omitempty"`
}

type AttachmentType added in v0.1.15 

type AttachmentType string
const (
	Directory       AttachmentType = "directory"
	File            AttachmentType = "file"
	GithubReference AttachmentType = "github_reference"
	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 {

	// RPC provides typed server-scoped RPC methods.
	// This field is nil until the client is connected via Start().
	RPC *rpc.ServerRpc
	// 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(ctx context.Context, 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 required and must include an OnPermissionRequest handler.

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

Example: 

// Basic session
session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
    OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
})

// Session with model and tools
session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
    OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
    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(ctx context.Context, 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(context.Background(), "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(ctx context.Context) (*GetAuthStatusResponse, error)

GetAuthStatus returns current authentication status

func (*Client) GetForegroundSessionID added in v0.1.21 

func (c *Client) GetForegroundSessionID(ctx context.Context) (*string, error)

GetForegroundSessionID returns the ID of the session currently displayed in the TUI.

This is only available when connecting to a server running in TUI+server mode (--ui-server). Returns nil if no foreground session is set.

Example: 

sessionID, err := client.GetForegroundSessionID()
if err != nil {
    log.Fatal(err)
}
if sessionID != nil {
    fmt.Printf("TUI is displaying session: %s\n", *sessionID)
}

func (*Client) GetStatus added in v0.1.15 

func (c *Client) GetStatus(ctx context.Context) (*GetStatusResponse, error)

GetStatus returns CLI status including version and protocol information

func (*Client) ListModels added in v0.1.15 

func (c *Client) ListModels(ctx context.Context) ([]ModelInfo, error)

ListModels returns available models with their metadata.

Results are cached after the first successful call to avoid rate limiting. The cache is cleared when the client disconnects.

func (*Client) ListSessions added in v0.1.19 

func (c *Client) ListSessions(ctx context.Context, filter *SessionListFilter) ([]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, optional summaries, and context information.

An optional filter can be provided to filter sessions by cwd, git root, repository, or branch.

Example: 

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

Example with filter: 

sessions, err := client.ListSessions(context.Background(), &SessionListFilter{Repository: "owner/repo"})

func (*Client) On added in v0.1.21 

func (c *Client) On(handler SessionLifecycleHandler) func()

On subscribes to all session lifecycle events.

Lifecycle events are emitted when sessions are created, deleted, updated, or change foreground/background state (in TUI+server mode).

Returns a function that, when called, unsubscribes the handler.

Example: 

unsubscribe := client.On(func(event copilot.SessionLifecycleEvent) {
    fmt.Printf("Session %s: %s\n", event.SessionID, event.Type)
})
defer unsubscribe()

func (*Client) OnEventType added in v0.1.21 

func (c *Client) OnEventType(eventType SessionLifecycleEventType, handler SessionLifecycleHandler) func()

OnEventType subscribes to a specific session lifecycle event type.

Returns a function that, when called, unsubscribes the handler.

Example: 

unsubscribe := client.OnEventType(copilot.SessionLifecycleForeground, func(event copilot.SessionLifecycleEvent) {
    fmt.Printf("Session %s is now in foreground\n", event.SessionID)
})
defer unsubscribe()

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context, 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(context.Background(), "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(ctx context.Context, sessionID string, config *ResumeSessionConfig) (*Session, error)

ResumeSession resumes an existing conversation session by its ID.

This is a convenience method that calls Client.ResumeSessionWithOptions. The config must include an OnPermissionRequest handler.

Example: 

session, err := client.ResumeSession(context.Background(), "session-123", &copilot.ResumeSessionConfig{
    OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
})

func (*Client) ResumeSessionWithOptions 

func (c *Client) ResumeSessionWithOptions(ctx context.Context, 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(context.Background(), "session-123", &copilot.ResumeSessionConfig{
    OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
    Tools: []copilot.Tool{myNewTool},
})

func (*Client) SetForegroundSessionID added in v0.1.21 

func (c *Client) SetForegroundSessionID(ctx context.Context, sessionID string) error

SetForegroundSessionID requests the TUI to switch to displaying the specified session.

This is only available when connecting to a server running in TUI+server mode (--ui-server).

Example: 

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

func (*Client) Start 

func (c *Client) Start(ctx context.Context) 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(context.Background()); err != nil {
    log.Fatal("Failed to start:", err)
}
// Now ready to create sessions

func (*Client) State added in v0.1.21 

func (c *Client) State() ConnectionState

State returns the current connection state of the client.

Possible states: StateDisconnected, StateConnecting, StateConnected, StateError.

Example: 

if client.State() == copilot.StateConnected {
    session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
        OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
    })
}

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 error that aggregates all errors encountered during cleanup.

Example: 

if err := client.Stop(); err != nil {
    log.Printf("Cleanup error: %v", err)
}

type ClientOptions 

type ClientOptions struct {
	// CLIPath is the path to the Copilot CLI executable (default: "copilot")
	CLIPath string
	// CLIArgs are extra arguments to pass to the CLI executable (inserted before SDK-managed args)
	CLIArgs []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 controls whether to use stdio transport instead of TCP.
	// Default: nil (use default = true, i.e. stdio). Use Bool(false) to explicitly select TCP.
	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).
	// Each entry is of the form "key=value".
	// If Env is nil, the new process uses the current process's environment.
	// If Env contains duplicate environment keys, only the last value in the
	// slice for each duplicate key is used.
	Env []string
	// GitHubToken is the GitHub token to use for authentication.
	// When provided, the token is passed to the CLI server via environment variable.
	// This takes priority over other authentication methods.
	GitHubToken string
	// UseLoggedInUser controls whether to use the logged-in user for authentication.
	// When true, the CLI server will attempt to use stored OAuth tokens or gh CLI auth.
	// When false, only explicit tokens (GitHubToken or environment variables) are used.
	// Default: true (but defaults to false when GitHubToken is provided).
	// Use Bool(false) to explicitly disable.
	UseLoggedInUser *bool
}

ClientOptions configures the CopilotClient

type CodeChanges added in v0.1.21 

type CodeChanges struct {
	FilesModified []string `json:"filesModified"`
	LinesAdded    float64  `json:"linesAdded"`
	LinesRemoved  float64  `json:"linesRemoved"`
}

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 Content added in v0.1.24 

type Content struct {
	Text        *string        `json:"text,omitempty"`
	Type        ContentType    `json:"type"`
	Cwd         *string        `json:"cwd,omitempty"`
	ExitCode    *float64       `json:"exitCode,omitempty"`
	Data        *string        `json:"data,omitempty"`
	MIMEType    *string        `json:"mimeType,omitempty"`
	Description *string        `json:"description,omitempty"`
	Icons       []Icon         `json:"icons,omitempty"`
	Name        *string        `json:"name,omitempty"`
	Size        *float64       `json:"size,omitempty"`
	Title       *string        `json:"title,omitempty"`
	URI         *string        `json:"uri,omitempty"`
	Resource    *ResourceClass `json:"resource,omitempty"`
}

type ContentType added in v0.1.24 

type ContentType string
const (
	Audio        ContentType = "audio"
	Image        ContentType = "image"
	Resource     ContentType = "resource"
	ResourceLink ContentType = "resource_link"
	Terminal     ContentType = "terminal"
	Text         ContentType = "text"
)

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 CopilotUsage added in v0.1.29 

type CopilotUsage struct {
	TokenDetails []TokenDetail `json:"tokenDetails"`
	TotalNanoAiu float64       `json:"totalNanoAiu"`
}

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"`
	ProviderCallID *string       `json:"providerCallId,omitempty"`
	Stack          *string       `json:"stack,omitempty"`
	StatusCode     *int64        `json:"statusCode,omitempty"`
	Title          *string       `json:"title,omitempty"`
	InfoType       *string       `json:"infoType,omitempty"`
	WarningType    *string       `json:"warningType,omitempty"`
	NewModel       *string       `json:"newModel,omitempty"`
	PreviousModel  *string       `json:"previousModel,omitempty"`
	NewMode        *string       `json:"newMode,omitempty"`
	PreviousMode   *string       `json:"previousMode,omitempty"`
	Operation      *Operation    `json:"operation,omitempty"`
	// Relative path within the workspace files directory
	Path                            *string                  `json:"path,omitempty"`
	HandoffTime                     *time.Time               `json:"handoffTime,omitempty"`
	RemoteSessionID                 *string                  `json:"remoteSessionId,omitempty"`
	Repository                      *RepositoryUnion         `json:"repository"`
	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"`
	CodeChanges                     *CodeChanges             `json:"codeChanges,omitempty"`
	CurrentModel                    *string                  `json:"currentModel,omitempty"`
	ErrorReason                     *string                  `json:"errorReason,omitempty"`
	ModelMetrics                    map[string]ModelMetric   `json:"modelMetrics,omitempty"`
	SessionStartTime                *float64                 `json:"sessionStartTime,omitempty"`
	ShutdownType                    *ShutdownType            `json:"shutdownType,omitempty"`
	TotalAPIDurationMS              *float64                 `json:"totalApiDurationMs,omitempty"`
	TotalPremiumRequests            *float64                 `json:"totalPremiumRequests,omitempty"`
	Branch                          *string                  `json:"branch,omitempty"`
	Cwd                             *string                  `json:"cwd,omitempty"`
	GitRoot                         *string                  `json:"gitRoot,omitempty"`
	CurrentTokens                   *float64                 `json:"currentTokens,omitempty"`
	MessagesLength                  *float64                 `json:"messagesLength,omitempty"`
	CheckpointNumber                *float64                 `json:"checkpointNumber,omitempty"`
	CheckpointPath                  *string                  `json:"checkpointPath,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"`
	RequestID                       *string                  `json:"requestId,omitempty"`
	Success                         *bool                    `json:"success,omitempty"`
	SummaryContent                  *string                  `json:"summaryContent,omitempty"`
	TokensRemoved                   *float64                 `json:"tokensRemoved,omitempty"`
	AgentMode                       *AgentMode               `json:"agentMode,omitempty"`
	Attachments                     []Attachment             `json:"attachments,omitempty"`
	Content                         *string                  `json:"content,omitempty"`
	InteractionID                   *string                  `json:"interactionId,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"`
	TotalResponseSizeBytes          *float64                 `json:"totalResponseSizeBytes,omitempty"`
	EncryptedContent                *string                  `json:"encryptedContent,omitempty"`
	MessageID                       *string                  `json:"messageId,omitempty"`
	ParentToolCallID                *string                  `json:"parentToolCallId,omitempty"`
	Phase                           *string                  `json:"phase,omitempty"`
	ReasoningOpaque                 *string                  `json:"reasoningOpaque,omitempty"`
	ReasoningText                   *string                  `json:"reasoningText,omitempty"`
	ToolRequests                    []ToolRequest            `json:"toolRequests,omitempty"`
	APICallID                       *string                  `json:"apiCallId,omitempty"`
	CacheReadTokens                 *float64                 `json:"cacheReadTokens,omitempty"`
	CacheWriteTokens                *float64                 `json:"cacheWriteTokens,omitempty"`
	CopilotUsage                    *CopilotUsage            `json:"copilotUsage,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"`
	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"`
	AllowedTools                    []string                 `json:"allowedTools,omitempty"`
	Name                            *string                  `json:"name,omitempty"`
	PluginName                      *string                  `json:"pluginName,omitempty"`
	PluginVersion                   *string                  `json:"pluginVersion,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"`
	Role                            *Role                    `json:"role,omitempty"`
}

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 ErrorOccurredHandler added in v0.1.20 

type ErrorOccurredHandler func(input ErrorOccurredHookInput, invocation HookInvocation) (*ErrorOccurredHookOutput, error)

ErrorOccurredHandler handles error-occurred hook invocations

type ErrorOccurredHookInput added in v0.1.20 

type ErrorOccurredHookInput struct {
	Timestamp    int64  `json:"timestamp"`
	Cwd          string `json:"cwd"`
	Error        string `json:"error"`
	ErrorContext string `json:"errorContext"` // "model_call", "tool_execution", "system", "user_input"
	Recoverable  bool   `json:"recoverable"`
}

ErrorOccurredHookInput is the input for an error-occurred hook

type ErrorOccurredHookOutput added in v0.1.20 

type ErrorOccurredHookOutput struct {
	SuppressOutput   bool   `json:"suppressOutput,omitempty"`
	ErrorHandling    string `json:"errorHandling,omitempty"` // "retry", "skip", "abort"
	RetryCount       int    `json:"retryCount,omitempty"`
	UserNotification string `json:"userNotification,omitempty"`
}

ErrorOccurredHookOutput is the output for an error-occurred hook

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 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 HookInvocation added in v0.1.20 

type HookInvocation struct {
	SessionID string
}

HookInvocation provides context about a hook invocation

type Icon added in v0.1.24 

type Icon struct {
	MIMEType *string  `json:"mimeType,omitempty"`
	Sizes    []string `json:"sizes,omitempty"`
	Src      string   `json:"src"`
	Theme    *Theme   `json:"theme,omitempty"`
}

type InfiniteSessionConfig added in v0.1.18 

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

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 LineRange added in v0.1.24 

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

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]any

MCPServerConfig can be either MCPLocalServerConfig or MCPRemoteServerConfig Use a map[string]any 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"`
	SupportedReasoningEfforts []string          `json:"supportedReasoningEfforts,omitempty"`
	DefaultReasoningEffort    string            `json:"defaultReasoningEffort,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 ModelMetric added in v0.1.21 

type ModelMetric struct {
	Requests Requests `json:"requests"`
	Usage    Usage    `json:"usage"`
}

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"`
	ReasoningEffort bool `json:"reasoningEffort"`
}

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 Operation added in v0.1.25 

type Operation string
const (
	Create Operation = "create"
	Delete Operation = "delete"
	Update Operation = "update"
)

type PermissionHandlerFunc added in v0.1.28 

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

PermissionHandlerFunc 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]any `json:"-"` // Additional fields vary by kind
}

PermissionRequest represents a permission request from the server

func (*PermissionRequest) UnmarshalJSON added in v0.1.28 

func (p *PermissionRequest) UnmarshalJSON(data []byte) error

UnmarshalJSON implements custom JSON unmarshaling for PermissionRequest to capture additional fields (varying by kind) into the Extra map.

type PermissionRequestResult 

type PermissionRequestResult struct {
	Kind  string `json:"kind"`
	Rules []any  `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 PostToolUseHandler added in v0.1.20 

type PostToolUseHandler func(input PostToolUseHookInput, invocation HookInvocation) (*PostToolUseHookOutput, error)

PostToolUseHandler handles post-tool-use hook invocations

type PostToolUseHookInput added in v0.1.20 

type PostToolUseHookInput struct {
	Timestamp  int64  `json:"timestamp"`
	Cwd        string `json:"cwd"`
	ToolName   string `json:"toolName"`
	ToolArgs   any    `json:"toolArgs"`
	ToolResult any    `json:"toolResult"`
}

PostToolUseHookInput is the input for a post-tool-use hook

type PostToolUseHookOutput added in v0.1.20 

type PostToolUseHookOutput struct {
	ModifiedResult    any    `json:"modifiedResult,omitempty"`
	AdditionalContext string `json:"additionalContext,omitempty"`
	SuppressOutput    bool   `json:"suppressOutput,omitempty"`
}

PostToolUseHookOutput is the output for a post-tool-use hook

type PreToolUseHandler added in v0.1.20 

type PreToolUseHandler func(input PreToolUseHookInput, invocation HookInvocation) (*PreToolUseHookOutput, error)

PreToolUseHandler handles pre-tool-use hook invocations

type PreToolUseHookInput added in v0.1.20 

type PreToolUseHookInput struct {
	Timestamp int64  `json:"timestamp"`
	Cwd       string `json:"cwd"`
	ToolName  string `json:"toolName"`
	ToolArgs  any    `json:"toolArgs"`
}

PreToolUseHookInput is the input for a pre-tool-use hook

type PreToolUseHookOutput added in v0.1.20 

type PreToolUseHookOutput struct {
	PermissionDecision       string `json:"permissionDecision,omitempty"` // "allow", "deny", "ask"
	PermissionDecisionReason string `json:"permissionDecisionReason,omitempty"`
	ModifiedArgs             any    `json:"modifiedArgs,omitempty"`
	AdditionalContext        string `json:"additionalContext,omitempty"`
	SuppressOutput           bool   `json:"suppressOutput,omitempty"`
}

PreToolUseHookOutput is the output for a pre-tool-use hook

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 ReferenceType added in v0.1.29 

type ReferenceType string
const (
	Discussion ReferenceType = "discussion"
	Issue      ReferenceType = "issue"
	PR         ReferenceType = "pr"
)

type RepositoryClass added in v0.1.24 

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

type RepositoryUnion added in v0.1.24 

type RepositoryUnion struct {
	RepositoryClass *RepositoryClass
	String          *string
}

func (*RepositoryUnion) MarshalJSON added in v0.1.24 

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

func (*RepositoryUnion) UnmarshalJSON added in v0.1.24 

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

type Requests added in v0.1.21 

type Requests struct {
	Cost  float64 `json:"cost"`
	Count float64 `json:"count"`
}

type ResourceClass added in v0.1.24 

type ResourceClass struct {
	MIMEType *string `json:"mimeType,omitempty"`
	Text     *string `json:"text,omitempty"`
	URI      string  `json:"uri"`
	Blob     *string `json:"blob,omitempty"`
}

type Result added in v0.1.15 

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

type ResumeSessionConfig 

type ResumeSessionConfig struct {
	// ClientName identifies the application using the SDK.
	// Included in the User-Agent header for API requests.
	ClientName string
	// Model to use for this session. Can change the model when resuming.
	Model 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
	// Provider configures a custom model provider
	Provider *ProviderConfig
	// ReasoningEffort level for models that support it.
	// Valid values: "low", "medium", "high", "xhigh"
	ReasoningEffort string
	// OnPermissionRequest is a handler for permission requests from the server.
	// If nil, all permission requests are denied by default.
	// Provide a handler to approve operations (file writes, shell commands, URL fetches, etc.).
	OnPermissionRequest PermissionHandlerFunc
	// OnUserInputRequest is a handler for user input requests from the agent (enables ask_user tool)
	OnUserInputRequest UserInputHandler
	// Hooks configures hook handlers for session lifecycle events
	Hooks *SessionHooks
	// WorkingDirectory is the working directory for the session.
	// Tool operations will be relative to this directory.
	WorkingDirectory string
	// ConfigDir overrides the default configuration directory location.
	ConfigDir string
	// 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
	// InfiniteSessions configures infinite sessions for persistent workspaces and automatic compaction.
	InfiniteSessions *InfiniteSessionConfig
	// DisableResume, when true, skips emitting the session.resume event.
	// Useful for reconnecting to a session without triggering resume-related side effects.
	DisableResume bool
}

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

	// RPC provides typed session-scoped RPC methods.
	RPC *rpc.SessionRpc
	// 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 (*Session) Abort 

func (s *Session) Abort(ctx context.Context) 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(context.Background(), copilot.MessageOptions{
        Prompt: "Write a very long story...",
    })
}()

// Abort after 5 seconds
time.Sleep(5 * time.Second)
if err := session.Abort(context.Background()); 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(ctx context.Context) ([]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(context.Background())
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(ctx context.Context, 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(context.Background(), 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(ctx context.Context, options MessageOptions) (*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(context.Background(), copilot.MessageOptions{
    Prompt: "What is 2+2?",
}) // 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
	// ClientName identifies the application using the SDK.
	// Included in the User-Agent header for API requests.
	ClientName string
	// Model to use for this session
	Model string
	// ReasoningEffort level for models that support it.
	// Valid values: "low", "medium", "high", "xhigh"
	// Only applies to models where capabilities.supports.reasoningEffort is true.
	ReasoningEffort 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.
	// If nil, all permission requests are denied by default.
	// Provide a handler to approve operations (file writes, shell commands, URL fetches, etc.).
	OnPermissionRequest PermissionHandlerFunc
	// OnUserInputRequest is a handler for user input requests from the agent (enables ask_user tool)
	OnUserInputRequest UserInputHandler
	// Hooks configures hook handlers for session lifecycle events
	Hooks *SessionHooks
	// WorkingDirectory is the working directory for the session.
	// Tool operations will be relative to this directory.
	WorkingDirectory string
	// 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 SessionContext added in v0.1.24 

type SessionContext struct {
	// Cwd is the working directory where the session was created
	Cwd string `json:"cwd"`
	// GitRoot is the git repository root (if in a git repo)
	GitRoot string `json:"gitRoot,omitempty"`
	// Repository is the GitHub repository in "owner/repo" format
	Repository string `json:"repository,omitempty"`
	// Branch is the current git branch
	Branch string `json:"branch,omitempty"`
}

SessionContext contains working directory context for a session

type SessionEndHandler added in v0.1.20 

type SessionEndHandler func(input SessionEndHookInput, invocation HookInvocation) (*SessionEndHookOutput, error)

SessionEndHandler handles session-end hook invocations

type SessionEndHookInput added in v0.1.20 

type SessionEndHookInput struct {
	Timestamp    int64  `json:"timestamp"`
	Cwd          string `json:"cwd"`
	Reason       string `json:"reason"` // "complete", "error", "abort", "timeout", "user_exit"
	FinalMessage string `json:"finalMessage,omitempty"`
	Error        string `json:"error,omitempty"`
}

SessionEndHookInput is the input for a session-end hook

type SessionEndHookOutput added in v0.1.20 

type SessionEndHookOutput struct {
	SuppressOutput bool     `json:"suppressOutput,omitempty"`
	CleanupActions []string `json:"cleanupActions,omitempty"`
	SessionSummary string   `json:"sessionSummary,omitempty"`
}

SessionEndHookOutput is the output for a session-end hook

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"
	AssistantStreamingDelta     SessionEventType = "assistant.streaming_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"
	SessionContextChanged       SessionEventType = "session.context_changed"
	SessionError                SessionEventType = "session.error"
	SessionHandoff              SessionEventType = "session.handoff"
	SessionIdle                 SessionEventType = "session.idle"
	SessionInfo                 SessionEventType = "session.info"
	SessionModeChanged          SessionEventType = "session.mode_changed"
	SessionModelChange          SessionEventType = "session.model_change"
	SessionPlanChanged          SessionEventType = "session.plan_changed"
	SessionResume               SessionEventType = "session.resume"
	SessionShutdown             SessionEventType = "session.shutdown"
	SessionSnapshotRewind       SessionEventType = "session.snapshot_rewind"
	SessionStart                SessionEventType = "session.start"
	SessionTaskComplete         SessionEventType = "session.task_complete"
	SessionTitleChanged         SessionEventType = "session.title_changed"
	SessionTruncation           SessionEventType = "session.truncation"
	SessionUsageInfo            SessionEventType = "session.usage_info"
	SessionWarning              SessionEventType = "session.warning"
	SessionWorkspaceFileChanged SessionEventType = "session.workspace_file_changed"
	SkillInvoked                SessionEventType = "skill.invoked"
	SubagentCompleted           SessionEventType = "subagent.completed"
	SubagentDeselected          SessionEventType = "subagent.deselected"
	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 SessionHooks added in v0.1.20 

type SessionHooks struct {
	OnPreToolUse          PreToolUseHandler
	OnPostToolUse         PostToolUseHandler
	OnUserPromptSubmitted UserPromptSubmittedHandler
	OnSessionStart        SessionStartHandler
	OnSessionEnd          SessionEndHandler
	OnErrorOccurred       ErrorOccurredHandler
}

SessionHooks configures hook handlers for a session

type SessionLifecycleEvent added in v0.1.21 

type SessionLifecycleEvent struct {
	Type      SessionLifecycleEventType      `json:"type"`
	SessionID string                         `json:"sessionId"`
	Metadata  *SessionLifecycleEventMetadata `json:"metadata,omitempty"`
}

SessionLifecycleEvent represents a session lifecycle notification

type SessionLifecycleEventMetadata added in v0.1.21 

type SessionLifecycleEventMetadata struct {
	StartTime    string  `json:"startTime"`
	ModifiedTime string  `json:"modifiedTime"`
	Summary      *string `json:"summary,omitempty"`
}

SessionLifecycleEventMetadata contains optional metadata for lifecycle events

type SessionLifecycleEventType added in v0.1.21 

type SessionLifecycleEventType string

SessionLifecycleEventType represents the type of session lifecycle event 

const (
	SessionLifecycleCreated    SessionLifecycleEventType = "session.created"
	SessionLifecycleDeleted    SessionLifecycleEventType = "session.deleted"
	SessionLifecycleUpdated    SessionLifecycleEventType = "session.updated"
	SessionLifecycleForeground SessionLifecycleEventType = "session.foreground"
	SessionLifecycleBackground SessionLifecycleEventType = "session.background"
)

type SessionLifecycleHandler added in v0.1.21 

type SessionLifecycleHandler func(event SessionLifecycleEvent)

SessionLifecycleHandler is a callback for session lifecycle events

type SessionListFilter added in v0.1.24 

type SessionListFilter struct {
	// Cwd filters by exact working directory match
	Cwd string `json:"cwd,omitempty"`
	// GitRoot filters by git root
	GitRoot string `json:"gitRoot,omitempty"`
	// Repository filters by repository (owner/repo format)
	Repository string `json:"repository,omitempty"`
	// Branch filters by branch
	Branch string `json:"branch,omitempty"`
}

SessionListFilter contains filter options for listing sessions

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"`
	Context      *SessionContext `json:"context,omitempty"`
}

SessionMetadata contains metadata about a session

type SessionStartHandler added in v0.1.20 

type SessionStartHandler func(input SessionStartHookInput, invocation HookInvocation) (*SessionStartHookOutput, error)

SessionStartHandler handles session-start hook invocations

type SessionStartHookInput added in v0.1.20 

type SessionStartHookInput struct {
	Timestamp     int64  `json:"timestamp"`
	Cwd           string `json:"cwd"`
	Source        string `json:"source"` // "startup", "resume", "new"
	InitialPrompt string `json:"initialPrompt,omitempty"`
}

SessionStartHookInput is the input for a session-start hook

type SessionStartHookOutput added in v0.1.20 

type SessionStartHookOutput struct {
	AdditionalContext string         `json:"additionalContext,omitempty"`
	ModifiedConfig    map[string]any `json:"modifiedConfig,omitempty"`
}

SessionStartHookOutput is the output for a session-start hook

type ShutdownType added in v0.1.21 

type ShutdownType string
const (
	Error   ShutdownType = "error"
	Routine ShutdownType = "routine"
)

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 Theme added in v0.1.24 

type Theme string
const (
	Dark  Theme = "dark"
	Light Theme = "light"
)

type TokenDetail added in v0.1.29 

type TokenDetail struct {
	BatchSize    float64 `json:"batchSize"`
	CostPerBatch float64 `json:"costPerBatch"`
	TokenCount   float64 `json:"tokenCount"`
	TokenType    string  `json:"tokenType"`
}

type Tool 

type Tool struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	Parameters  map[string]any `json:"parameters,omitempty"`
	Handler     ToolHandler    `json:"-"`
}

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  any
}

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]any     `json:"toolTelemetry,omitempty"`
}

ToolResult represents the result of a tool invocation.

type Usage added in v0.1.21 

type Usage struct {
	CacheReadTokens  float64 `json:"cacheReadTokens"`
	CacheWriteTokens float64 `json:"cacheWriteTokens"`
	InputTokens      float64 `json:"inputTokens"`
	OutputTokens     float64 `json:"outputTokens"`
}

type UserInputHandler added in v0.1.20 

type UserInputHandler func(request UserInputRequest, invocation UserInputInvocation) (UserInputResponse, error)

UserInputHandler handles user input requests from the agent The handler should return a UserInputResponse. Returning an error fails the request.

type UserInputInvocation added in v0.1.20 

type UserInputInvocation struct {
	SessionID string
}

UserInputInvocation provides context about a user input request

type UserInputRequest added in v0.1.20 

type UserInputRequest struct {
	Question      string
	Choices       []string
	AllowFreeform *bool
}

UserInputRequest represents a request for user input from the agent

type UserInputResponse added in v0.1.20 

type UserInputResponse struct {
	Answer      string
	WasFreeform bool
}

UserInputResponse represents the user's response to an input request

type UserPromptSubmittedHandler added in v0.1.20 

type UserPromptSubmittedHandler func(input UserPromptSubmittedHookInput, invocation HookInvocation) (*UserPromptSubmittedHookOutput, error)

UserPromptSubmittedHandler handles user-prompt-submitted hook invocations

type UserPromptSubmittedHookInput added in v0.1.20 

type UserPromptSubmittedHookInput struct {
	Timestamp int64  `json:"timestamp"`
	Cwd       string `json:"cwd"`
	Prompt    string `json:"prompt"`
}

UserPromptSubmittedHookInput is the input for a user-prompt-submitted hook

type UserPromptSubmittedHookOutput added in v0.1.20 

type UserPromptSubmittedHookOutput struct {
	ModifiedPrompt    string `json:"modifiedPrompt,omitempty"`
	AdditionalContext string `json:"additionalContext,omitempty"`
	SuppressOutput    bool   `json:"suppressOutput,omitempty"`
}

UserPromptSubmittedHookOutput is the output for a user-prompt-submitted hook

Source Files

View all Source files

Directories

Path Synopsis
cmd
bundler command
Bundler downloads Copilot CLI binaries and packages them as a binary file, along with a Go source file that embeds the binary and metadata.
 Bundler downloads Copilot CLI binaries and packages them as a binary file, along with a Go source file that embeds the binary and metadata.
internal
e2e/testharness
embeddedcli
flock
jsonrpc2
samples module

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.