agent

type Controls interface {
	// SetModel changes the model for later runs, sub-agents included.
	SetModel(name string) error
	// SetThink turns reasoning on or off for later runs.
	SetThink(on bool) error
	// AddMCP starts a stdio MCP server whose tools are offered from the
	// next run as mcp__<name>__<tool>, returning the label RemoveMCP
	// takes.
	AddMCP(ctx context.Context, name, command string) (string, error)
	// RemoveMCP closes a server AddMCP started.
	RemoveMCP(label string) error
	// Info is what the session is: its ID, where it is kept, the tools
	// it was assembled with, what its instruction layers left out and
	// its MCP servers.
	Info() Info
}

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

type ExecutorOptions struct {
	// Name and Version are the program's, which the executor is told.
	Name, Version string
	// PassEnv and KeyEnv are Options' own: the command that starts the
	// executor (a docker exec, an ssh) gets this machine's environment
	// with credentials removed, except those PassEnv names, and never
	// KeyEnv's variable, whatever names it, so the model's key never
	// reaches the sandbox.
	PassEnv []string
	KeyEnv  string
	// Secrets name more variables that hold credentials (the
	// extensions' Secrets: extension.SecretsOf). Like KeyEnv's, the
	// command that starts the executor never gets them, whatever names
	// them.
	Secrets []string
	// LauncherEnv names more variables the command that starts the
	// executor is given, credentials included: ssh's SSH_AUTH_SOCK, the
	// token a kubectl credential plugin reads. They are that command's
	// alone; the session's tools and MCP servers run in the executor,
	// with its environment, and never see them. Naming KeyEnv is an
	// error.
	LauncherEnv []string
	// MaxReadBytes is the session's max_read_bytes, Options.MaxReadBytes
	// as the executor's tools are to take it: the most bytes of a file
	// they read, which the executor caps at its own -max-read-bytes.
	// Zero is tool.DefaultMaxRead. The executor's tools are built when
	// it is dialed, so it is given here, not in Options. When the
	// executor caps it lower, or is a dax execute older than the
	// setting and the setting is not the default, dax warns
	// (CaptureWarnings).
	MaxReadBytes int64
	// Box, when set, is what the session asks of a box host (`dax box
	// serve`, which makes the box the tools run in): a profile and its
	// tightenings, as JSON, sent on every connection. Any other
	// executor ignores it.
	Box json.RawMessage
}

type Info struct {
	// ID is the session's ID. Recorded is false for a session nothing
	// is kept of (no store), whose ID names nothing after it closes.
	ID       string
	Recorded bool
	// Path is its directory in a local store; empty otherwise.
	Path    string
	Tools   []agentkit.ToolOrigin
	Omitted []agentkit.Omission
	// Workspace says where its tools act: the kind, the ref and the
	// root.
	Workspace workspace.Descriptor
	// MCP are its MCP servers, each with where it runs and what it is
	// for, listed the same wherever it runs.
	MCP []MCPServerInfo
}

type MCPServer struct {
	// Name is the prefix of the server's tools.
	Name string
	// Command is the command line, split as a shell splits words with
	// nothing expanded; no shell runs it.
	Command string
	// Host runs Command on this machine whatever the workspace, with
	// this machine's environment scrubbed, even with an Executor: a
	// server called independently of the sandbox.
	Host bool
	// URL is a streamable HTTP server called from this machine, in
	// place of a command; TokenEnv names the variable whose token is
	// sent to its origin alone, and which every child's environment
	// loses.
	URL, TokenEnv string
	// Project says the project's config named the server: it starts only
	// when the user trusts the project's set (Options.TrustMCP).
	Project bool
	// Description says what the server is for, for a person reading a
	// list of servers.
	Description string

	// SecretEnv names variables a command's server is given from this
	// process's environment, which every other child of the session
	// loses (Secrets): it is started as a workspace's offered server is
	// (agentworkspace's Offer), its output, standard output and standard
	// error, redacted of their values before the session reads any of
	// it. A secret stays on the machine whose environment holds it, so
	// such a server must be placed on this machine (Host), never in a
	// workspace; not for a project's server or a URL; and none may be
	// KeyEnv, a TokenEnv, an extension's secret, a pass list's or a
	// served workspace's token variable.
	SecretEnv []string
	// contains filtered or unexported fields
}

type MCPServerInfo struct {
	// Name is the prefix of its tools, mcp__<name>__<tool>.
	Name string
	// Placement is where it runs, and Where names that place: the
	// workspace, as a session's warnings name one, or the URL's origin
	// alone (urlPlace), since a hosted server's key is often in its
	// path. Where is empty on this machine.
	Placement Placement
	Where     string
	// Description is what the config, or the workspace that offers the
	// server, says it is for: text from whoever wrote it, which a front
	// cleans before it shows it.
	Description string
	// Secrets says this session gives it secrets (MCPServer.SecretEnv)
	// and starts it on this machine, redacting them from what it
	// writes. A server a workspace offers is never marked, even one
	// that holds secrets there: agentworkspace does not tell a client
	// that an offered server does (agentworkspace#23).
	Secrets bool
	// Added is the label RemoveMCP takes, for a server AddMCP started;
	// empty for one the session opened with.
	Added string
}

