agent

type Adapter interface {
	// Ref returns the agent-runtime identifier. Must match the workflow's
	// AgentStep.Uses literal exactly (e.g. "anthropic/claude-code"). Stable
	// over the adapter's lifetime; Registry uses this as the key.
	Ref() string

	// Capabilities reports static claims about this adapter's behavior.
	// Must be callable on a freshly-constructed adapter (no per-invocation
	// state needed). Tested by Bucket 14/15 routing in slice 5.4 + 5.2.
	Capabilities() Caps

	// Version returns the concrete version string this adapter resolves to
	// for the given container handle (the binary's PATH is per-container).
	// Called once per (ref, container) pair at run start; the result is
	// persisted in run.started.Runtimes. Resume re-invokes Version and
	// hard-errors on drift (spec §8 pinning). Adapters that don't have a
	// natural binary version (the fake) return a constructor-supplied
	// constant; adapters wrapping a CLI return the CLI's --version output
	// or equivalent.
	//
	// The handle is passed so an adapter wrapping a containerized binary
	// can `Backend.Exec(handle, "claude --version")` to discover the
	// version in the binary's actual deployment environment. Slice 5.1's
	// fake adapter ignores handle.
	Version(ctx context.Context, handle container.Handle) (string, error)

	// ValidateConfig is called once per node at run start (U1's cli/with_guard.go
	// walk) AND defensively at dispatch (slice 5.2, local_dispatcher_agent.go).
	// Returns *ErrInvalidConfig with a path-aware message on rejection. Strict
	// by default: unknown keys are errors (slice 5.3 enforces this for the
	// Claude Code adapter).
	ValidateConfig(with ir.RawConfig) error

	// Launch runs the agent inside the supplied handle. Slice 5.3 γ contract:
	// returns IMMEDIATELY with both channels open. The events channel emits
	// AgentEvents as the harness produces them (one per content block for
	// assistant messages); the caller MUST range over it concurrently with
	// awaiting outcome. The events channel CLOSES when the harness's stream
	// ends (process exit + stdout pipe drain). The outcome channel delivers
	// exactly one AgentOutcome AFTER events closes, then closes itself.
	//
	// === DRAIN-OR-LEAK CONTRACT =====================================
	// Callers MUST drain the events channel to completion. Failure to
	// drain blocks the adapter's parser goroutine on `events <- ev` once
	// the channel's internal buffer fills (Claude adapter: 16 events;
	// fake adapter: scripted-event-count + 1, so unbounded for practical
	// purposes). A blocked parser goroutine cannot send AgentOutcome on
	// outcomeCh — it hangs until ctx-cancel. Two safe patterns:
	//
	//   // Sequential drain (simplest):
	//   events, outcomeCh, err := adapter.Launch(...)
	//   if err != nil { /* pre-launch failure */ }
	//   for ev := range events { /* render, log, etc. */ }
	//   outcome := <-outcomeCh
	//
	//   // Concurrent drain (runAgent's pattern — preserves realtime UX):
	//   events, outcomeCh, err := adapter.Launch(...)
	//   if err != nil { /* pre-launch failure */ }
	//   drainDone := make(chan []AgentEvent, 1)
	//   go func() {
	//       var buf []AgentEvent
	//       for ev := range events {
	//           buf = append(buf, ev)
	//           // tap.Write(ev) here — this is where realtime renders.
	//       }
	//       drainDone <- buf
	//   }()
	//   outcome := <-outcomeCh
	//   buf := <-drainDone
	//
	// Adapters that buffer events to a size matching scripted/expected
	// event count (the fake's pattern) are forgiving — caller-side bugs
	// that ignore events don't leak. The Claude adapter cannot do this
	// because event count is unknown until claude exits, so it ships a
	// fixed-size buffer and relies on the caller to drain.
	// ================================================================
	//
	// On a non-nil err return (pre-launch), BOTH channels are nil — the
	// adapter never reached the launch step. On a successful return both
	// channels are non-nil and must be drained.
	//
	// Independence (spec §5.5): when Capabilities().PersistentSession is false,
	// Launch MUST NOT reference, store, or reuse any state from a prior Launch
	// call against the same Adapter instance. When PersistentSession is true,
	// any reuse must be explicit adapter-owned provider state (for example
	// with.session), and PR0a guards prevent such adapters from running in
	// gate.evaluate.
	//
	// (Pre-slice-5.3: signature was (AgentResult, <-chan AgentEvent,
	// error) with events pre-closed before Launch returned — buffer-then-
	// burst. The γ rewrite enables true realtime UX; the events
	// buffer-then-burst pattern is preserved by the caller's
	// `for range events` loop.)
	Launch(ctx context.Context, handle container.Handle, inv AgentInvocation) (<-chan AgentEvent, <-chan AgentOutcome, error)
}

