// 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 d, ok := event.Data.(*copilot.AssistantMessageData); ok {

// fmt.Println(d.Content)

// }

// })

//

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

package copilot

import (

"bufio"

"context"

"encoding/json"

"errors"

"fmt"

"io"

"log"

"net"

"net/netip"

"os"

"os/exec"

"path/filepath"

"regexp"

"runtime/debug"

"strconv"

"strings"

"sync"

"sync/atomic"

"time"

"github.com/google/uuid"

"github.com/github/copilot-sdk/go/internal/embeddedcli"

"github.com/github/copilot-sdk/go/internal/jsonrpc2"

"github.com/github/copilot-sdk/go/internal/truncbuffer"

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

)

// defaultBearerTokenProviderName is the implicit provider name for the singular,

// whole-session [ProviderConfig]. Named providers are keyed by their own Name.

const defaultBearerTokenProviderName = "default"

type cloudSkillProviderError struct{}

func (cloudSkillProviderError) Error() string {

return "Skill providers are not supported for cloud sessions."

}

// collectBearerTokenProviders gathers the per-provider [BearerTokenProvider] callbacks

// from the singular provider and any named providers, keyed by provider name. The

// singular provider uses the implicit name "default"; named providers use their

// own Name. Returns nil when no callbacks are configured.

func collectBearerTokenProviders(provider *ProviderConfig, providers []NamedProviderConfig) map[string]BearerTokenProvider {

callbacks := make(map[string]BearerTokenProvider)

if provider != nil && provider.BearerTokenProvider != nil {

callbacks[defaultBearerTokenProviderName] = provider.BearerTokenProvider

}

for i := range providers {

if providers[i].BearerTokenProvider != nil {

callbacks[providers[i].Name] = providers[i].BearerTokenProvider

}

}

if len(callbacks) == 0 {

return nil

}

return callbacks

}

func validateSessionFSConfig(config *SessionFSConfig) error {

if config == nil {

return nil

}

if config.InitialWorkingDirectory == "" {

return errors.New("SessionFS.InitialWorkingDirectory is required")

}

if config.SessionStatePath == "" {

return errors.New("SessionFS.SessionStatePath is required")

}

if config.Conventions != rpc.SessionFSSetProviderConventionsPosix && config.Conventions != rpc.SessionFSSetProviderConventionsWindows {

return errors.New("SessionFS.Conventions must be either 'posix' or 'windows'")

}

return nil

}

// validateEnvironmentOptions enforces the transport-specific rules for

// per-client environment, working directory, and telemetry. It panics (fails

// loud) on a misconfiguration, matching the other SDKs.

//

// The in-process transport loads the native runtime into this process, whose

// single environment block and process-global working directory cannot carry

// per-client values, and whose telemetry lowers to shared process-global env

// vars — so options that depend on them are rejected there. Child-process

// transports each own their OS process, so per-connection env is allowed, but

// setting it in both the client-level option and the connection is rejected.

func validateEnvironmentOptions(connection RuntimeConnection, opts *ClientOptions) {

if _, ok := connection.(InProcessConnection); ok {

if opts.Env != nil {

panic("Env is not supported with InProcessConnection: the in-process transport loads the native runtime into the shared host process, whose single environment block cannot carry per-client values. Set the variables on the host process environment instead.")

}

if opts.WorkingDirectory != "" {

panic("WorkingDirectory is not supported with InProcessConnection: the native runtime shares the host process working directory. Use a child-process transport, or set the process working directory before creating the client.")

}

if opts.Telemetry != nil {

panic("Telemetry is not supported with InProcessConnection: telemetry configuration is lowered to environment variables read by native runtime code running in the shared host process, so per-client telemetry cannot be honored in-process. Configure telemetry via the host process environment, or use a child-process transport.")

}

return

}

if cp, ok := connection.(childProcessConnection); ok {

if cp.connEnv() != nil && opts.Env != nil {

panic("Set environment variables via either the client-level Env option or the connection's Env, not both. Prefer the connection-level Env for child-process transports.")

}

}

}

