bridge

Documentation

Overview

Package bridge provides shared infrastructure for JSON-line bridge harnesses. Both the ohmypi and claudeagent adapters embed BridgeSession to avoid duplicating subprocess lifecycle, event reading, and log rotation logic.

Index

• func BridgeCandidates(configured, executablePath, bridgeName string) []string
• func BuildSandboxCmd(ctx context.Context, rt BridgeRuntime, ...) (*exec.Cmd, string, error)
• func CleanupOldSegments(logDir, sessionID string)
• func CompressFile(src, dst string) error
• func DedupePaths(paths []string) []string
• func EnsureBridgeDependencies(rt BridgeRuntime, depSubpath, bridgeLabel string) error
• func EscapeSandboxPath(path string) string
• func FirstNonEmpty(values ...string) string
• func IsBridgeScript(path string) bool
• func MapBridgeEvent(raw struct{ ... }) (*adapter.AgentEvent, error)
• func ResolveBunExecutable(configured string) (string, error)
• type BridgeMsg
• type BridgeRuntime
  • func ResolveBridgeRuntime(configured, bridgeName, notFoundLabel string) (BridgeRuntime, error)
  • func ResolveBridgeRuntimeFrom(configured, executablePath, bridgeName, notFoundLabel string) (BridgeRuntime, error)
  • func (r BridgeRuntime) LaunchDir(workDir string) string
• type BridgeSession
  • func NewBridgeSession(id string, mode adapter.SessionMode) *BridgeSession
  • func (s *BridgeSession) Abort(_ context.Context) error
  • func (s *BridgeSession) CloseEvents()
  • func (s *BridgeSession) CloseLogAndCompress()
  • func (s *BridgeSession) Compact(_ context.Context) error
  • func (s *BridgeSession) EventsChan() <-chan adapter.AgentEvent
  • func (s *BridgeSession) SendAnswer(_ context.Context, answer string) error
  • func (s *BridgeSession) SendBridgeMsg(msgType, text string) error
  • func (s *BridgeSession) SendMessage(_ context.Context, msg string) error
  • func (s *BridgeSession) SendPrompt(text string) error
  • func (s *BridgeSession) StartReaders()
  • func (s *BridgeSession) Steer(_ context.Context, msg string) error
  • func (s *BridgeSession) Wait(ctx context.Context) error
  • func (s *BridgeSession) WriteRawMsg(data []byte) error
• type SessionMetaFunc

Functions

func BridgeCandidates

func BridgeCandidates(configured, executablePath, bridgeName string) []string

BridgeCandidates returns candidate bridge paths to search, in priority order. bridgeName is the filename stem used in default candidate paths.

func BuildSandboxCmd

func BuildSandboxCmd(ctx context.Context, rt BridgeRuntime, workDir, bunPath, bunCacheDir, homeDirName string) (*exec.Cmd, string, error)

BuildSandboxCmd constructs a sandboxed command for the bridge subprocess. homeDirName is the config directory name (e.g. ".claude" or ".omp"). Returns the command, the created temp directory path, and any error.

func CleanupOldSegments

func CleanupOldSegments(logDir, sessionID string)

CleanupOldSegments removes old compressed segments, keeping max 5.

func CompressFile

func CompressFile(src, dst string) error

CompressFile compresses src to dst using gzip, then removes src. No defers are used to prevent double-close on the happy path. On failure, dst is removed to avoid leaving incomplete output on disk.

func DedupePaths

func DedupePaths(paths []string) []string

DedupePaths removes duplicate and empty paths after normalizing with filepath.Clean.

func EnsureBridgeDependencies

func EnsureBridgeDependencies(rt BridgeRuntime, depSubpath, bridgeLabel string) error

EnsureBridgeDependencies checks that the bridge's npm dependencies are installed. depSubpath is the node_modules subpath to check (e.g. "@oh-my-pi/pi-coding-agent"). bridgeLabel is used in error messages (e.g. "ohmypi source bridge").

func EscapeSandboxPath

func EscapeSandboxPath(path string) string

EscapeSandboxPath escapes a path for use in a sandbox-exec profile. It replaces backslashes and double quotes to prevent profile injection.

func FirstNonEmpty

func FirstNonEmpty(values ...string) string

FirstNonEmpty returns the first non-empty string from the provided values.

func IsBridgeScript

func IsBridgeScript(path string) bool

IsBridgeScript returns true if the path has a TypeScript/JavaScript extension.

func MapBridgeEvent

func MapBridgeEvent(raw struct {
	Type  string          `json:"type"`
	Event json.RawMessage `json:"event"`
},
) (*adapter.AgentEvent, error)

MapBridgeEvent maps a bridge event envelope to an adapter.AgentEvent.

func ResolveBunExecutable

func ResolveBunExecutable(configured string) (string, error)

ResolveBunExecutable resolves the bun binary path.

