@aragon-agent/cli 0.6.37 → 0.6.39

package/dist/exec/events.d.ts

@@ -13,6 +13,10 @@
  * the same reason: a shape, erased at compile time.
  */
 import type { ServiceStatus } from '../proc/types.js';
+import type { AgentScope, DecisionInstallPayload, DecisionKind, DecisionToolPayload } from './bridge/protocol.js';
+import type { ExecThreadEndReason } from './threads/limits.js';
+import type { HookPoint } from './hooks/limits.js';
+import type { NormalizedPlan, NormalizedQuestion } from '../tools/human-input.js';
 /**
  * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
  * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
@@ -23,9 +27,38 @@ import type { ServiceStatus } from '../proc/types.js';
  */
 export declare const EXEC_SCHEMA_VERSION = 1;
 /** The three baselines of section 4.2. `plan` is a MODE, never a filter. */
-export type ExecPermissionMode = 'auto' | 'plan' | 'strict';
+export type ExecPermissionMode = 'auto' | 'plan' | 'strict' | 'ask';
 export type ExecOutputFormat = 'text' | 'json' | 'stream-json';
-export type ExecInputFormat = 'text' | 'stream-json';
+/**
+ * `bridge` is `stream-json` plus a request/response channel on stdin
+ * (headless-host-bridge). It REQUIRES `--output-format stream-json`, for the same
+ * structural reason `stream-json` does: a per-event write is where `seq` is
+ * stamped, and `json` writes one object at the very end.
+ */
+export type ExecInputFormat = 'text' | 'stream-json' | 'bridge';
+/**
+ * Present on every event a bridge caller can correlate. All five are OPTIONAL and
+ * absent in `stream-json` mode, which is what keeps that stream byte-identical
+ * (AC-2): a field that is not set is not serialized.
+ *
+ * `seq` is stamped by `BridgeWriter`, never by an emitter, so "gap-free" is a
+ * property of one loop rather than of every construction site.
+ */
+export interface ExecCorrelation {
+    seq?: number;
+    requestId?: string;
+    /**
+     * WHICH CONVERSATION THIS EVENT BELONGS TO (headless-threads-and-lifecycle-hooks
+     * section 2.3.10, I-T10).
+     *
+     * ABSENT OUTSIDE THREAD MODE, which is what keeps `stream-json` byte-identical
+     * (I-C1): a field that is not set is not serialized. Inside thread mode it is stamped
+     * on EVERY line that carries a `sessionId` - see `ExecRunner.emit`, which is the one
+     * place that can promise it, plus the six explicit `bridge.write` sites that bypass
+     * `emit()`.
+     */
+    threadId?: string;
+}
 /**
  * Why the run ended.
  *
@@ -58,7 +91,7 @@ export interface ExecErrorInfo {
     code: string;
     message: string;
 }
-export interface ExecSystemInitEvent {
+export interface ExecSystemInitEvent extends ExecCorrelation {
     type: 'system';
     subtype: 'init';
     schemaVersion: number;
@@ -87,6 +120,16 @@ export interface ExecSystemInitEvent {
      * wrong costs the user their conversation, so this build states it.
      */
     capabilities?: string[];
+    /**
+     * `2` when this run speaks the bridge protocol, absent otherwise.
+     *
+     * A NEW OPTIONAL FIELD, so `EXEC_SCHEMA_VERSION` does not move (file header).
+     * It exists because `capabilities` answers "which frames may I send" and this
+     * answers "what shape are they" - and only the second can ever be bumped
+     * incompatibly. A caller that checks it before `includes('bridge')` is doing the
+     * two-step in the right order.
+     */
+    protocolVersion?: number;
     /**
      * Absolute path of the session file THIS run reads and writes; `null` under
      * `--no-save-session` (web-use-durable-control-and-tier-accountability W2).
@@ -111,8 +154,27 @@ export interface ExecSystemInitEvent {
      * latter.
      */
     sessionFile?: string | null;