// 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{

// Connection: copilot.URIConnection{URL: "localhost:3000"},

// })

//

// if err := client.Start(); err != nil {

// log.Fatal(err)

// }

// defer client.Stop()

type Client struct {

options ClientOptions

process *exec.Cmd

processStdin io.WriteCloser

client *jsonrpc2.Client

actualPort int

actualHost string

state connectionState

sessions map[string]*Session

sessionsMux sync.Mutex

ahp ahpHostState

gitHubTokenProviders map[string]GitHubTokenProvider

gitHubTokenProvidersMux sync.RWMutex

requestAdapter *copilotRequestAdapter

requestAdapterMux sync.Mutex

installationConfirmationAdapter *installationConfirmationAdapter

installationConfirmationAdapterMux sync.Mutex

sessionOperations map[string]*sessionOperation

sessionOperationsMux sync.Mutex

isExternalServer bool

conn net.Conn // stores net.Conn for external TCP connections

useStdio bool // resolved value from options

useInProcess bool // true for InProcessConnection (FFI transport)

ffiHost inProcessHost

runOnUiThread func(action func() error) error

// resolved process options for the spawned runtime (zero values for URIConnection)

cliPath string

cliArgs []string

port int

tcpConnectionToken string

modelsCache []ModelInfo

modelsCacheMux sync.Mutex

lifecycleHandlers map[uint64]SessionLifecycleHandler

typedLifecycleHandlers map[SessionLifecycleEventType]map[uint64]SessionLifecycleHandler

nextLifecycleHandlerID uint64

lifecycleHandlersMux sync.Mutex

startStopMux sync.RWMutex // protects process and state during start/[force]stop

processDone chan struct{}

processErrorPtr *error

osProcess atomic.Pointer[os.Process]

negotiatedProtocolVersion int

// effectiveConnectionToken is the token sent in `connect`; auto-generated when

// the SDK spawns its own CLI in TCP mode.

effectiveConnectionToken string

onListModels func(ctx context.Context) ([]ModelInfo, error)

// RPC provides typed server-scoped RPC methods.

// This field is nil until the client is connected via Start().

RPC *rpc.ServerRPC

// internalRPC provides SDK-internal RPC methods (handshake helpers etc.).

// Lowercase = not exported; external callers cannot reach it.

internalRPC *rpc.InternalServerRPC

}

type sessionOperation struct {

mutex sync.Mutex

users int

}

// NewClient creates a new Copilot runtime client with the given options.

//

// If options is nil, default options are used (spawns the bundled runtime over

// stdio). The client is not connected after creation; call [Client.Start] to

// connect, or simply call [Client.CreateSession]/[Client.ResumeSession], which

// auto-start the runtime on first use.

//

// Example:

//

// // Default options: bundled runtime over stdio

// client := copilot.NewClient(nil)

//

// // Custom CLI path over stdio

// client := copilot.NewClient(&copilot.ClientOptions{

// Connection: copilot.StdioConnection{Path: "/usr/local/bin/copilot"},

// LogLevel: "debug",

// })

//

// // Connect to an already-running runtime

// client := copilot.NewClient(&copilot.ClientOptions{

// Connection: copilot.URIConnection{URL: "localhost:8080"},

// })