Types

type BridgeMsg

type BridgeMsg struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

BridgeMsg represents a message sent to a bridge subprocess.

type BridgeRuntime

type BridgeRuntime struct {
	Path     string
	NeedsBun bool
}

BridgeRuntime describes a located bridge binary or script.

func ResolveBridgeRuntime

func ResolveBridgeRuntime(configured, bridgeName, notFoundLabel string) (BridgeRuntime, error)

ResolveBridgeRuntime locates the bridge binary relative to the substrate executable.

func ResolveBridgeRuntimeFrom

func ResolveBridgeRuntimeFrom(configured, executablePath, bridgeName, notFoundLabel string) (BridgeRuntime, error)

ResolveBridgeRuntimeFrom resolves a bridge binary from the given configuration and executable path. bridgeName is the filename used in default candidate paths (e.g. "omp-bridge" or "claude-agent-bridge"). notFoundLabel is used in error messages (e.g. "ohmypi bridge" or "claude-agent bridge").

func (BridgeRuntime) LaunchDir

func (r BridgeRuntime) LaunchDir(workDir string) string

LaunchDir returns the working directory for the bridge process.

type BridgeSession

type BridgeSession struct {
	ID      string
	Mode    adapter.SessionMode
	Cmd     *exec.Cmd
	Stdin   io.WriteCloser
	Stdout  io.Reader
	Stderr  io.Reader
	Events  chan adapter.AgentEvent
	LogFile *os.File
	LogPath string
	LogDir  string
	WorkDir string

	// TmpDir is the sandbox temp directory created for this session.
	// The session owner is responsible for calling os.RemoveAll on cleanup.
	TmpDir string

	// ParseSessionMeta is called by readEvents for each session_meta line.
	ParseSessionMeta SessionMetaFunc
	// contains filtered or unexported fields
}

BridgeSession implements the core subprocess lifecycle, event reading, and log rotation shared by all bridge-based harnesses.

Adapter-specific harnesses embed this struct and add their own fields (e.g. claudeSessionID, ompSessionFile) and accessor methods.

func NewBridgeSession

func NewBridgeSession(id string, mode adapter.SessionMode) *BridgeSession

NewBridgeSession creates a BridgeSession with initialized channels.

func (*BridgeSession) Abort

func (s *BridgeSession) Abort(_ context.Context) error

Abort terminates the agent session gracefully.

func (*BridgeSession) CloseEvents

func (s *BridgeSession) CloseEvents()

closeEvents safely closes the events channel exactly once.

func (*BridgeSession) CloseLogAndCompress

func (s *BridgeSession) CloseLogAndCompress()

CloseLogAndCompress closes the log file and starts async compression. Callers must hold s.mu.

func (*BridgeSession) Compact

func (s *BridgeSession) Compact(_ context.Context) error

Compact requests manual context compaction to free up context window space. Fire-and-forget: writes the compact message and returns immediately.

func (*BridgeSession) EventsChan

func (s *BridgeSession) EventsChan() <-chan adapter.AgentEvent

Events returns a channel emitting agent events.

func (*BridgeSession) SendAnswer

func (s *BridgeSession) SendAnswer(_ context.Context, answer string) error

SendAnswer sends an answer to resolve a pending ask_foreman tool call.

func (*BridgeSession) SendBridgeMsg

func (s *BridgeSession) SendBridgeMsg(msgType, text string) error

SendBridgeMsg marshals and sends a typed message to the bridge subprocess. This is the single shared write path — all send methods delegate here.

func (*BridgeSession) SendMessage

func (s *BridgeSession) SendMessage(_ context.Context, msg string) error

SendMessage sends a message to the running agent.

func (*BridgeSession) SendPrompt

func (s *BridgeSession) SendPrompt(text string) error

SendPrompt sends a prompt message to the bridge.

func (*BridgeSession) StartReaders

func (s *BridgeSession) StartReaders()

StartReaders launches background goroutines for reading events and stderr.

func (*BridgeSession) Steer

func (s *BridgeSession) Steer(_ context.Context, msg string) error

Steer sends a steering prompt that interrupts the agent's active streaming turn.

func (*BridgeSession) Wait

func (s *BridgeSession) Wait(ctx context.Context) error

Wait blocks until the session completes (done or error).

func (*BridgeSession) WriteRawMsg

func (s *BridgeSession) WriteRawMsg(data []byte) error

WriteRawMsg writes a pre-marshaled JSON line to the bridge subprocess. Use for protocol messages that don't fit the simple {type, text} shape (e.g. bridgeInitMsg with many fields). Callers marshal data themselves.

type SessionMetaFunc

type SessionMetaFunc func(line []byte)

SessionMetaFunc is called when readEvents encounters a top-level session_meta event. The implementer extracts adapter-specific fields (e.g. session ID, session file) from the raw JSON line.