broker

type Channel ¶

type Channel byte

Channel identifies which stream a frame belongs to.

const (
	ChanStdout Channel = 1
	ChanStderr Channel = 2
	ChanStdin  Channel = 3
	ChanExit   Channel = 4
	ChanError  Channel = 5
	// ChanStdinClose signals end-of-input; a zero-length stdin frame would be
	// ambiguous with "no bytes available yet".
	ChanStdinClose Channel = 6
)

type Client ¶

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

Client dials the broker socket. It is safe for concurrent use: every call opens its own connection, which is what lets a mixed pipeline run several sandboxed segments at once.

func NewClient(sockPath string) *Client

func NewClientFromEnv() (*Client, error)

func (c *Client) RunCommand(ctx context.Context, command string,
	stdin io.Reader, stdout, stderr io.Writer) (int, error)

type CommandRunner ¶ added in v0.17.0

type CommandRunner interface {
	RunCommand(ctx context.Context, command string, stdin io.Reader,
		stdout, stderr io.Writer) (int, error)
}

CommandRunner executes one command line inside the sandbox. The broker client is the production implementation; tests substitute their own.

type Executor ¶

type Executor interface {
	Execute(ctx context.Context, req Request, stdin io.Reader,
		stdout, stderr io.Writer) (int, error)
}

Executor runs one command line. The production implementation is ShellExecutor; tests substitute a fake so the server can be exercised without spawning anything.

type Frame ¶

type Frame struct {
	Channel Channel
	Payload []byte
}

Frame is one decoded frame.

func ReadFrame(r io.Reader) (Frame, error)

func (f Frame) ExitCode() int

type Request ¶

type Request struct {
	Command string `json:"command"`
	// Cwd is client-controlled: it comes straight from the sandboxed agent's
	// own working directory (see Client.RunCommand's workingDir helper). It
	// reaches the interpreter's Dir option and, through it, --workdir of the
	// commands the interpreter execs, but nothing in this package bounds it to
	// any particular root — see ShellExecutor.Execute for where that bound
	// actually lives.
	Cwd       string `json:"cwd"`
	WithStdin bool   `json:"with_stdin"`
}

Request is the first message on a connection: what to run and where.

It carries a command *line*, not an argv. The broker interprets the shell language itself and executes each simple command, so splitting it here would duplicate that work in the one place that cannot see the result.

There is deliberately no environment field. The command's environment is a policy decision owned by the command profile: the broker's own environment is filtered by nono before it starts, and each command's is decided by its entry. A request-supplied environment could not work — the agent's nono profile strips those variables long before they could be reported — and must not work, because the request originates inside the sandbox it would configure.

func ReadRequest(r io.Reader) (Request, error)

type Server ¶

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

Server accepts one command per connection on a unix socket. It runs in the dedicated broker process — outside the agent's own sandbox, but inside a nono session of its own — which is the point: a process cannot create a new sandbox boundary around itself, so the broker needs a boundary of its own rather than borrowing the agent's, or worse, running with the unsandboxed launcher's own reach.

That session is started by internal/claude.startCommandBroker, which runs `nono run --profile <command profile> -- agent-sandbox broker --socket <path>` (see claude.BrokerArgs) as a sibling of the agent's own sandbox, not a child of it — nono refuses to nest.

func NewServer(sockPath string, exec Executor) (*Server, error)

func (s *Server) Close() error

func (s *Server) Serve()

func (s *Server) SocketPath() string

type ShellExecutor ¶ added in v0.17.0

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

ShellExecutor runs one command line. It parses and evaluates the shell language in this process with mvdan.cc/sh and executes every simple command itself, which is what keeps each execution mediated: the broker runs inside a nono session whose command policies decide what may be executed at all, and handing the line to a real shell would hand that decision to the shell.

Everything the shell language does with the filesystem — globbing, redirects, command substitution — is performed here and is therefore bounded by the broker's own sandbox, not by the agent's.

func NewShellExecutor() *ShellExecutor

func (e *ShellExecutor) Execute(ctx context.Context, req Request,
	stdin io.Reader, stdout, stderr io.Writer) (int, error)

func (e *ShellExecutor) Run(ctx context.Context, command, cwd string,
	stdin io.Reader, stdout, stderr io.Writer) (int, error)