agent

type Access string

type Backend struct {
	// Name is the backend's identity everywhere: the value of the agent
	// setting that selects it, and the basename of the executable a
	// session of it runs. The two are one fact because Agents is procs'
	// list of executable basenames and an agent setting is one of its
	// entries.
	Name string
	// Credentials are the variables the CLI reads its provider
	// credential from. opencode and pi are authenticated through
	// whichever provider they are configured for, so their lists hold
	// one key per provider they read: any one of them is a credential,
	// and every one of them that is set is forwarded.
	Credentials []string
	// ProviderEnv are the variables the CLI is configured and
	// authenticated through, beyond the host environment every session
	// inherits: its providers' credentials and its own settings. A
	// trailing "*" is a prefix.
	ProviderEnv []string
	// ArgvMarker says whether the command line the backend's
	// implementation builds carries a marker procs finds the session by
	// in the process table. A backend without one is found through its
	// pid file alone; procs' package comment says why.
	ArgvMarker bool
	// Restricted declares whether the backend can establish
	// RunRestricted's read-only floor, and whether a restricted turn can
	// continue a session it owns. The pointer is deliberate: nil means a
	// descriptor forgot to make the declaration, distinct from an explicit
	// unsupported declaration.
	Restricted *RestrictedCapabilities
	// WritableTools declares, for every placement (Placements), whether an
	// ordinary turn, one that may write, can be held to the built-in tools
	// its grants name when they do not grant ToolsAll. A placement the map
	// does not name is unsupported: the turn is refused with
	// ErrUnsupported before anything starts, and so is one declared
	// unsupported, whose Remedy the error carries. A test holds every
	// descriptor to a declaration for every placement.
	WritableTools map[Placement]ToolSupport
	// contains filtered or unexported fields
}

type Bind struct {
	Source      string
	Destination string
	Access      Access
}

type Boundary interface {
	Verify(req Request) (*Turn, error)
}

type Confinement struct {
	// Sandbox is the profile's host sandbox, SandboxNone or SandboxClaude.
	Sandbox string
	// Mounts are the granted mounts. Where one lies inside another the
	// inner one decides, so a read-only mount inside a read-write one stays
	// read-only.
	Mounts []Mount
	// System are the system paths and, once the runner has resolved it, the
	// agent's executable. They add to what the mounts allow.
	System []Mount
	// Denied are the files and directories that stay unreadable and
	// unexecutable inside Mounts and System: the VCS executables of a turn
	// without VCS. A denied file is denied at its own path, whatever shell
	// or symbolic link leads there, and under a hard link in a directory
	// that holds a denied path. A hard link to it anywhere else in Mounts or
	// System is not found.
	Denied []string
}

type Confiner interface {
	// Check reports whether this platform can enforce c, without starting
	// anything. Its error wraps ErrUnsupported.
	Check(c Confinement) error
	// Start starts cmd under c. It never starts cmd with less than c.
	Start(cmd *exec.Cmd, c Confinement) error
}

type ContainerBoundary struct {
	// Environ is the host environment agent credentials are read from; nil
	// reads os.Environ.
	Environ func() []string
	// Home is the container's private HOME.
	Home string
	// SessionsDir is where a session directory is created for a request
	// that names none.
	SessionsDir string
	// MountDirs must be granted read-write.
	MountDirs []string
	// SkillMountDirs must be granted when the profile has skills.
	SkillMountDirs []string
	// Masks are read-only binds the runner owns, laid over paths of the
	// image for a turn without VCS: a stand-in over each VCS executable the
	// image has (see NewContainer). Their sources need no grant: they show
	// the container nothing of the host but the stand-ins themselves.
	Masks []Bind
}

type Dagger struct {
	// Engine is where the engine listens on the host: "unix://<path>" for
	// its socket, "tcp://<host>:<port>", or "docker-container://<name>"
	// for an engine in a container of the host's container engine
	// (Runner.DockerBin) that publishes neither.
	Engine string
	// Version is the Dagger CLI release installed in the sandbox, the
	// engine's own: "v0.20.5" or "0.20.5".
	Version string
}

type Enforcer interface {
	// Prepare checks the grants on their own and asks the platform whether
	// it can enforce them, without starting an agent. A kind this platform
	// cannot enforce is refused with an error that wraps ErrUnsupported,
	// never prepared with less.
	Prepare(ctx context.Context, grants Grants) (Session, error)
}

