@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/activities/execute-deep-agent/subagent-wiring.js

@@ -0,0 +1,119 @@
+/**
+ * Sub-agent middleware composition for ExecuteDeepAgent.
+ *
+ * Each sub-agent invocation gets its own middleware stack
+ * (`compileSubagents` builds one per invocation, stigmer/stigmer#1699) with:
+ * - Path normalization (issue #429), FIRST, on every graph since issue #754
+ *   — workspace-relative paths are rewritten to the virtual root's dialect
+ *   before deepagents' permission validation and the backend see them,
+ *   exactly as on the parent (`compileSubagents` always passes it).
+ * - Fresh loop detection (independent cycle tracking)
+ * - Tool intent (issue #276) — the shell tool's bind-time schema gains the
+ *   optional model-authored `description`, so sub-agent shell rows carry
+ *   intent titles exactly like the parent's
+ * - Fresh tool truncation (same limits as parent)
+ * - Periodic execution budget (interval=30, max=4 advisories)
+ * - Tool scope (`middleware/tool-scope.ts`) with THIS sub-agent's scope —
+ *   the parent's narrowed by the sub-agent's own lists, never widened —
+ *   installed whenever that scope carries a list, independent of the gate,
+ *   and ahead of it, exactly as on the parent
+ * - Approval gate (so a mutating tool *inside* a sub-agent is gated, not
+ *   bypassed) — installed only when the parent itself is gated
+ *   (`approvalGate` present; absent under auto-approve-all)
+ * - Shared cost cap view (parent's budget, no reset on sub-agent start; once
+ *   the run nears the cap, each invocation is told on its next call, whichever
+ *   graph's spend crossed)
+ * - Error hints (issue #255): a thrown tool error becomes a recoverable
+ *   ToolMessage exactly as on the parent. Without it, any tool throw — a
+ *   plan-mode permission denial, an MCP hiccup — propagated out of the
+ *   sub-agent graph and killed the whole delegated task, losing all its
+ *   accumulated work, where the parent's identical error is one failed
+ *   tool round the model adapts to.
+ *
+ * - OTel spans: a `chat` span per model call and an `execute_tool` span per
+ *   tool call, innermost as on the parent. Until 2026-10 the stack left them
+ *   out on the belief that the parent's context covered them; nothing in the
+ *   parent spans a sub-agent's own calls, so its work was invisible. The
+ *   invocation's `invoke_agent` span is the transformer's
+ *   (`subagent-transformer.ts`), opened inside the parent's `task` span.
+ *
+ * The sub-agent middleware stack does NOT include:
+ * - Graceful stop (parent handles STOP signal propagation)
+ *
+ * Approval-gate note: the gate is what *creates* the LangGraph `interrupt()`.
+ * A sub-agent's interrupt does surface at the parent checkpoint and resumes
+ * correctly (verified in subagent-approval-propagation.test.ts), but only if
+ * the gate runs inside the sub-agent in the first place — omitting it here was
+ * the live HITL bypass this wiring closes.
+ */
+import { createPathNormalizationMiddleware } from "../../middleware/path-normalization.js";
+import { createLoopDetectionMiddleware } from "../../middleware/loop-detection.js";
+import { createToolTruncationMiddleware } from "../../middleware/tool-truncation.js";
+import { createExecutionBudgetMiddleware } from "../../middleware/execution-budget.js";
+import { createToolIntentMiddleware } from "../../middleware/tool-intent.js";
+import { createApprovalGateMiddleware, } from "../../middleware/approval-gate.js";
+import { createErrorHintsMiddleware } from "../../middleware/error-hints.js";
+import { createOtelSpansMiddleware } from "../../middleware/otel-spans.js";
+import { createToolScopeMiddleware } from "../../middleware/tool-scope.js";
+const SUB_AGENT_ADVISORY_INTERVAL = 30;
+const SUB_AGENT_MAX_ADVISORIES = 4;
+/**
+ * Build the middleware stack for a single sub-agent.
+ *
+ * Returns an ordered array mirroring the parent composition:
+ * [path normalization] → loop detection → execution budget (periodic) →
+ * tool intent → tool truncation → [tool scope] → [approval gate] → cost
+ * cap view → error hints → OTel spans.
+ * Normalization is outermost so everything downstream observes canonical
+ * workspace-absolute paths (matching the parent). The gate sits before the
+ * cost-cap view so an approval pause happens before budget accounting, and
+ * error hints come after the gate — both matching the parent order
+ * (…→ truncation → approval gate → cost cap → error hints …),
+ * which keeps the gate's HITL interrupt outside the hints' try/catch.
+ */
+export function buildSubAgentMiddleware(options = {}) {
+    const stack = [];
+    if (options.pathNormalization) {
+        stack.push(createPathNormalizationMiddleware(options.pathNormalization));
+    }
+    stack.push(createLoopDetectionMiddleware({ enabled: true }));
+    stack.push(createExecutionBudgetMiddleware({
+        warningInterval: SUB_AGENT_ADVISORY_INTERVAL,
+        maxWarnings: SUB_AGENT_MAX_ADVISORIES,
+    }));
+    // Sub-agent shell rows render in the same thread as the parent's and must
+    // carry the same model-authored intent titles (issue #276).
+    stack.push(createToolIntentMiddleware());
+    stack.push(createToolTruncationMiddleware(options.toolTruncation));
+    if (options.toolScope?.scope.restricted) {
+        stack.push(createToolScopeMiddleware(options.toolScope));
+    }
+    if (options.approvalGate) {
+        // captureIgnored: a sub-agent flows gitignored writes — and, since
+        // issue #303, non-secret CAS-owned deletes — into CAS iff a CAS observer
+        // backs its filesystem backend (compileSubagents passes this as
+        // `!!casObserver`). When true, inherit the parent gate verbatim so its
+        // captureIgnored + recordBlockedSecret + captureDeleteBefore feed the SAME
+        // shared observer that backs the sub-agent's writes. When false (default;
+        // non-capture mode, or no observer), force CAS routing off and drop both
+        // observer sinks so gitignored paths stay on the interrupt gate — a flowed
+        // gitignored edit on an unobserved backend would apply unobserved,
+        // unreviewable bytes. Sub-agent git-tracked edits are always captured by
+        // the backend-agnostic boundary diff.
+        stack.push(createApprovalGateMiddleware(options.captureIgnored
+            ? options.approvalGate
+            : {
+                ...options.approvalGate,
+                captureIgnored: false,
+                recordBlockedSecret: undefined,
+                captureDeleteBefore: undefined,
+            }));
+    }
+    if (options.costAdvisory) {
+        stack.push(options.costAdvisory.forSubAgent());
+    }
+    stack.push(createErrorHintsMiddleware());
+    stack.push(createOtelSpansMiddleware(options.otelSpans));
+    return stack;
+}
+//# sourceMappingURL=subagent-wiring.js.map