type AgentEvent struct {
	Kind    string `json:"kind"`
	Payload []byte `json:"payload,omitempty"`
	Stream  string `json:"stream,omitempty"`
	Live    bool   `json:"live,omitempty"`
	// Display is the adapter-populated, normalized summary the live renderer uses.
	// json:"-" — transient presentation. For Live events, the interpreter copies
	// sanitized scalar display metadata into agent.event; it never serializes this
	// struct directly. Zero value (DisplayOther) → terse fallback.
	Display EventDisplay `json:"-"`
}

type AgentInvocation struct {
	NodePath   string       `json:"node_path"`      // engine/path output for the AgentStep (e.g. "graph[0]" or "gate[2].attempt-1.generate[0]")
	Uses       string       `json:"uses"`           // agent-runtime ref (must match Adapter.Ref())
	RunContext RunContext   `json:"run_context"`    // explicit run/epoch identity for live-capable adapters
	With       ir.RawConfig `json:"with,omitempty"` // opaque per-runtime config; validated by Adapter.ValidateConfig
	// RoleWith is the engine-resolved (scope-substituted) role with: for a
	// DerivedAdapter-backed step. The engine substitutes the role's raw templated
	// with: against the step scope and threads it here so the role layer merges as
	// already-rendered config. Nil for a non-role step or a direct caller (tests) —
	// then DerivedAdapter falls back to its stored raw role with:. Engine
	// operational state like Thread/ResumeSession; json:"-": never journaled.
	RoleWith        ir.RawConfig   `json:"-"`
	OutputSchema    *ir.JSONSchema `json:"output_schema,omitempty"`    // step's output_schema (the adapter passes to harness as --json-schema or layer-2 extractor schema)
	Env             SecretEnv      `json:"-"`                          // env vars forwarded into the harness exec (slice 5.3 reads ANTHROPIC_API_KEY etc.); never JSON-marshaled so secrets cannot reach the state log
	IdempotencyKey  string         `json:"idempotency_key,omitempty"`  // resolved-template; passed to harness env per spec §10
	Feedback        ir.RawConfig   `json:"feedback,omitempty"`         // prior gate verdict on repair attempts > 1 (nil on attempt 1)
	Thread          []ThreadTurn   `json:"thread,omitempty"`           // engine-assembled prior turns (separate channel from Feedback); generator-only
	ContextEvidence []ThreadTurn   `json:"context_evidence,omitempty"` // evaluator-only source evidence; not active conversation history
	// InputFiles carries resolved file bytes to a CONTAINERLESS adapter (the
	// containerless analog of container.InputFile staging). Empty for
	// container-backed steps. json:"-": bytes never reach the state log.
	InputFiles []InputFile `json:"-"`
	// Attempt is the 1-based retry-attempt index the engine is currently on for
	// this node (1 on the first try, 2 on the first retry, …). Threaded from
	// NodeIntent.Attempt by the dispatcher so an adapter can distinguish a fresh
	// try from a retry. Engine operational state like ResumeSession, not author
	// with: config; json:"-": never journaled. Zero when a caller builds an
	// AgentInvocation directly (tests) without wiring it.
	Attempt int `json:"-"`
	// RecoveryContinue is true when the resolved retry.recovery strategy for this
	// step is "continue" (resume the persistent session on a retry) rather than
	// "restart". Set by the engine from the merged retry.Policy (engine resolves an
	// unset value to a per-adapter default); meaningful only for a PersistentSession
	// adapter. Combined with Attempt>0 it tells the adapter that a leftover
	// in-progress turn from a prior attempt in THIS run may be abandoned and the
	// thread resumed, instead of hard-halting for a cross-process replay. Engine
	// operational state like Attempt/ResumeSession; json:"-": never journaled.
	RecoveryContinue bool `json:"-"`
	// ResumeSession is set true by the engine when it successfully restored a
	// committed session transcript for this node before calling adapter.Launch.
	// The adapter uses it to select the correct CLI flag:
	//   - false (fresh turn): pass --session-id <uuid> (create/adopt a session)
	//   - true  (restored turn): pass --resume <uuid> (re-prime from restored transcript)
	// It is engine operational state, not author with: config — modelled after
	// the existing Thread/ContextEvidence fields. json:"-": never journaled.
	ResumeSession bool `json:"-"`
	// SessionConfigDir is the absolute per-run CLAUDE_CONFIG_DIR the engine
	// computes for claude-family adapters (<stagingRoot>/claude-session/<run-id>);
	// the adapter forwards it as the CLAUDE_CONFIG_DIR env var so claude relocates
	// its whole config tree per run. Set for any container-backed IsolatedConfigDir
	// adapter — both the base anthropic/claude-code adapter (config isolation only)
	// and the session adapter (which ALSO captures the projects/ subtree). Empty
	// for non-claude / containerless steps.
	// Engine-set, like ResumeSession — keep it out of the journal.
	SessionConfigDir string `json:"-"`
	// WorkflowDir is the absolute directory containing the step's own module's
	// workflow file (ir.LoadedModule.WorkflowPath's directory — the loader
	// resolves imports/assets relative to this same directory). The engine sets
	// it for every agent step (engine/agent_step.go, from ictx.def.Module).
	// Consumed by a Containerless PersistentSession adapter (agent/codexlive,
	// F33) to default a host-side `cwd` when the workflow author omits it —
	// codexlive has no container filesystem, so its `cwd` is a real host path
	// the harness operates in. Engine-set, like SessionConfigDir; empty only
	// when a caller builds an AgentInvocation directly (tests) without wiring it.
	WorkflowDir string `json:"-"`
}

