adapter

type Adapter interface {
	// Name is the stable, non-empty identifier of the CLI this adapter drives
	// (e.g. "claude-code"). It never changes across calls.
	Name() string

	// Binary is the executable name to find on PATH (e.g. "claude"). It is a
	// pure descriptor — non-empty, never a path with metacharacters — that the
	// CORE Detect function feeds to a HostProber's LookPath. The adapter owns no
	// fds: it merely names what to look for.
	Binary() string

	// VersionArgs are the arguments that make the CLI print its version
	// (e.g. {"--version"}). It is a pure descriptor and must be non-nil (an
	// empty slice, meaning "the bare binary prints its version", is allowed;
	// nil is not). Detect passes these to HostProber.Run.
	VersionArgs() []string

	// ParseVersion extracts a semantic version from the version command's stdout.
	// It is PURE and TOTAL: it never panics on any string (garbage, empty,
	// multibyte, unbounded) and is deterministic. ok==true implies a non-empty
	// version. Detect calls it on the stdout HostProber.Run captured.
	ParseVersion(output string) (version string, ok bool)

	// SupportedVersions is the inclusive version range this adapter is known to
	// drive correctly.
	SupportedVersions() VersionConstraint

	// Command composes the exec argv for a fresh launch. argv[0] is a real
	// program path — never a shell, never a single metacharacter-bearing string.
	// It is pure: the same spec yields the same argv, and it opens nothing.
	Command(spec LaunchSpec) ([]string, error)

	// Options is the declarative launch-option schema the launch form renders.
	Options() []OptionSpec

	// SignalSources declares how this CLI's idle/active signal is observed
	// (hooks, an event stream, or grid heuristics).
	SignalSources() []SignalSource

	// Resume composes the exec argv to resume an existing conversation. With no
	// ConversationID it returns an empty argv (nothing to resume); a non-empty
	// argv always carries the id.
	Resume(spec ResumeSpec) ([]string, error)

	// ExtractConversationID reads the conversation id out of the CLI's rendered
	// grid and/or raw transcript tail. It is TOTAL — never panics on a nil or
	// garbage grid+tail — and deterministic. ok==true implies a non-empty id.
	ExtractConversationID(grid *vt.Snap, tail []byte) (string, bool)
}

type ApprovalApplier interface {
	// ApprovalKeys returns the keystrokes that answer the dialog CURRENTLY on
	// snap with the given verdict (VerdictAllow | VerdictDeny), to be written to
	// the session's PTY VERBATIM.
	//
	// action is the PENDING REQUEST'S own ToolAction.Type, as the adapter
	// classified it at capture, and the adapter must refuse a dialog that is not
	// THAT request's. Proving only that some answerable dialog is on screen is
	// not enough: a hook is fire-and-forget, so a dialog reaches the glass before
	// its own card exists, and an answer for the request the owner just closed at
	// the terminal would otherwise be typed into the one that replaced it. Which
	// screens belong to which action is per-CLI knowledge and therefore the
	// adapter's, exactly like the key map.
	//
	// ok is false for any grid the adapter cannot positively identify as a
	// dialog it has a RECORDED key map for, for a dialog raised by a different
	// action than the request's, and for a verdict that dialog has no key for.
	// All three are refusals and never guesses: a key returned for the wrong
	// screen is typed into whatever has focus, while a refusal only declines the
	// phone's tap and leaves the terminal's own dialog untouched.
	ApprovalKeys(snap *vt.Snap, verdict, action string) (keys string, ok bool)
}

type AuthProbe interface {
	// AuthCredentialsFile is the credentials file path RELATIVE to the user
	// home directory (e.g. ".codex/auth.json"). It returns a relative path,
	// never an absolute one: the core joins it beneath the daemon's home, and
	// joining is the core's act.
	AuthCredentialsFile() string

	// AuthIdentity derives a stable ACCOUNT identity from the file's raw bytes.
	// The contract that makes the watcher sound: the identity is INVARIANT
	// under routine token refreshes (providers rewrite the file with fresh
	// tokens on a cadence, so mtime or a whole-file hash would false-positive)
	// and changes exactly when the logged-in account changes. The value must
	// never carry a secret -- derive a digest, not the token. ok==false means
	// the bytes do not parse as this provider's credentials (mid-login, a
	// truncated write, garbage), which the watcher treats as "unknown: hold".
	AuthIdentity(raw []byte) (identity string, ok bool)
}