package/dist/activities/execute-deep-agent/subagent-wiring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-wiring.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/subagent-wiring.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAUH,OAAO,EAAE,iCAAiC,EAAE,MAAM,wCAAwC,CAAC;AAC3F,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AACnF,OAAO,EAAE,8BAA8B,EAAE,MAAM,qCAAqC,CAAC;AACrF,OAAO,EAAE,+BAA+B,EAAE,MAAM,sCAAsC,CAAC;AACvF,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EACL,4BAA4B,GAE7B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAC3E,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,MAAM,2BAA2B,GAAG,EAAE,CAAC;AACvC,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAoCnC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,uBAAuB,CACrC,UAAqC,EAAE;IAEvC,MAAM,KAAK,GAAwB,EAAE,CAAC;IAEtC,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC;QAC9B,KAAK,CAAC,IAAI,CAAC,iCAAiC,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,6BAA6B,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAE7D,KAAK,CAAC,IAAI,CAAC,+BAA+B,CAAC;QACzC,eAAe,EAAE,2BAA2B;QAC5C,WAAW,EAAE,wBAAwB;KACtC,CAAC,CAAC,CAAC;IAEJ,0EAA0E;IAC1E,4DAA4D;IAC5D,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;IAEzC,KAAK,CAAC,IAAI,CAAC,8BAA8B,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC;IAEnE,IAAI,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;QACxC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,mEAAmE;QACnE,yEAAyE;QACzE,gEAAgE;QAChE,uEAAuE;QACvE,2EAA2E;QAC3E,0EAA0E;QAC1E,yEAAyE;QACzE,2EAA2E;QAC3E,mEAAmE;QACnE,yEAAyE;QACzE,sCAAsC;QACtC,KAAK,CAAC,IAAI,CAAC,4BAA4B,CACrC,OAAO,CAAC,cAAc;YACpB,CAAC,CAAC,OAAO,CAAC,YAAY;YACtB,CAAC,CAAC;gBACE,GAAG,OAAO,CAAC,YAAY;gBACvB,cAAc,EAAE,KAAK;gBACrB,mBAAmB,EAAE,SAAS;gBAC9B,mBAAmB,EAAE,SAAS;aAC/B,CACN,CAAC,CAAC;IACL,CAAC;IAED,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACzB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,WAAW,EAAE,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,0BAA0B,EAAE,CAAC,CAAC;IACzC,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAEzD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/activities/execute-deep-agent/todo-list.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The parent's to-do list: langchain's `todoListMiddleware`, with Stigmer's
+ * words for its tool and its system line.
+ *
+ * Why the middleware and not our own: it owns the `todos` state channel, the
+ * tool, and the refusal of two list updates in one response, and the
+ * product reads what it writes (the parent's `write_todos` is what
+ * `status.todos` projects and what the clients' progress card renders,
+ * `harness/transcript/builder.ts`, `shared/todos.ts`). Parent only: a
+ * sub-agent's list never reaches the execution.
+ *
+ * Why our own words: langchain's defaults are an 11.4 KB tool description
+ * and a 1 KB system block, sent on every model call of every turn whether
+ * or not a list is kept, and they ask for the list to be updated "as soon
+ * as you are done with a step. Do not batch", which the benchmark's
+ * per-call record showed as one model call per update, five of seventeen on
+ * a multi-part task. These texts keep what the product relies on (a list for
+ * work of several parts, the three states the card shows, one item in
+ * progress) and make each update ride with another tool call.
+ *
+ * The threshold is "several separate parts", not a step count: a first cut
+ * said "three or more distinct steps", and the model then kept a list on a
+ * one-change edit (read, edit, test) with every update in a round of its
+ * own. A soft "update with your next action" was not followed either, so
+ * the rule names the call's company outright.
+ *
+ * Plan mode's build progress names no tool: its directive says "your to-do
+ * list" (`shared/implement-plan-prompt.ts`) and leaves each harness's tool
+ * to say what it is, so the description opens by saying exactly that.
+ *
+ * The system line cannot be empty: the middleware appends it as a block of
+ * its own, and an empty option would still send a whitespace block.
+ */
+import { todoListMiddleware } from "langchain";
+/** The to-do tool's description, as the model reads it. */
+export declare const TODO_TOOL_DESCRIPTION: string;
+/** The line the middleware adds to the system prompt. */
+export declare const TODO_SYSTEM_PROMPT: string;
+/** The parent graph's to-do middleware, with Stigmer's texts. */
+export declare function createTodoListMiddleware(): ReturnType<typeof todoListMiddleware>;