type AgentOutcome struct {
	Result AgentResult `json:"result,omitempty"`
	Err    error       `json:"-"` // errors don't JSON-marshal well; engine state log handles errors separately
}

type AgentResult struct {
	Output   map[string]any    `json:"output,omitempty"`
	ExitCode int               `json:"exit_code"`
	Metrics  MetricSet         `json:"metrics"`
	Files    map[string][]byte `json:"files,omitempty"`
	// Live is a data-only handoff from PersistentSession adapters to the
	// dispatcher/interpreter. It carries operational registry metadata for
	// post-commit finalization; it is never a bindable output.
	Live *LiveDispatch `json:"-"`
	// Transcript is the adapter-provided verbatim {clean user prompt, verbatim
	// final assistant message} pair for continues: threading. The engine reads
	// no with: key — the ADAPTER supplies both halves (reading its own with:
	// legitimately). json:"-": never journaled raw (Phase 4 Commit content-
	// addresses it as a blob ref when the step participates in a conversation),
	// matching the Env SecretEnv json:"-" precedent.
	Transcript ThreadTurn `json:"-"`
}

type Caps struct {
	NativeSchema bool `json:"native_schema"`

	// Containerless reports that this adapter performs its work WITHOUT a
	// container (e.g. a direct network call). When true, an agent step may
	// omit `container:` (ir/validate_structural.go allows the empty ref; the
	// run-start guard in cli/runtimes.go permits it only for these adapters).
	// Zero value false -> every CLI-wrapping adapter keeps requiring a
	// container, unchanged.
	Containerless bool `json:"containerless"`

	// Threaded reports that this adapter prepends an engine-supplied
	// AgentInvocation.Thread to its request (continues: threading). This drives
	// conformance routing plus CLI and defensive engine guards (a continues:
	// step against a non-Threaded adapter fails fast). Direct Containerless
	// precedent.
	Threaded bool `json:"threaded,omitempty"`

	// ContextEvidence reports that this adapter can render engine-assembled
	// evaluator source context as evidence, without treating it as an active
	// conversation continuation. Normal continues: threading still uses Threaded.
	ContextEvidence bool `json:"context_evidence,omitempty"`

	// PersistentSession reports that this adapter can reuse a live/persistent
	// session across launches. It is a static runtime declaration used by CLI
	// guards, defensive engine guards, conformance routing, and docs. Zero value
	// false preserves the fresh-launch behavior required for gate evaluators;
	// PersistentSession adapters are rejected in gate.evaluate contexts while
	// remaining allowed elsewhere, including gate.generate.
	PersistentSession bool `json:"persistent_session,omitempty"`

	// InlineInputFiles reports that a Containerless adapter delivers a step's
	// input_files to the model as inline message parts (agent.InputFile) rather
	// than staging into a container. awf/llm does this; codex-live does not.
	// Zero value false FAILS CLOSED: the run-start guard rejects a containerless
	// step declaring input_files against a non-inline adapter instead of
	// silently dropping the files.
	InlineInputFiles bool `json:"inline_input_files,omitempty"`

	// IsolatedConfigDir reports that this adapter benefits from a per-run,
	// RunID-keyed isolated config directory (mapped to its config-dir env var,
	// e.g. CLAUDE_CONFIG_DIR) so concurrent runs do not collide on shared host
	// config. The engine computes the dir (<staging-root>/claude-session/<run-id>)
	// and threads it via AgentInvocation.SessionConfigDir; the adapter sets it on
	// the exec env. Container-backed only (a Containerless adapter has no container
	// filesystem to isolate). Orthogonal to PersistentSession, which ADDITIONALLY
	// captures/restores the session as that dir's projects/ subtree.
	IsolatedConfigDir bool `json:"isolated_config_dir,omitempty"`

	// SurfacesLiveness grades how finely this adapter streams live progress
	// signals a stall watchdog can trust as proof the turn is still working.
	// The zero value LivenessNone means "not measured / no signal", so an
	// adapter that hasn't been characterized never overclaims. Only adapters we
	// have MEASURED set a higher tier (codexlive = Coarse, claude-family = Fine).
	SurfacesLiveness Liveness `json:"surfaces_liveness,omitempty"`
}