func NewClient(options *ClientOptions) *Client {

opts := ClientOptions{}

client := &Client{

options: opts,

state: stateDisconnected,

sessions: make(map[string]*Session),

gitHubTokenProviders: make(map[string]GitHubTokenProvider),

actualHost: "localhost",

isExternalServer: false,

useStdio: true,

}

if options != nil {

opts = *options

}

for _, path := range opts.BuiltinPluginDirectories {

if !filepath.IsAbs(path) {

panic(fmt.Sprintf("BuiltinPluginDirectories must contain only absolute paths: %s", path))

}

}

opts.BuiltinPluginDirectories = append([]string(nil), opts.BuiltinPluginDirectories...)

// Resolve the connection. An explicit connection always wins; otherwise

// honor the same process/environment override as the other SDKs.

connection := opts.Connection

if connection == nil {

env := opts.Env

if env == nil {

env = os.Environ()

}

connection = resolveDefaultConnection(env)

}

switch conn := connection.(type) {

case StdioConnection:

client.useStdio = true

client.cliPath = conn.Path

if len(conn.Args) > 0 {

client.cliArgs = append([]string{}, conn.Args...)

}

case TCPConnection:

client.useStdio = false

client.cliPath = conn.Path

if len(conn.Args) > 0 {

client.cliArgs = append([]string{}, conn.Args...)

}

client.port = conn.Port

client.tcpConnectionToken = conn.ConnectionToken

case URIConnection:

if conn.URL == "" {

panic("URIConnection requires a non-empty URL")

}

host, port := parseCLIURL(conn.URL)

client.actualHost = host

client.actualPort = port

client.isExternalServer = true

client.useStdio = false

client.tcpConnectionToken = conn.ConnectionToken

case InProcessConnection:

client.useStdio = false

client.useInProcess = true

client.runOnUiThread = conn.RunOnUiThread

default:

panic(fmt.Sprintf("unknown RuntimeConnection type: %T", connection))

}

// Validate transport-specific option constraints (fail loud). The in-process

// transport loads the runtime into this process, whose single environment

// block, process-global working directory, and shared telemetry state cannot

// carry per-client values. Child-process transports may set env via either

// the client-level option or the connection, but not both.

validateEnvironmentOptions(connection, &opts)

// Validate auth options when connecting to an external runtime.

if client.isExternalServer && (opts.GitHubToken != "" || opts.UseLoggedInUser != nil) {

panic("GitHubToken and UseLoggedInUser cannot be used with URIConnection (external runtime manages its own auth)")

}

// For child-process transports, a connection-level env takes precedence over

// the client-level env (setting both was rejected above). Resolve it before

// defaulting so an explicit empty connection env stays authoritative.

if cp, ok := connection.(childProcessConnection); ok {

if env := cp.connEnv(); env != nil {

opts.Env = env

}

}

// Default Env to current environment if not set

if opts.Env == nil {

opts.Env = os.Environ()

}

// Check the effective environment for a child-process runtime override.

if client.cliPath == "" && !client.useInProcess {

if cliPath := getEnvValue(opts.Env, "COPILOT_CLI_PATH"); cliPath != "" {

client.cliPath = cliPath

}

}

// Resolve the effective connection token: explicit value if set; else if the SDK

// spawns its own runtime in TCP mode, generate a UUID; otherwise empty. The

// in-process transport uses no socket, so it needs no connection token.

if client.tcpConnectionToken != "" {

client.effectiveConnectionToken = client.tcpConnectionToken

} else if !client.useStdio && !client.isExternalServer && !client.useInProcess {

client.effectiveConnectionToken = uuid.NewString()

}

if opts.OnListModels != nil {

client.onListModels = opts.OnListModels

}

if opts.SessionFS != nil {

if err := validateSessionFSConfig(opts.SessionFS); err != nil {

panic(err.Error())

}

}

client.options = opts

validateNewClientForMode(&client.options)

return client

}

func resolveRuntimeExecutable(explicitPath, bundledRuntimePath string) (string, error) {

if explicitPath != "" {

return explicitPath, nil

}

if bundledRuntimePath == "" {

return "", errors.New(

"managed Copilot runtime unavailable: the embedded bundle does not contain copilot-runtime and adjacent runtime.node; regenerate the bundle, provide an explicit path, or set COPILOT_CLI_PATH",

)

}

return bundledRuntimePath, nil

}

const defaultConnectionEnvVar = "COPILOT_SDK_DEFAULT_CONNECTION"

// resolveDefaultConnection selects the transport when no explicit connection

// was supplied. The override is primarily used by hosts and the E2E transport