type Options struct {
	// Name and Version are what the session calls its harness: in the
	// system prompt, to the kit, and in the session header. Empty is
	// dax and Version. A program built on dax gives its own.
	Name, Version string
	// Description is what the kit says the agent is; empty is dax's
	// for dax, and a plain line for a program that named itself.
	Description string
	// Extensions are everything the session offers the model past
	// itself, in order: dax's command line gives dax-coding, and
	// dax-agents, dax-skills and dax-memory as the settings say. With
	// none the model has no tools but MCP servers'.
	Extensions []extension.Extension
	// Streamer is the model; dax's command line builds one from the
	// configuration.
	Streamer openresponses.Streamer
	// SubagentStreamer is the model the sub-agents' requests go through
	// (extension.Env's SubagentModel); nil is Streamer. dax's command
	// line gives one of its own when the sub-agents' prompt cache lives
	// for another time than the main conversation's (subagent_cache_ttl).
	// Compaction and an A2A caller's conversation go through Streamer.
	SubagentStreamer openresponses.Streamer
	// Model is the model name the requests carry.
	Model string
	// Fit is the reasoning effort to ask a model for in place of the
	// one Think implies, from what its vendor says it takes; nil asks
	// as configured. It is applied where each configuration is built,
	// never to a request on its way out, so the session records the
	// request that was sent.
	Fit   func(ctx context.Context, model string, want openresponses.ReasoningEffort) openresponses.ReasoningEffort
	Think bool
	// Effort is the reasoning effort Think asks for; empty is low.
	Effort openresponses.ReasoningEffort
	// Dir is the directory on this machine the session started in.
	// With no Workspace it is where the tools act, as a
	// workspace.Local. The project's instructions (AGENTS.md, an
	// extension's project files such as .dax/skills) are read through
	// the workspace, not from Dir; only when the workspace is Dir on
	// this machine and Dir is below its repository's root are the
	// AGENTS.md files between the two read from here.
	Dir string
	// Workspace is where the tools act and what the session records as
	// its cwd and workspace: a container, a remote runtime, or this
	// machine. Nil is a workspace.Local over Dir, with an environment
	// scrubbed of credentials (PassEnv, KeyEnv), which the session
	// closes; one given here is the caller's to close.
	Workspace workspace.Workspace
	// ServersWorkspace is a second workspace beside Workspace (or the
	// executor's), whose offered servers (workspace.ServerProvider) the
	// session connects and nothing else: a served or tunnelled one
	// granted servers alone (config.ServersAlone), so a server holding a
	// secret of another machine's is used while the tools act in the
	// session's own workspace. Its servers are connected as the
	// workspace's offered ones are, through mcpStart, under the same
	// names, collisions, rules and restarts; no tool acts in it, no file
	// of it is read, and its servers are recorded under its identity in
	// the session's header. One that offers none, that is the
	// workspace, or that grants more than servers (exec, which reads a
	// running server's environment, or write, which changes its code)
	// fails the session. It is the caller's to close, after the session.
	ServersWorkspace workspace.Workspace
	// Executor runs the extensions' tools elsewhere, in `dax execute`
	// (DialExecutor), in place of building them in this process over a
	// workspace: their calls, facts and stamps are the executor's, and
	// the session records its workspace. Setting both Executor and
	// Workspace is an error. Every extension with Tools must be one the
	// executor runs, and no extension's matcher may give a served
	// tool's subjects (the policy reads the executor only through the
	// tools' facts). MCP servers start in the executor (its workspace
	// is a workspace.Starter there), and an executor that cannot start
	// one fails them, never starting them here. The project's files
	// are read through it. It is the caller's to close, after the
	// session.
	Executor *Executor
	// BoxConfine is the session's box.confine, with a box host in front
	// of Executor: config.ConfineUnits or config.ConfineWorkspace has the
	// policy take that box's tools as confined (confine.go), so a bare
	// ask rule for them does not ask. Empty or config.ConfineOff, and
	// any value without a box host's envelope, claims nothing.
	BoxConfine string
	// Store records the session: a store the caller opened, which it
	// closes after the session; a remote one (agentsession RFC 0003)
	// fits here as a local one does. Nil opens the content-addressed
	// store at Root.
	Store agentsession.Store
	// Root is the local session store, a content-addressed store
	// holding every project's sessions, used when Store is nil; both
	// empty disables recording.
	Root string
	// Sync is when an append to the store at Root is durable before it
	// returns: every append (the default), a response or a call's
	// output and what came before it, or at Close.
	Sync cas.SyncPolicy
	// UserDir is the user's dax directory, ~/.dax: its AGENTS.md is
	// read before the project's.
	UserDir string
	// Instructions is text of the user's own, from the config's
	// instructions_file, added to dax's part of the system prompt.
	Instructions string

	// AgentsMD reads UserDir/AGENTS.md, AgentsMDGlobal and the
	// AGENTS.md chain from the repository's root down to the
	// workspace's root into the instructions (https://agents.md);
	// never a file above the repository.
	AgentsMD bool
	// AgentsMDGlobal are the user's own instruction files for every
	// session (the config's agents_md_global), read under AgentsMD
	// after UserDir/AGENTS.md and before the chain, in order. They are
	// paths on this machine whatever the workspace, since they are the
	// user's and not the project's, and are not screened; a missing
	// one is skipped.
	AgentsMDGlobal []string
	// Compact, when positive, is the estimated token budget above which
	// the transcript is folded before a call.
	Compact int
	// CompactServer folds through the server's compaction endpoint
	// (compact.New) instead of a local summary (compact.NewLocal).
	CompactServer bool
	// Policy is the user's and the project's rules; the session adds
	// the extensions' (Settings.Shipped) and builds the policy that
	// decides which calls run, ask or are refused. nil lets every call
	// run, and the extensions' BeforeToolCall hooks are not run.
	Policy *policy.Settings
	// MCP are the MCP servers connected with the session, each offering
	// its tools as mcp__<Name>__<tool>. A command's server runs in the
	// workspace when it can start a process (workspace.Starter), at its
	// root and with its environment, and otherwise on this machine; with
	// an Executor it runs in the executor, and one that cannot start a
	// process fails the session. A server placed on the host runs on
	// this machine whatever the workspace, and one at a URL is called
	// from this machine. The servers the workspace offers of its own
	// (workspace.ServerProvider: a box host's units) are connected
	// beside these. A project's servers start only when TrustMCP is set
	// or the trust file holds their set for this workspace. Their stderr
	// is dax's, cleaned.
	MCP []MCPServer
	// TrustMCP trusts the set of MCP servers the project's config names
	// for this workspace, starts them, and records the trust in
	// MCPTrustFile, so a later session of the project with the same set
	// starts them without it (-trust-mcp).
	TrustMCP bool
	// MCPTrustFile is where the trusted sets are kept; empty is
	// DefaultMCPTrustFile under DefaultUserDir.
	MCPTrustFile string
	// MaxReadBytes is the most bytes of a file a tool should read,
	// which extension.ToolEnv carries; zero is tool.DefaultMaxRead.
	// With an Executor, its tools take ExecutorOptions.MaxReadBytes,
	// given when it was dialed, and not this.
	MaxReadBytes int64
	// PassEnv names credential-looking variables the processes of the
	// workspace.Local the session opens when Workspace is nil, MCP
	// servers among them, may still inherit; every other credential is
	// removed from their environment. A workspace given in Workspace
	// carries its own (Workspace.Env), and an MCP server that cannot
	// start in it runs on this machine with an environment scrubbed the
	// same way.
	PassEnv []string
	// KeyEnv is the variable the provider's key was read from. It is
	// removed from the same environments even when its name does not
	// look like a credential's, unless PassEnv names it, as are the
	// variables the extensions name in Secrets.
	KeyEnv string
	// Log receives dax's own notes: compactions, denials, skill grants.
	// nil discards them.
	Log func(format string, args ...any)
	// ViewGrace is how long an A2A caller's conversation's question
	// waits for a view to attach again once the last has gone, as one
	// reconnecting does, before it is given up; zero is
	// DefaultViewGrace.
	ViewGrace time.Duration
	// contains filtered or unexported fields
}

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