type CredentialNamer interface {
	RequiredEnv() []string
}

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

type DisplayClass uint8

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

type ErrAdapterAlreadyRegistered struct {
	Ref string
}

type ErrAdapterNotFound struct {
	Ref string
}

type ErrAgentLaunch struct {
	Cause     error
	RetryHint *RetryHint
}

type ErrInvalidConfig struct {
	Ref    string // adapter ref (e.g. "anthropic/claude-code")
	Key    string // the with-key that caused the error (e.g. "session_id"); empty if the whole config is bad
	Reason string // human-readable reason

	// KeyUnknown is true when the rejection is an unknown with-key (a typo'd
	// or wrong-adapter key name). The run-start guard always surfaces these;
	// value-shape errors are suppressed for templated ("{{...}}") values.
	KeyUnknown bool
}

type ErrUnparseableOutput struct {
	NodePath string
}

type EventDisplay struct {
	Class   DisplayClass
	Tool    string // tool name (ToolCall/ToolResult)
	Text    string // see semantics above
	Lines   int    // ToolResult: full output line count (0 = n/a)
	Bytes   int    // ToolResult: full output byte size (0 = n/a)
	IsError bool   // ToolResult/Error: failure state
}

type InputFile struct {
	Name    string
	Content []byte
	MIME    string
}

type LiveDispatch struct {
	AdapterRef     string
	SessionKey     string
	SessionKeyHash string
	LeaseID        string
	ActiveTurnID   string
	ProviderTurnID string
	RunID          string
	NodePath       string
	Epoch          uint32
	CommittedUnix  int64
}