type Grants struct {
	// Env is the complete allowlist of environment variable names. A name
	// ending in "*" grants every name with that prefix. Host variables are
	// inherited only when listed; a variable the profile or request sets
	// that is not listed is refused.
	Env []string
	// Tools are the tools the agent may use: built-in tool names (or
	// ToolsAll) and "mcp__<server>" for each MCP server. The profile's
	// allowed tools and MCP servers may narrow them, never widen them.
	Tools []string
	// Mounts are the paths the session may read or write. The working
	// directory must lie inside one of them.
	Mounts []Mount
	// Within, when set, confines every mount: a mount that resolves outside
	// it, through ".." or a symbolic link, is refused.
	Within string
	// VCS grants version control: VCS credentials and configuration in the
	// environment, VCS executables, and writable VCS metadata. Without it
	// all three are denied.
	VCS bool
	// DaggerEngine grants the Dagger engine at this address (Dagger.Engine)
	// to a session whose profile asks for it, and only in SandboxSbx. A
	// profile that asks for another engine, or none, is refused.
	DaggerEngine string
	// HostServers grants a SandboxSbx session MCP servers the caller runs
	// on the host's loopback itself (HostServer). Every other mode refuses
	// them.
	HostServers []HostServer
}

type HostBoundary struct {
	// Environ is the host environment; nil reads os.Environ.
	Environ func() []string
	// StripPrefix removes host variables with this prefix even when granted.
	StripPrefix string
	// AddDirs are directories the agent is told it may write.
	AddDirs []string
	// Confiner enforces a confined turn; nil selects this platform's, which
	// is Landlock on Linux, Seatbelt on macOS and none anywhere else.
	Confiner Confiner
	// SystemPaths are what a confined turn reaches beyond its mounts; nil
	// selects DefaultSystemPaths.
	SystemPaths []Mount
	// SessionsDir is where a session directory is created for a request
	// that names none. A confined turn must be granted it.
	SessionsDir string
	// SkillDirs hold the prepared skills; a confined turn with skills must
	// be granted them.
	SkillDirs []string
}

type HostMCP struct {
	Name  string
	Entry MCPEntry
	// Env overrides the session environment for the host server (secrets stay in memory).
	Env             map[string]string
	ListenArgs      []string
	TokenEnv        string
	ListeningPrefix string
	Path            string
}

type HostServer struct {
	// Name is the server's name, the key of its Profile.MCP entry.
	Name string
	// Port is the port it listens on, on the host's loopback.
	Port int
}

type Interrupted struct {
	// Role is who ran the session, and Name the session directory's name.
	Role string
	Name string
	Dir  string
	// Transcript is the path of the unfinished transcript, empty when the
	// session was killed before it wrote one.
	Transcript string
	// Turns is how many assistant messages the transcript holds. It is an
	// approximation of the turn count a finished session reports: that
	// number comes from the event that ends a stream, which an interrupted
	// session never emitted.
	Turns int
	// Killed is true when the session was stopped on purpose (orphan cleanup)
	// rather than lost with the process that ran it, and Note is what the
	// marker said.
	Killed bool
	Note   string
}

type MCPEntry struct {
	Type    string            `json:"type,omitempty"`
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
	URL     string            `json:"url,omitempty"`
	Headers map[string]string `json:"headers,omitempty"`
	// EnvVars names variables Codex must inherit from its own environment.
	// Claude, OpenCode and pi inherit it already, so this is not a file entry.
	EnvVars []string `json:"-"`
	// BearerTokenEnv names the process variable holding an HTTP bearer token.
	// Backend writers render an environment reference, never the secret value.
	BearerTokenEnv string `json:"-"`
}

type Mount struct {
	Path   string
	Access Access
}

type Outcome struct {
	Work   work.Ref `json:"work"`
	Status string   `json:"status"`
	Note   string   `json:"note,omitempty"`
}

type Placement struct {
	Sandbox string
	Confine bool
}

