Documentation
¶
Overview ¶
Package router routes a command to drop/host/sandbox and executes it, independent of any transport (MCP, CLI). Output is written to the caller's io.Writers.
Index ¶
- Constants
- Variables
- func Route(cmd string, allow []string, drop []DropRule) (decision, matched, message string)
- func Run(ctx context.Context, req Request) (int, error)
- func RunHost(ctx context.Context, args []string, stdin io.Reader, stdout, stderr io.Writer) (int, error)
- func RunHostShell(ctx context.Context, raw string, stdin io.Reader, stdout, stderr io.Writer) (int, error)
- type CommandRunner
- type Config
- type DropRule
- type Line
- type PipelineNode
- type Request
- type Result
- type Router
- type Segment
Constants ¶
const SandboxNotRunningHint = "command broker is not available; run Claude via `agent-sandbox claude`, which starts it automatically"
SandboxNotRunningHint is the actionable message shown when a command is routed to the sandbox but the command broker is not available. It is exported because the same situation is detected before Run is ever reached: `agent-sandbox exec` and `agent-sandbox command-router` fail to build a broker client when AGENT_SANDBOX_BROKER_SOCKET is unset, and must print this rather than a raw dial error.
Variables ¶
var ErrSandboxNotRunning = errors.New("sandbox is not running")
ErrSandboxNotRunning signals that a command was routed to the sandbox but the broker could not run it there. A CommandRunner returns it (possibly wrapped) so the router can print an actionable message instead of a raw broker error. Detect it with errors.Is.
var ErrUnterminatedQuote = errors.New("unterminated quote")
ErrUnterminatedQuote is returned by ParseLine when a quote is never closed.
Functions ¶
func Route ¶
Route decides where cmd runs. Allow is checked before drop, so a command matching both an allow and a drop pattern runs on the host. On a drop, matched is the pattern and message is the rule's custom message (empty for the default).
func Run ¶ added in v0.9.2
Run routes req.Command per segment and executes the resulting pipelines in sequence, honoring && / || / ; operators between pipelines.
Types ¶
type CommandRunner ¶ added in v0.15.0
type CommandRunner interface {
RunSandboxed(ctx context.Context, argv []string, stdin io.Reader, stdout, stderr io.Writer) (int, error)
}
CommandRunner executes an argv inside the sandbox.
type Config ¶ added in v0.9.2
type Config struct {
AllowPatterns []string
DropRules []DropRule
CommandRunner CommandRunner // nil allowed (host/drop-only lines)
}
Config holds routing patterns and the optional command runner.
type DropRule ¶ added in v0.14.3
DropRule is a drop pattern with an optional custom refusal message. An empty Message means the caller should print the default "dropped: ..." line.
type Line ¶ added in v0.9.2
type Line struct {
Raw string
Pipelines []PipelineNode
Seps []string // "&&" | "||" | ";" (len == len(Pipelines)-1)
Fallback bool
}
Line is a parsed command line: a sequence of pipelines joined by sequential operators. When Fallback is true the line contains a construct we do not split (command substitution or background &) and must run whole.
type PipelineNode ¶ added in v0.9.2
PipelineNode is a sequence of segments joined by "|".
type Request ¶ added in v0.9.2
type Request struct {
Command string
AllowPatterns []string
DropRules []DropRule
CommandRunner CommandRunner
Stdout io.Writer
Stderr io.Writer
}
Request carries everything Run needs for a single command.
type Router ¶ added in v0.9.2
type Router struct {
// contains filtered or unexported fields
}
Router routes and runs command lines.
func (*Router) NeedsSandbox ¶ added in v0.15.0
NeedsSandbox reports whether running command requires a command runner. It uses ParseLine to check each segment individually, so a pipeline with any sandbox-routed segment returns true, and a Fallback line always returns true.