// matrix; explicit connection options always take precedence.

func resolveDefaultConnection(env []string) RuntimeConnection {

value := getEnvValue(env, defaultConnectionEnvVar)

switch {

case value == "", strings.EqualFold(value, "stdio"):

return StdioConnection{}

case strings.EqualFold(value, "inprocess"):

return InProcessConnection{}

default:

panic(fmt.Sprintf(

"invalid %s value %q: expected \"inprocess\", \"stdio\", or unset",

defaultConnectionEnvVar,

value,

))

}

}

// getEnvValue looks up a key in an environment slice ([]string of "KEY=VALUE").

// Returns the value if found, or empty string otherwise.

func getEnvValue(env []string, key string) string {

prefix := key + "="

for i := len(env) - 1; i >= 0; i-- {

if strings.HasPrefix(env[i], prefix) {

return env[i][len(prefix):]

}

}

return ""

}

// setEnvValue returns a copy of env with all existing entries for key removed and

// a single trailing KEY=VALUE entry added so SDK-managed values win deterministically.

func setEnvValue(env []string, key string, value string) []string {

prefix := key + "="

filtered := make([]string, 0, len(env)+1)

for _, entry := range env {

if !strings.HasPrefix(entry, prefix) {

filtered = append(filtered, entry)

}

}

return append(filtered, key+"="+value)

}

// parseCLIURL parses a CLI URL into host and port components.

//

// Supports formats: "host:port", "[ipv6]:port", "http://host:port", "https://host:port", or just "port".

// Panics if the URL format is invalid or the port is out of range.

func parseCLIURL(url string) (string, int) {

// Remove protocol if present

cleanURL, _ := strings.CutPrefix(url, "https://")

cleanURL, _ = strings.CutPrefix(cleanURL, "http://")

// Use the standard parser only for the bracketed IPv6 form. Keep the

// existing host:port parsing behavior for all other inputs.

if strings.HasPrefix(cleanURL, "[") {

host, portStr, err := net.SplitHostPort(cleanURL)

if err != nil {

panic(fmt.Sprintf("Invalid port in URIConnection: %s", url))

}

addr, err := netip.ParseAddr(host)

if err != nil || !addr.Is6() {

panic(fmt.Sprintf("Invalid URIConnection format: %s", url))

}

port, err := strconv.Atoi(portStr)

if err != nil || port <= 0 || port > 65535 {

panic(fmt.Sprintf("Invalid port in URIConnection: %s", url))

}

return host, port

}

// Parse host:port or port format

var host string

var portStr string

if before, after, found := strings.Cut(cleanURL, ":"); found {

host = before

portStr = after

} else {

portStr = cleanURL

}

if host == "" {

host = "localhost"

}

port, err := strconv.Atoi(portStr)

if err != nil || port <= 0 || port > 65535 {

panic(fmt.Sprintf("Invalid port in URIConnection: %s", url))

}

return host, port

}

// Start starts the CLI server (if not using an external server) and establishes

// a connection.

//

// If connecting to an external server (via URIConnection), 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 (c *Client) Start(ctx context.Context) error {

c.startStopMux.Lock()

defer c.startStopMux.Unlock()

if c.state == stateConnected {

return nil

}

c.state = stateConnecting

// Only start CLI server process if not connecting to external server

if !c.isExternalServer {

if err := c.startCLIServer(ctx); err != nil {

c.process = nil

c.state = stateError

return err

}

}

// Connect to the server

if err := c.connectToServer(ctx); err != nil {

killErr := c.killProcess()

c.state = stateError

return errors.Join(err, killErr)

}

// Verify protocol version compatibility

if err := c.verifyProtocolVersion(ctx); err != nil {

c.client.Stop()

c.client = nil

c.conn = nil

c.RPC = nil

c.internalRPC = nil

killErr := c.killProcess()

c.state = stateError

return errors.Join(err, killErr)

}

