bridge

package
v0.2.29 Latest Latest
Warning

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

Go to latest
Published: Oct 13, 2026 License: MIT Imports: 28 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func ClaudeExecutable

func ClaudeExecutable() (string, error)

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

func FindSessionRelay(wd string) (string, error)

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

func GeminiRules(files ...string) func(bind.Tool) (denied bool)

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

func IsNoSessionRelay(err error) bool

IsNoSessionRelay says the error is that no relay was found.

func Tested

func Tested(name, version string) bool

Tested reports whether this runner was run against the client version. The MCP bridge is tested against the protocol, not a product: the version it reports is the server's, so any is admitted without a warning.

Types

type Asker

type Asker interface {
	Asks(t bind.Tool) (bool, error)
}

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

func NewClaude(extra ...string) (*Claude, error)

NewClaude starts a second copy of Claude Code. extra is passed to it and exists for tests.

func NewClaudeIn added in v0.2.14

func NewClaudeIn(p Proc, extra ...string) (*Claude, error)

NewClaudeIn starts Claude Code in a session's directory and environment.

func (*Claude) Asks

func (c *Claude) Asks(t bind.Tool) (bool, error)

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

func (c *Claude) AwaitLateServers(d time.Duration) bool

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

func (c *Claude) Call(t bind.Tool, args map[string]any) (string, error)

func (*Claude) Client

func (c *Claude) Client() (string, string)

func (*Claude) Close

func (c *Claude) Close()

func (*Claude) Denied

func (c *Claude) Denied(t bind.Tool) (bool, error)

func (*Claude) HasSchemas

func (c *Claude) HasSchemas() bool

func (*Claude) Inventory

func (c *Claude) Inventory() ([]bind.Tool, error)

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 NewCodex

func NewCodex() (*Codex, error)

func NewCodexIn added in v0.2.14

func NewCodexIn(p Proc) (*Codex, error)

NewCodexIn starts Codex's app-server in a session's directory and environment.

func (*Codex) Asks

func (c *Codex) Asks(t bind.Tool) (bool, error)

Asks reports whether the user set the tool's approval_mode to "prompt".

func (*Codex) Call

func (c *Codex) Call(t bind.Tool, args map[string]any) (string, error)

func (*Codex) Client

func (c *Codex) Client() (string, string)

func (*Codex) Close

func (c *Codex) Close()

func (*Codex) Denied

func (c *Codex) Denied(t bind.Tool) (bool, error)

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

func (c *Codex) HasSchemas() bool

func (*Codex) Inventory

func (c *Codex) Inventory() ([]bind.Tool, error)

func (*Codex) OperationDenied added in v0.2.8

func (c *Codex) OperationDenied(t bind.Tool) (bool, error)

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

func (b *ConfigBridge) Call(t bind.Tool, args map[string]any) (string, error)

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

func (*ConfigBridge) Inventory added in v0.2.19

func (b *ConfigBridge) Inventory() ([]bind.Tool, error)

Inventory lists the tools of every usable server, with their annotations and schemas.

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 NewCopilot() (*Copilot, error)

func NewCopilotIn added in v0.2.19

func NewCopilotIn(p Proc) (*Copilot, error)

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

func (c *Copilot) Call(t bind.Tool, args map[string]any) (string, error)

Call runs one tool through the session. A result Copilot reports as a failure or a refusal is returned as an error.

func (*Copilot) Client added in v0.2.19

func (c *Copilot) Client() (string, string)

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

func (c *Copilot) Denied(bind.Tool) (bool, error)

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

func (c *Copilot) HasSchemas() bool

func (*Copilot) Inventory added in v0.2.19

func (c *Copilot) Inventory() ([]bind.Tool, error)

Inventory lists the tools of each MCP server the person connected, by the server's own tool names. Copilot's built-in tools (shell, file edits) are not connections and are left out, as is the TAP server itself.

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 NewGoose

func NewGoose() (*Goose, error)

func NewGooseIn added in v0.2.14