type Permission struct {
	Call *openresponses.FunctionCall
	// Reason is the policy's question, with what it was asking about:
	// the rule, the secret path, the git config key, the part of a
	// command line.
	Reason string
}

type Placement string

type Rules struct {
	// Permit decides a call the policy asked about: allow, or refuse,
	// with a note the model is told either way. reason is the policy's
	// question. Nil refuses every call.
	Permit func(call *openresponses.FunctionCall, reason string) (allow bool, note string)
	// Reply answers a question asked while a call runs: a sub-agent's
	// call the policy asks about (q.Call), a tool's own question. What
	// it says with the answer is its Note, which the model is told of an
	// answer about a call. Nil leaves the questions unasked: a
	// sub-agent's call is refused with a note to make it from the main
	// agent, and a tool's question is cancelled.
	Reply func(q agentturn.Question) agenttool.Answer
	// Refused, when set, is told of each call Permit refused.
	Refused func(call *openresponses.FunctionCall)
	// By, when set, names who gave the reply Reply has just given to q,
	// written beside the answer (agentturn.ContextWithAnswerer):
	// AtTerminal for a person's answer, a trigger of the controller's
	// own for a rule's. It is asked per reply, so rules that ask a
	// person and answer for them when nobody can (a decline at the end
	// of the input) name the person only for what the person said. The
	// zero Trigger, or a nil By, leaves the reply unattributed.
	By func(q agentturn.Question) agentturn.Trigger
}

type Session struct {
	Kit *agentkit.Kit
	// contains filtered or unexported fields
}

type UnhashedCause struct {
	Entry string
	session.Unhashed
	Responses int
}