if c.options.ExtensionLaunchProvider != nil {

if _, err := c.RPC.RegisterExtensionLaunchProvider(ctx); err != nil {

c.client.Stop()

c.client = nil

c.conn = nil

c.RPC = nil

c.internalRPC = nil

killErr := c.killProcess()

c.state = stateError

return errors.Join(err, killErr)

}

}

if len(c.options.BuiltinPluginDirectories) > 0 {

if _, err := c.client.Request(ctx, "plugins.builtin.set", map[string]any{

"paths": c.options.BuiltinPluginDirectories,

}); err != nil {

c.client.Stop()

c.client = nil

c.conn = nil

c.RPC = nil

c.internalRPC = nil

killErr := c.killProcess()

c.state = stateError

return errors.Join(err, killErr)

}

}

// If a session filesystem provider was configured, register it.

if c.options.SessionFS != nil {

req := &rpc.SessionFSSetProviderRequest{

InitialCwd: c.options.SessionFS.InitialWorkingDirectory,

SessionStatePath: c.options.SessionFS.SessionStatePath,

Conventions: c.options.SessionFS.Conventions,

}

if c.options.SessionFS.Capabilities != nil {

sqlite := c.options.SessionFS.Capabilities.Sqlite

binary := c.options.SessionFS.Capabilities.Binary

req.Capabilities = &rpc.SessionFSSetProviderCapabilities{

Sqlite: &sqlite,

Binary: &binary,

}

}

_, err := c.RPC.SessionFS.SetProvider(ctx, req)

if err != nil {

killErr := c.killProcess()

c.state = stateError

return errors.Join(err, killErr)

}

}

// If a request handler was configured, register as the inference provider.

if c.options.RequestHandler != nil {

if _, err := c.RPC.LlmInference.SetProvider(ctx); err != nil {

killErr := c.killProcess()

c.state = stateError

return errors.Join(err, killErr)

}

}

c.state = stateConnected

return nil

}

// Stop stops the CLI server and closes all active sessions.

//

// This method performs graceful cleanup:

// 1. Closes all active sessions (releases in-memory resources)

// 2. Requests runtime shutdown for SDK-owned CLI processes

// 3. Closes owned stdio input and waits up to 10 seconds for host cleanup and exit

// 4. Terminates any remaining owned CLI process and closes the JSON-RPC connection

//

// Note: session data on disk is preserved, so sessions can be resumed later.

// To permanently remove session data before stopping, call [Client.DeleteSession]

// for each session first.

//

// Returns an error that aggregates all errors encountered during cleanup.

//

// Example:

//

// if err := client.Stop(); err != nil {

// log.Printf("Cleanup error: %v", err)

// }