type BackendPlan struct {
	// Program is the backend executable's NAME on PATH (e.g. "codex"). It must contain
	// no path separator: naming a program and naming a path are different acts, and only
	// the first is the adapter's.
	Program string
	// Args are the backend process's arguments (argv[1:]).
	Args []string
	// AgentArgs are appended VERBATIM to the agent's own argv so it attaches to the
	// backend the core started. Empty is legal.
	AgentArgs []string
}

type BackendSource interface {
	// Backend describes the side process for one session, or reports ok==false.
	//
	// ok == false IS THE ORDINARY CASE and never a defect: most CLIs need no backend, and
	// an adapter that answers false is complete and fully supported (ADR-010 §5's posture).
	//
	// PURE and TOTAL on Interactions' terms: deterministic, never panics on an empty or
	// pathological SocketPath, and it performs no I/O.
	Backend(spec BackendSpec) (BackendPlan, bool)
}

type BackendSpec struct {
	// SocketPath is the per-session backend endpoint, inside the session state dir.
	SocketPath string
}

type CapabilityEntry struct {
	CLI            string   `json:"cli"`
	Version        string   `json:"version"`
	Hooks          bool     `json:"hooks"`
	Resume         bool     `json:"resume"`
	ConversationID bool     `json:"conversation_id"`
	Options        int      `json:"options"`
	Signals        []string `json:"signals"` // sorted, de-duped SignalSource kinds
}

type ContextGuardAction struct {
	Method            string
	ThreadIDParameter string
	AutomaticDispatch bool
	Support           ContextGuardSupport
}

type ContextGuardContinuer interface {
	// ContextGuardContinuation returns the request that starts text as the
	// continuation turn on thread. Pure, total, no I/O, and version-fenced
	// exactly like the automatic action: ok=false means nothing may be sent.
	ContextGuardContinuation(version, threadID, text string) (method string, params map[string]any, ok bool)
}

type ContextGuardEventKind string

type ContextGuardNotification struct {
	Kind         ContextGuardEventKind
	ThreadID     string
	UsedTokens   uint64
	ContextLimit uint64
	Quality      ContextGuardQuality
	Deprecated   bool
}

type ContextGuardQuality string

type ContextGuardSource interface {
	ParseContextGuardNotification(raw []byte, expectedThreadID string) (ContextGuardNotification, bool)
	ContextGuardAction(version string) (ContextGuardAction, bool)
}

type ContextGuardSupport string

type ConversationIDValidator interface {
	IsValidConversationID(string) bool
}

type ConversationIdentitySource interface {
	ConversationIDFromEvent(HookPayload) (string, bool)
}

type DatedTranscriptLayout interface {
	// TranscriptDay returns the UTC calendar day the CLI filed convID's transcript
	// under, when the id itself carries that day, and false when it does not. It does
	// NOT validate convID beyond what reading the day needs -- callers owe
	// IsCanonicalConversationID before it and an os.Root anchor after it.
	TranscriptDay(convID string) (time.Time, bool)
}

type DecisionAction struct {
	Reply json.RawMessage
}

type DecisionChoice struct {
	ID    string
	Label string
	// Verdict is this decision's grant/refuse polarity: allow | deny | other.
	// REQUIRED on an approval_request (conformance obligation, owner ruling
	// 2026-08-07); Validate additionally rejects a value outside the three.
	//
	// It is the daemon's only source for §3.6's allowed/denied split. Nothing
	// downstream can derive it: the ids are the CLI's own by §3.5's design, and a
	// daemon classifying `cancel` as a refusal would be guessing at a vocabulary
	// it does not own — the posture IS-TOOL-2 forbids for the same reason. The
	// adapter knows it at capture, which is where Mode is decided too.
	//
	// ponytail: MACHINE-SIDE, like Keystrokes — it is never copied onto the item
	// and never reaches the phone. The card labels its buttons from
	// decisions[].label (IS-APR-3) and no phone surface switches on polarity, so a
	// wire field would be a second place for the two to disagree. A phone that
	// later needs it (styling a destructive button) is an additive §3.5 field and
	// a schema change, not an unused field shipped ahead of its consumer.
	Verdict string
}

