Documentation
¶
Overview ¶
Package bridge borrows a client's MCP connections for the runner.
A bridge holds no credential and reads no configuration. It asks the client, over the client's own control channel, what tools it has and asks it to call one. How each client is reached, what it names things and how it spells an annotation is code in this package; what the user has connected is always discovered live.
Every bridge is a stand-in. It is deleted when its client can run a primitive itself.
Index ¶
- func ClaudeExecutable() (string, error)
- func FindSessionRelay(wd string) (string, error)
- func GeminiRules(files ...string) func(bind.Tool) (denied bool)
- func IsNoSessionRelay(err error) bool
- func Tested(name, version string) bool
- type Asker
- type Bridge
- type Claude
- func (c *Claude) Asks(t bind.Tool) (bool, error)
- func (c *Claude) AwaitLateServers(d time.Duration) bool
- func (c *Claude) Call(t bind.Tool, args map[string]any) (string, error)
- func (c *Claude) Client() (string, string)
- func (c *Claude) Close()
- func (c *Claude) Denied(t bind.Tool) (bool, error)
- func (c *Claude) HasSchemas() bool
- func (c *Claude) Inventory() ([]bind.Tool, error)
- type Codex
- func (c *Codex) Asks(t bind.Tool) (bool, error)
- func (c *Codex) Call(t bind.Tool, args map[string]any) (string, error)
- func (c *Codex) Client() (string, string)
- func (c *Codex) Close()
- func (c *Codex) Denied(t bind.Tool) (bool, error)
- func (c *Codex) HasSchemas() bool
- func (c *Codex) Inventory() ([]bind.Tool, error)
- func (c *Codex) OperationDenied(t bind.Tool) (bool, error)
- type ConfigBridge
- func (b *ConfigBridge) Blocked() map[string]string
- func (b *ConfigBridge) Call(t bind.Tool, args map[string]any) (string, error)
- func (b *ConfigBridge) Client() (string, string)
- func (b *ConfigBridge) Close()
- func (b *ConfigBridge) Denied(bind.Tool) (bool, error)
- func (b *ConfigBridge) HasSchemas() bool
- func (b *ConfigBridge) Inventory() ([]bind.Tool, error)
- type Configured
- type ConfiguredServer
- type Copilot
- type Goose
- type Kilo
- func (k *Kilo) Call(t bind.Tool, args map[string]any) (string, error)
- func (k *Kilo) Client() (string, string)
- func (k *Kilo) Close()
- func (k *Kilo) ConfiguredServers() ([]ConfiguredServer, error)
- func (k *Kilo) Denied(t bind.Tool) (bool, error)
- func (k *Kilo) HasSchemas() bool
- func (k *Kilo) Inventory() ([]bind.Tool, error)
- func (k *Kilo) UsePins(tools []bind.Tool)
- type LateServers
- type MCP
- type OperationDenier
- type PinnedOnly
- type Proc
- type SessionRelay
- func (r *SessionRelay) Call(t bind.Tool, args map[string]any) (string, error)
- func (r *SessionRelay) Client() (string, string)
- func (r *SessionRelay) Close()
- func (r *SessionRelay) ConfiguredServers() ([]ConfiguredServer, error)
- func (r *SessionRelay) Denied(t bind.Tool) (bool, error)
- func (r *SessionRelay) HasSchemas() bool
- func (r *SessionRelay) Inventory() ([]bind.Tool, error)
- type VSCode
- func (v *VSCode) Asks(t bind.Tool) (bool, error)
- func (v *VSCode) Call(t bind.Tool, args map[string]any) (string, error)
- func (v *VSCode) Client() (string, string)
- func (v *VSCode) Close()
- func (v *VSCode) Denied(bind.Tool) (bool, error)
- func (v *VSCode) HasSchemas() bool
- func (v *VSCode) Inventory() ([]bind.Tool, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ClaudeExecutable ¶
ClaudeExecutable returns the Claude Code executable TAP should use. It prefers the native per-user install and falls back to PATH, matching the bridge's control-channel launcher.
func FindSessionRelay ¶ added in v0.2.19
FindSessionRelay returns the socket of the relay in the session that started this runner: the relay whose process is one of this process's ancestors, else one whose session directory is the runner's working directory. The directory and socket must belong to this user and be private to them.
func GeminiRules ¶
GeminiRules reads the tool rules of Gemini CLI from the user's settings and from the project's, the project's adding to the user's.
func IsNoSessionRelay ¶ added in v0.2.19
IsNoSessionRelay says the error is that no relay was found.
Types ¶
type Asker ¶
Asker is implemented by a bridge that can read the person's own "ask me first" rule for a tool. The runner then puts a call to that tool in front of them even when the primitive declares it a read.
type Bridge ¶
type Bridge interface {
// Client names the client and its version, as the client reports them.
Client() (name, version string)
// Inventory lists every tool the client can dispatch.
Inventory() ([]bind.Tool, error)
// Denied reports whether the user has forbidden their client to use a
// tool. The runner refuses such a tool.
Denied(t bind.Tool) (bool, error)
// Call dispatches one tool through the client's own session and returns
// its result as text.
Call(t bind.Tool, args map[string]any) (string, error)
// HasSchemas reports whether the client gives tool input schemas, so the
// receipt can say whether a contract could have been checked.
HasSchemas() bool
Close()
}
type Claude ¶
type Claude struct {
// contains filtered or unexported fields
}
Claude reaches Claude Code through the control channel of its stream-json input. Control requests start no model turn. The channel is undocumented.
func NewClaude ¶
NewClaude starts a second copy of Claude Code. extra is passed to it and exists for tests.
func NewClaudeIn ¶ added in v0.2.14
NewClaudeIn starts Claude Code in a session's directory and environment.
func (*Claude) Asks ¶
Asks reports whether the user has an "ask" rule for the tool: Claude Code would stop and ask them before using it.
func (*Claude) AwaitLateServers ¶ added in v0.1.21
AwaitLateServers waits for the claude.ai connectors. Claude Code fetches them from the account after it starts answering, so an early mcp_status can list only local servers. It returns once a claude.ai server is listed and none is pending, or at d; true means the inventory is worth reading again.
func (*Claude) HasSchemas ¶
type Codex ¶
type Codex struct {
// contains filtered or unexported fields
}
Codex reaches Codex through its app-server protocol, the interface its own desktop app uses. Codex marks it experimental.
func NewCodexIn ¶ added in v0.2.14
NewCodexIn starts Codex's app-server in a session's directory and environment.
func (*Codex) Denied ¶
Denied reports whether the user's Codex configuration switches the tool off: its server is disabled, it is not in the server's enabled_tools, or it is in disabled_tools.
func (*Codex) HasSchemas ¶
type ConfigBridge ¶ added in v0.2.19
type ConfigBridge struct {
// contains filtered or unexported fields
}
ConfigBridge reaches a client that offers no way for another program to run its tools (Crush, Cursor) by opening the runner's own connection to each MCP server in the client's own configuration. It changes nothing in the client and holds no credentials: a server whose entry carries a secret (environment values or headers) is not used, nor is one that needs a sign-in the client stored, nor one the person has not approved in the client. Each is reported as blocked, naming what it needs.
func NewConfigBridgeIn ¶ added in v0.2.19
func NewConfigBridgeIn(client string, p Proc) (*ConfigBridge, error)
NewConfigBridgeIn reads client's MCP configuration ("crush", "cursor") as the client resolves it for the session's directory.
func (*ConfigBridge) Blocked ¶ added in v0.2.19
func (b *ConfigBridge) Blocked() map[string]string
Blocked names each configured server the bridge does not use, and why.
func (*ConfigBridge) Call ¶ added in v0.2.19
Call runs one tool on the runner's connection to its server.
func (*ConfigBridge) Client ¶ added in v0.2.19
func (b *ConfigBridge) Client() (string, string)
func (*ConfigBridge) Close ¶ added in v0.2.19
func (b *ConfigBridge) Close()
func (*ConfigBridge) Denied ¶ added in v0.2.19
func (b *ConfigBridge) Denied(bind.Tool) (bool, error)
Denied is false: a server the person disabled or did not approve is not connected at all, so its tools are never offered.
func (*ConfigBridge) HasSchemas ¶ added in v0.2.19
func (b *ConfigBridge) HasSchemas() bool
type Configured ¶ added in v0.2.19
type Configured interface {
ConfiguredServers() ([]ConfiguredServer, error)
}
Configured is a bridge that can say which MCP servers its client is configured with, without listing their tools.
type ConfiguredServer ¶ added in v0.2.19
type ConfiguredServer struct {
Name string
Type string // local, remote, stdio, http, as the client spells it
Command string // the command and its arguments, joined by spaces
URL string
// Connected is the client's own report that the server is connected.
// StatusKnown is false when the client reports nothing about it, as
// Gemini CLI does: a configured server is then all that can be said.
Connected bool
StatusKnown bool
}
ConfiguredServer is one MCP server a client is configured with, as the client's own configuration names it. The runner reads it to find which servers may fill a capability on a client that does not list its tools. Nothing here is a credential: headers, environment and tokens are left where they are.
func GeminiServers ¶ added in v0.2.19
func GeminiServers(files ...string) []ConfiguredServer
GeminiServers reads the MCP servers from Gemini CLI's settings files, the user's and the project's, a later file overriding an earlier one by name. Gemini reports no connection status, so StatusKnown is false.
type Copilot ¶ added in v0.2.19
type Copilot struct {
// contains filtered or unexported fields
}
Copilot reaches GitHub Copilot CLI through its headless JSON-RPC server (`copilot --headless --stdio`, the protocol GitHub's Copilot SDK speaks). A session started there lists the MCP tools the person connected (session.tools.getCurrentMetadata) and runs one through Copilot's own invocation pipeline (session.tools.execute), with no model turn, using Copilot's own connection to the server.
Copilot applies the person's own permission rules to each call: a tool they denied is refused by Copilot. When Copilot would ask, it asks this client (permission.requested); the bridge approves only the call the runner is making at that moment, which the runner's effect gate has already let through, and rejects anything else.
func NewCopilot ¶ added in v0.2.19
func NewCopilotIn ¶ added in v0.2.19
NewCopilotIn starts Copilot CLI's headless server in a session's directory and environment, so it reads the same configuration as the person's Copilot.
func (*Copilot) Call ¶ added in v0.2.19
Call runs one tool through the session. A result Copilot reports as a failure or a refusal is returned as an error.
func (*Copilot) Close ¶ added in v0.2.19
func (c *Copilot) Close()
Close lets Copilot exit on its own, then stops everything it started and waits until it has: Copilot writes session state as it exits, and its MCP servers outlive it unless stopped.
func (*Copilot) Denied ¶ added in v0.2.19
Denied is answered by Copilot itself when the call is made: a tool the person denied comes back refused.
func (*Copilot) HasSchemas ¶ added in v0.2.19
type Goose ¶
type Goose struct {
// contains filtered or unexported fields
}
Goose reaches Goose through ACP (`goose acp`), with Goose's own custom requests: _goose/unstable/tools/list lists a session's extension tools and _goose/unstable/tools/call runs one through Goose's extension manager, with no model turn. Goose marks both unstable.
Goose runs an app tool call only in auto mode, so the bridge's session is put in auto mode and Goose shows no approval of its own: the runner's effect gate is the only approval. A tool the user set to never_allow is denied.
func NewGooseIn ¶ added in v0.2.14
NewGooseIn starts goose in a session's directory and environment.
func (*Goose) Call ¶
Call runs one extension tool through Goose. A result Goose marks isError is returned as an error, so a failure is never read back as output.
func (*Goose) Close ¶
func (g *Goose) Close()
Close deletes the bridge's session, so it does not show in Goose's history, and stops Goose.
func (*Goose) HasSchemas ¶
type Kilo ¶
type Kilo struct {
// contains filtered or unexported fields
}
Kilo is the HTTP client for an OpenCode-family session's routes (configuration, MCP status, health, call-tool), reached through the TAP relay plugin in the person's own OpenCode or Kilo session (sessionrelay.go). The relay runs each tool on its own connection to the server, so the runner's effect gate is the only approval. A tool the person's configuration switches off (tools: {name: false}) or denies (permission: {name: "deny"}) is denied.
On its own Kilo lists no MCP server's tools: the runner gives it the tools that may fill the primitive's declared capabilities, and those of servers the session reports connected are the inventory. SessionRelay lists them from the relay instead.
func (*Kilo) Call ¶
Call runs one MCP tool through Kilo. A result Kilo marks isError is an error, so a failure is never read back as output.
func (*Kilo) Close ¶
func (k *Kilo) Close()
Close stops the server the bridge started, and everything it started: kilo is a launcher, and the server is its child.
func (*Kilo) ConfiguredServers ¶ added in v0.2.19
func (k *Kilo) ConfiguredServers() ([]ConfiguredServer, error)
ConfiguredServers reads the servers from Kilo's own resolved configuration (GET /config, which merges the user's and the project's files) and whether each is connected (GET /mcp). Nothing is changed.
func (*Kilo) Denied ¶
Denied reports a tool the person's Kilo configuration switches off (tools: {"<server>_<tool>": false}) or denies (permission: {"<server>_<tool>": "deny"}). Keys may use * as a wildcard; the most specific matching key decides.
func (*Kilo) HasSchemas ¶
type LateServers ¶ added in v0.1.21
Bridge is the whole of what the runner needs from a client. LateServers is a Bridge whose client connects some servers after it has started answering. AwaitLateServers waits, at most d, for them to be listed and connected, and reports whether the inventory is worth reading again.
type MCP ¶
type MCP struct {
// contains filtered or unexported fields
}
MCP reaches one MCP server directly, over streamable HTTP. It is the bridge for a runner with no client to borrow from: a service that runs primitives itself hands the runner the MCP endpoint it would call and the header that authenticates it. The server decides, per call, what the caller may do; this bridge adds no policy of its own.
func NewMCPWithName ¶
NewMCPWithName opens an MCP server over streamable HTTP. connectionName, when nonempty, is the local connection alias used as bind.Tool.Server; the endpoint's advertised tool names and all wire calls remain unchanged. An empty name preserves NewMCP's serverInfo.name behavior.
func (*MCP) Call ¶
Call dispatches one tool. A result the server marks isError is returned as an error, so a refusal is never read back as the tool's output.
func (*MCP) Client ¶
Client names the protocol rather than a product: what is on the other end is whatever MCP server the caller pointed at.
func (*MCP) Close ¶
func (m *MCP) Close()
Close ends the session. A server that does not support ending sessions answers 405, which is not an error.
func (*MCP) Denied ¶
Denied always reports false. There is no user between the runner and the server to have forbidden anything; the server refuses what it will not do.
func (*MCP) HasSchemas ¶
type OperationDenier ¶ added in v0.2.8
OperationDenier checks an advertised operation behind an allowed dispatcher. A client's allow list names callable MCP tools, not the dispatcher's hidden operations. Explicit operation denials still apply; transport allow lists are checked separately on the actual catalog and dispatch tools.
type PinnedOnly ¶
PinnedOnly is a bridge whose client cannot list its tools: the runner gives it the tools a primitive pins or that it resolved for the primitive's capabilities, and only those can bind.
type Proc ¶ added in v0.2.14
type Proc struct {
Dir string
Env []string // KEY=value; nil means the runner's own environment
// ToolMeta is the host-supplied context of this MCP call, distinct from
// model arguments. It is forwarded only for this run, never persisted as
// bridge authority or shared between requests.
ToolMeta json.RawMessage
}
Proc is where a bridge starts its client's program: the working directory and environment of the agent session it serves. One runner can serve many sessions at once, each started in its own project with its own environment, so these cannot come from the runner's own process. The zero value uses the runner's own.
type SessionRelay ¶ added in v0.2.19
type SessionRelay struct {
// contains filtered or unexported fields
}
SessionRelay reaches the person's running OpenCode or Kilo through the TAP relay plugin in its session. It lists every tool of the servers the session configured, with the annotations and schemas the servers give (the relay connects to each server itself), and calls one through the relay. The person's tool switches and permission rules in the session's configuration are honoured as the Kilo bridge honours them.
func NewSessionRelay ¶ added in v0.2.19
func NewSessionRelay(client string, p Proc) (*SessionRelay, error)
NewSessionRelay finds the relay in the session that started this runner. client is "kilo" or "opencode".
func (*SessionRelay) Call ¶ added in v0.2.19
Call runs one tool through the relay's connection to the server.
func (*SessionRelay) Client ¶ added in v0.2.19
func (r *SessionRelay) Client() (string, string)
func (*SessionRelay) Close ¶ added in v0.2.19
func (r *SessionRelay) Close()
func (*SessionRelay) ConfiguredServers ¶ added in v0.2.19
func (r *SessionRelay) ConfiguredServers() ([]ConfiguredServer, error)
ConfiguredServers is the session's configured servers.
func (*SessionRelay) Denied ¶ added in v0.2.19
func (r *SessionRelay) Denied(t bind.Tool) (bool, error)
Denied applies the session's own tool switches and permission rules.
func (*SessionRelay) HasSchemas ¶ added in v0.2.19
func (r *SessionRelay) HasSchemas() bool
type VSCode ¶
type VSCode struct {
// contains filtered or unexported fields
}
VSCode reaches Visual Studio Code, and so GitHub Copilot's tools, through the TAP extension (vscode/ in this repository). The extension starts this runner as an MCP server and gives it a private local socket; over it the runner lists the editor's language model tools, the MCP servers the user connected included, and calls them with vscode.lm.invokeTool. The editor makes each call with its own connection. Such a call carries no chat invocation token, so VS Code does not show it in the chat: a tool that asks for confirmation puts up a modal dialog instead, which cancellation does not close. The runner therefore asks the person itself, with an MCP elicitation that VS Code shows in the chat that called tap_run.
func (*VSCode) Asks ¶
Asks reports whether the user's chat.tools.eligibleForAutoApproval setting lists the tool as false, which makes VS Code ask them before every use.
func (*VSCode) Denied ¶
Denied reports false: VS Code gives an extension no way to read which tools the user has switched off in the chat tools picker.