type Policy struct {
	// Sandbox is the kind: SandboxNone, SandboxClaude, SandboxContainer or
	// SandboxSbx.
	Sandbox string
	// Env is the allowlist of variable names the turn's environment is
	// built from.
	Env []string
	// Tools are the built-in tools the agent is started with; nil is all
	// of them. MCPServers are the servers it may be given.
	Tools      []string
	MCPServers []string
	// Mounts are the granted paths. Where one lies inside another the inner
	// one decides.
	Mounts []Mount
	// System is what a host turn reaches beyond its mounts: the system
	// paths, and the executables of the agents the runner names, of which a
	// turn runs one. Nil for a container or a sandbox, which reaches its
	// image and nothing else of the host.
	System []Mount
	// VCS is whether version control is granted.
	VCS bool
	// DeniedExecutables are the names shadowed on the turn's PATH, and
	// Denied the paths that can be neither read nor executed: on the host
	// for a host turn, inside the image for a container. A sandbox has no
	// denied paths.
	DeniedExecutables []string
	Denied            []string
	// Image is what a container turn runs, or the template a sandbox is
	// created from (empty: sbx's own for Agent). Binds are everything a
	// container or a sandbox is given of the host: the mounts, and a
	// container's stand-ins over Denied. A turn adds to them only a granted
	// mount again, under the path a symbolic link names a directory of the
	// request by.
	Image string
	Binds []Bind
	// Agent is the agent a sandbox is created for; empty for any other
	// kind.
	Agent string
	// DaggerEngine is the Dagger engine a sandbox turn whose profile asks
	// for it reaches, and HostServers the caller's servers on the host's
	// loopback it may be allowed to reach.
	DaggerEngine string
	HostServers  []HostServer
}

type Profile struct {
	Name  string
	Agent string
	Model string
	// Fallback is the profile a caller runs the session on instead when
	// this one has no capacity (ops.SelectProfile), agent included, and it
	// may have a fallback of its own. The claude backend also passes a
	// claude fallback's model as --fallback-model, so claude switches to it
	// within the session; a fallback on another agent is the caller's to
	// run. Nil is no fallback.
	Fallback        *Profile
	Effort          string
	MaxTurns        int
	Timeout         time.Duration
	AllowedTools    []string
	DisallowedTools []string
	// MCP contains prepared entries; MCPEntries expands configured references once.
	MCP map[string]MCPEntry
	// Sandbox is one of Sandboxes; empty is SandboxNone.
	Sandbox string
	// Confine has the operating system hold a host session (SandboxNone or
	// SandboxClaude) to its granted mounts: see HostBoundary. A platform
	// that cannot refuses the session with ErrUnsupported.
	Confine bool
	// SandboxImage is the image a SandboxContainer session runs in, and the
	// template a SandboxSbx session is created from (empty selects the
	// sbx CLI's own template for the agent, SbxTemplates).
	SandboxImage string
	// Dagger gives a SandboxSbx session the Dagger CLI and a host's Dagger
	// engine to run it against; nil is neither. The session must also be
	// granted the engine (Grants.DaggerEngine).
	Dagger                  *Dagger
	SandboxDomains          []string
	ContainerUseEnvironment string
	// VCSAccess permits workspace VCS mounts and caller-supplied VCS environment.
	// It is not a security boundary on an unsandboxed host that is not confined.
	VCSAccess bool
	Shell     string
	Env       map[string]string
	Skills    []string
	// PiPackages are pi package sources (npm:, git:, a URL or a local path)
	// an ordinary pi session loads after PiMCPAdapter. RunRestricted loads
	// neither packages nor the adapter.
	PiPackages []string
}

type RateLimit struct {
	// Status is rate_limit_info.status. Only "allowed" and
	// "allowed_warning" are known to mean the session may keep going;
	// anything else is treated as blocking, because the blocked value has
	// never been observed here and must not be guessed at.
	Status string `json:"status,omitempty"`
	// Type is rate_limit_info.rateLimitType ("five_hour", "seven_day").
	Type string `json:"type,omitempty"`
	// ResetsAt is when the window rolls, from rate_limit_info.resetsAt.
	// Zero when the event carried none.
	ResetsAt time.Time `json:"resets_at,omitempty"`
}