type Detection struct {
	Found    bool   // the CLI binary was located
	Path     string // absolute path to the binary, when Found
	Version  string // detected version string, when Found
	InRange  bool   // Version falls within SupportedVersions
	ProbeErr string // first line of the version probe's output when it errored/exited non-zero (the CLI's own diagnostic, e.g. codex's "Reinstall Codex"); empty on success

	// ConfiguredModel and Models are ADDITIVE DATA ONLY — the frozen contract
	// gains fields, no behavior. The CORE Detect above never sets them (it stays
	// I/O-free); they are filled by the host-I/O model probe in
	// internal/adapter/detect (reading each CLI's on-disk config) and consumed by
	// the launch-form model-option overlay in cmd/swarm.
	ConfiguredModel string        // the model the CLI is actually configured to default to (best-effort; empty when unknown), pre-filling the launch form's model field
	Models          []ModelChoice // the model choices the CLI exposes, discovered from its config (best-effort; nil when the CLI has no enumeration or none could be read)
}

type Fixture struct {
	SchemaVersion int           `json:"schema_version"`
	CLI           string        `json:"cli"`
	Version       string        `json:"version"`
	Scenario      string        `json:"scenario"`
	PTYCapture    []byte        `json:"pty_capture"` // base64 on the wire
	HookPayloads  []HookPayload `json:"hook_payloads,omitempty"`
}

type HookPayload struct {
	Event        string          `json:"event"`
	Raw          json.RawMessage `json:"raw"`
	ReceivedAtMs int64           `json:"received_at_ms"`
}

type HostProber interface {
	// LookPath resolves name to an absolute program path, or returns an error if
	// it is not found on PATH.
	LookPath(name string) (string, error)
	// Run executes path with args and returns its combined version stdout.
	Run(path string, args []string) (stdout string, err error)
}