func (c *Client) Stop() error {

c.disconnectAhpHosts()

var errs []error

// Disconnect all active sessions

c.sessionsMux.Lock()

sessions := make([]*Session, 0, len(c.sessions))

for _, session := range c.sessions {

sessions = append(sessions, session)

}

c.sessionsMux.Unlock()

for _, session := range sessions {

if err := session.Disconnect(); err != nil {

errs = append(errs, fmt.Errorf("failed to disconnect session %s: %w", session.SessionID, err))

}

}

c.sessionsMux.Lock()

c.sessions = make(map[string]*Session)

c.sessionsMux.Unlock()

c.clearGitHubTokenProviders()

c.closeCopilotRequestAdapter()

c.closeInstallationConfirmationAdapter()

c.startStopMux.Lock()

defer c.startStopMux.Unlock()

if (c.process != nil || c.ffiHost != nil) && !c.isExternalServer && c.RPC != nil {

rpcClient := c.RPC

runtimeShutdownStart := time.Now()

shutdownDone := make(chan error, 1)

go func() {

_, err := rpcClient.Runtime.Shutdown(context.Background())

shutdownDone <- err

}()

select {

case err := <-shutdownDone:

if err != nil {

c.logDebugTiming(runtimeShutdownStart, "CopilotClient.Stop runtime shutdown failed")

errs = append(errs, fmt.Errorf("failed to gracefully shut down runtime: %w", err))

} else {

c.logDebugTiming(runtimeShutdownStart, "CopilotClient.Stop runtime shutdown complete")

}

case <-time.After(runtimeShutdownTimeout):

c.logDebugTiming(runtimeShutdownStart, "CopilotClient.Stop runtime shutdown timed out")

errs = append(errs, fmt.Errorf("timed out gracefully shutting down runtime after %s", runtimeShutdownTimeout))

}

}

// The stdio host finalizes telemetry after EOF, not after runtime.shutdown.

// Keep stdout open while allowing the child to finish that cleanup naturally.

if c.process != nil && !c.isExternalServer && c.processStdin != nil {

processExitStart := time.Now()

if err := c.processStdin.Close(); err != nil && !errors.Is(err, os.ErrClosed) {

errs = append(errs, fmt.Errorf("failed to close CLI stdin: %w", err))

}

c.processStdin = nil

select {

case <-c.processDone:

c.logDebugTiming(processExitStart, "CopilotClient.Stop CLI process exited gracefully")

c.osProcess.Store(nil)

c.process = nil

case <-time.After(processExitTimeout):

c.logDebugTiming(processExitStart, "CopilotClient.Stop CLI process exit timed out; killing process")

}

}

if c.process != nil && !c.isExternalServer {

if err := c.killProcessAndWait(); err != nil {

errs = append(errs, err)

}

}

c.process = nil

// Tear down the in-process FFI host (closes the connection and shuts down the

// native runtime). No child process to reap in this mode.

if c.ffiHost != nil {

c.ffiHost.Dispose()

c.ffiHost = nil

}

// Close external TCP connection if exists

if c.isExternalServer && c.conn != nil {

if err := c.conn.Close(); err != nil {

errs = append(errs, fmt.Errorf("failed to close socket: %w", err))

}

c.conn = nil

}

// Then close JSON-RPC client (readLoop can now exit)

if c.client != nil {

c.client.Stop()

c.client = nil

}

// Clear models cache

c.modelsCacheMux.Lock()

c.modelsCache = nil

c.modelsCacheMux.Unlock()

c.state = stateDisconnected

if !c.isExternalServer {

c.actualPort = 0

}

c.RPC = nil

c.internalRPC = nil

return errors.Join(errs...)

}

func (c *Client) logDebugTiming(start time.Time, message string) {

switch strings.ToLower(c.options.LogLevel) {

case "debug", "all":

log.Printf("%s elapsed=%s", message, time.Since(start))

}

}

// 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)

//

// Event processing observes the stop signal before dispatching each remaining

// callback. Callbacks already being dispatched are not awaited and may finish

// after this method returns; an event handler can itself call ForceStop.

// Pending response waits fail when the session is retired, without waiting for

// an idle event or their context deadline.

// Registered session callbacks are released locally, including unadmitted event

// handler entries retained by a dispatch snapshot.

//

// 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 (c *Client) ForceStop() {

c.disconnectAhpHosts()

// Kill the process without waiting for startStopMux, which Start may hold.

// This unblocks any I/O Start is doing (connect, version check).

if p := c.osProcess.Swap(nil); p != nil {

p.Kill()

}

// Clear sessions immediately without trying to destroy them

c.sessionsMux.Lock()

sessions := make([]*Session, 0, len(c.sessions))

for _, session := range c.sessions {

sessions = append(sessions, session)

}

c.sessions = make(map[string]*Session)

c.sessionsMux.Unlock()

for _, session := range sessions {

session.clearSkillProvider()

session.cancelPendingExternalTools()

session.stopEventProcessing()

}

c.clearGitHubTokenProviders()

c.closeCopilotRequestAdapter()

c.closeInstallationConfirmationAdapter()

c.startStopMux.Lock()

defer c.startStopMux.Unlock()

// Kill CLI process (only if we spawned it)