type Request struct {
	// Name identifies the session in logs, e.g. "builder-task-12-r1".
	Name    string
	Profile Profile
	// ValidOutcomes is nil to accept any status; an empty non-nil set accepts none.
	ValidOutcomes []string
	// HostMCP optionally starts a caller-owned stdio server on the host for
	// container and sandbox sessions.
	HostMCP *HostMCP
	// ContainerEnv overrides Env only inside a container or a sandbox.
	ContainerEnv map[string]string
	// Workspace supplies the working directory and optional VCS resources.
	Workspace vcs.Workspace
	// VCSEnv and VCSContainerEnv are caller-owned identity, credentials and
	// configuration, injected only when the profile allows VCS access.
	VCSEnv          map[string]string
	VCSContainerEnv map[string]string
	// VCSContainerPath are caller-owned directories put in front of the
	// image's PATH inside a container or a sandbox, only when the profile
	// allows VCS access: wrappers such as a gh that fetches its own
	// credentials. Each must be inside a directory the box mounts. On the
	// host the caller sets PATH in Env itself.
	VCSContainerPath []string
	// SystemPrompt is appended to claude's default system prompt.
	SystemPrompt string
	// Prompt is the task given to the session.
	Prompt string
	// Env are extra environment variables.
	Env map[string]string
	// SessionDir is the per-session directory. When empty one is created;
	// callers that want to reference it in prompts create it first with
	// Runner.NewSessionDir.
	SessionDir string
	// Grants are the session's complete capabilities. Run verifies the
	// request against them before it starts anything and refuses a request
	// without them.
	Grants *Grants
	// ResumeID, when set, is the agent's own id of an earlier session
	// (Result.ClaudeID) whose conversation this one continues, so a later
	// round of the same role starts with the previous round's context
	// instead of relearning the codebase. Claude, opencode, pi and codex
	// (through thread/resume) honour it. The caller owns the id's
	// lifetime, and an id the agent no longer knows ends two ways: claude,
	// opencode and codex fail the launch before saying anything — for
	// codex, an error response to thread/resume, including JSON-RPC
	// -32600 ("no rollout found for thread id <id>"), ends the session as
	// an error with no fallback to thread/start — which the caller's
	// retry runs fresh, while pi starts a new session under that id with
	// no earlier context.
	ResumeID string
	// CostCapUSD, when above zero, is the most the session may cost: the
	// runner stops it once the known cost its stream reports reaches this
	// many dollars, and a session that ends with a known cost at or over
	// it is reported as capped too (Result.CostCapped). Zero is no cap. A
	// cost the backend does not report never reaches the cap: codex's app
	// server records token counts in the transcript
	// (thread/tokenUsage/updated) but never prices them, so this cap stays
	// inert and no codex session is ever stopped by it.
	CostCapUSD float64
}

type RestrictedCapabilities struct {
	Supported bool
	FollowUp  bool
	// ReadServer says the backend has no read-only file tool of its own
	// once its command execution is switched off, so a restricted turn is
	// given the runner's read server (readserver.go) to read the
	// workspace with instead.
	ReadServer bool
}

type RestrictedResult struct {
	*Result
	Model string
}

type Result struct {
	Name       string        `json:"name"`
	Role       string        `json:"role"`
	SessionDir string        `json:"session_dir"`
	Transcript string        `json:"transcript"`
	StartedAt  time.Time     `json:"started_at"`
	Duration   time.Duration `json:"duration"`
	ExitCode   int           `json:"exit_code"`
	// Signal is the signal that terminated the agent, or 0 when it exited
	// of its own accord. Go reports an ExitCode of -1 for a signalled
	// process and the signal is the only part that says why, so both are
	// recorded: the number here, its name in ErrorSubtype ("signal_killed").
	Signal int `json:"signal,omitempty"`
	// ClaudeID is the id the agent gave the session: claude's, opencode's
	// or pi's session id, or codex's thread id. The JSON name stays
	// claude_session_id for older readers of result.json. Agent is the
	// backend that gave it (AgentClaude when the profile named none), the
	// only one that can resume it.
	ClaudeID     string  `json:"claude_session_id,omitempty"`
	Agent        string  `json:"agent,omitempty"`
	ResultText   string  `json:"result_text,omitempty"`
	IsError      bool    `json:"is_error"`
	ErrorSubtype string  `json:"error_subtype,omitempty"`
	NumTurns     int     `json:"num_turns"`
	CostUSD      float64 `json:"cost_usd"`
	// CostKnown says whether the stream reported any cost at all: claude
	// reports the cost in the result event of its stream alone, so a
	// session killed before it emitted one has no cost at all rather than
	// a cost of zero, and codex reports tokens but never a cost. Nothing
	// derives one. Opencode and pi report each step's cost as it ends, so
	// a session stopped part way has the cost of the steps it finished.
	CostKnown bool `json:"cost_known"`
	// CostCapped says the known cost reached Request.CostCapUSD: the
	// runner stopped the session for it, or it ended with a final cost at
	// or over the cap. ErrorSubtype is SubtypeCostCap, and CostUSD is the
	// cost observed until then. A caller's cancellation is never this.
	CostCapped bool    `json:"cost_capped,omitempty"`
	TimedOut   bool    `json:"timed_out"`
	Outcome    Outcome `json:"outcome"`
	HasOutcome bool    `json:"has_outcome"`
	// RateLimit is the last rate-limit event of the session's stream, or
	// nil when it carried none.
	RateLimit *RateLimit `json:"rate_limit,omitempty"`
	// Diagnostics are failures the agent reported that ResultText may not
	// mention, one line each: an MCP server that did not start, or an MCP
	// tool call that failed. Codex reports them; other backends leave it
	// empty.
	Diagnostics []string `json:"diagnostics,omitempty"`
}