package/dist/activities/execute-deep-agent/todo-list.js

@@ -0,0 +1,51 @@
+/**
+ * The parent's to-do list: langchain's `todoListMiddleware`, with Stigmer's
+ * words for its tool and its system line.
+ *
+ * Why the middleware and not our own: it owns the `todos` state channel, the
+ * tool, and the refusal of two list updates in one response, and the
+ * product reads what it writes (the parent's `write_todos` is what
+ * `status.todos` projects and what the clients' progress card renders,
+ * `harness/transcript/builder.ts`, `shared/todos.ts`). Parent only: a
+ * sub-agent's list never reaches the execution.
+ *
+ * Why our own words: langchain's defaults are an 11.4 KB tool description
+ * and a 1 KB system block, sent on every model call of every turn whether
+ * or not a list is kept, and they ask for the list to be updated "as soon
+ * as you are done with a step. Do not batch", which the benchmark's
+ * per-call record showed as one model call per update, five of seventeen on
+ * a multi-part task. These texts keep what the product relies on (a list for
+ * work of several parts, the three states the card shows, one item in
+ * progress) and make each update ride with another tool call.
+ *
+ * The threshold is "several separate parts", not a step count: a first cut
+ * said "three or more distinct steps", and the model then kept a list on a
+ * one-change edit (read, edit, test) with every update in a round of its
+ * own. A soft "update with your next action" was not followed either, so
+ * the rule names the call's company outright.
+ *
+ * Plan mode's build progress names no tool: its directive says "your to-do
+ * list" (`shared/implement-plan-prompt.ts`) and leaves each harness's tool
+ * to say what it is, so the description opens by saying exactly that.
+ *
+ * The system line cannot be empty: the middleware appends it as a block of
+ * its own, and an empty option would still send a whitespace block.
+ */
+import { todoListMiddleware } from "langchain";
+import { ENGINE_TOOL } from "./engine-tools.js";
+/** The to-do tool's description, as the model reads it. */
+export const TODO_TOOL_DESCRIPTION = "Your to-do list, shown to the user as your progress. Use it when a request has several separate parts, " +
+    "or when the user asks for one. Skip it for a single change, however many steps it takes, and for questions.\n" +
+    "- Send the whole list each time. Each item is pending, in_progress or completed; keep exactly one " +
+    "in_progress while you work.\n" +
+    `- A \`${ENGINE_TOOL.writeTodos}\` call always shares its response with another tool call: update the list ` +
+    "alongside your next action, never in a response of its own, and send the last update with your last tool call.\n" +
+    "- Call this tool at most once per response.";
+/** The line the middleware adds to the system prompt. */
+export const TODO_SYSTEM_PROMPT = `Keep a to-do list with \`${ENGINE_TOOL.writeTodos}\` when a request has several separate parts; ` +
+    "the user sees it as your progress.";
+/** The parent graph's to-do middleware, with Stigmer's texts. */
+export function createTodoListMiddleware() {
+    return todoListMiddleware({ toolDescription: TODO_TOOL_DESCRIPTION, systemPrompt: TODO_SYSTEM_PROMPT });
+}
+//# sourceMappingURL=todo-list.js.map