type LiveResumePreflightRequest struct {
	NodePath     string       `json:"node_path"`
	AdapterRef   string       `json:"adapter_ref"`
	With         ir.RawConfig `json:"with,omitempty"`
	RunID        string       `json:"run_id"`
	CurrentEpoch uint32       `json:"current_epoch"`
	NextEpoch    uint32       `json:"next_epoch"`
}

type Liveness uint8

type MetricCost struct {
	Source   string  `json:"source,omitempty"`   // CostSourceReported | CostSourceDerived
	Currency string  `json:"currency,omitempty"` // ISO-4217; empty == USD
	Total    float64 `json:"total,omitempty"`
	Input    float64 `json:"input,omitempty"`  // derived only; includes cache, folded (future task)
	Output   float64 `json:"output,omitempty"` // derived only
}

type MetricSet struct {
	Cost   MetricCost   `json:"cost"`
	Tokens MetricTokens `json:"tokens"`
	Turns  int          `json:"turns"`
	// Model is the id pricing keyed on: the resolved model if the harness reported it
	// (claude system/init, codexlive thread/start), else the requested with:{model}, else empty.
	Model string `json:"model,omitempty"`
}

type MetricTokens struct {
	Input              int `json:"input"`
	Output             int `json:"output"`
	CacheCreationInput int `json:"cache_creation_input,omitempty"`
	CacheReadInput     int `json:"cache_read_input,omitempty"`
}

type ReactTurn struct {
	Role       string     `json:"role"`
	Content    string     `json:"content,omitempty"`
	ToolCalls  []ToolCall `json:"tool_calls,omitempty"`   // assistant turns only; OMIT (not []) when none
	ToolCallID string     `json:"tool_call_id,omitempty"` // tool turns only
}

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

type Resolver interface {
	// Lookup returns the Adapter registered under ref (true) or (nil, false)
	// if no such adapter is registered. Concurrency-safe; multiple goroutines
	// may Lookup concurrently (Phase 3 parallel branches dispatch concurrently
	// after Phase 5 wires AgentStep).
	Lookup(ref string) (Adapter, bool)
}

type ResumePreflighter interface {
	PreflightResume(context.Context, LiveResumePreflightRequest) error
}

type RetryHint struct {
	RetryAfter time.Duration
}

type RoleResolvedValidator interface {
	ValidateResolvedConfig(resolvedRole, step ir.RawConfig) error
}

type RoleWithProvider interface {
	RoleWith() ir.RawConfig
}

type RunContext struct {
	RunID        string `json:"run_id"`
	CurrentEpoch uint32 `json:"current_epoch"`
	NextEpoch    uint32 `json:"next_epoch"`
}

type SecretEnv map[string]string

type ThreadTurn struct {
	User      string `json:"user"`
	Assistant string `json:"assistant"`
}

type ToolCall struct {
	Index     int    `json:"index"` // stable position; the J in react[N].round-K.tool-J
	ID        string `json:"id"`    // matches the tool-role message's tool_call_id
	Name      string `json:"name"`
	Arguments string `json:"arguments"`
}

type ToolDef struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"input_schema"`
}

type ToolLoopInvocation struct {
	NodePath     string         `json:"node_path"`
	Uses         string         `json:"uses"`
	With         ir.RawConfig   `json:"with,omitempty"`
	Messages     []ReactTurn    `json:"messages"`
	Tools        []ToolDef      `json:"tools"`
	OutputSchema *ir.JSONSchema `json:"output_schema,omitempty"` // steers response_format (§6); engine validates post-hoc
}

type ToolLoopResult struct {
	Text         string         `json:"text"`
	Output       map[string]any `json:"output,omitempty"`
	ToolCalls    []ToolCall     `json:"tool_calls,omitempty"`
	FinishReason string         `json:"finish_reason"`
	Metrics      *MetricSet     `json:"metrics,omitempty"`
}

type ToolLoopRunner interface {
	RunToolLoop(ctx context.Context, inv ToolLoopInvocation) (ToolLoopResult, error)
}