Documentation
¶
Overview ¶
Package copilotbridge is the concrete ICopilotBridge over the Copilot Go SDK. It is the one place the adapter touches github.com/github/copilot-sdk/go and it cannot run without a Copilot CLI on the host, which is why the seam above it is what the specs exercise.
Index ¶
- Constants
- Variables
- func NewAgentMessagingTools(messenger IAgentMessenger, session uuid.UUID) []copilot.Tool
- type Config
- type CopilotBridge
- func (bridge *CopilotBridge) Close() error
- func (bridge *CopilotBridge) CreateSession(ctx context.Context, spec copilotadapter.BridgeSessionSpec) (copilotadapter.BridgeSession, error)
- func (bridge *CopilotBridge) ListHistorySessions(ctx context.Context, filter *copilot.SessionListFilter) ([]copilot.SessionMetadata, error)
- func (bridge *CopilotBridge) ListModels(ctx context.Context) ([]copilotadapter.BridgeModel, error)
- func (bridge *CopilotBridge) ReadHistory(ctx context.Context, filter *copilot.SessionListFilter) ([]HistorySnapshot, error)
- func (bridge *CopilotBridge) ReadSessionHistory(ctx context.Context, sessionID string) (HistorySnapshot, error)
- func (bridge *CopilotBridge) ResumeSession(ctx context.Context, spec copilotadapter.BridgeSessionSpec) (copilotadapter.BridgeSession, error)
- type HistorySnapshot
- type IAgentMessenger
- type MCPServerResolver
- type RegisterAgentInput
- type SendAgentMessageInput
- type ToolResolver
Constants ¶
const ( // RegisterAgentToolName is the session tool that names the session's agent. RegisterAgentToolName = "register_agent" // SendAgentMessageToolName is the session tool that messages another agent. SendAgentMessageToolName = "send_agent_message" )
Variables ¶
var IsolatedBuiltInToolNames = func() []copilotadapter.ToolName { names := make([]copilotadapter.ToolName, 0, len(copilot.BuiltInToolsIsolated)) for _, name := range copilot.BuiltInToolsIsolated { names = append(names, copilotadapter.ToolName(name)) } return names }()
IsolatedBuiltInToolNames is the one set of tool names the SDK exports (copilot.BuiltInToolsIsolated: the built-ins that act only inside the session, ask_user among them), re-exported typed and derived at init rather than retyped here, so it moves with the SDK version.
Functions ¶
func NewAgentMessagingTools ¶ added in v0.2.0
func NewAgentMessagingTools(messenger IAgentMessenger, session uuid.UUID) []copilot.Tool
NewAgentMessagingTools returns the agent messaging tools for one session. The session is bound here, from the bridge's own session spec, rather than read from the invocation, so a tool call can only act as the session it was configured for. The tools run in this process and reach the relay by a direct call: the in_process tier. Each call is still subject to the session's permission policy, like any other tool.
Types ¶
type Config ¶
type Config struct {
GitHubToken string
WorkingDirectory string
// HistorySourceDirectory is a read-only source tree copied into a
// wrapper-owned disposable Copilot home before the SDK starts. It is the
// only mode in which the history APIs are enabled.
HistorySourceDirectory string
Logger *slog.Logger
// ShutdownTimeout bounds process-owner cleanup after the adapter has made
// its per-session Disconnect attempts.
ShutdownTimeout time.Duration
// MCPServers are caller-owned tool transports shared by created and restored sessions.
// MCPServerResolver, when supplied, selects the transports for one durable
// session and takes precedence over this fallback map.
MCPServers map[string]copilot.MCPServerConfig
MCPServerResolver MCPServerResolver
// ToolResolver, when supplied, selects host-defined tools for one
// durable session. Their handlers run in this process, so a tool bound
// to the session (such as NewAgentMessagingTools) acts as that session
// without any credential.
ToolResolver ToolResolver
}
Config is what the binary hands New.
type CopilotBridge ¶
type CopilotBridge struct {
// contains filtered or unexported fields
}
CopilotBridge drives one Copilot CLI process for every adapter session.
func NewCopilotBridge ¶
func NewCopilotBridge(ctx context.Context, config Config) (*CopilotBridge, error)
NewCopilotBridge starts the CLI client. The CLI is spawned headless over stdio by the SDK.
func (*CopilotBridge) Close ¶
func (bridge *CopilotBridge) Close() error
Close stops the CLI process and gives every tracked Disconnect worker one final bounded drain window. Copilot SDK v1.0.11's graceful Client.Stop and Session.Disconnect both contain unbounded context.Background requests, so process ownership deliberately ends through ForceStop after the adapter has already attempted bounded per-session cleanup. If the SDK worker still does not return, Close reports the configured deadline; that worker remains counted by disconnectTracker until process exit instead of blocking shutdown.
func (*CopilotBridge) CreateSession ¶
func (bridge *CopilotBridge) CreateSession(ctx context.Context, spec copilotadapter.BridgeSessionSpec) (copilotadapter.BridgeSession, error)
CreateSession opens a CLI session and returns the data-shaped handle the adapter drives it through.
func (*CopilotBridge) ListHistorySessions ¶
func (bridge *CopilotBridge) ListHistorySessions(ctx context.Context, filter *copilot.SessionListFilter) ([]copilot.SessionMetadata, error)
ListHistorySessions returns typed metadata from the copied native history root without resuming or reading any session events. Hosts can use the SDK filter to choose IDs before calling ReadSessionHistory.
func (*CopilotBridge) ListModels ¶
func (bridge *CopilotBridge) ListModels(ctx context.Context) ([]copilotadapter.BridgeModel, error)
ListModels reports the models the CLI can use.
func (*CopilotBridge) ReadHistory ¶
func (bridge *CopilotBridge) ReadHistory(ctx context.Context, filter *copilot.SessionListFilter) ([]HistorySnapshot, error)
ReadHistory reads sessions from the bridge's explicitly configured native data root. The bridge creates that disposable copy before SDK startup: ResumeSession is the SDK's only public route to GetEvents and may update runtime metadata. No prompt is sent and no tool handler is registered while reading history.
func (*CopilotBridge) ReadSessionHistory ¶
func (bridge *CopilotBridge) ReadSessionHistory(ctx context.Context, sessionID string) (HistorySnapshot, error)
ReadSessionHistory reads one explicitly selected session from the copied native data root. It uses the SDK metadata lookup before opening the session, so callers can avoid enumerating unrelated copied sessions.
func (*CopilotBridge) ResumeSession ¶
func (bridge *CopilotBridge) ResumeSession(ctx context.Context, spec copilotadapter.BridgeSessionSpec) (copilotadapter.BridgeSession, error)
ResumeSession reconnects a persisted, nonterminal adapter session after the process restarts. The SDK receives the same model, working directory, instructions, request callbacks, and event hook as a newly created session.
type HistorySnapshot ¶
type HistorySnapshot struct {
Metadata copilot.SessionMetadata `json:"metadata"`
Events []copilot.SessionEvent `json:"events"`
}
HistorySnapshot is one copied native Copilot session and its typed event history. The SDK owns event decoding; this wrapper only associates events with the metadata used to discover the session.
type IAgentMessenger ¶ added in v0.2.0
type IAgentMessenger interface {
Attach(ctx context.Context, agent relay.AgentID, session uuid.UUID) (relay.Registration, error)
Send(ctx context.Context, session uuid.UUID, to relay.AgentID, message *agentv1.AgentMessage) (relay.Envelope[*agentv1.AgentMessage], error)
}
IAgentMessenger is the session messaging the agent tools call. *copilotadapter.SessionMessaging satisfies it.
type MCPServerResolver ¶
type MCPServerResolver func(ctx context.Context, spec copilotadapter.BridgeSessionSpec) (map[string]copilot.MCPServerConfig, error)
MCPServerResolver binds the host's MCP transports to one durable session. It keeps identity and credential policy in the composing binary instead of giving the generic Workbench adapter a dependency on a particular service.
type RegisterAgentInput ¶ added in v0.2.0
type RegisterAgentInput struct {
Agent string `json:"agent" jsonschema:"the agent identifier: lowercase letters, digits, dash or underscore, starting with a letter"`
}
RegisterAgentInput names the agent a session acts as.
type SendAgentMessageInput ¶ added in v0.2.0
type SendAgentMessageInput struct {
To string `json:"to" jsonschema:"the recipient agent's identifier"`
Message *agentv1.AgentMessage `` /* 134-byte string literal not displayed */
}
SendAgentMessageInput addresses a message to a registered agent. The message is the shared agent message contract, candace.agent.v1.AgentMessage.
type ToolResolver ¶ added in v0.2.0
type ToolResolver func(ctx context.Context, spec copilotadapter.BridgeSessionSpec) ([]copilot.Tool, error)
ToolResolver binds the host's in-process tools to one durable session.