package/dist/activities/execute-deep-agent/todo-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-list.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/todo-list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,2DAA2D;AAC3D,MAAM,CAAC,MAAM,qBAAqB,GAChC,yGAAyG;IACzG,+GAA+G;IAC/G,oGAAoG;IACpG,+BAA+B;IAC/B,SAAS,WAAW,CAAC,UAAU,6EAA6E;IAC5G,kHAAkH;IAClH,6CAA6C,CAAC;AAEhD,yDAAyD;AACzD,MAAM,CAAC,MAAM,kBAAkB,GAC7B,4BAA4B,WAAW,CAAC,UAAU,gDAAgD;IAClG,oCAAoC,CAAC;AAEvC,iEAAiE;AACjE,MAAM,UAAU,wBAAwB;IACtC,OAAO,kBAAkB,CAAC,EAAE,eAAe,EAAE,qBAAqB,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAC,CAAC;AAC1G,CAAC"}

package/dist/activities/execute-deep-agent/translator.d.ts

@@ -0,0 +1,167 @@
+/**
+ * DeepAgentTranslator — the native harness's translator: LangGraph's v3
+ * protocol events in, the canonical `TranscriptEvent` union out
+ * (`harness/transcript/events.ts`).
+ *
+ * The one module that knows LangGraph's wire shape:
+ * the shared builder folds what comes out of here and nothing of the engine
+ * reaches it otherwise. Every engine fact the builder used to read is
+ * answered on this side now (since #1097):
+ *
+ *   - the tool's result, rendered to the string the row carries — the
+ *     LangChain ToolMessage envelope and the LangGraph Command unwrapped;
+ *   - the tool's attribution (`mcpServerSlug`) and authorization provenance,
+ *     from the gate's posture (`resolveApprovalProvenance`, the gate's
+ *     read-side twin);
+ *   - a call the agent's tool lists refused, from the tool-scope
+ *     middleware's custom-stream event (`normalizeCustom`): a failure with
+ *     no provenance, since the call never started; and a call a hook
+ *     refused, from the same event written by the approval gate, a failure
+ *     whose provenance names the hook;
+ *   - which hook decided a call that runs, from the gate's `tool_policy`
+ *     custom-stream event: a hook is a process, so its answer is the
+ *     gate's to report and never re-derived here; the builder stamps it on
+ *     the row in either order of arrival;
+ *   - the SCOPE of every event — the root's transcript or one sub-agent's —
+ *     from LangGraph's namespace grammar, and the sub-agent's own lifecycle
+ *     (`sub_agent_started/finished/failed`) from deepagents' `task` tool
+ *     Until #1097 the builder read the namespace and the
+ *     tool's name itself, and kept a second copy of every handler for the
+ *     sub-agents' transcripts.
+ *
+ * What this translator deliberately does NOT answer: whether the gate holds
+ * a call. On native it never has to. LangGraph's `interrupt()` runs inside
+ * the gate middleware BEFORE the tool handler, so a held call emits no
+ * `tool-started` at all; the `tool-started` that does arrive is the engine's
+ * own word that the call was authorized — capture mode let the file write
+ * flow, a lease or the default cleared it, or the user approved it on a
+ * resume. The gate's decision has arms this side cannot evaluate (capture
+ * mode asks the workspace's git state, asynchronously;
+ * `middleware/approval-gate.ts`), and duplicating them would be a second copy
+ * of the decision — exactly the drift one writer per fact exists to end. So
+ * the held call reaches the transcript as `approval_proposed` from the
+ * post-stream seed, the one writer of a row's approval fields; the Cursor
+ * harness answers the same way since #1117. Until #1097 the builder carried a
+ * copy of the decision that gated MCP tools only, a path production never
+ * took.
+ *
+ * Attribution and provenance are answered for ROOT-scope calls only: a
+ * sub-agent's rows carry none on either harness today (#1133), and one
+ * handler set would otherwise stamp them as a side effect.
+ *
+ * The scope, in LangGraph's v3 grammar (read at @langchain/langgraph 1.3.2,
+ * and unchanged at 1.4.18 — the delegation, to-do, tool-call, structured-
+ * output and approval-resume streams were recorded on both and compared;
+ * deepagents' own `createSubagentTransformer`, which this once mirrored, left
+ * with deepagents 1.14 and langchain's `createAgent` registers its
+ * successor): the root's model events arrive under
+ * `["model_request:<uuid>"]` and its tool events under `["tools:<uuid>"]`
+ * (one segment); a `task` tool start at that depth opens a sub-agent, and
+ * the segment it arrived under is the prefix every event of that sub-agent's
+ * graph carries first (`["tools:<uuid>", "model_request:<inner>"]`, two or
+ * more segments). An event with a REGISTERED first segment and two or more
+ * segments is the sub-agent's; everything else is the root's — including a
+ * nested namespace whose prefix nobody registered, which folds into the
+ * root as it always did (a sub-agent resumed inside its own gate
+ * with no re-emitted `task` start is the production case). A `task` inside
+ * a sub-agent is an ordinary row of that sub-agent's transcript: one level
+ * of delegation is tracked, as before.
+ *
+ * Beside the transcript, {@link usageOf} answers the loop's one
+ * non-transcript question about the wire — the usage a
+ * `message-finish` carries — so the loop never parses a raw event itself.
+ * What the wire carries that the transcript does not: `lifecycle` and
+ * `provider` events, the standalone `usage` event, each event's `seq` and
+ * `node`. None of it was ever folded; the recorder keeps the raw event for
+ * a replay.
+ *
+ * The file was `v3-protocol-normalizer.ts` (a stateless `normalize`) until
+ * #1097 made it stateful — the same word as `execute-cursor/translator.ts`,
+ * so a third harness's author finds one shape in both.
+ *
+ * Defensive parsing: handles both snake_case and camelCase field names
+ * for tool IDs/names (protocol spec uses camelCase but recordings show
+ * snake_case). Uses `data.event` as canonical discriminator, with
+ * `data.type` as fallback.
+ */
+import type { V3ProtocolEvent } from "./v3-event-recorder.js";
+import type { TranscriptEvent } from "../../harness/transcript/events.js";
+import type { DeepAgentGateState } from "./turn-setup.js";
+export declare class DeepAgentTranslator {
+    private readonly gate;
+    /** First namespace segment → the sub-agent (its `task` call id) whose graph runs under it. */
+    private readonly subAgentByPrefix;
+    /** The `task` call ids whose completion closes a sub-agent. */
+    private readonly taskCalls;
+    /**
+     * @param gate the turn's gate posture, for attribution and provenance;
+     *   `null` where a turn runs with none (the unit arms that drive the
+     *   builder bare), and then every call is unattributed.
+     */
+    constructor(gate: DeepAgentGateState | null);
+    /** One raw event to its canonical events — `translate(raw)` is the one signature every harness's translator shares. */
+    translate(raw: V3ProtocolEvent): TranscriptEvent[];
+    /** The sub-agent an event belongs to, or `undefined` for the root (see the header for the grammar). */
+    private scopeOf;
+    /**
+     * A `task` start at the root opens a sub-agent keyed by the call id, with
+     * the segment it arrived under as the routing prefix (a depth-0 start —
+     * tests — gets a synthetic one so its children can still name it).
+     */
+    private openSubAgent;
+    /**
+     * The sub-agent a custom-stream event belongs to. A graph's custom writer
+     * stamps the namespace of the graph that streams, not of the node that
+     * wrote: the root's events arrive under `[]`, and a sub-agent's under the
+     * one segment its `task` call registered (read at @langchain/langgraph
+     * 1.4.18, `__tests__/hermetic/tool-lists.test.ts` pins both).
+     */
+    private customScopeOf;
+    /**
+     * A custom-stream event's transcript events (`normalizeCustom`), scoped
+     * like any other. A refused call never opens a sub-agent (the `task` call
+     * never ran); at the root it gets the server attribution, and keeps the
+     * provenance the gate's refusal carries. Inside a sub-agent no row
+     * carries provenance (#1133), so a refusal drops it and a hook's
+     * `tool_policy` is not reported; an unattended skip keeps it, the
+     * provenance `reconcileUnattendedSkips` stamps on the sub-agent's row
+     * after the stream, so the row's use is written as the skip it is.
+     */
+    private custom;
+    /** The attribution and provenance for one root-scope tool start. */
+    private attribute;
+}
+/**
+ * The stateless core: one raw event to its canonical events, root-scoped
+ * (no `subAgentId`) and unattributed (`mcpServerSlug: ""`, no provenance, no
+ * gate). The translator layers scope and the gate's answers on top; the arms
+ * that pin the wire's shape read this directly.
+ */
+export declare function normalize(event: V3ProtocolEvent): TranscriptEvent[];
+/**
+ * The token usage as LangChain's v3 protocol delivers it on a
+ * `message-finish`. `input_tokens` already INCLUDES the cache buckets (the
+ * Anthropic adapter folds them in); the loop prices over the disjoint parts.
+ */
+export interface V3UsagePayload {
+    readonly input_tokens?: number;
+    readonly output_tokens?: number;
+    readonly total_tokens?: number;
+    readonly input_token_details?: {
+        readonly cache_creation?: number;
+        readonly cache_read?: number;
+    };
+}
+/**
+ * The usage one raw event carries, or `undefined`. Read from `message-finish`
+ * ONLY — v3 also emits a standalone `usage` event for the same turn, and
+ * reading both would double-count. Every namespace's finish counts: a
+ * sub-agent's spend is the execution's spend (since #1096), and the cost
+ * cap the runtime enforces reads the whole execution.
+ *
+ * A loop concern, deliberately NOT a `TranscriptEvent`:
+ * usage is neither a row nor a message, and `translate`'s return type stays
+ * the one signature every harness's translator shares. The Cursor loop reads
+ * its usage from the SDK's `turn-ended` delta — the same division.
+ */
+export declare function usageOf(event: V3ProtocolEvent): V3UsagePayload | undefined;