agent

Overview ¶

agent.go defines the Agent facade: the struct that binds Options to real ACP wire methods over a *protocol.Conn (see conn.go's Handle/HandleNotify). This file wires only initialize, authenticate, and logout — the methods whose behavior does not depend on a live session (session/new and everything after it are later tasks; see the phase plan in harness/docs/plans/2026-07-23-acp-bridge-implementation.md).

capabilities.go computes the AgentCapabilities advertised in the initialize response from an Agent's Options: the capability advertisement matrix described in Task 2.2 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

close.go implements the session/close orchestration state machine: Task 2.7 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

Per the design doc's "Cancellation and close" section, session/close is "an orchestrated lifecycle operation, not a direct registry delete":

1. Mark the ACP session closing and reject new prompts (promptTracker. markClosing, reused from prompt.go's begin/end machinery — Task 2.4).
2. Cancel in-flight work with behavior equivalent to session/cancel (LiveSession.Interrupt — the same call handleSessionCancel already makes; not reimplemented here).
3. Resolve outstanding permission requests owned by the connection (gateTracker.CancelSession, Task 2.6's own integration point: it unblocks any pending client.RequestPermission call with ctx.Err(), which drainToTerminal's failGateClosed path already turns into RespondGate(Deny) automatically — no separate deny-delivery code is needed here).
4. Wait for the in-flight prompt (if any) to actually finish draining — not fire-and-forget: the channel promptTracker.markClosing returns closes only once the drained handlePrompt call has returned.
5. Call the optional SessionCloser.Shutdown capability, bounded by closeShutdownGrace.
6. Remove the session from the live registry — only now, after every step above has completed.

Durable history is never touched here: SessionDeleter (session/delete) is a completely separate optional capability this handler never calls.

compact.go implements the `/compact` internal slash command and its available_commands_update advertisement: Task 4.2 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

`/compact` is the one and only internal Harness command this facade ever exposes through session/prompt (see the design doc's "Slash commands and compaction": "No other internal Harness command is automatically exposed."). It exists only when Options.Compactor is configured (host.go); handlePrompt (prompt.go) checks isCompactSlashCommand on every incoming prompt and, only when both conditions hold, routes to handleCompactPrompt below instead of the ordinary Submit path — any other slash-prefixed (or plain) text, or "/compact" itself when no Compactor is configured, falls through unchanged to blocksFromPrompt/Submit exactly as before this task.

Correlating a compaction command's outcome differs from Task 2.4's turn correlation (prompt.go's drainToTerminal). A submitted turn only learns its LoopID/TurnID from an intervening TurnStarted event, so drainToTerminal needs two phases: correlate the loop/turn first, then match every subsequent event against it. A compaction attempt's own terminal events — CompactWaiterResolved and CompactWaiterRejected (harness/pkg/event/compaction.go) — already carry Header.Cause.CommandID directly (they are Reply events: see event.Reply and event.CompactWaiterReplyID), so a single phase suffices: drainCompactionToTerminal matches the submitted command id straight off each event it observes, with no intermediate "started" event to wait for.

available_commands_update is advertised lazily: the first time handlePrompt runs for a session (see ensureAvailableCommandsAdvertised), not eagerly at session/new/session/load/session/resume. This is a deliberate choice, not an oversight: session/resume's own documented contract is to send zero session/update notifications at all (see resume.go's package doc, an already-tested invariant), so hooking advertisement into session establishment would either have to special-case resume out again or silently break that invariant. Tying it to the first prompt instead reaches every session-establishment path uniformly, without touching session.go/resume.go/replay.go at all.

Options.Compactor is a connection-level field, set once before any session exists, so it answers exactly one question: whether compaction is available at all, for the sole purpose of deciding whether to advertise and route `/compact` (above, and ensureAvailableCommandsAdvertised below). It is NEVER invoked to actually perform a compaction — a single connection-wide field cannot tell two different sessions' compactions apart, so the actual Compactor for a given `/compact` call is always resolved from that SPECIFIC session's live value instead (live.(Compactor) in handleCompactPrompt), the same per-session type-assertion pattern SessionCloser already uses (host.go's Compactor doc; close.go's live.(SessionCloser)).

config.go implements the session/set_config_option and session/set_mode handlers: Task 4.1 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md, the first task of Phase 4.

Both wire methods run through the single unexported applyConfigOption: handleSessionSetConfigOption calls it with the request's own configId/ value, and handleSessionSetMode calls it with the well-known ModeConfigOptionID (host.go) and the requested mode id reinterpreted as a SessionConfigValueID. There is no second, independent "apply a mode change" implementation anywhere in this package — this is what keeps the two wire methods convergent rather than two behaviors a future change could accidentally let drift apart.

applyConfigOption itself:

1. Fetches the LATEST RuntimeConfigCatalog snapshot for this request — never one cached from session/new, an earlier request, or anywhere else. All external input (configId/value) is untrusted, so it is validated against what is true right now.
2. Rejects an unknown configId or an unknown value for that configId (InvalidParams), fail closed, before the RuntimeConfigController is ever consulted.
3. Short-circuits to a no-op success when the requested value already equals the option's current value: config writes are idempotent (see RuntimeConfigController's doc in host.go), and this facade enforces that itself rather than trusting every controller implementation to — the controller is not called, and no notification is sent.
4. Otherwise calls RuntimeConfigController.SetRuntimeConfigOption, then sends exactly one config_option_update session/update notification carrying the complete resulting option state, before returning that same state to the caller.

initialConfigState is the second entry point into this file's translation logic: session.go's handleSessionNew, replay.go's handleSessionLoad, and resume.go's handleSessionResume all call it to populate their response's ConfigOptions/Modes fields with the newly-established session's current RuntimeConfigCatalog snapshot, reusing translateRuntimeConfigOptions (the exact same helper applyConfigOption's own response uses) rather than a second, independent translation.

delete.go implements the session/delete handler: Task 3.4 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md, the final task of Phase 3.

session/delete is the deliberate converse of close.go's own invariant. close.go documents that "durable history is never touched" by session/close -- SessionDeleter is a completely separate optional capability that handler never calls. This file is the mirror image: it is the ONLY path in this package that may ever invoke SessionDeleter, and only for a sessionId that does NOT currently name a live, registered session (a.sessions.get, registry.go). Attempting to delete a session while it is still live is rejected outright, before the Deleter is ever consulted: durable history must never be deleted out from under a live session, so a client must session/close it first (see the design doc's "Cancellation and close": "Delete remains separate and is advertised only when a host supplies explicit storage and authorization semantics").

Wire error for "session still active" ¶

The pinned schema (protocol/schema/v1/schema.json) defines DeleteSessionRequest as exactly {sessionId, _meta} and DeleteSessionResponse as exactly {_meta} -- no dedicated field or error code anywhere in the schema names "the session is still active" as a distinguished condition, unlike (for example) ErrorCodeResourceNotFound or ErrorCodeAuthenticationRequired, which the schema's ErrorCode $def does single out. Absent a schema-documented specific code, this handler reports the rejection as protocol.InvalidRequest (-32600), reusing the exact precedent prompt.go's ErrSessionClosing and ErrPromptAlreadyInFlight already set for an analogous "invalid given current session state" condition (see prompt.go's handlePrompt) -- not a guessed or novel mapping.

gates.go implements the ACP permission-gate bridge: Task 2.6 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

prompt.go's drainToTerminal (Task 2.4) correlates a session/prompt to its exact turn and drains that turn's event stream to its terminal, forwarding every translatable Public event along the way as a session/update notification (Task 2.5). A turn can also PARK on an open gate mid-drain: a tool call awaiting human approval (gate.KindPermission) or an explicit user question (gate.KindAskUser) blocks the loop until it is answered. This file adds the handling drainToTerminal needs for that: when it observes a correlated, Public event.GateOpened for a translatable gate, it issues a session/request_permission call on the client connection, waits for the client's chosen option, validates that option was genuinely one that was offered, and answers the durable gate via LiveSession.RespondGate with the matching gate.GateResponse — all before drainToTerminal continues draining toward the turn's eventual terminal.

Only gate.KindPermission is translated ¶

The design doc ("Permissions and host-owned gates") describes the flow as applying to "Harness permission and ask-user gates" generically. Reading the real gate contract (harness/pkg/gate) shows the two kinds are not actually symmetric for this purpose:

• gate.KindPermission's answer is exactly one of the three gate.ApprovalAction strings (Approve / Approve always for this workspace / Deny — see gate.ApprovalControls, which documents these as the gate's "exact, complete control set"). That is precisely what ACP's session/request_permission was designed to carry: a fixed, closed set of named options the user picks exactly one of, tagged with a PermissionOptionKind hint whose four values (allow_once/ allow_always/reject_once/reject_always) already have obvious, non-guessed counterparts for the three approval actions.

• gate.KindAskUser's answer is NOT an action pick: internal/loopruntime's translateAskUserResponse (sessionruntime/gates.go) reads the answer from response.Values["answer"] — arbitrary free text, or one value from a bounded schema.Field's Options when the question offered fixed choices (loopruntime's askUserFields). RequestPermissionResponse's Outcome, however, carries only a discriminated Cancelled-or-Selected choice with an OptionID — there is no field anywhere on the ACP outcome for arbitrary answer text. Even in the bounded-choices case, ACP's PermissionOptionKind is a closed, approve/deny-flavored enum (see types_gen.go's UnmarshalJSON, which rejects anything else): there is no non-fabricated kind that represents "the user picked one of N arbitrary named choices" without guessing an approve/deny semantic that the actual question never had (a "which color?" question tagged allow_once/reject_once would misrepresent the choice to a client rendering approval icons around it).

This is the same category of gap already documented for elicitation in Task 1.7/1.8 (protocol/acp.go and internal/mockpeer/main.go): the pinned v1.20.0 schema has no wire shape that can carry this gate kind's answer faithfully, so — per the plan's own "pinned artifact wins" precedence rule — it is intentionally left untranslated here rather than inventing one. An ask-user GateOpened observed mid-drain therefore falls through exactly like any other untranslatable progress event (see drainToTerminal): the drain continues silently, and the gate stays open until something else (a future ACP capability, or a product-level ask-user answer path outside this facade) resolves it.

Host-owned gates (form, open-url) are never exposed here either ¶

gate.KindForm and gate.KindOpenURL are host-owned (gate.ResolverSession, never gate.ResolverLoop — see sessionruntime's hostOwnedGate), answered through session.GateHost's own AwaitGateAnswer path, not through a loop's RespondGate. This file's translation is scoped to gate.KindPermission with gate.ResolverLoop specifically (permissionOptionsFromGate checks both), so a host-owned gate is never even considered for request_permission — it is structurally excluded, not filtered out by a capability check. This matters because the design doc's own aspiration here ("session/elicitation ... when the connected client advertises elicitation") is doubly unrepresentable: the pinned schema has no elicitation method at all (confirmed absent in Task 1.7/1.8: no Elicit on ClientConn, no elicit entry in methods_gen.go) AND no client capability field for it either (protocol.ClientCapabilities has exactly Fs/Session/Terminal — see types_gen.go — nothing resembling elicitation or an open-URL interaction). There is therefore no capability to negotiate and nothing to gate a matrix test on beyond what gates_test.go already asserts: host-owned gate kinds are never flattened into request_permission, full stop, regardless of what a client advertises.

Package agent is the Looprig-facing ACP agent facade: the only package in this module that may import Harness's or Core's public packages (see acp/CLAUDE.md and harness/docs/plans/2026-07-17-acp-bridge-design.md, "Agent-side host boundary").

ACP setup cannot depend directly on serve.Rig: a Harness rig's option type is opaque to ACP, workspace placement is fixed when a rig is defined, and ACP setup carries product concerns (cwd, MCP servers, replay, catalogs, runtime configuration) that Harness itself does not know about. This file therefore defines small, consumer-owned host interfaces that the product composition root implements; the facade does not touch rig.SessionOption or workspace placement directly.

list.go implements the session/list handler and the session_info_update observation callback: Task 3.3 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md, amended by a follow-up fix to how session/list reports cwd (see this file's "cwd resolution" section below).

The CurrentWorkspace/cwd discrepancy ¶

This task's original design doc ("Session listing and metadata") said SessionMeta.CurrentWorkspace maps to ACP's cwd. It does not: reading the REAL harness/pkg/sessionstore/catalog.go, SessionMeta.CurrentWorkspace is a WorkspacePointer — Ref (a content-addressed workspace-SNAPSHOT digest, "v1:sha256:<64 hex>"), EventID, Seq, and Source (checkpoint vs restore). That identifies which immutable snapshot the session's workspace was last pointed at, not a live filesystem directory path; SessionMeta carries no field anywhere that represents a session's working-directory string at all. Mapping WorkspacePointer.Ref into ACP's Cwd string would be actively wrong (a client would try to treat a content hash as a path). The design doc has since been corrected to say this plainly (see harness/docs/plans/2026-07-17-acp-bridge-design.md, "Session listing and metadata"); a durable per-session cwd field on SessionMeta itself is a legitimate future Harness-side follow-up, out of scope here (see SessionCatalogEntry's doc in host.go).

cwd resolution ¶

The first version of this handler worked around the gap above by emitting SessionInfo.Cwd = "" for every entry. That is schema-non-conformant: the pinned ACP schema requires SessionInfo.cwd to be a non-empty absolute path, so a strict client could reject the whole session/list response over one malformed row. This version instead resolves each catalog entry's cwd through resolvedCwd and, when no cwd can be determined, OMITS that session from the response entirely — an incomplete-but-schema-valid listing beats a complete-but-invalid one. resolvedCwd consults two sources, in order:

1. This facade's own live session registry (sessions.cwd): if the session id is currently live/registered, its Setup.Cwd — already validated and canonicalized at session establishment (session/new, session/load, and session/resume all construct it via NewSetup) — is authoritative, unconditionally overriding whatever (if anything) the catalog itself reports for that same id. A live session is therefore always conformant in session/list, even before any product adapter learns to answer cwd for cold/non-live sessions.
2. The catalog entry's own SessionCatalogEntry.Cwd (host.go), for a session that is not currently live. A host that knows a cold session's cwd may supply it there; one that does not leaves it empty.

A session for which neither source yields a cwd is omitted, never emitted with an empty or fabricated cwd.

Pagination under cwd omission ¶

Omission happens AFTER pagination, not before: the facade still paginates over the catalog's full sorted entry set (sortedSessionMetas, paginateSessionMetas) exactly as it did before this fix, bounding each page at MaxPageSize entries and advancing the cursor to the last entry's SessionID regardless of whether that entry's cwd was resolvable. Only then, for the entries within that already-computed page, does handleSessionList drop the unresolvable-cwd ones from the response's Sessions list. This means an omitted session still "consumes" a page slot — a page can legitimately come back with fewer than MaxPageSize entries (even zero) while NextCursor is still non-nil, if enough sessions in that slice have no resolvable cwd.

This is a deliberate choice over the alternative (filtering out unresolvable-cwd entries BEFORE pagination, so every non-final page is guaranteed exactly MaxPageSize returned entries): filtering first would require re-deriving what a "page" means — either paginating over a separately-materialized filtered-and-sorted slice (an extra full pass and a second sorted view to keep consistent with the unfiltered one), or scanning ahead an unbounded distance through the catalog to accumulate MaxPageSize survivors, which turns a fixed-cost page fetch into a variable, input-dependent one. Pagination position (the cursor) staying anchored to the same catalog-wide sorted-by-SessionID key regardless of cwd resolvability is also simpler to reason about and to test: the cursor always means "resume strictly after this SessionID in the full catalog," never "resume after the Nth *cwd-resolvable* entry," a definition that would shift under a client every time the underlying cwd knowledge changed. The tradeoff this accepts is exactly what the doc above says: a client may see a short (or empty) page before NextCursor goes nil; it must keep following NextCursor to reach the end, exactly as it already must for an ordinary short-vs-full page.

The facade paginates over the catalog's SessionCatalogEntry entries sorted ascending by their Meta.SessionID bytes (sortedSessionMetas) — a stable, catalog-independent ordering that does not depend on ListSessions' own return order. A cursor is an opaque, HMAC-authenticated token naming the last SessionID included in the previous page (cursorPayload); it is validated (decodeListCursor) before ever being used to compute a page, and any structural or authentication failure is a typed *InvalidCursorError, mapped to InvalidParams — never silently treated as "start over" or accepted as some other position. The HMAC key (Agent.cursorKey) is generated fresh via crypto/rand at New() time, once per Agent instance: cursors are short-lived pagination tokens a client is expected to consume within one process's lifetime (they are never persisted or expected to survive a restart), so there is no reason to derive the key from anything stable across restarts, and every reason not to use a fixed or caller-influenced key.

session_info_update ¶

host.go's SessionCatalog interface exposes only a pull method (ListSessions): there is nothing already there a product could register a push callback against, and the direction of this signal is product-into- facade (the product's own catalog-observation mechanism learns of a change and tells the facade), not facade-into-product like every other host.go seam. ObserveSessionMeta is the narrow, facade-owned callback surface that fills that gap: a product calls it once per catalog observation (a KV watch, an event-driven fold — never a poll loop this facade runs itself), and it is the facade's OWN job — not the caller's — to decide whether that observation actually changed anything worth telling the client about (see ObserveSessionMeta's doc).

prompt.go implements the session/prompt correlation engine and the session/cancel handler: Task 2.4 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

ACP's session/prompt is a request whose response completes only at a turn terminal, but Harness's Submit is fire-and-forget: it returns a command id and the turn's outcome arrives later, asynchronously, on the session's event stream. Bridging the two requires the two-phase correlation rule from the design doc ("Prompt correlation and event translation"):

1. Subscribe before submitting (see handlePrompt: SubscribeEvents is called, and its error path returned, strictly before Submit is ever called — a TurnStarted racing in immediately after Submit returns can therefore never be missed).
2. Match TurnStarted.Header.Cause.CommandID to the submitted command id.
3. Capture that event's LoopID and TurnID (Header.Coordinates).
4. Match every following event using both captured identifiers, ignoring everything else (interleaved activity from other loops, other turns, or other prompts' TurnStarted events) as a decoy.
5. Complete the ACP response only on the correlated TurnDone, TurnFailed, or TurnInterrupted.

registry.go is the bounded, concurrency-safe registry of live ACP sessions the facade tracks between session/new and each later session-scoped method (Task 2.3 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md).

replay.go implements the replay translator for session/load: Task 3.1 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

Live ephemeral token and tool-progress events are not durable (see translate.go's package doc and event.go's Class doc: only Enduring events are ever journaled). session/load therefore cannot replay the live token stream at all — TokenDelta, ToolCallStarted, and ToolCallCompleted are all Ephemeral (see event.go's TokenDelta doc and event/tool.go's ToolCallStarted/ToolCallCompleted docs) and never appear in durable history. Instead this file reconstructs, from the session's Enduring event history alone:

• user messages, from TurnStarted.Message;
• assistant messages and completed tool calls, from StepDone.Messages (the step's single *content.AIMessage followed by its *content.ToolResultMessages — see event.go's StepDone doc); and
• the session's current context-window usage, from the LAST ContextMeasured seen (reusing translate.go's translateContextMeasurement directly).

This grouped, four-bucket order — every user message, then every assistant message, then every completed tool call, then one final metadata update — is the exact shape the design doc's "Load replay versus live streaming" section and this task describe, not an interleaved chronological replay: it deliberately does not attempt to reproduce per-turn interleaving.

TurnDone/TurnFailed/TurnInterrupted are turn-boundary markers only and never separately translated: TurnDone.Message is the concatenation of content already reconstructed from this turn's StepDone events, so translating it too would duplicate client-visible content (see the no-duplication property this task requires; translate.go's live translator applies the identical "drop, don't guess" rule to TurnDone for the same reason).

resume.go implements the session/resume handler: Task 3.2 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

Unlike session/load (replay.go), Host.ResumeSession returns a plain LiveSession, not a LoadedSession (see host.go's SessionHost doc): there is no replay anchor and therefore no durable-history reconstruction to perform. The pinned schema documents session/resume as resuming a session "without returning previous messages (unlike session/load) ... for agents that can resume sessions but don't implement full session loading." This handler accordingly never calls a.client.SessionUpdate at all — the exact property this file's test proves — making it the simplest of the three session-establishment handlers: validate Setup, call Host.ResumeSession, register the result, and respond immediately.

session.go implements ACP session identity mapping, the reusable session-scoped resolution helper, and the session/new handler: Task 2.3 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

Every session-scoped ACP method beyond session/new (session/prompt, the permission gates, session/cancel, session/close, and Phase 3's load/resume/list/delete) must resolve its wire sessionId through resolveSession before the id touches the host or any session state: resolveSession validates the string first (ParseSessionID) and only then consults the live-session registry, so a malformed id is rejected before a lookup — let alone a host call — is ever attempted.

translate.go implements the live event translator: Task 2.5 of harness/docs/plans/2026-07-23-acp-bridge-implementation.md.

prompt.go's drainToTerminal (Task 2.4) already correlates a session/prompt to its exact turn (LoopID/TurnID) and drains that turn's event stream to its terminal. Until now it silently discarded every non-terminal event it saw along the way ("progress event ...: not a terminal"). This file adds the translator drainToTerminal uses to turn each of those in-flight, public events into the ACP session/update notification it forwards to the client, so a prompt's progress is actually streamed live rather than only observed internally while the client waits on the terminal response.

Harness events carry two orthogonal classifications this translator must respect: Class (Ephemeral/Enduring — durability, irrelevant here) and EventVisibility (Public/Internal). Only Public events are ever translated; this is a hard security boundary, not a convenience filter, so it is checked directly by Translate rather than trusted solely to the Harness hub's own delivery filter (see event.ShouldDeliver) upstream.