type Interaction struct {
	// Kind is one of the eight kinds above. Required.
	Kind string
	// Status is one of the four statuses above, or empty when the kind carries
	// none (interaction-schema.md §2: "absent means not applicable to the kind").
	Status string

	// Ref is the CLI's OWN id for this interaction, in the CLI's own vocabulary.
	// It is NOT the item_id and never reaches the phone: the daemon mints the
	// ULID item_id (IS-APR-1 leaves exactly one id on the wire) and maps Ref to
	// it. It serves two machine-side jobs, which is why there is one field and
	// not two:
	//
	//   - it is the ref Decision(ref, decisionID) is later called with, for an
	//     approval_request (ADR-010 §4);
	//   - it is the correlation key that lets the daemon fold successive records
	//     of ONE item under one item_id — the agent_message increments of
	//     IS-DELTA-1 and the tool_run open+close IS-DELTA-3 collapses. The
	//     adapter is the only party that sees the CLI's own id, so nobody else
	//     can supply it.
	//
	// Empty for a self-contained one-record item.
	Ref string

	// ClientRef is the id THE CLIENT supplied when it originated this interaction, echoed
	// back by the CLI verbatim -- Codex's `userMessage.clientId`, which the daemon set as
	// `clientUserMessageId` on turn/start or turn/steer.
	//
	// It exists because it is the ONLY exact composer-echo correlation any provider offers.
	// The alternative -- matching the echoed prompt by TEXT -- has a probed mis-attribution
	// on record (internal/skeleton/chat.go's pendingSendTTL doc: an OWNER-typed "yes" was
	// stamped source=phone because a phone send of "yes" was still pending). An adapter
	// whose CLI carries no such id leaves this empty, and the daemon falls back to what it
	// already does.
	//
	// Like Ref, it is MACHINE-SIDE: the daemon consumes it and it never reaches the wire.
	ClientRef string

	// TurnRef is the CLI's OWN id for the TURN this interaction belongs to -- Codex's
	// `params.turnId`, a UUIDv7 the app-server mints.
	//
	// THE TURN RULE ITSELF IS STILL THE DAEMON'S. IS-ENV-1 says a turn opens on a
	// user_message and closes on a terminal agent_message, `turn_id` on the wire is the
	// daemon's own ULID, and none of that changes: this field sources NO boundary and
	// decides NO grouping. It is the third machine-side correlation key beside Ref and
	// ClientRef, and it exists for one reason -- a provider whose turn operations take the
	// CLI's own turn id as a PRECONDITION cannot be driven with an id the CLI never minted.
	//
	// PROBED (Wave R7 review BLOCKING 1, and confirmed against the real 0.147.0 server):
	// `turn/steer` documents expectedTurnId as "Required active turn id precondition. The
	// request fails when it does not match the currently active turn", and R7 round 1 sent
	// the daemon's 26-char ULID against the server's UUIDv7 -- so EVERY mid-turn phone send
	// was rejected, and `turn/interrupt` was worse, because the server's honest
	// `no active turn to interrupt` for an id it had never seen was swallowed as benign and
	// a Stop that stopped nothing reported success.
	//
	// Like Ref and ClientRef it is MACHINE-SIDE and never reaches the wire. An adapter whose
	// CLI has no turn identity leaves it empty, and the daemon's turn state is unaffected.
	TurnRef string

	// user_message (§3.1) / agent_message (§3.2). Text on an agent_message is the
	// INCREMENT this record appends, never the accumulated body (IS-DELTA-1).
	Text       string
	Source     string // user_message only: phone | owner | derived
	StopReason string // agent_message terminal record only: end_turn | interrupted | error

	// tool_run (§3.3). ExitCode is meaningful only for an execute action; the
	// daemon omits it otherwise, so a zero here is not "exited 0" for a read.
	Tool             string
	Action           ToolAction // §7; also the approval_request summary action
	OutputExcerpt    string
	TruncationMarker string // the CLI's own truncation text, VERBATIM (IS-TOOL-3)
	ExitCode         int

	// file_change (§3.4). IS-FC-1: only an APPLIED change is a file_change; a
	// proposed edit is an approval_request.
	Path        string
	Change      string // create | modify | delete | rename
	OldPath     string // rename only
	DiffExcerpt string // unified diff text; the producer normalizes (spike-SB: Claude's Edit body is old_string/new_string)
	Added       int
	Removed     int

	// approval_request (§3.5). content_hash, expires_at and the agent_instance
	// binding tuple are daemon-authoritative and deliberately absent here.
	Summary   string
	Decisions []DecisionChoice // the CLI's OWN decision vocabulary, not a normalized one
	// Mode declares the apply mechanism AT CAPTURE, because that is where the
	// spike-SC carve-out is decidable — the adapter can see the tool and its
	// input then, so the daemon knows before the phone renders whether the
	// request resolves natively (ADR-010 §4).
	Mode        string
	PromptLines []string // prompt_card only: the sanitized prompt region, as text

	// Keystrokes is the decision->keystroke map, keyed by DecisionChoice.ID.
	// Present IFF Mode == prompt_card, because Decision is never called on that
	// path, so the map must be produced at capture (ADR-010 §2/§4).
	//
	// ponytail: this is MACHINE-SIDE data with a deliberate ceiling — the daemon
	// holds it and SHALL NOT copy it onto the item. IS-APR-3 forbids the item
	// carrying it and IS-LIFE-6 forbids the phone authoring the keystroke, so a
	// wire field for it would only invite the implementation those rules exist to
	// prevent. It rides Interaction because Interaction is the only adapter->core
	// carrier there is; DecisionAction deliberately has no Keys field.
	Keystrokes map[string]string

	// plan_update (§3.7). IS-PLAN-1: latest-state, not incremental.
	Revision int
	Steps    []PlanStep
}