type Runner struct {
	// ClaudeBin is the claude executable. Default "claude".
	ClaudeBin string
	// CodexBin is the codex executable, run for a role whose agent is
	// codex. Default "codex".
	CodexBin string
	// OpenCodeBin is the opencode executable, run for a role whose agent
	// is opencode. Default "opencode".
	OpenCodeBin string
	// PiBin is the pi executable, run for a role whose agent is pi.
	// Default "pi".
	PiBin string
	// DockerBin is the container engine a container session is run with,
	// and the one a SandboxSbx session's docker-container Dagger engine is
	// reached through (Dagger.Engine). Default ContainerEngine.
	DockerBin string
	// SbxBin is the Docker Sandboxes CLI a SandboxSbx session is run with.
	// Default SandboxCLI.
	SbxBin string
	// ContainerListen is the address the caller-supplied MCP server listens on
	// for a container or sandbox session. Empty picks the address the box
	// reaches the host by (see containerListen and sandboxListen).
	ContainerListen string
	SessionsDir     string
	// EnvironmentPrefix is removed from the inherited host environment.
	EnvironmentPrefix string
	// NamePrefix prefixes backend titles and container names.
	NamePrefix string
	// ContainerLabel identifies containers during orphan inspection.
	ContainerLabel         string
	ContainerHome          string
	ContainerUseRepository string
	// MountDirs are directories a container or sandbox session writes; each must be
	// granted read-write.
	MountDirs []string
	// Skills prepares generic skill plugin directories.
	Skills SkillPreparer
	// SkillMountDirs hold the prepared skills; a container or sandbox session or a
	// confined host session with skills must be granted them.
	SkillMountDirs []string
	// AddDirs are extra directories claude may write (the state dir). Each
	// must be granted read-write.
	// Codex, which runs without a sandbox, needs no such list, and neither
	// does opencode, whose --auto approves writing outside the worktree,
	// nor pi, which has no approvals to ask.
	AddDirs []string
	// Confiner enforces a confined host session (Profile.Confine); nil
	// selects this platform's. SystemPaths are what such a session reaches
	// beyond its mounts; nil selects DefaultSystemPaths.
	Confiner    Confiner
	SystemPaths []Mount

	// Stream, when set, receives every stream-json line (debug output).
	Stream io.Writer
	Logger *slog.Logger
	// contains filtered or unexported fields
}

type SandboxBoundary struct {
	// SessionsDir is where a session directory is created for a request
	// that names none.
	SessionsDir string
	// MountDirs must be granted read-write.
	MountDirs []string
	// SkillMountDirs must be granted when the profile has skills.
	SkillMountDirs []string
}

type Session interface {
	// Policy is what the session enforces on every turn it runs.
	Policy() Policy
	// Run runs one turn under the session's grants: see Admit for what it
	// does to the request. A turn the policy does not describe, because
	// something the policy was read from has changed since Prepare, is
	// refused with ErrPolicyChanged before anything starts. Otherwise it is
	// Runner.Run.
	Run(ctx context.Context, req Request) (*Result, error)
	// Release frees what Prepare made. Run is refused with ErrReleased
	// afterwards. Call it once no turn of the session is running; calling it
	// again does nothing.
	Release(ctx context.Context) error
}

type SkillPreparer interface {
	Prepare(context.Context, []string) ([]string, error)
}

type ToolSupport struct {
	Supported bool
	Remedy    string
}

type Turn struct {
	// Env is the complete process environment, as NAME=value pairs, before
	// the backend's own configuration variables are added.
	Env []string
	// Tools are the built-in tools passed to the agent; nil means all.
	Tools []string
	// Mounts are the granted paths with their symbolic links resolved.
	Mounts []Mount
	// WriteDirs are the writable directories beyond the working directory
	// the agent is told about.
	WriteDirs []string
	// VCS is whether version control is granted and requested.
	VCS bool
	// DeniedExecutables are shadowed on PATH for the session.
	DeniedExecutables []string
	// Binds are everything a container or Docker Sandbox session sees of
	// the host; nil for a host session.
	Binds []Bind
	// Confinement is what the operating system enforces for a confined host
	// session; nil for any other.
	Confinement *Confinement
	// DaggerEngine is the Dagger engine the session reaches; empty for
	// none.
	DaggerEngine string
	// HostServers are the granted host servers the profile's MCP entries
	// reach, in name order: the ports a SandboxSbx session is allowed on
	// the host's loopback.
	HostServers []HostServer
}