harness

type Agent struct {
	Name            string
	Description     string
	Model           string
	ReasoningEffort string
	Verbosity       string
	MaxRecursion    *int
	CustomShell     CustomShell
	Space           string
	Prompt          string
	Location        string
	Permission      PermissionSet
	OutputSchema    map[string]any
	Frontmatter     map[string]any
	FrontmatterNode *yaml.Node
	FileMode        fs.FileMode
	Mode            AgentMode

	// Easy-only fields, compiled from an easy file's sections; advanced agents leave them zero.
	// Model entries keep their text as written, provider prefix and #effort included.
	WorkingDirectory string
	Commands         map[string]string
	SecretsARN       []string
	Subagents        []string
	ApproverModel    string
	ApproverPrompt   string
	Routines         []AgentRoutine
	TagGroups        [][]string
	// DelegatedFrom lists the agents that may write into this agent's sessions; nil means any agent.
	DelegatedFrom []string
	// NetworkTargets lists the emulated shell's allowed network targets; nil means public addresses only.
	NetworkTargets []string
	// Tools, set by the embedder for an easy agent's subagent session, names the only tools it has: tool names
	// and MCP server.tool subjects. Nil means every tool.
	Tools []string
}

type AgentLoadConfig struct {
	// MCPToolGroups maps every configured MCP server to its tool groups (read, write) of tool-name patterns.
	MCPToolGroups map[string]map[string][]string
	// Providers names every configured model provider, openai included.
	Providers []string
	// Skills is the skills root; easy skills entries name folders in it.
	Skills fs.FS
}

type AgentLoadResult struct {
	Agents Agents
	Errors []error
}

type AgentMaxRecursionError struct {
	Location string
	Err      error
}

type AgentMode string

type AgentRoutine struct {
	Schedule    string
	Instruction string
}

type Agents struct {
	Items map[string]Agent
}

type Attachment struct {
	MIME     string `json:"mime"`
	Filename string `json:"filename,omitempty"`
	URL      string `json:"url"`
}

type BackgroundJob struct {
	// ID is the call's turn-scoped tool call key (ToolCallKey), stable across resume.
	ID   string
	Kind BackgroundKind
	// Label is execute's description or task's description.
	Label string
	Agent string
	// SubagentKey is the child-session key of the subagent a task call runs; empty for execute.
	SubagentKey string
	CallID      string
	// Detached reports that the call asked to start in the background.
	Detached bool
}

type BackgroundJobs interface {
	// Enabled reports whether background mode is offered at all.
	Enabled() bool
	// Run runs work and returns when it finishes attached to its call, or once it runs in the
	// background. Attached work stops with ctx and keeps its cancellation cause.
	Run(ctx context.Context, job *BackgroundJob, work BackgroundWork) (BackgroundResult, error)
}

type BackgroundKind string

type BackgroundResult struct {
	// Output is the finished work's output; empty when Moved.
	Output string
	// Moved reports that the work runs, or already ran, in the background.
	Moved bool
}

type BackgroundWork interface {
	RunBackground(ctx context.Context) (string, error)
	// Detach marks the work as running outside its turn, before Run reports the move. It reports
	// false, leaving the work attached, once the work stored its result for its turn.
	Detach() bool
}

type BashResult struct {
	Output    string
	ErrorCode string
	Success   bool
}

type ChatResponse struct {
	Kind     string
	Text     string
	Tool     *ToolDiagnostic
	Subagent *SubagentDiagnostic
	Provider *ProviderDiagnostic
}

type ChildKey struct {
	Path, Parent, Turn, Call string
}

type ChildSessions interface {
	AppendChildEntry(ctx context.Context, key ChildKey, entry *SessionEntry) error
	// WriteSubagent delivers write to its subagent session, which it starts when new, and reports
	// whether write joined the session's running turn. A replayed write delivers nothing again.
	WriteSubagent(ctx context.Context, write *SubagentWrite) (steered bool, err error)
	// AwaitSubagent waits for the turn of the subagent session at key that runs the write of the task
	// call callKey, and returns its answer and the agent type and model it ended as.
	AwaitSubagent(ctx context.Context, key, callKey string) (string, ReplayAttribution, error)
}

type CodeModeCall struct {
	Type         string                  `json:"type"`
	ParentCallID string                  `json:"parent_call_id"`
	Key          string                  `json:"key,omitempty"`
	Name         string                  `json:"name,omitempty"`
	Arguments    string                  `json:"arguments,omitempty"`
	Status       codeModeCallStatus      `json:"status,omitempty"`
	Summary      string                  `json:"summary,omitempty"`
	Outcome      permissionReviewOutcome `json:"outcome,omitempty"`
	Reason       string                  `json:"reason,omitempty"`
}

type Config struct {
	Model                      shared.ResponsesModel
	AutoApproverModel          shared.ResponsesModel
	ReasoningEffort            shared.ReasoningEffort
	Diagnostics                bool
	ExperimentalStrongerSkills bool
	ExpandPromptShellCommands  PromptShellCommandExpansion
	CompactThreshold           int64
	CompactionSteering         string
	ParallelToolCalls          int
	// ShellTempDir is the workspace-relative or absolute directory used as TMPDIR
	// for bash and prompt !`…` commands. Required; must exist inside the workspace.
	ShellTempDir string
	// SpillDir is the workspace-relative or absolute directory for oversized
	// execute output. Empty uses <workspace>/.rocketcode/spill.
	SpillDir string
	// RetainedResultDir is the directory, relative to SpillDir, that keeps oversized output of
	// background execute scripts readable for 7 days. Required; give each conversation its own.
	RetainedResultDir      string
	AutoApprovePermissions bool
	Observability          ObservabilityConfig
	ChildSessions          ChildSessions
	Journal                Journal
	BackgroundJobs         BackgroundJobs
	CustomTools            []Tool
	ShellEnv               map[string]string
	// ChildContext supplies host messages to permission reviewers.
	ChildContext []SessionEntry
	// OriginHeader is the embedder's trusted statement of who started the turn, which permission
	// reviewers read ahead of the untrusted transcript.
	OriginHeader string
	// ShellCommand builds the executable used for bash tool (and prompt !`…`)
	// commands. Required; pass DefaultShellCommand{} to match permission validation.
	// Custom implementations must preserve the validated Bash syntax and semantics.
	// An agent's shell frontmatter overrides it for that agent.
	ShellCommand shellCommander
	// Sandbox runs emulated shells. The zero value refuses them.
	Sandbox      sandbox.Runtime
	MCPServers   map[string]mcpclient.ServerConfig
	MCPWorkspace string
}

type ContinueMode string

type CustomShell struct {
	// Path is a program that runs as <Path> <command>.
	Path string
	// Emulated means real Bash in the sandbox (shell: emulated, and every easy agent). The embedder sets Dir
	// for each turn; until it does, the agent's shell commands do not run.
	Emulated bool
	// Dir is the emulated shell's writable folder, shown at its host path. A bash call runs there, or in its
	// workdir taken from there, and skips the workspace path check: the sandbox does the confining.
	Dir string
	// ReadOnly are folders, none inside another, the emulated shell shows read-only at their host paths besides
	// Dir. An easy agent's file tools see Dir and these, as its shell does.
	ReadOnly []string
	// Commands are the emulated shell's host commands: a name and the command line host bash runs, with the
	// guest's arguments appended.
	Commands map[string]string
	// NetworkTargets limit the emulated shell's curl as they limit webfetch; nil means public addresses only.
	NetworkTargets []string
	// Secrets are environment variables only host programs get: the emulated shell's host commands, and an
	// easy agent's prompt and skill expansion in host bash.
	Secrets map[string]string
}

type DefaultShellCommand struct{}

type InertBackgroundJobs struct{}

type InertChildSessions struct{}

type InertJournal struct{}

type InertSteerDrain struct{}

type Journal interface {
	Load(ctx context.Context, key string) (json.RawMessage, bool, error)
	Save(ctx context.Context, key string, value json.RawMessage) error
	// SaveTurn saves turn turnID's step under its key and, in the same write, each of lists: its
	// items replace the list's saved items from index From on. A running turn writes each item once.
	SaveTurn(ctx context.Context, turnID string, step json.RawMessage, lists []TurnItems) error
	// Items returns the items SaveTurn saved in turn turnID's list, in order.
	Items(ctx context.Context, turnID string, list TurnList) ([]json.RawMessage, error)
	// SaveTrace persists display-only public progress for the root turn.
	SaveTrace(ctx context.Context, turnID string, trace []json.RawMessage) error
	// SaveCodeModeCall persists one Code Mode record of the root turn under its key, apart from the
	// trace, so a record is written when its call starts and finishes and never with other progress.
	SaveCodeModeCall(ctx context.Context, turnID, key string, record json.RawMessage) error
	// CodeModeCalls returns the root turn's saved Code Mode records in the order they were first saved.
	CodeModeCalls(ctx context.Context, turnID string) ([]json.RawMessage, error)
}

type Looper interface {
	Loop(ctx context.Context, input <-chan PromptInput, sessionIn iter.Seq2[SessionEntry, error], sessionOut sessionWriter, interrupts <-chan os.Signal) error
}

type ModelResolver interface {
	Resolve(model string) (*openai.Client, ProviderOrigin, error)
}

type ObservabilityConfig struct {
	Enabled     bool
	Tracer      trace.Tracer
	TraceConfig instrumentation.TraceConfig
}

type PermissionAction string

type PermissionBucket struct {
	Name  string
	Rules []PermissionRule
}

type PermissionReview struct {
	Outcome   permissionReviewOutcome
	Rationale string
}

type PermissionRule struct {
	Pattern  string
	Action   PermissionAction
	Reviewer string
	// contains filtered or unexported fields
}

type PermissionSet struct {
	Buckets []PermissionBucket
	Sudo    bool
	Easy    bool
	// contains filtered or unexported fields
}

type PromptInput struct {
	// ID identifies this input in local durable replay, not provider requests.
	ID string
	// TurnID, when set, is the turn's stable identity and journal key across restarts.
	TurnID string
	// Role defaults to PromptInputRoleUser when empty.
	Role PromptInputRole
	// Texts are the prompt's text pieces. The prompt text is their concatenation;
	// each piece carries its own separators. More than one piece is sent as
	// separate text parts, which a provider's prompt cache marker can target.
	Texts []string
	// ExpandShellCommands enables !`command` expansion for this trusted input,
	// even when input expansion is disabled for the runtime as a whole.
	ExpandShellCommands bool `json:",omitempty"`
	// Header is the exact generated prefix of the first piece, saved only in local replay.
	Header      string
	Attachments []Attachment
	DirectSkill *PromptInputDirectSkill
	// Agent, on a steer drained into a running subagent turn, is the agent type that turn runs as from
	// its next step on.
	Agent string
	// Responses receives user-visible response items for this prompt. The runtime
	// closes it after the prompt's turn reaches a terminal state.
	Responses chan<- ChatResponse `json:"-"`
}

type PromptInputDirectSkill struct {
	Name      string `json:"name"`
	Arguments string `json:"arguments,omitempty"`
}

type PromptInputRole string

type PromptShellCommandExpansion struct {
	// PrimaryPrompts covers the agent prompt of every session, a Task subagent's included, since a
	// subagent runs as a session of the embedder (ChildSessions).
	PrimaryPrompts bool
	// SubagentPrompts covers the prompts of permission review agents.
	SubagentPrompts bool
	SkillPrompts    bool
	InputPrompts    bool
}

type ProviderDiagnostic struct {
	Provider       string            `json:"provider"`
	Model          string            `json:"model"`
	Phase          string            `json:"phase"`
	HTTPStatus     int               `json:"http_status,omitempty"`
	ResponseStatus string            `json:"response_status,omitempty"`
	Code           string            `json:"code,omitempty"`
	Type           string            `json:"type,omitempty"`
	Message        string            `json:"message,omitempty"`
	Attempt        int               `json:"attempt,omitempty"`
	RetryAfter     string            `json:"retry_after,omitempty"`
	ResponseID     string            `json:"response_id,omitempty"`
	Headers        map[string]string `json:"headers,omitempty"`
}

type ProviderOrigin struct {
	Provider         string
	Model            string
	CompactThreshold int64
	// PromptCacheMarkersRelativePosition, when set, is the negative index of the text
	// piece in the last request message that carries an Anthropic cache_control marker.
	PromptCacheMarkersRelativePosition *int
}

type Providers struct {
	OpenAI *openai.Client
}

type PublicProgress struct {
	ID       string              `json:"id"`
	ParentID string              `json:"parent_id,omitempty"`
	Kind     PublicProgressKind  `json:"kind"`
	State    PublicProgressState `json:"state"`
	Text     string              `json:"text,omitempty"`
	Agent    string              `json:"agent,omitempty"`
	Model    string              `json:"model,omitempty"`
	// SubagentKey is the key of the subagent a task call runs or continues under the history that
	// holds the call, as OpenCode keeps a task part's child session ID in its metadata.
	SubagentKey string `json:"subagent_key,omitempty"`
}

type PublicProgressKind string

type PublicProgressState string

type ReplayAttribution struct {
	Start           int     `json:"start"`
	End             int     `json:"end"`
	Agent           string  `json:"agent,omitempty"`
	Model           string  `json:"model,omitempty"`
	ReasoningEffort *string `json:"reasoning_effort,omitempty"`
}

type ReplayDecodeError struct {
	EntryIndex int
	ItemIndex  int
	Kind       string
	Cause      error
}

type Runtime = looper

type SessionEntry struct {
	Version           int                 `json:"version"`
	Type              string              `json:"type"`
	Timestamp         time.Time           `json:"timestamp"`
	TurnID            string              `json:"turn_id,omitempty"`
	ResponseID        string              `json:"response_id,omitempty"`
	Model             string              `json:"model,omitempty"`
	Agent             string              `json:"agent,omitempty"`
	ReasoningEffort   *string             `json:"reasoning_effort,omitempty"`
	ReplayAttribution []ReplayAttribution `json:"replay_attribution,omitempty"`
	TokenUsage        *TokenUsage         `json:"token_usage,omitempty"`
	ReplayInput       []json.RawMessage   `json:"replay_input,omitempty"`
	OutputTrace       []json.RawMessage   `json:"output_trace,omitempty"`
}

type Skill struct {
	Name          string
	Description   string
	License       string
	Compatibility string
	Metadata      map[string]any
	Location      string
	Content       string
}

type SkillLoadResult struct {
	Skills Skills
	Errors []error
}

type Skills struct {
	Root  string
	Items map[string]Skill
	Dirs  []string
	// contains filtered or unexported fields
}

type SteerDrain interface {
	Drain(ctx context.Context, responseID string, phase TurnPhase, applied []string) ([]PromptInput, error)
}

type SubagentDiagnostic struct {
	Name     string              `json:"name"`
	Label    string              `json:"label"`
	Index    int                 `json:"index,omitempty"`
	Total    int                 `json:"total,omitempty"`
	Text     string              `json:"text,omitempty"`
	Tool     *ToolDiagnostic     `json:"tool,omitempty"`
	Subagent *SubagentDiagnostic `json:"subagent,omitempty"`
	Provider *ProviderDiagnostic `json:"provider,omitempty"`
}

type SubagentWrite struct {
	// Key is the session's child key.
	Key ChildKey
	// CallKey is the task call's tool call key, which identifies the write.
	CallKey string
	// Agent is the subagent type that runs Prompt, and Delegator the agent that wrote it.
	Agent, Delegator, Prompt string
	// Mode is a continue's mode; empty for a new subagent.
	Mode ContinueMode
	// Model, an entry of Agent.Subagents as written, and Tools (Agent.Tools) are what an easy agent's
	// subagent session, which runs that agent, runs with; an agent type's leaves them empty.
	Model string
	Tools []string
}

type TokenUsage struct {
	PromptTokens              int64 `json:"prompt_tokens,omitempty"`
	CompletionTokens          int64 `json:"completion_tokens,omitempty"`
	TotalTokens               int64 `json:"total_tokens,omitempty"`
	PromptCacheReadTokens     int64 `json:"prompt_cache_read_tokens,omitempty"`
	PromptCacheWriteTokens    int64 `json:"prompt_cache_write_tokens,omitempty"`
	CompletionReasoningTokens int64 `json:"completion_reasoning_tokens,omitempty"`
}

type Tool struct {
	Name               string
	Description        string
	Parameters         map[string]any
	Permission         string
	VisibilitySubjects []string
	Subjects           func(json.RawMessage) ([]string, error)
	Call               func(context.Context, json.RawMessage, chan<- ChatResponse) (ToolResult, error)
	// Resumable calls interrupted by a restart run again instead of being reported interrupted.
	Resumable bool
	// TurnBound calls refuse to run in background work, which has left the turn they act on.
	TurnBound bool
}

type ToolDiagnostic struct {
	Phase     string          `json:"phase"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments,omitempty"`
	Result    string          `json:"result,omitempty"`
	Status    string          `json:"status,omitempty"`
	Action    json.RawMessage `json:"action,omitempty"`
}

type ToolResult struct {
	Output      string
	Attachments []Attachment
	// Data is an optional structured payload for code-mode bindings (e.g. BashResult).
	Data any
}

type TracelessJournal struct {
	Parent Journal
}

type TurnItems struct {
	List  TurnList
	From  int
	Items []json.RawMessage
}

type TurnList string

type TurnPhase int