bridge

Documentation

Overview

Package bridge implements the bridge as a pure backend runner: the daemon hub owns all gateway I/O and feeds inputs over a control socket, the bridge runs the injected backend per turn and emits events back. The loop is model-agnostic: it never knows which backend (Claude, …) responds.

Index

• func ResolveAttachments(ctx context.Context, client *http.Client, m contracts.Message, session string, ...) []string
• func Run(ctx context.Context, newBackend BackendFactory, orch contracts.Orchestrator, ...) error
• func RunOneShot(ctx context.Context, newBackend BackendFactory, orch contracts.Orchestrator, ...) error
• func StagingRoot() string
• type BackendFactory
• type Options

Functions

func ResolveAttachments

func ResolveAttachments(ctx context.Context, client *http.Client, m contracts.Message, session string, hosts map[string]bool) []string

ResolveAttachments turns a message's attachments into local file paths a backend can reference — images to look at, PDFs and text to read. file:// attachments are validated and passed through (the gateway already staged them on local disk — e.g. the terminal TUI's clipboard paste); every other (https CDN) attachment is downloaded through the SSRF allowlist. Unsupported, oversized, missing, off-allowlist, and beyond-cap attachments are skipped so a turn is never lost over a file — but every skip is logged with its reason: an attachment that vanishes without a word is how an empty allowlist went unnoticed long enough to drop every screenshot ever sent. Order is preserved; at most maxAttachmentsPerMessage files are attempted (a candidate that fails to resolve still counts against the cap).

It is the host-side entry point (the turnloop has the Message; the bridge only sees Events), producing the paths carried in Event.Attachments.

SECURITY: a file:// attachment is a local-file read into the model context, so it is pinned to the staging root — a gateway must copy a file there before it can name it, and a path outside is refused. A gateway that forwards attachment URLs influenced by a remote author must still use https rather than staging whatever it is handed, so the SSRF allowlist applies. What a resolved file *contains* is untrusted either way: the backend is handed a path, and the text inside a document an author uploaded is that author's words, not instructions.

func Run

func Run(ctx context.Context, newBackend BackendFactory, orch contracts.Orchestrator, o Options) error

Run is the bridge entry point: a pure backend runner. It requires a hub socket (the daemon hub owns all gateway I/O) and drives the backend over it.

func RunOneShot

func RunOneShot(ctx context.Context, newBackend BackendFactory, orch contracts.Orchestrator, channel string, in <-chan contracts.Event, out chan<- contracts.Event) error

RunOneShot runs one backend turn in-process over event channels. It is the bridge seam used by the operator's short-lived session seed path: no control socket or gateway is involved, but the same backend turn machinery (including orchestrator context/observation) is exercised.

func StagingRoot

func StagingRoot() string

StagingRoot is the one tree an attachment may live in on local disk. Every gateway that hands the host a local file stages it under here, and the bridge's own downloads land here too, so "the gateway staged this file" is an invariant the core can check rather than a promise it has to take on faith. It is exported so a gateway names the same tree the core enforces instead of guessing at it.

Types

type BackendFactory

type BackendFactory func(channelID string) (contracts.Backend, error)

BackendFactory builds the model-edge backend for a resolved channel. It is injected so core stays free of any model-specific code: the binary supplies a factory closing over its chosen backend (e.g. claude.NewBackend). The channel id is passed because a backend may key its session/process on it, and the channel can be created inside Run.

type Options

type Options struct {
	Channel string
	// HubSocket selects pure-runner (hub) mode: the bridge dials this socket,
	// reads input/pick frames from the daemon hub, and emits turn events back.
	HubSocket string
	// Roster lists the agents this session may delegate to (optional). When nil or
	// empty, no delegation affordance is injected.
	Roster contracts.RosterProvider
}

Options configures one bridge run (parsed from CLI flags by the binary). In pure-runner mode the bridge only needs the channel to key its backend and the hub socket to dial; the progress level is decided host-side by the renderer.