type InteractionSource interface {
	// Interactions maps ONE captured event body to zero or more items. PURE and
	// TOTAL, on the same terms as ExtractConversationID: never panics on a nil,
	// truncated, garbage, or unbounded body; deterministic; and it never returns
	// content it did not observe in p.Raw.
	Interactions(p HookPayload) []Interaction

	// Decision describes HOW to apply one offered choice to the pending approval
	// named by ref, as a descriptor the CORE executes — the adapter performs no I/O
	// (E9.2), exactly as Command/Resume return an argv core runs. ok == false means
	// this CLI has no native mechanism here and the daemon must use the prompt card.
	//
	// decisionID is a DecisionChoice.ID — the CLI's OWN vocabulary (§3.5), which is
	// what the adapter itself offered. It is NOT DecisionChoice.Verdict: the
	// normalized allow|deny|other bit is what the DAEMON classifies §3.6's
	// allowed/denied from, and an adapter switching on it here would be answering a
	// choice it never offered.
	Decision(ref, decisionID string) (DecisionAction, bool)
}

type KeystrokeComposer interface {
	// ComposerKeys is the byte sequence that enters text into the CLI's own composer,
	// written to the session's PTY verbatim. The daemon supplies the submit framing.
	ComposerKeys(text string) []byte
}

type LaunchGateAnswerer interface {
	// LaunchGateKeys returns the keystrokes that ACCEPT the gate currently on snap, to be
	// written to the session's PTY verbatim as one complete answer (select and confirm).
	//
	// ok is false for any grid the adapter cannot positively identify as that gate, with
	// its options on screen and the selection state readable. A refusal types nothing; a
	// key returned for the wrong screen is typed into whatever has focus.
	LaunchGateKeys(snap *vt.Snap) (keys string, ok bool)
}

type LaunchSpec struct {
	Cwd           string
	Name          string
	Options       map[string]string
	InitialPrompt string
}

type LiveName struct {
	Name  string
	Since time.Time
}

type LiveNameSource interface {
	// LiveNameDir is the registry directory, relative to the daemon user's home.
	LiveNameDir() string
	// LiveNameFromFile parses one registry file. ok reports that the file names
	// conversationID's session AND carries a usable name and timestamp. Total and
	// deterministic on any input.
	LiveNameFromFile(raw []byte, conversationID string) (LiveName, bool)
}

type ModelChoice struct {
	ID      string
	Display string
}

type OptionSpec struct {
	Key      string   // unique option key
	Label    string   // human-readable label
	Type     string   // "string" | "bool" | "choice"
	Default  string   // default value; for a choice it must be "" or one of Choices
	Choices  []string // permitted values when Type == "choice"
	Suggest  []string // optional curated values an editable string option cycles (left/right); empty = free text only
	Required bool     // the form must collect a value
}

type PlanStep struct {
	Text  string
	State string // pending | in_progress | completed | cancelled
}

type ResumeSpec struct {
	Cwd            string
	ConversationID string
	Name           string
	Options        map[string]string
}

type SessionNameRequest struct {
	Method string
	Params map[string]string
}

type SessionNameSync interface {
	SetSessionName(conversationID, name string) (SessionNameRequest, bool)
	SessionNameFromEvent(HookPayload) (conversationID, name string, ok bool)
}

type SignalSource struct {
	Kind       string
	Descriptor map[string]string
}

type ToolAction struct {
	Type    string // read | edit | write | search | execute | fetch | other
	Path    string // read/edit/write
	Query   string // search
	Command string // execute
}

type TranscriptLayout interface {
	// ProjectDirName encodes a working directory into the single directory name
	// the CLI files that cwd's transcripts under (e.g. "/a/b" -> "-a-b"). It
	// returns a BARE NAME, never a path: the core joins it beneath the provider
	// root it opened, and joining is the core's act.
	ProjectDirName(cwd string) string

	// TranscriptFileName names the transcript file for one conversation id
	// within that directory. It does NOT validate convID -- callers owe
	// IsCanonicalConversationID before this and an os.Root anchor after it.
	TranscriptFileName(convID string) string
}

type TurnInterrupter interface {
	// InterruptKeys is the CLI's OWN cancel sequence, written to the session's PTY
	// verbatim. It must be non-empty: a declared interrupt that types nothing is a Stop
	// button that does nothing.
	InterruptKeys() []byte
}

type VersionConstraint struct {
	Min string
	Max string
}