bridge

package
v3.3.1 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package bridge is "mai mcp": it gets a lease for an agent and bridges the MCP stdio of an app to POST /mcp of the server.

The bridge holds the pool lease of the agent, and one lease for each named session of its chats. A chat gives the label or the login of its session as the argument session of each tool call, for example lane-1. The first call with the label gets the lease of that session, as the tool login does. The tool login is optional: it gets the lease and gives a handle, which a chat can give as session in place of the label. The bridge removes the argument and sends the call with the lease of that session. A tool call with no argument session uses the pool lease.

When a lease ends on the server, the bridge asks for a new lease. Only a refusal of the server (an HTTP 4xx answer with an error code) ends a named session in the bridge. A server error, an answer with no code, or a network error keeps the session, and the next call or heartbeat tries again.

Each lease token is only in the memory of the bridge. It is never in a file, an argument, or the environment. Stdout carries only JSON-RPC lines. Logs go to stderr.

Index

Constants

View Source
const (
	ExitOK    = 0
	ExitError = 1
)

Exit codes of Run.

Variables

This section is empty.

Functions

func OutputClosed added in v3.2.0

func OutputClosed(f *os.File) bool

OutputClosed tells if the read end of the pipe or of the socket of f is closed. Then no process can read what the bridge writes to f. For such a file, poll gives POLLHUP on macOS and POLLERR or POLLHUP on Linux. A file that is not open gives POLLNVAL. OutputClosed does not change the mode of f.

Types

type Bridge

type Bridge struct {
	Agent    string
	Instance string
	Endpoint string    // The base URL of the server, for example http://127.0.0.1:8765.
	Keys     KeySource // The bridge reads the agent key at each lease request.
	Client   *http.Client
	StateDir string
	App      string // The app at the top of the process chain.
	AppPID   int    // The parent PID of the bridge. The notice file has this PID in its name.
	PID      int    // The PID of the bridge.
	Folder   string
	Stdin    io.Reader
	Stdout   io.Writer
	Stderr   io.Writer
	// AppGone tells if the app is gone, for example because its process ended, or because it
	// closed the read end of the standard output. After the end of the standard input, the
	// bridge then stops the requests in flight at once, because nothing can read their
	// answers. nil means that the bridge cannot tell. Then it waits a maximum of drainTimeout
	// for these answers.
	AppGone func() bool
	// contains filtered or unexported fields
}

Bridge holds the state of one bridge process. Set the exported fields, then call Run.

func (*Bridge) Run

func (b *Bridge) Run(ctx context.Context) int

Run gets the pool lease, bridges stdin to /mcp until stdin ends, a write to stdout fails, or ctx ends, and then ends each lease of the bridge. After the end of stdin, each request in flight gets its answer, for a maximum of drainTimeout, unless the app is gone (drain). Cancel ctx on SIGINT, SIGTERM, or SIGHUP. A failed write to stdout or stderr must not stop the process, thus ignore SIGPIPE.

The pool lease can have no session, when no pool session of the agent is free. The bridge then serves the requests that use no session and the named sessions. When the start gets no lease, Run stops. After the start, only an agent key that is not valid stops Run.

type Config

type Config struct {
	Instance string `json:"instance"`
	Port     int    `json:"port"`
	Image    string `json:"image"`
	DataDir  string `json:"data_dir"`
}

Config is the part of the CLI configuration file that the bridge and the hook use. When the file or a field is not there, the default value applies.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig is the configuration when the file has no value.

func LoadConfig

func LoadConfig(configDir string) (Config, error)

LoadConfig reads <configDir>/config.json.

func (Config) Endpoint

func (c Config) Endpoint() string

Endpoint is the base URL of the HTTP API of the server.

type KeySource added in v3.2.0

type KeySource interface {
	Get(account string) (string, error)
}

KeySource gives the key of an account. The key file of the CLI (keys.File) is one.

Jump to

Keyboard shortcuts

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