func NewGooseIn(p Proc) (*Goose, error)

NewGooseIn starts goose in a session's directory and environment.

func (*Goose) Call

func (g *Goose) Call(t bind.Tool, args map[string]any) (string, error)

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

func (g *Goose) Client() (string, string)

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

func (g *Goose) Denied(t bind.Tool) (bool, error)

Denied reports a tool the user set to never_allow in Goose.

func (*Goose) HasSchemas

func (g *Goose) HasSchemas() bool

func (*Goose) Inventory

func (g *Goose) Inventory() ([]bind.Tool, error)

Inventory lists the tools of each extension the user connected. Goose names an extension's tool <extension>__<tool>. Goose gives no annotations, so every effect is Unknown.

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

func (k *Kilo) Call(t bind.Tool, args map[string]any) (string, error)

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

func (k *Kilo) Client() (string, string)

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

func (k *Kilo) Denied(t bind.Tool) (bool, error)

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

func (k *Kilo) HasSchemas() bool

func (*Kilo) Inventory

func (k *Kilo) Inventory() ([]bind.Tool, error)

Inventory is the given tools whose server Kilo reports connected.

func (*Kilo) UsePins

func (k *Kilo) UsePins(tools []bind.Tool)

UsePins gives the bridge the tools that may fill the primitive's capabilities, with whatever the runner knows of their effects.

type LateServers added in v0.1.21

type LateServers interface {
	AwaitLateServers(d time.Duration) bool
}

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 NewMCP

func NewMCP(url string, header http.Header) (*MCP, error)

NewMCP opens a session with the server at url, sending header on every request.

func NewMCPWithName

func NewMCPWithName(url string, header http.Header, connectionName string) (*MCP, error)

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

func (m *MCP) Call(t bind.Tool, args map[string]any) (string, error)

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

func (m *MCP) Client() (string, string)

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

func (m *MCP) Denied(bind.Tool) (bool, error)

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

func (m *MCP) HasSchemas() bool

func (*MCP) Inventory

func (m *MCP) Inventory() ([]bind.Tool, error)

type OperationDenier added in v0.2.8

type OperationDenier interface {
	OperationDenied(t bind.Tool) (bool, error)
}

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

type PinnedOnly interface {
	Bridge
	UsePins(tools []bind.Tool)
}

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.

func (Proc) Environ added in v0.2.14

func (p Proc) Environ() []string

Environ is the session's environment.

func (Proc) Getenv added in v0.2.14

func (p Proc) Getenv(name string) string

Getenv reads the session's environment.

func (Proc) LookPath added in v0.2.14

func (p Proc) LookPath(name string) (string, error)

LookPath finds a program on the session's PATH.

func (Proc) Wd added in v0.2.14

func (p Proc) Wd() string

Wd is the session's working directory.

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

func (r *SessionRelay) Call(t bind.Tool, args map[string]any) (string, error)

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

func (*SessionRelay) Inventory added in v0.2.19

func (r *SessionRelay) Inventory() ([]bind.Tool, error)

Inventory lists each enabled server's tools. A server the relay could not reach is left out, and said why in the runner's log.

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 NewVSCode

func NewVSCode(socket string) (*VSCode, error)

NewVSCode connects to the extension's socket.

func (*VSCode) Asks

func (v *VSCode) Asks(t bind.Tool) (bool, error)

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

func (v *VSCode) Call(t bind.Tool, args map[string]any) (string, error)

func (*VSCode) Client

func (v *VSCode) Client() (string, string)

func (*VSCode) Close

func (v *VSCode) Close()

func (*VSCode) Denied

func (v *VSCode) Denied(bind.Tool) (bool, error)

Denied reports false: VS Code gives an extension no way to read which tools the user has switched off in the chat tools picker.

func (*VSCode) HasSchemas

func (v *VSCode) HasSchemas() bool

func (*VSCode) Inventory

func (v *VSCode) Inventory() ([]bind.Tool, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL