api

type Action string

type ApprovalDecision struct {
	ExecutionID string
	ToolCallID  string
	RequestSeq  int64
	Approved    bool
	Reason      string
	Identity    IdentityRef
}

type ApprovalParkedError struct {
	Ref ApprovalRef
}

type ApprovalRef struct {
	ExecutionID string
	ToolCallID  string
	RequestSeq  int64
}

type ApprovalRequest struct {
	ToolCallID string
	Reason     string
}

type ApprovalResult struct {
	ToolCallID string
	Approved   bool
	Reason     string
	RequestSeq int64 `json:",omitempty"` // sequence of the host-owned APPROVAL_REQUEST; zero for legacy decisions
}

type AuthorizationRequest struct {
	Caller     CallerIdentity
	Action     Action
	SessionUID string
	Owner      CallerIdentity
	// Method is the full originating RPC name, for example
	// "/agentsessions.v1.Sessions/Exec" (Sessions_Exec_FullMethodName in genpb).
	// All checks for that RPC retain this value, including compound permissions,
	// auto-creation and recovery. Direct Go handler calls populate it too.
	// OwnerAuthorizer and OwnerAllowlistAuthorizer decide by Action, not Method.
	Method string
}

type Authorizer interface {
	Authorize(context.Context, AuthorizationRequest) error
}

type CallerIdentity struct {
	Issuer  string
	Subject string
}

type Capabilities struct {
	Resumability Resumability
	ForkSafe     bool // no un-replayable side effects mid-turn -> fork via replay is safe
	RequiresGPU  bool
	Streaming    bool
	// ReasoningReplay: the harness persists and replays opaque provider reasoning parts
	// verbatim via the provider's stateless path (not previous_response_id / server lineage).
	// This keeps a reasoning harness on STATELESS_REPLAY — it adds NO snapshot edge. Verified
	// across Anthropic/OpenAI/Gemini in the Track A reasoning-continuity spike.
	ReasoningReplay bool
}

type ComputeRef struct {
	Runtime      string
	Worker       string // pod/worker id when live/warm; empty when cold
	Snapshot     *SnapshotRef
	Capabilities RuntimeCapabilities
	Attributes   map[string]string // backend-specific, e.g. substrate actor/atespace
}

type ComputeState string

type DeletionState string

type Delta struct {
	ExecutionID string
	PartIndex   int32
	Chunk       string
	Done        bool
}

type Descriptor struct {
	ID           string
	Version      string   // stable author-owned replay version; empty is supported as unknown
	Models       []string // supported/required IDs; a subset of explicit host policy, never its default
	Tools        []ToolSpec
	Capabilities Capabilities
}

type Error struct {
	Code        int32
	Description string
}

type Event struct {
	// ExecutionID, timestamp, and content live on the Event; ordering (seq) and integrity
	// (prev_hash / content_hash) are host-assigned and live on the log-record envelope
	// (eventlog.Record / proto LogRecord), not on the harness-emitted Event.
	ExecutionID   string
	Timestamp     time.Time
	SchemaVersion int32 // versions the event body; replay survives schema skew

	Kind EventKind

	// typed body (exactly one set)
	Message        *Message
	ModelCall      *ModelCall
	ToolCall       *ToolCall
	Result         *ToolResult
	Approval       *ApprovalRequest
	ApprovalResult *ApprovalResult
	Usage          *Usage
	Lifecycle      *Lifecycle
	End            *HarnessEnd
	Err            *Error
	ExecutionStart *ExecutionStart
	Parked         *ApprovalRef `json:",omitempty"` // transport only, excluded from durable history

	Actor IdentityRef // emitter principal -> provenance on every action
}

type EventKind string

type EventSink interface {
	// Model performs a model call and returns the completion. Live: the host invokes the
	// model and records the result. Replay: the host serves the recorded result from the
	// journal and does not invoke the model. Because the result flows back through this
	// mediated call, the harness never touches a provider SDK directly — the load-bearing
	// replay rule. Reasoning parts ride in the returned ModelResponse.Message and are
	// recorded verbatim for replay/fork continuity (I2). The completion is recorded as the
	// turn's output by the host; do not also emit the same content via Output (double-record).
	//
	// ctx carries the execution's cancellation and deadline through to the provider call, so
	// a cancelled turn stops an in-flight completion instead of orphaning it. Pass the ctx
	// from Run, or one derived from it.
	Model(ctx context.Context, req ModelRequest) (ModelResponse, error)
	// Output streams assistant output (a delta or a full message).
	Output(ctx context.Context, delta string) error
	// ToolCall emits a tool call and returns its result. For CONTROLLER_MEDIATED or
	// REQUIRES_APPROVAL tools it blocks until the host returns a result; for
	// IN_HARNESS_REPORTED tools the author executes the tool and calls Report instead.
	// ctx bounds that wait: a cancelled ctx unblocks it rather than hanging on a host that
	// never replies.
	ToolCall(ctx context.Context, tc ToolCall) (ToolResult, error)
	// Report records the result of a tool the harness executed itself.
	Report(ctx context.Context, tr ToolResult) error
	// Usage records token/cost accounting. To record a model call's usage, pass the
	// ModelResponse.Usage that Model returned: Replay and Resume serve the recorded usage with
	// the recorded completion, so the same call matches the record.
	Usage(ctx context.Context, u Usage) error
}

type ExecState string

type ExecutionStart struct {
	// Model is the effective default under an explicit host policy. Empty keeps pre-policy
	// semantics, including unvalidated model requests. Omit it to preserve old journal hashes.
	Model          string `json:",omitempty"`
	Config         []byte
	ResumeFromSeq  int64
	InputCount     *int64
	Harness        string // resolved registry name; empty legacy values use the session harness
	HarnessVersion string // advertised opaque version; empty is unknown and retains legacy behavior
	// ComputeInstance is Incarnation.ComputeInstance of the compute the turn was placed on; empty when
	// the backend set none (a stateless harness, or a backend that cannot tell instances apart).
	ComputeInstance string
}

type FilePart struct {
	MIME   string
	Bytes  []byte
	URI    string
	Digest string // content digest of the URI target, so the hash-chain covers externalized bytes
	Name   string
}

type ForkOpts struct {
	ChildSessionUID string
}

type Harness interface {
	// Describe returns the static contract, used to match the harness to a Runtime.
	Describe(ctx context.Context) (Descriptor, error)

	// Run drives exactly one execution (turn). It reads the Start, emits events via
	// sink, and returns nil on COMPLETED or an error on FAILED. Cancellation via ctx.
	Run(ctx context.Context, s *Start, sink EventSink) error
}

type HarnessEnd struct {
	State string // COMPLETED | FAILED | CANCELED
	Error *Error
}

type IdentityContext struct {
	Principal IdentityRef
	MintToken TokenMinter // nil when identity is not configured (dev)
}

type IdentityRef struct {
	Principal string
	Issuer    string
	Subject   string // session-scoped sub
}

type Incarnation struct {
	ID         string
	Worker     string // pod/worker id
	Address    string // where the harness server listens, or the ingress that routes to it
	Runtime    string // "pod" | "kata" | "clh" | "substrate"
	FenceToken int64  // monotonic; the log rejects appends from a superseded incarnation
	// CallMetadata is request metadata the host must attach to every call it makes to the harness at
	// Address. A backend whose harness sits behind a shared ingress uses it to name the target
	// sandbox (substrate: ate-target-actor); a backend that hands out a direct address leaves it
	// empty. It is routing, not authentication: nothing here proves the caller's identity.
	CallMetadata map[string]string
	// ComputeInstance is an opaque identity of the compute instance behind ID that differs between two
	// instances reusing one ID (substrate: the actor's server-assigned UID, while ID is the actor
	// name). A backend sets it only when the harness keeps its state in that instance's memory
	// (REQUIRES_MEMORY_SNAPSHOT). The host records it in the turn's EXECUTION_START and refuses a turn
	// or a Resume placed on an instance other than the latest one the journal recorded for that
	// harness since the session's FORK marker, or the clone that marker recorded from Fork's
	// incarnation (ErrMemoryStateLost): a replacement holds none of the state. Suspend and a stateful
	// fork pass that recorded instance to Snapshot, which refuses another one.
	// Empty records nothing and skips the check.
	ComputeInstance string
	// RecordedCheckpoint, on the Incarnation passed to Snapshot, is the checkpoint the session's
	// journal last recorded for the session (see SessionSpec.RecordedCheckpoint); the zero value
	// means none. Suspend and a stateful fork set it. A backend whose compute can hold a snapshot
	// the journal never recorded (substrate: a capture a memory-tier Snapshot refused) refuses with
	// ErrMemoryStateLost, before capturing, compute that holds another one: capturing it again
	// would record state that is not the session's. Create, Restore and Fork leave it empty.
	RecordedCheckpoint SnapshotRef
}

type InstanceRestorer interface {
	RestoreInstance(ctx context.Context, ref SnapshotRef, recorded func() (string, error)) (Incarnation, error)
}

type Lifecycle struct {
	Kind     LifecycleKind
	Detail   string
	Snapshot *SnapshotRef // captured state, set on SUSPEND (§5.1)
	// ComputeInstance is set only on FORK: Incarnation.ComputeInstance of the compute the child was
	// cloned onto. The child's turns are compared with it until the child records its own; empty
	// (a stateless fork, or a marker written before the field existed) compares nothing.
	ComputeInstance string
}

type LifecycleKind string

type Mediation string

type Message struct {
	Role  string // system | user | assistant (A2A calls this "agent") | tool
	Parts []Part
}

type ModelCall struct {
	Model     string
	Params    map[string]string
	InputHash string // required for STATELESS_REPLAY so the §9.1 I0 check can run
	ID        string // correlation id for the served ModelResult (proto ModelCall.id)
}

type ModelPolicy struct {
	Default string
	Allowed []string
}

type ModelRequest struct {
	// Model may override Start.Model within host policy. Empty resolves to that default only
	// for policy-aware invocations; old invocations retain their original requests and hashes.
	Model    string
	Messages []Message // context (history + new input) sent to the model
	Params   map[string]string
	// Tools are the definitions offered to the model on this call. Order is significant.
	Tools []ToolDefinition `json:",omitempty"`
	// ToolChoice constrains whether and which tool the model calls. Nil means the provider default.
	ToolChoice *ToolChoice `json:",omitempty"`
}

type ModelResponse struct {
	Message Message
	Usage   Usage
}

type Origin struct {
	Source     string            // e.g. "github.com/acme/repo", "foundry/project-x"
	Subject    string            // e.g. "issues/42", "threads/abc"
	URI        string            // optional link
	Attributes map[string]string // adapter-specific extras; well-known keys via profiles
}

type OwnerAllowlistAuthorizer struct {
	Allow map[Action][]CallerIdentity
}

type OwnerAuthorizer struct{}

type Part struct {
	Text      *TextPart
	File      *FilePart
	Data      map[string]any
	Reasoning *ReasoningPart
	// ToolCall is a model's request to call a tool, carried in an assistant message. Mediation
	// and IdempotencyKey are unset on a model output. To execute the call, copy it, set them on
	// the copy, and pass the copy to EventSink.ToolCall: the returned message can share this
	// pointer with the recorded completion, so changing it in place alters a hashed event.
	ToolCall *ToolCall `json:",omitempty"`
	// ToolResult is a tool's result fed back to the model, carried in a message with role
	// "tool". ToolResult.ID is the ID of the ToolCall it answers.
	ToolResult *ToolResult `json:",omitempty"`
}

type ReasoningPart struct {
	Provider      string // "anthropic" | "openai" | "google"
	ModelID       string
	Opaque        []byte // set, OR OpaqueURI when externalized
	OpaqueURI     string
	OpaqueDigest  string // content digest of OpaqueURI target (hash-chain covers externalized bytes)
	Summary       []Part // optional, non-authoritative, compaction-droppable
	ItemID        string
	Ordinal       int32
	ValidityScope string // = execution id (turn)
}

type Resumability string

type Runtime interface {
	// Create starts a cold incarnation (sandbox) for a session and returns a handle
	// including the address where the harness server listens.
	Create(ctx context.Context, s *SessionSpec) (Incarnation, error)

	// Snapshot captures the incarnation's state. SnapshotLocal (warm/pause) keeps it
	// node-resident. SnapshotExternal owns the cold transition: it captures required state,
	// releases dedicated per-incarnation compute where applicable, and preserves the state
	// and any backend handles Restore needs. A backend without memory snapshots may return
	// a filesystem/journal handle; without dedicated per-session compute, its shared harness
	// server may remain running.
	//
	// A non-empty in.ComputeInstance is the instance the caller requires behind in.ID (the
	// latest one the journal recorded). A backend that sets ComputeInstance refuses with
	// ErrMemoryStateLost when another instance is there, or none is, before it captures anything
	// if it can tell, and in any case before returning a ref: a snapshot of a replacement would
	// hand its callers compute that holds none of the session's state. in.RecordedCheckpoint is
	// the checkpoint the journal last recorded; a backend may refuse, with ErrMemoryStateLost,
	// compute that holds another one (see Incarnation.RecordedCheckpoint).
	Snapshot(ctx context.Context, in Incarnation, kind SnapshotKind) (SnapshotRef, error)

	// Restore brings an incarnation back from a snapshot. Sub-second on memory-capable
	// backends; a filesystem-only backend restores the workspace and relies on the host
	// replaying the event log.
	Restore(ctx context.Context, ref SnapshotRef) (Incarnation, error)

	// Fork creates a child incarnation. A backend with MemorySnapshot clones ref's captured state so
	// the child continues from the parent's RAM; a filesystem-only backend returns a fresh incarnation
	// and relies on the host replaying the child's copied log prefix. Implementations must not leak a
	// partially-provisioned child: on any failure after the child exists, tear it down before returning.
	// A backend that finds ref no longer held by the parent returns an error wrapping
	// ErrSnapshotSuperseded. The host records the returned ComputeInstance on the child's FORK
	// marker, and compares the child's compute with it until the child's first turn records one.
	Fork(ctx context.Context, ref SnapshotRef, opts ForkOpts) (Incarnation, error)

	// Stop is destructive teardown: it destroys the incarnation and frees its dedicated compute.
	// Callers must not assume a captured SnapshotRef remains restorable after Stop.
	Stop(ctx context.Context, in Incarnation) error

	// Status reports the incarnation's compute-lifecycle state.
	Status(ctx context.Context, in Incarnation) (ComputeState, error)

	// Capabilities reports what this backend supports.
	Capabilities() RuntimeCapabilities
}

type RuntimeCapabilities struct {
	MemorySnapshot bool // can capture/restore RAM+process (pod: false, kata/clh: true)
	CoWFork        bool // copy-on-write fork
	Attest         bool // attestation on restore (confidential)
	GPUState       bool // accelerator state capture
}

type Session struct {
	UID     string
	Project string // tenant / namespace
	Name    string

	Harness string
	Model   string // model-agnostic id, e.g. "azure-openai/gpt-x", "anthropic/..."

	Exec         ExecState    // execution/turn axis (the event-log axis)
	ComputeState ComputeState // incarnation axis
	LastSeq      int64        // event-log cursor = the resume/replay point

	ParentUID string // set iff this session was forked
	ForkSeq   int64  // parent event seq forked at

	Identity IdentityRef
	Compute  *ComputeRef // current incarnation; nil when SUSPENDED/TERMINATED
	Origin   *Origin     // neutral external context; filled by a producer adapter

	Labels      map[string]string
	Annotations map[string]string // free-form adapter metadata (K8s-style)
}

type SessionSpec struct {
	SessionUID string
	Image      string
	Harness    string
	Identity   IdentityRef
	// StartedTurns counts the turns the session's journal records as started (an EXECUTION_START) on
	// the harness being placed, whether they completed, failed or were interrupted: any of them may
	// have changed that harness's in-memory state. For a forked child it counts the turns of the copied
	// prefix that ran on this harness. A turn another harness ran (an ExecRequest.harness override) is
	// not counted, since it left no state in this harness's compute; a turn the host cannot attribute
	// (no recorded harness name, or a name it does not serve) is.
	//
	// A backend uses it to refuse creating fresh compute for a REQUIRES_MEMORY_SNAPSHOT session that
	// already has state only its old compute held (ErrMemoryStateLost). It is a function rather than a
	// number so that the backend counts only after it has seen the compute is missing: a turn is
	// journaled before it runs, so every turn that ran on the lost compute is then visible, including
	// one another host sharing the journal recorded while this call was being placed. A backend that
	// does not need it does not call it. Nil declares a session with no started turns on this harness.
	StartedTurns func() (int, error)
	// RecordedCheckpoint reads the checkpoint the session's journal last recorded for this session:
	// the SnapshotRef of its latest SUSPEND whose Local names the session, or a zero SnapshotRef
	// (ExternalURI "") when there is none, as for a session never suspended or a fork child before
	// its first Suspend (a parent's SUSPEND in a child's copied prefix is not the child's).
	//
	// A backend whose compute can hold a snapshot the journal never recorded (substrate: a capture a
	// memory-tier Snapshot refused stays on the actor) compares it with the snapshot the existing
	// compute holds before attaching to or resuming it, and refuses another with
	// ErrMemoryStateLost. Like StartedTurns it is a function, so the backend reads the journal only
	// after it has read the compute, and sees a SUSPEND another host recorded in between. A backend
	// that does not need it does not call it. Nil declares no recorded checkpoint.
	RecordedCheckpoint func() (SnapshotRef, error)
}

type SnapshotKind string

type SnapshotRef struct {
	Local       string // node/handle-local ref, or (filesystem-only) the session handle to replay
	ExternalURI string // external blob (cold/suspend)
	Memory      bool   // RAM/process captured? kata/clh: true, pod: false
	Sealed      bool   // encrypted + attested (confidential)
}

type Start struct {
	// ExecutionID identifies this Run on the wire. Modern runs share it with journal events;
	// legacy runs use a session-scoped legacy- compatibility token that is never journaled.
	ExecutionID string
	// SessionUID carries the ControllerFrame session envelope for tool/approval correlation.
	// Model-only callers that do not use that envelope may leave it empty.
	// Model is the host-resolved default for a policy-enabled execution. Empty retains the
	// harness's existing default. Replay/resume restore the recorded value, not today's policy.
	Model         string    `json:",omitempty"`
	SessionUID    string    `json:",omitempty"`
	Config        []byte    // opaque per-execution config; journaled verbatim and restored on replay/resume
	History       []Event   // every event before this execution's start, also after a memory restore
	Inputs        []Message // invocation inputs; originals are restored on controller replay/resume
	Identity      IdentityContext
	ResumeFromSeq int64 // opaque harness cursor, journaled with Config; distinct from the append CAS cursor
}

type TextPart struct{ Text string }

type TokenMinter func(ctx context.Context, audience []string) (string, error)

type ToolCall struct {
	ID             string
	Tool           string // tool name / MCP method
	Args           map[string]any
	Mediation      Mediation
	IdempotencyKey string // dedups a retried side-effecting call tool-side (§3/I3)
}

type ToolChoice struct {
	Mode ToolChoiceMode
	Name string
}

type ToolChoiceMode string

type ToolDefinition struct {
	Name        string
	Description string
	InputSchema map[string]any // JSON Schema object; JSON-shaped values only (see package wire)
}

type ToolResult struct {
	ID           string
	Output       map[string]any
	OutputURI    string // externalized large output (MCP resource_link); else inline Output
	OutputDigest string // content digest of OutputURI target (hash-chain covers externalized bytes)
	IsError      bool
	Error        string
	// Content is the model-facing result (MCP CallToolResult.content). A harness records on the
	// TOOL_RESULT event the same ToolResult it feeds back as a tool_result part, so history rebuilt
	// from the log can give the model what it saw live.
	Content []Part `json:",omitempty"`
	// Additive durable receipt fields are omitted at zero to preserve old model-input hashes.
	Code                ToolResultCode `json:",omitempty"`
	ApprovalRequestSeq  int64          `json:",omitempty"`
	ApprovalDecisionSeq int64          `json:",omitempty"`
	// Approval carries a host decision to a direct sink caller. It is transient: neither Go JSON
	// nor wire conversion includes it in a receipt or model history. The durable decision is a
	// separate APPROVAL_RESULT event; the receipt binds it by sequence above.
	Approval *ApprovalResult `json:"-"`
}

type ToolResultCode int32

type ToolSpec struct {
	Name        string
	Description string
	Mediation   Mediation
}

type Usage struct {
	Model           string
	InputTokens     int64
	OutputTokens    int64
	ReasoningTokens int64
}