// This is a fallback in case the process wasn't killed above (e.g. if Start hadn't set

// osProcess yet), or if the process was restarted and osProcess now points to a new process.

if c.process != nil && !c.isExternalServer {

_ = c.killProcess() // Ignore errors since we're force stopping

}

c.process = nil

// Dispose the in-process FFI host (if any) without waiting on graceful shutdown.

if c.ffiHost != nil {

c.ffiHost.Dispose()

c.ffiHost = nil

}

// Close external TCP connection if exists

if c.isExternalServer && c.conn != nil {

_ = c.conn.Close() // Ignore errors

c.conn = nil

}

// Close JSON-RPC client

if c.client != nil {

c.client.Stop()

c.client = nil

}

// Clear models cache

c.modelsCacheMux.Lock()

c.modelsCache = nil

c.modelsCacheMux.Unlock()

c.state = stateDisconnected

if !c.isExternalServer {

c.actualPort = 0

}

c.RPC = nil

c.internalRPC = nil

}

func (c *Client) ensureConnected(ctx context.Context) error {

if c.client != nil {

return nil

}

return c.Start(ctx)

}

// 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, this will automatically start the runtime.

//

// The config parameter is optional. If no OnPermissionRequest handler is provided,

// permission requests are surfaced as events for the caller to resolve manually.

//

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

//

// Example:

//

// // Basic session

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

//

// // 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,

// },

// },

// })

//

// extractTransformCallbacks separates transform callbacks from a SystemMessageConfig,

// returning a wire-safe config and a map of callbacks (nil if none).

func extractTransformCallbacks(config *SystemMessageConfig) (*SystemMessageConfig, map[string]SectionTransformFn) {

if config == nil || config.Mode != "customize" || len(config.Sections) == 0 {

return config, nil

}

callbacks := make(map[string]SectionTransformFn)

wireSections := make(map[string]SectionOverride)

for id, override := range config.Sections {

if override.Transform != nil {

callbacks[id] = override.Transform

wireSections[id] = SectionOverride{Action: "transform"}

} else {

wireSections[id] = override

}

}

if len(callbacks) == 0 {

return config, nil

}

wireConfig := &SystemMessageConfig{

Mode: config.Mode,

Content: config.Content,

Sections: wireSections,

}

return wireConfig, callbacks

}

func hasManagedSettings(enableManagedSettings *bool, managedSettings *ManagedSettings) bool {

return (enableManagedSettings != nil && *enableManagedSettings) || managedSettings != nil

}

func validateAskUserVariant(variant AskUserVariant) error {

if variant != "" && variant != AskUserVariantLegacy && variant != AskUserVariantElicitation {

return fmt.Errorf("invalid AskUserVariant %q: expected %q, %q, or unset", variant, AskUserVariantLegacy, AskUserVariantElicitation)

}

return nil

}

func (c *Client) CreateSession(ctx context.Context, config *SessionConfig) (*Session, error) {

return c.createSession(ctx, config, nil)

}

// CreateSessionWithMCPAuthRuntimeRefresh creates a session using the opt-in MCP

// auth handler instead of config.OnMCPAuthRequest. A nil handler uses the legacy

// callback. All other options and session lifecycle behavior match CreateSession.

func (c *Client) CreateSessionWithMCPAuthRuntimeRefresh(ctx context.Context, config *SessionConfig, handler MCPAuthRuntimeRefreshHandler) (*Session, error) {

return c.createSession(ctx, config, handler)

}

