codexbridge

Documentation

Overview

Package codexbridge carries Intercom tool calls from a Codex MCP helper to the controller process that owns the Intercom broker connection.

The bridge is deliberately private and small: one authenticated JSON frame is exchanged per Unix-socket connection. It does not connect to the broker.

Index

• Constants
• Variables
• func GenerateToken() (string, error)
• func RunHelper(ctx context.Context, opts HelperOptions) error
• type Client
  • func NewClient(opts ClientOptions) (*Client, error)
  • func (c *Client) ListPeers(ctx context.Context, metadata json.RawMessage) ([]string, error)
  • func (c *Client) Ping(ctx context.Context) error
  • func (c *Client) SendMessage(ctx context.Context, metadata json.RawMessage, to, message string) (wire.SendAck, error)
• type ClientOptions
• type Controller
  • func Listen(parent context.Context, opts Options) (*Controller, error)
  • func (c *Controller) Close() error
  • func (c *Controller) Done() <-chan struct{}
  • func (c *Controller) SocketPath() string
• type Handler
• type HandlerFuncs
  • func (h HandlerFuncs) ListPeers(ctx context.Context, metadata json.RawMessage) ([]string, error)
  • func (h HandlerFuncs) SendMessage(ctx context.Context, metadata json.RawMessage, to, message string) (wire.SendAck, error)
• type HelperOptions
• type Options
• type RemoteError
  • func (e *RemoteError) Error() string

Constants

const (

	// MaxFrameSize bounds both requests and responses on the private bridge.
	// It is larger than the broker frame because a bridge request also carries
	// authentication and Codex routing metadata.
	MaxFrameSize = 1 << 20
)

Variables

var (
	ErrFrameTooLarge = errors.New("codex bridge: frame too large")
)

Functions

func GenerateToken

func GenerateToken() (string, error)

GenerateToken returns a cryptographically random token suitable for Options and ClientOptions. The token must be passed to the helper through a private channel such as its environment, not written into the binding state file.

func RunHelper

func RunHelper(ctx context.Context, opts HelperOptions) error

RunHelper verifies the controller with an authenticated startup ping, then serves send_message and list_peers over MCP stdio until EOF or cancellation. It never opens an Intercom broker connection.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client makes authenticated bridge calls. It is safe for concurrent use. Each call uses a separate Unix connection, avoiding shared-stream failure and head-of-line blocking between tool calls.

func NewClient

func NewClient(opts ClientOptions) (*Client, error)

func (*Client) ListPeers

func (c *Client) ListPeers(ctx context.Context, metadata json.RawMessage) ([]string, error)

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

func (*Client) SendMessage

func (c *Client) SendMessage(ctx context.Context, metadata json.RawMessage, to, message string) (wire.SendAck, error)

type ClientOptions

type ClientOptions struct {
	SocketPath string
	Token      string
	Timeout    time.Duration
}

ClientOptions configures calls from the MCP helper to a Controller.

type Controller

type Controller struct {
	// contains filtered or unexported fields
}

Controller owns the private Unix listener. Listen starts its accept loop; Close stops it, waits for active calls, and removes the socket.

func Listen

func Listen(parent context.Context, opts Options) (*Controller, error)

Listen validates the private parent directory, creates SocketPath with mode 0600, and begins serving. The immediate parent must be a real mode-0700 directory owned by the current effective user.

func (*Controller) Close

func (c *Controller) Close() error

Close stops the controller. It is safe to call concurrently.

func (*Controller) Done

func (c *Controller) Done() <-chan struct{}

Done closes after the accept loop and all active handlers have exited.

func (*Controller) SocketPath

func (c *Controller) SocketPath() string

SocketPath returns the canonical path owned by the controller.

type Handler

type Handler interface {
	SendMessage(ctx context.Context, metadata json.RawMessage, to, message string) (wire.SendAck, error)
	ListPeers(ctx context.Context, metadata json.RawMessage) ([]string, error)
}

Handler is implemented by the controller that owns the broker connection. metadata is the raw tools/call _meta value supplied by Codex. It is nil when _meta was absent and contains "null" when Codex explicitly supplied null.

type HandlerFuncs

type HandlerFuncs struct {
	SendMessageFunc func(context.Context, json.RawMessage, string, string) (wire.SendAck, error)
	ListPeersFunc   func(context.Context, json.RawMessage) ([]string, error)
}

HandlerFuncs adapts functions to Handler.

func (HandlerFuncs) ListPeers

func (h HandlerFuncs) ListPeers(ctx context.Context, metadata json.RawMessage) ([]string, error)

func (HandlerFuncs) SendMessage

func (h HandlerFuncs) SendMessage(ctx context.Context, metadata json.RawMessage, to, message string) (wire.SendAck, error)

type HelperOptions

type HelperOptions struct {
	SocketPath string
	Token      string
	Version    string
	Timeout    time.Duration
	Stdin      io.Reader
	Stdout     io.Writer
}

HelperOptions configures the stdio MCP process injected into an adopted Codex session.

type Options

type Options struct {
	SocketPath     string
	Token          string
	Handler        Handler
	RequestTimeout time.Duration
	MaxConcurrent  int
}

Options configures a controller-side bridge listener.

type RemoteError

type RemoteError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

RemoteError is a controller-side failure returned over the private bridge.

func (*RemoteError) Error

func (e *RemoteError) Error() string