+    /**
+     * Thread mode only: the pool this run opened with (section 4.3 / AC-8).
+     *
+     * DECLARED HERE BECAUSE THE LINE CARRIES IT: an object literal spread into a return value
+     * escapes excess-property checking, so a misspelled key or a dropped field compiles and
+     * then silently disappears from the wire. `default` names the thread a caller is already
+     * talking to when it sends no `threadId`.
+     */
+    threads?: {
+        maxOpen: number;
+        concurrency: number;
+        default: string;
+    };
+    /**
+     * `true` when this run accepts `hook_register` / `hook_answer`, i.e. whenever it speaks the
+     * bridge protocol (section 4.6). A CAPABILITY, NOT A COUNT: zero hooks registered is still
+     * a hook-capable run.
+     */
+    hooks?: boolean;
 }
-export interface ExecUserEvent {
+export interface ExecUserEvent extends ExecCorrelation {
     type: 'user';
     sessionId: string;
     turn: number;
@@ -121,11 +183,18 @@ export interface ExecUserEvent {
      * `todo_continue` marks a message the CLI generated on the caller's behalf
      * through the follow-through loop. A wrapper replaying a transcript has to be
      * able to tell those apart from what it actually sent.
+     *
+     * `result_repair` is the second such message (headless-request-scope-and-typed-
+     * result section 2.3.5): the CLI telling the model that its `submit_result` was
+     * rejected, or never happened at all. A NEW MEMBER OF AN EXISTING UNION, which is
+     * the additive shape this file's header allows - a consumer that only knows the
+     * first two members already has to handle a value it does not recognise, and a
+     * value it does not recognise must not change what it does with the other two.
      */
-    source: 'caller' | 'todo_continue';
+    source: 'caller' | 'todo_continue' | 'result_repair';
 }
 /** One caller input and its complete automatic follow-through chain. */
-export interface ExecTurnStateEvent {
+export interface ExecTurnStateEvent extends ExecCorrelation {
     type: 'turn_state';
     sessionId: string;
     requestSeq: number;
@@ -152,13 +221,13 @@ export interface ExecThinkingEvent {
     turn: number;
     text: string;
 }
-export interface ExecAssistantEvent {
+export interface ExecAssistantEvent extends ExecCorrelation {
     type: 'assistant';
     sessionId: string;
     turn: number;
     text: string;
 }
-export interface ExecToolCallEvent {
+export interface ExecToolCallEvent extends ExecCorrelation {
     type: 'tool_call';
     sessionId: string;
     turn: number;
@@ -166,7 +235,7 @@ export interface ExecToolCallEvent {
     name: string;
     input: Record<string, unknown>;
 }
-export interface ExecToolResultEvent {
+export interface ExecToolResultEvent extends ExecCorrelation {
     type: 'tool_result';
     sessionId: string;
     turn: number;
@@ -352,6 +421,135 @@ export interface ExecRetryEvent {
     errorType: string;
     delayMs: number;
 }
+/**
+ * The bridge control channel (headless-host-bridge §4.2.2).
+ *
+ * SEVEN ADDITIVE EVENT TYPES, AND `EXEC_SCHEMA_VERSION` DOES NOT MOVE - the rule
+ * this file's header states: adding a field or an event type never bumps it.
+ *
+ * They exist because a callback API has to be a wire API for an embedder, and a
+ * wire API needs an id, an answer and an outcome that can be logged. `ack` proves
+ * a request was received; `decision_request` / `decision_resolved` are one
+ * decision's two ends, and keeping BOTH is what makes "the caller denied it" and
+ * "the caller never answered" distinguishable after the fact - a run that only
+ * recorded the refusal would look identical to a timeout in every transcript.
+ */
+export interface ExecAckEvent extends ExecCorrelation {
+    type: 'ack';
+    /** The caller's own id, echoed. Absent when the frame carried none. */
+    id?: string;
+    accepted: boolean;
+    /** Why it was refused, when it was: `not_running`, `plan_mode_read_only`, ... */
+    code?: string;
+    message?: string;
+    /** `false` means this frame started driving a turn right away. */
+    queued?: boolean;
+    /** The runner's own turn counter, known only when the turn begins. */
+    requestSeq?: number;
+    /** `steer` only: the receipt id Core will confirm in a `steering` event. */
+    steeringId?: string;
+    /**
+     * `interrupt{requestId}` only: the message had not started, so it was deleted
+     * from the queue rather than aborting a turn. A caller that asked to withdraw
+     * its own queued message needs this to know nothing else was disturbed.
+     */
+    cancelled?: 'queued';
+    /** `tool_register` only: whose tool array was replaced. Always `'lead'`. */
+    scope?: 'lead';
+    /** `tool_register` only: the names that are now registered. */
+    tools?: string[];
+    /** `tool_register` only: the first turn the new set can be used in. */
+    appliedAtTurn?: number;
+    /**
+     * `thread_open` only: the session id this thread writes (section 2.3.2's ack table).
+     *
+     * Stated rather than left to be derived: `explicitSessionId` wins and the default thread
+     * reuses the process id, so a caller that guessed `${base}-${threadId}` would be wrong in
+     * two of the three cases.
+     */
+    sessionId?: string;
+    /** `thread_open` only: the thread's session file, `null` under `--no-save-session`. */
+    sessionFile?: string | null;
+    /** `thread_open` only. Always `false`: a thread never resumes (section 1.4). */
+    resumed?: boolean;
+    /** `hook_register` only: the ids that are now live, in registration order. */
+    hooks?: string[];
+    /** `thread_list` only: one summary per thread, in open order. */
+    threads?: Array<{
+        threadId: string;
+        sessionId: string;
+        state: 'opening' | 'open' | 'closing' | 'closed';
+        requests: number;
+        turns: number;
+        inFlight: boolean;
+    }>;
+    /** Non-fatal notes about an ACCEPTED frame (a clipped description, say). */
+    warnings?: string[];
+}
+export interface ExecDecisionRequestEvent {
+    type: 'decision_request';
+    requestId: string;
+    sessionId: string;
+    kind: DecisionKind;
+    createdAt: number;
+    deadlineAt: number;
+    timeoutMs: number;
+    tool?: DecisionToolPayload;
+    questions?: NormalizedQuestion[];
+    plan?: NormalizedPlan;
+    install?: DecisionInstallPayload;
+    /** Always present on the wire; the type keeps it optional for stub callers. */
+    agent?: AgentScope;
+}
+export interface ExecDecisionResolvedEvent {
+    type: 'decision_resolved';
+    requestId: string;
+    sessionId: string;
+    kind: DecisionKind;
+    /**
+     * `error` is the fail-closed answer to a frame that could not be trusted; it is
+     * distinct from `aborted` because one is the caller's fault and the other is
+     * the turn's.
+     */
+    outcome: 'allow' | 'deny' | 'timeout' | 'aborted' | 'error';
+    scope?: 'once' | 'session';
+    reason?: string;
+}
+export interface ExecToolInvokeEvent {
+    type: 'tool_invoke';
+    requestId: string;
+    sessionId: string;
+    /** Core's tool call id, so this pairs with the `tool_call` event beside it. */
+    callId: string;
+    turn: number;
+    tool: string;
+    input: Record<string, unknown>;
+    timeoutMs: number;
+    deadlineAt: number;
+    agent: AgentScope;
+}
+export interface ExecToolCancelEvent {
+    type: 'tool_cancel';
+    requestId: string;
+    sessionId: string;
+    reason: 'timeout' | 'turn_aborted' | 'host_shutdown';
+}
+export interface ExecPongEvent extends ExecCorrelation {
+    type: 'pong';
+    id?: string;
+    now: number;
+}
+export interface ExecSteeringEvent extends ExecCorrelation {
+    type: 'steering';
+    sessionId: string;
+    /**
+     * ARRAY, NOT A SINGLE ID (review P1-7). Core's `steering_accepted` carries
+     * `ids: string[]` because one drain can accept a whole batch; reporting only the
+     * first would leave the rest permanently unconfirmed on the caller's side, which
+     * is precisely what the receipt exists to prevent.
+     */
+    steeringIds: string[];
+}
 export interface ExecErrorEvent {
     type: 'error';
     sessionId: string;
@@ -396,6 +594,57 @@ export interface ExecResultEvent {
         passed: number;
         failed: number;
     } | null;
+    /**
+     * The accepted structured result (headless-request-scope-and-typed-result
+     * section 2.3.7), or `null` when `--result-schema` was given and nothing was
+     * ever accepted.
+     *
+     * ABSENT, NOT `null`, WITHOUT THE FLAG (I-C1). "The field is missing" and "this
+     * build has no such capability" look identical in JSON, which is exactly why the
+     * flag-ON failure path must instead be an EXPLICIT `null`: a caller that passed
+     * `--result-schema` can then read one field and know whether it got what it asked
+     * for. Two different questions, two different encodings.
+     */
+    structured?: {
+        value: unknown;
+        schemaName: string;
+        schemaBytes: number;
+        attempts: number;
+        acceptedAt: number;
+    } | null;
+    /**
+     * The model's last prose, present only when `result.result` was REPLACED by the
+     * canonical JSON text - that is, when a structured result was accepted.
+     *
+     * The README's `aragon exec --output-format json ... | jq -r .result` idiom has to
+     * keep working, and under a schema the answer IS the object, so `result` carries
+     * the object and the prose moves here instead of being lost.
+     */
+    text?: string;
+    /**
+     * The thread-by-thread account, thread mode only (section 2.3.2 / AC-37).
+     *
+     * ABSENT IN EVERY NON-THREAD RUN. `items` is ordered by OPEN ORDER so a wrapper can
+     * zip it with the `thread_state` events it received; `usage`/`cost` on the `result`
+     * itself are the sums of these, which is why the same numbers appear twice - once as
+     * the total a single-call embedder wants, once per tenant.
+     */
+    threads?: {
+        opened: number;
+        closed: number;
+        /** Threads whose account reported `isError`. */
+        failed: number;
+        items: Array<{
+            threadId: string;
+            sessionId: string;
+            requests: number;
+            turns: number;
+            usage: ExecUsage;
+            cost: ExecCost;
+            isError: boolean;
+            reason: ExecThreadEndReason;
+        }>;
+    };
     error: ExecErrorInfo | null;
 }
 /**
@@ -421,7 +670,135 @@ export interface ExecJobEvent {
     progress?: string;
     exitCode?: number | null;
 }
-export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTurnStateEvent | ExecProgressEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecFastTierEvent | ExecCompactionEvent | ExecRetryEvent | ExecJobEvent | ExecErrorEvent | ExecResultEvent;
+/**
+ * Why ONE request ended (headless-request-scope-and-typed-result section 2.4.6).
+ *
+ * A SEPARATE UNION FROM `ExecStopReason`, ON PURPOSE. Adding members to the process
+ * union would break every downstream exhaustive `switch` over it, and the two answer
+ * genuinely different questions: "why did this process end" and "why did this
+ * request end". A request can stop while the process keeps serving the next one -
+ * that is the entire point of the feature - so the two must not share a vocabulary
+ * that implies they move together.
+ */
+export type ExecRequestStopReason = 'completed' | 'max_turns' | 'timeout' | 'cancelled' | 'error';
+/** A request-level failure. `code` is stable; `message` is prose for a human. */
+export interface ExecRequestError {
+    code: string;
+    message: string;
+}
+/**
+ * One request's account: what it cost, how it ended, and whether the caller got
+ * what it asked for (section 2.4.6).
+ *
+ * BRIDGE MODE ONLY (I-C3). The v1 input format (`--input-format stream-json`) is
+ * already a multi-prompt loop, but emitting this event there would change its byte
+ * output, which is the one thing the compatibility strategy cannot allow.
+ */
+export interface ExecRequestEndEvent extends ExecCorrelation {
+    type: 'request_end';
+    sessionId: string;
+    /** The caller's id, or the CLI's `prompt_<n>` when the frame carried none. */
+    requestId: string;
+    /**
+     * The same number space as `turn_state.requestSeq` and the `ack` for this
+     * request.
+     *
+     * OPTIONAL, AND THAT IS NOT SLOPPINESS (review P0-2). The number is minted at the
+     * moment a prompt is SERVED. A prompt cancelled while still in the queue was
+     * never served, so it never got one - and inventing one would collide with a
+     * later real request. Absent is the honest answer.
+     */
+    requestSeq?: number;
+    stopReason: ExecRequestStopReason;
+    isError: boolean;
+    /** Turns this request took, including repair and follow-through continuations. */
+    turns: number;
+    durationMs: number;
+    usage: ExecUsage;
+    cost: ExecCost;
+    /** This request's last assistant text, clipped to `REQUEST_LIMITS.maxResultChars`. */
+    result: string;
+    /** The accepted structured result, or `null`; absent when no schema was given. */
+    structured?: {
+        value: unknown;
+        schemaName: string;
+        attempts: number;
+    } | null;
+    error: ExecRequestError | null;
+}
+/** Everything `request_end` needs; `type` is stamped by the builder below. */
+export type ExecRequestEndParams = Omit<ExecRequestEndEvent, 'type'>;
+export declare function buildRequestEndEvent(params: ExecRequestEndParams): ExecRequestEndEvent;
+/**
+ * One thread's lifecycle (headless-threads-and-lifecycle-hooks section 2.3.2).
+ *
+ * `phase` HAS THREE MEMBERS AND NOT FIVE, deliberately: `busy` / `idle` are already
+ * carried by `turn_state`, and two state machines describing one fact will eventually
+ * disagree. This file's own history has one such lesson (`ui/team-status.ts`), which is
+ * why the smaller set is the one that survived.
+ */
+export interface ExecThreadStateEvent extends ExecCorrelation {
+    type: 'thread';
+    sessionId: string;
+    threadId: string;
+    phase: 'opened' | 'closing' | 'closed';
+    /** Only on `'closed'`. */
+    reason?: ExecThreadEndReason;
+    /** Only on `'closed'`: this thread's account. */
+    requests?: number;
+    turns?: number;
+    durationMs?: number;
+    usage?: ExecUsage;
+    cost?: ExecCost;
+    isError?: boolean;
+}
+/**
+ * One hook round trip, outward (headless-threads-and-lifecycle-hooks section 2.4.2).
+ *
+ * `requestId` IS REQUIRED, like `decision_request`'s, and for the same reason: a hook
+ * request that cannot name the request it belongs to cannot be timed out, cancelled or
+ * audited. `prompt_pre` therefore fires after `scope.begin()` and before the `ack`, so
+ * the id always exists.
+ */
+export interface ExecHookRequestEvent extends ExecCorrelation {
+    type: 'hook_request';
+    sessionId: string;
+    requestId: string;
+    /**
+     * THIS ROUND TRIP'S OWN ID: what `hook_answer.respondsTo` must name.
+     *
+     * IT IS NOT `requestId`, AND THAT IS A GAP FOUND DURING IMPLEMENTATION. One hook fires many
+     * times inside one request, so the semantic id cannot identify a round trip - while
+     * `decision_request` does not have the problem, because one decision belongs to one request.
+     * Recorded in the spec's implementation-notes section.
+     */
+    hookRequestId: string;
+    hookId: string;
+    point: HookPoint;
+    /** The point-specific payload; see the tool/prompt/turn modules below. */
+    payload: Record<string, unknown>;
+}
+/**
+ * The other end of exactly one `hook_request` (I-H5).
+ *
+ * `outcome` is the operational fact and `code` the stable reason; keeping BOTH is what
+ * makes "the hook timed out" and "the hook answered nonsense" distinguishable after the
+ * fact, which a single boolean never is.
+ */
+export interface ExecHookResolvedEvent extends ExecCorrelation {
+    type: 'hook_resolved';
+    sessionId: string;
+    requestId: string;
+    /** The same `hookRequestId` its request carried, so the pair is unambiguous. */
+    hookRequestId?: string;
+    hookId: string;
+    point: HookPoint;
+    outcome: 'answered' | 'timeout' | 'aborted' | 'invalid' | 'saturated' | 'unregistered';
+    action?: string;
+    /** Present when `outcome !== 'answered'`, and for a rejected answer. */
+    code?: string;
+}
+export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTurnStateEvent | ExecProgressEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecFastTierEvent | ExecCompactionEvent | ExecRetryEvent | ExecJobEvent | ExecAckEvent | ExecDecisionRequestEvent | ExecDecisionResolvedEvent | ExecToolInvokeEvent | ExecToolCancelEvent | ExecPongEvent | ExecSteeringEvent | ExecThreadStateEvent | ExecHookRequestEvent | ExecHookResolvedEvent | ExecErrorEvent | ExecRequestEndEvent | ExecResultEvent;
 /** Everything `system/init` needs that the runner cannot derive for itself. */
 export interface ExecInitParams {
     sessionId: string;
@@ -436,11 +813,54 @@ export interface ExecInitParams {
     permissionMode: ExecPermissionMode;
     tools: string[];
     resumed: boolean;
+    /**
+     * Thread mode only: the pool this run opened with, so a wrapper can decide whether
+     * opening a fifth thread is worth the round trip (section 2.3.2 / AC-8).
+     *
+     * ABSENT ON EVERY NON-THREAD RUN (I-C1). `default` is stated rather than implied: a caller
+     * that never sends `threadId` needs to know which conversation it is already talking to.
+     */
+    threads?: {
+        maxOpen: number;
+        concurrency: number;
+        default: string;
+    };
+    /**
+     * `true` when this run accepts `hook_register` / `hook_answer`, i.e. in bridge mode.
+     *
+     * A CAPABILITY, NOT A COUNT: zero hooks registered is still a hook-capable run, and a
+     * caller that cannot tell the two apart would conclude "hooks are unsupported" from
+     * "I have not registered one".
+     *
+     * IT IS NOT GATED ON `--threads`, so a bridge run's init line gains this key and the
+     * `hooks` capability string. That is an ADDITIVE change to a v1 bridge line - a caller
+     * that compares capability SETS is unaffected, one that compares literals is not - and it
+     * is the price of "declare it where it is true" (section 4.6). `threads` is the key that
+     * stays absent, which is what keeps a non-thread run byte-identical.
+     */
+    hooks?: boolean;
     /**
      * Absolute path of the session file this run reads and writes; `null` under
      * `--no-save-session`. See `ExecSystemInitEvent.sessionFile`.
      */
     sessionFile?: string | null;
+    /**
+     * `true` under `--input-format bridge`. Stamped by `runExec`, never by a caller,
+     * and it is what adds `protocolVersion` plus the bridge capability strings -
+     * declaring `bridge` in a `stream-json` run would tell a wrapper to send frames
+     * nothing is reading.
+     */
+    bridge?: boolean;
+    /**
+     * `true` when this run carries `--result-schema`, so `submit_result` is
+     * registered and the `<structured_result>` block is in the system prompt.
+     *
+     * A SEPARATE FLAG FROM THE OPTIONS, not derived from them here: this module is
+     * pure types and builders and must not learn what a flag is. `runExec` stamps it,
+     * which also keeps the capability list a fact about the run rather than about the
+     * argv it was started with.
+     */
+    structuredResult?: boolean;
 }
 /**
  * What this build announces in `system/init`.
@@ -470,6 +890,41 @@ export interface ExecInitParams {
  *                            is still resumable instead of guessing the path.
  */
 export declare const EXEC_CAPABILITIES: readonly string[];
+/**
+ * What a run must be able to observe about ITSELF to answer "which capability
+ * strings do I announce".
+ *
+ * AN OBJECT, NOT A BOOLEAN (review P0-4). Until this round the list was assembled
+ * from one flag (`bridge`), and `structured_result` cannot join it: that capability
+ * is TRUE ONLY FOR A RUN THAT ACTUALLY CARRIES `--result-schema`. Appending it to
+ * the `EXEC_CAPABILITIES` constant would make a run without the flag announce a
+ * capability it does not have, which is precisely the failure the field exists to
+ * prevent - a caller would send a schema-shaped expectation and get prose back.
+ *
+ * Named for what it describes: the capabilities of THIS RUN, not of this build.
+ */
+export interface ExecCapabilities {
+    bridge: boolean;
+    /** True ONLY when this run carries `--result-schema`. */
+    structuredResult: boolean;
+    /** True only for a run that opened `--threads` (review P1-5). */
+    threads?: boolean;
+    /** True only for a bridge run, which is the only run that accepts hook frames. */
+    hooks?: boolean;
+}
+/**
+ * The capability strings one run announces: `EXEC_CAPABILITIES` plus whatever its
+ * own switches add, APPEND ONLY.
+ *
+ * A SEPARATE LIST RATHER THAN A LONGER `EXEC_CAPABILITIES`, because declaring
+ * `bridge` in a `stream-json` run would tell a wrapper to send frames nothing is
+ * reading - and it would send them into a stdin parser that ignores them, so the
+ * caller's first real symptom would be "no decision_request ever arrives".
+ *
+ * `'structured_result'` IS PUSHED HERE AND NOWHERE ELSE. There is exactly one
+ * derivation point, so `system/init` and `aragon info` cannot disagree.
+ */
+export declare function execCapabilities(caps: ExecCapabilities): string[];
 export declare function buildInitEvent(params: ExecInitParams): ExecSystemInitEvent;
 /** Everything `result` needs. `schemaVersion` is stamped here, never by a caller. */
 export type ExecResultParams = Omit<ExecResultEvent, 'type' | 'schemaVersion'>;

package/dist/exec/events.js

@@ -1,3 +1,7 @@
+// BY VALUE, AND THE DIRECTION IS ONE-WAY: `bridge/protocol.ts` never imports this
+// module, so a wrapper reading `system/init` and a caller writing frames share one
+// copy of the two bridge constants instead of two that can disagree.
+import { BRIDGE_CAPABILITIES, BRIDGE_PROTOCOL_VERSION } from './bridge/protocol.js';
 /**
  * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
  * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
@@ -7,6 +11,9 @@
  * additive change and every wrapper would pin an exact number forever.
  */
 export const EXEC_SCHEMA_VERSION = 1;
+export function buildRequestEndEvent(params) {
+    return { type: 'request_end', ...params };
+}
 /**
  * What this build announces in `system/init`.
  *
@@ -49,7 +56,40 @@ export const EXEC_CAPABILITIES = [
     // asking for this string, and an older wrapper never asks.
     'todo-acceptance',
 ];
+/**
+ * The capability strings one run announces: `EXEC_CAPABILITIES` plus whatever its
+ * own switches add, APPEND ONLY.
+ *
+ * A SEPARATE LIST RATHER THAN A LONGER `EXEC_CAPABILITIES`, because declaring
+ * `bridge` in a `stream-json` run would tell a wrapper to send frames nothing is
+ * reading - and it would send them into a stdin parser that ignores them, so the
+ * caller's first real symptom would be "no decision_request ever arrives".
+ *
+ * `'structured_result'` IS PUSHED HERE AND NOWHERE ELSE. There is exactly one
+ * derivation point, so `system/init` and `aragon info` cannot disagree.
+ */
+export function execCapabilities(caps) {
+    const list = [...EXEC_CAPABILITIES];
+    if (caps.structuredResult)
+        list.push('structured_result');
+    // THE TWO NEW STRINGS FOLLOW THE SAME RULE as `structured_result` (review P1-5):
+    // conditions on THIS RUN, pushed from the ONE derivation point. `hooks` keys off
+    // `bridge` rather than off `threads` because hooks need only the frame channel - tying
+    // them to threads would force the commonest embedding shape ("one conversation, one
+    // redactor") to sign a multi-tenant contract it does not use (section 9.9).
+    if (caps.threads)
+        list.push('threads');
+    if (caps.hooks)
+        list.push('hooks');
+    if (caps.bridge)
+        list.push(...BRIDGE_CAPABILITIES);
+    return list;
+}
 export function buildInitEvent(params) {
+    const bridge = params.bridge === true;
+    const structuredResult = params.structuredResult === true;
+    const threads = params.threads !== undefined;
+    const hooks = params.hooks === true;
     return {
         type: 'system',
         subtype: 'init',
@@ -62,7 +102,13 @@ export function buildInitEvent(params) {
         permissionMode: params.permissionMode,
         tools: params.tools,
         resumed: params.resumed,
-        capabilities: [...EXEC_CAPABILITIES],
+        capabilities: execCapabilities({ bridge, structuredResult, threads, hooks }),
+        ...(bridge ? { protocolVersion: BRIDGE_PROTOCOL_VERSION } : {}),
+        // CONDITIONAL SPREADS, so a non-thread run's init line keeps the exact key set it
+        // had before this round (I-C1). The counters live in the type, the absence is the
+        // proof.
+        ...(params.threads !== undefined ? { threads: params.threads } : {}),
+        ...(hooks ? { hooks: true } : {}),
         // `?? null` rather than a conditional spread: the field's contract is
         // three-valued for a CONSUMER (`undefined` = an old build that cannot say,
         // `null` = this run saves nothing, a string = here it is), and omitting it