func (c *Client) createSession(ctx context.Context, config *SessionConfig, runtimeRefreshHandler MCPAuthRuntimeRefreshHandler) (*Session, error) {

if config == nil {

config = &SessionConfig{}

}

if config.Cloud != nil && config.SkillProvider != nil {

return nil, cloudSkillProviderError{}

}

if config.GitHubToken != "" && config.GitHubTokenProvider != nil {

return nil, fmt.Errorf("GitHubToken and GitHubTokenProvider cannot be used together")

}

if err := validateAskUserVariant(config.AskUserVariant); err != nil {

return nil, err

}

if trust := config.TrustWorkingDirectory; trust != "" && trust != WorkingDirectoryTrustSession && trust != WorkingDirectoryTrustUser {

return nil, fmt.Errorf("invalid TrustWorkingDirectory %q: expected %q, %q, or unset", trust, WorkingDirectoryTrustSession, WorkingDirectoryTrustUser)

}

if err := c.ensureConnected(ctx); err != nil {

return nil, err

}

c.applyConfigDefaultsForMode(config)

registrationID := c.registerGitHubTokenProvider(config.GitHubTokenProvider)

registrationTransferred := false

defer func() {

if !registrationTransferred {

c.unregisterGitHubTokenProvider(registrationID)

}

}()

req := createSessionRequest{}

req.Model = config.Model

req.ClientName = config.ClientName

req.ReasoningEffort = config.ReasoningEffort

req.ReasoningSummary = config.ReasoningSummary

req.ContextTier = config.ContextTier

req.ConfigDir = config.ConfigDirectory

req.EnableConfigDiscovery = config.EnableConfigDiscovery

req.TrustWorkingDirectory = string(config.TrustWorkingDirectory)

req.SkipEmbeddingRetrieval = config.SkipEmbeddingRetrieval

req.EmbeddingCacheStorage = config.EmbeddingCacheStorage

req.OrganizationCustomInstructions = config.OrganizationCustomInstructions

req.EnableOnDemandInstructionDiscovery = config.EnableOnDemandInstructionDiscovery

req.EnableFileHooks = config.EnableFileHooks

req.EnableHostGitOperations = config.EnableHostGitOperations

req.EnableSessionStore = config.EnableSessionStore

req.EnableSkills = config.EnableSkills

if config.SkillProvider != nil {

req.HasSkillProvider = Bool(true)

}

req.Tools = config.Tools

systemMessage := c.systemMessageForMode(config.SystemMessage)

wireSystemMessage, transformCallbacks := extractTransformCallbacks(systemMessage)

req.SystemMessage = wireSystemMessage

availableTools, excludedTools, precedence, ferr := c.resolveToolFilterOptions(config.AvailableTools, config.ExcludedTools)

if ferr != nil {

return nil, ferr

}

req.AvailableTools = availableTools

req.ExcludedTools = excludedTools

req.ToolFilterPrecedence = precedence

req.ExcludedBuiltInAgents = config.ExcludedBuiltInAgents

req.Provider = config.Provider

req.Capi = config.Capi

req.Providers = config.Providers

req.Models = config.Models

req.AskUserVariant = config.AskUserVariant

req.EnableSessionTelemetry = config.EnableSessionTelemetry

req.EnableCitations = config.EnableCitations

req.EnableFileChangeTracking = config.EnableFileChangeTracking

req.SessionLimits = config.SessionLimits

req.Autopilot = config.Autopilot

req.IsExperimentalMode = config.EnableExperimentalMode

req.SkipCustomInstructions = config.SkipCustomInstructions

req.RefreshCustomInstructions = config.RefreshCustomInstructions

req.CustomAgentsLocalOnly = config.CustomAgentsLocalOnly

req.CoauthorEnabled = config.CoauthorEnabled

req.ManageScheduleEnabled = config.ManageScheduleEnabled

req.ModelCapabilities = config.ModelCapabilities

req.WorkingDirectory = config.WorkingDirectory

req.AdditionalDirectories = config.AdditionalDirectories

req.MCPServers = config.MCPServers

req.Diagnostics = config.Diagnostics

req.MCPOAuthTokenStorage = config.MCPOAuthTokenStorage

req.AuthClientIDMetadataURL = config.AuthClientIDMetadataURL

req.EnvValueMode = "direct"

req.CustomAgents = config.CustomAgents

req.DefaultAgent = config.DefaultAgent

req.Agent = config.Agent

req.SkillDirectories = config.SkillDirectories