@stigmer/runner 3.15.1 → 3.15.2-dev.20260913223433

package/dist/activities/execute-deep-agent/turn-stream.js

@@ -0,0 +1,242 @@
+/**
+ * The native deep-agent harness's stream phase — the single per-event
+ * consumption loop that turns a live LangGraph v3 event stream into the
+ * streamed transcript and the one fact that decides how
+ * the turn goes on (the graph paused at a gate).
+ *
+ * What the loop asks of the runtime, through the sink (`harness/types.ts`):
+ * `recordActivity()` per event (with the tool name on a tool start), so the
+ * runtime's stall watchdog measures the engine; `reportUsage()` per parent
+ * `message_finish`, priced here at the registry's rates for the model the
+ * turn runs on (`shared/model-pricing.ts`), so the runtime accounts and
+ * enforces the cost cap and writes `streamingUsage` (Q-M2a-2); `requestPersist()`
+ * where a discrete change or the streaming cadence says so
+ * (`shared/persist-decision.ts` over the builder's one dirty flag), AWAITED,
+ * so a platform STOP the runtime reads from that write aborts the signal
+ * before the next event is pulled; and `stopSignal`, checked at every event
+ * boundary and listened to inside the pull, where a stop cancels the graph
+ * run — the same act for every cause of stopping (the runtime knows why;
+ * this loop never does). An error the aborted run throws is the abort itself
+ * and settles `interrupted`, never `failed`.
+ *
+ * WHEN the run is aborted (S3 M2a, F-M2a-18): on the arrival of the next
+ * event — the graph's own step boundary — or after {@link STOP_GRACE_MS} if
+ * no event arrives. A LangGraph run aborted while a step is in flight leaves
+ * `@langchain/core` with an orphaned rejection (`AsyncGeneratorWithSetup`
+ * races its first pull against the signal eagerly, and an abort mid-step
+ * rejects a promise nothing awaits), which surfaces as a process-level
+ * `unhandledRejection` — logged by `main.ts`, but noise the runner must not
+ * produce on every pause. Aborting as an event arrives is clean, and it is
+ * exactly when the orchestrator's loop aborted; so the loop never aborts
+ * right after a persist, even one that answered STOP — it lets the next
+ * event arrive and stops there. A live engine yields an event well inside
+ * the grace; a wedged engine (the runtime's stall watchdog is the caller
+ * here) is forced, and that one orphan is the price of unblocking it — the
+ * contract's bound on settling `interrupted` is what wins.
+ *
+ * Until S3 M2a this loop (`streaming-v3.ts`) armed its own 120 s stall
+ * check, pulsed the Temporal heartbeat every 2 s, read STOP from its own
+ * persist and activated a graceful-stop middleware on it, told a pause from
+ * the activity's cancellation signal, and wrote PAUSED, COMPLETED and
+ * TERMINATED itself; every one of those is the runtime's now, and the loop
+ * reports only `completed`, `awaiting_approval` or `interrupted`. The
+ * graph's recursion limit propagates as its own error for `turn.ts` to
+ * classify (`tool_call_limit`), and an empty stream is an error the same
+ * way (`failed` on the `internal` surface).
+ */
+import { shouldPersistStreamingStatus } from "../../shared/persist-decision.js";
+import { StreamingUpdateScheduler, loadStreamingConfig } from "../../shared/streaming-scheduler.js";
+import { computeTurnCost } from "../../shared/model-pricing.js";
+import { TimeoutError, withTimeout } from "../../shared/with-timeout.js";
+import { InlinePublisher } from "./inline-publisher.js";
+import { StreamingSideEffects } from "./streaming-side-effects.js";
+import { createV3EventRecorder } from "./v3-event-recorder.js";
+import { normalize } from "./v3-protocol-normalizer.js";
+import { V3StatusBuilder } from "./v3-status-builder.js";
+/**
+ * How long the loop waits for `run.output` after the stream ended before
+ * proceeding without the final state (the structured response rides it).
+ */
+const RUN_OUTPUT_TIMEOUT_MS = 30_000;
+/**
+ * How long a stop waits for the next event before the run is aborted
+ * mid-step (see the header). Well inside the contract kit's settle bound and
+ * far above any token cadence a live model has.
+ */
+const STOP_GRACE_MS = 1_000;
+export function createDeepAgentTranscript(input, sink, engine, workspace) {
+    const builder = new V3StatusBuilder(input.executionId, sink.status, {
+        onUsage: (usage) => {
+            // LangChain's `input_tokens` already INCLUDES the cache buckets (the
+            // Anthropic adapter folds them in; the cost advisory reads them the
+            // same way), so the counts are reported as delivered and the price
+            // is computed over the disjoint buckets.
+            const inputTokens = usage.input_tokens ?? 0;
+            const outputTokens = usage.output_tokens ?? 0;
+            const cacheReadTokens = usage.input_token_details?.cache_read ?? 0;
+            const cacheWriteTokens = usage.input_token_details?.cache_creation ?? 0;
+            const uncachedInput = Math.max(inputTokens - cacheReadTokens - cacheWriteTokens, 0);
+            sink.reportUsage({
+                inputTokens,
+                outputTokens,
+                cacheReadTokens,
+                cacheWriteTokens,
+                estimatedCostUsd: computeTurnCost(engine.pricing, uncachedInput, outputTokens, cacheWriteTokens, cacheReadTokens),
+                model: engine.modelName,
+            });
+        },
+    });
+    builder.setApprovalProvider({
+        policies: engine.gate.policies,
+        toolServerMap: engine.gate.toolServerMap,
+        leasedCategories: engine.gate.leasedCategories,
+        globalBypass: engine.gate.globalBypass,
+        unattended: engine.gate.unattended,
+    });
+    const publisher = new InlinePublisher({
+        workspaceBackend: workspace.backend,
+        artifactStorage: input.artifactStorage,
+        statusWriter: builder,
+        executionId: input.executionId,
+    });
+    return { builder, publisher };
+}
+/**
+ * Start the graph run and consume it to the end, folding every event into
+ * the transcript. Returns why it ended; throws only what `turn.ts`
+ * classifies (the recursion limit, an empty stream, an engine error).
+ */
+export async function consumeDeepAgentStream(deps) {
+    const { input, sink, engine, graphInput, transcript } = deps;
+    const { executionId } = input;
+    const { builder, publisher } = transcript;
+    const scheduler = new StreamingUpdateScheduler(loadStreamingConfig());
+    const recorder = createV3EventRecorder(executionId, process.env.V3_EVENT_RECORD_DIR);
+    const sideEffects = new StreamingSideEffects({ inlinePublisher: publisher });
+    const abortController = new AbortController();
+    let forceAbort;
+    const abortRun = () => {
+        if (forceAbort !== undefined)
+            clearTimeout(forceAbort);
+        forceAbort = undefined;
+        abortController.abort("stopped by the runtime");
+    };
+    const onStop = () => {
+        forceAbort = setTimeout(abortRun, STOP_GRACE_MS);
+    };
+    sink.stopSignal.addEventListener("abort", onStop, { once: true });
+    let eventsProcessed = 0;
+    /** The stop, taken at a boundary: abort the run now and settle. */
+    const interrupted = () => {
+        abortRun();
+        return {
+            reason: "interrupted",
+            eventsProcessed,
+            runOutput: undefined,
+            pendingPublishPromises: sideEffects.pendingPublishPromises,
+        };
+    };
+    try {
+        if (sink.stopSignal.aborted)
+            return interrupted();
+        const run = (await engine.graph.streamEvents(graphInput.kind === "resume" ? graphInput.command : graphInput.input, { ...engine.langgraphConfig, version: "v3", signal: abortController.signal }));
+        sink.recordActivity();
+        // An aborted run rejects `run.output` with the abort error; an
+        // interrupted turn never awaits it (there is no final state to read), so
+        // the rejection is claimed here or it surfaces as unhandled. A completed
+        // turn still awaits the same promise below and reads its value.
+        run.output.catch(() => undefined);
+        try {
+            for await (const event of run) {
+                if (sink.stopSignal.aborted)
+                    return interrupted();
+                recorder?.record(event, eventsProcessed);
+                let detail;
+                for (const normalized of normalize(event)) {
+                    builder.processEvent(normalized);
+                    if (normalized.kind === "tool_started")
+                        detail = normalized.name;
+                }
+                sideEffects.onProtocolEvent(event);
+                eventsProcessed++;
+                sink.recordActivity(detail);
+                const persist = shouldPersistStreamingStatus({ deltaEnricherDirty: false, todosDirty: false, contentDirty: builder.forceNextUpdate }, scheduler, eventsProcessed);
+                if (!persist)
+                    continue;
+                builder.clearForceFlag();
+                // The runtime attaches the mid-run file-change progress on this write
+                // (the chokepoint's step 2), as it does on every write. Awaited so a platform STOP the runtime reads from this write has
+                // aborted the signal by the time the next event arrives — where the
+                // stop is taken (see the header on why not here).
+                await sink.requestPersist();
+                scheduler.markUpdateSent(eventsProcessed);
+            }
+        }
+        catch (err) {
+            // The aborted run throws its own abort out of the pull; that is the
+            // stop the runtime asked for, not a failure.
+            if (sink.stopSignal.aborted)
+                return interrupted();
+            throw err;
+        }
+        if (eventsProcessed === 0) {
+            throw new Error("Stream completed without processing any events. " +
+                "This may indicate a configuration error or v3 API incompatibility.");
+        }
+        if (builder.awaitingApproval) {
+            console.log(`[turn-stream] execution=${executionId} stream ended at a gate; awaiting approval`);
+            return {
+                reason: "awaiting_approval",
+                eventsProcessed,
+                runOutput: undefined,
+                pendingPublishPromises: sideEffects.pendingPublishPromises,
+            };
+        }
+        console.log(`[turn-stream] execution=${executionId} stream finished — processed ${eventsProcessed} events`);
+        const runOutput = await extractRunOutput(run, executionId);
+        sink.recordActivity();
+        return { reason: "completed", eventsProcessed, runOutput, pendingPublishPromises: sideEffects.pendingPublishPromises };
+    }
+    finally {
+        sink.stopSignal.removeEventListener("abort", onStop);
+        if (forceAbort !== undefined)
+            clearTimeout(forceAbort);
+        await recorder?.flush();
+    }
+}
+/**
+ * The graph's final state, bounded: `run.output` normally resolves the
+ * moment the stream ends, but a state that never settles must not hold the
+ * turn (the structured response is recoverable from the final text; the
+ * runtime's epilogue does that).
+ *
+ * Bounded through the shared `withTimeout`, never a hand-rolled
+ * `Promise.race` against a bare `setTimeout`: a race leaves its losing timer
+ * armed, and a referenced timer holds the Node event loop open. The
+ * orchestrator's copy of this wait left a 30 s timer behind every completed
+ * execution, so a runner asked to exit right after one idled for the full
+ * Kubernetes termination grace (stigmer#1008, fixed on the orchestrator in
+ * stigmer#1092 while this adapter was on its branch; this copy had cleared
+ * its timer in a `finally` from the start, and took the shared shape at the
+ * merge so there is one way to bound a wait). `withTimeout` clears the timer
+ * on whichever side settles first; `turn-stream.test.ts` pins that nothing
+ * stays armed on either side.
+ */
+async function extractRunOutput(run, executionId) {
+    try {
+        const finalState = await withTimeout(RUN_OUTPUT_TIMEOUT_MS, `run.output did not resolve within ${RUN_OUTPUT_TIMEOUT_MS}ms`, () => run.output);
+        const output = finalState;
+        console.log(`[turn-stream] execution=${executionId} — run.output resolved. ` +
+            `Keys: [${Object.keys(output ?? {}).join(", ")}]. hasStructuredResponse=${output?.structuredResponse !== undefined}`);
+        return output;
+    }
+    catch (err) {
+        if (err instanceof TimeoutError) {
+            console.warn(`[turn-stream] execution=${executionId} — ${err.message}. Proceeding without final state.`);
+            return undefined;
+        }
+        console.warn(`[turn-stream] execution=${executionId} — run.output rejected: ${err}`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=turn-stream.js.map

package/dist/activities/execute-deep-agent/turn-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-stream.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/turn-stream.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,42 @@
+/**
+ * One native deep-agent engine turn — the LangGraph slice of the harness,
+ * behind the turn runtime's contract (`harness/types.ts`).
+ *
+ * `runDeepAgentTurn` is what `adapter.ts`'s `runTurn` delegates to: the
+ * setup over the runtime's record (`turn-setup.ts`), the stream over the
+ * sink (`turn-stream.ts`), the settle (`turn-settle.ts`), and its own
+ * teardown — the MCP connection and the checkpoint saver. Everything else
+ * about a turn is the runtime's (`harness/run-turn.ts`): the resolution
+ * phases, the workspace lock and the `.stigmer` link, the persist
+ * chokepoint, the watchdog, the heartbeat, the cost cap, the interruption
+ * table, the completion epilogue, the SKIP/REJECT settlement.
+ *
+ * This module is where `deepagents` and `@langchain/*` enter the adapter's
+ * graph (through `turn-setup.ts` and its siblings), which is WHY it is a
+ * separate module from `adapter.ts` and is loaded there with a dynamic
+ * import inside `boot`: the harness table's static graph must stay SDK-free
+ * so a worker that does not serve this harness never pays for LangChain
+ * (`harness-adapters.ts`). Nothing outside `adapter.ts` imports this module.
+ *
+ * Never throws out of `runDeepAgentTurn`: the graph exhausting its recursion
+ * limit is the `tool_call_limit` outcome (the platform's budget, not a
+ * failure; the runtime writes TERMINATED with the cross-repo prefix); any
+ * other exception — a provider error unwrapped from LangChain's middleware
+ * wrapper, an MCP connect failure, an empty stream — is `failed` on the
+ * `internal` surface with `describeExecutionError`'s sentence as
+ * `status.error` whole (Q-M2a-9). Never branches on why `stopSignal`
+ * aborted, never writes a phase or a terminal copy, never imports
+ * `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
+ *
+ * Engine disposition: nothing is parked between turns. The sqlite saver is
+ * opened and closed per turn (it holds an OS handle); the MCP subprocesses
+ * are connected and closed per turn. Both are closed on EVERY exit path in
+ * the `finally`, before the runtime removes the link and releases the lock.
+ *
+ * Extracted from `index.ts` `createDeepAgentActivities` at S3 M2a; the
+ * hermetic goldens under `__tests__/hermetic/` pin the result byte for
+ * byte, with the ruled alignments quoted in their headers.
+ */
+import type { TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
+import { type DeepAgentAdapterConfig } from "./turn-setup.js";
+export declare function runDeepAgentTurn(input: TurnInput, sink: TurnSink, config: DeepAgentAdapterConfig): Promise<TurnOutcome>;

package/dist/activities/execute-deep-agent/turn.js

@@ -0,0 +1,116 @@
+/**
+ * One native deep-agent engine turn — the LangGraph slice of the harness,
+ * behind the turn runtime's contract (`harness/types.ts`).
+ *
+ * `runDeepAgentTurn` is what `adapter.ts`'s `runTurn` delegates to: the
+ * setup over the runtime's record (`turn-setup.ts`), the stream over the
+ * sink (`turn-stream.ts`), the settle (`turn-settle.ts`), and its own
+ * teardown — the MCP connection and the checkpoint saver. Everything else
+ * about a turn is the runtime's (`harness/run-turn.ts`): the resolution
+ * phases, the workspace lock and the `.stigmer` link, the persist
+ * chokepoint, the watchdog, the heartbeat, the cost cap, the interruption
+ * table, the completion epilogue, the SKIP/REJECT settlement.
+ *
+ * This module is where `deepagents` and `@langchain/*` enter the adapter's
+ * graph (through `turn-setup.ts` and its siblings), which is WHY it is a
+ * separate module from `adapter.ts` and is loaded there with a dynamic
+ * import inside `boot`: the harness table's static graph must stay SDK-free
+ * so a worker that does not serve this harness never pays for LangChain
+ * (`harness-adapters.ts`). Nothing outside `adapter.ts` imports this module.
+ *
+ * Never throws out of `runDeepAgentTurn`: the graph exhausting its recursion
+ * limit is the `tool_call_limit` outcome (the platform's budget, not a
+ * failure; the runtime writes TERMINATED with the cross-repo prefix); any
+ * other exception — a provider error unwrapped from LangChain's middleware
+ * wrapper, an MCP connect failure, an empty stream — is `failed` on the
+ * `internal` surface with `describeExecutionError`'s sentence as
+ * `status.error` whole (Q-M2a-9). Never branches on why `stopSignal`
+ * aborted, never writes a phase or a terminal copy, never imports
+ * `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
+ *
+ * Engine disposition: nothing is parked between turns. The sqlite saver is
+ * opened and closed per turn (it holds an OS handle); the MCP subprocesses
+ * are connected and closed per turn. Both are closed on EVERY exit path in
+ * the `finally`, before the runtime removes the link and releases the lock.
+ *
+ * Extracted from `index.ts` `createDeepAgentActivities` at S3 M2a; the
+ * hermetic goldens under `__tests__/hermetic/` pin the result byte for
+ * byte, with the ruled alignments quoted in their headers.
+ */
+import { tryInferProvider } from "../../shared/llm-proxy.js";
+import { describeExecutionError } from "../../shared/model-error.js";
+import { isGraphRecursionError } from "../../shared/tool-rounds.js";
+import { buildDeepAgentWorkspace, buildEngine, composeGraphInput, connectTools, openCheckpointer, readGateState, resolveModelName, } from "./turn-setup.js";
+import { consumeDeepAgentStream, createDeepAgentTranscript } from "./turn-stream.js";
+import { settleDeepAgentTurn } from "./turn-settle.js";
+export async function runDeepAgentTurn(input, sink, config) {
+    if (sink.stopSignal.aborted)
+        return { kind: "interrupted" };
+    let checkpointer;
+    let connection;
+    let modelName;
+    try {
+        modelName = await resolveModelName(input);
+        checkpointer = await openCheckpointer(input, sink, config);
+        const workspace = buildDeepAgentWorkspace(input);
+        // What this engine observes touching CAS-owned paths — the one capture
+        // fact the runtime cannot read from the tree (`harness/capture.ts`).
+        sink.bindCasObservations(() => workspace.casObserver.snapshot());
+        const tools = await connectTools(input, sink);
+        connection = tools.connection;
+        if (sink.stopSignal.aborted)
+            return { kind: "interrupted" };
+        const gate = readGateState(input, tools);
+        const engine = await buildEngine(input, sink, config, { modelName, checkpointer, workspace, tools, gate });
+        if (sink.stopSignal.aborted)
+            return { kind: "interrupted" };
+        const graphInput = await composeGraphInput(input, engine);
+        sink.recordActivity();
+        const transcript = createDeepAgentTranscript(input, sink, engine, workspace);
+        const stream = await consumeDeepAgentStream({ input, sink, engine, graphInput, transcript });
+        return await settleDeepAgentTurn({ input, sink, engine, transcript, stream });
+    }
+    catch (err) {
+        return classifyThrown(err, input, config, modelName);
+    }
+    finally {
+        await closeQuietly(input.executionId, "MCP connection", () => connection?.client.close());
+        // Only the durable sqlite saver holds an OS handle (an open DB file);
+        // memory/http savers have no close(), so this is duck-typed.
+        const closable = checkpointer;
+        await closeQuietly(input.executionId, "checkpointer", () => closable?.close?.());
+    }
+}
+/**
+ * An exception that escaped the turn, classified. The graph's recursion
+ * limit is the budget's own signal (`shared/tool-rounds.ts`), not an error:
+ * the work is checkpointed and the conversation continues on the next
+ * message. Anything else is described by `describeExecutionError` (a model
+ * error arrives MiddlewareError-wrapped with raw provider prose and is
+ * unwrapped to its stable platform code; non-model errors keep the root
+ * error's identity) on the `internal` surface: the runner or its transport
+ * broke.
+ */
+function classifyThrown(err, input, config, modelName) {
+    if (isGraphRecursionError(err)) {
+        console.log(`ExecuteDeepAgent reached the tool-call limit: execution=${input.executionId}`);
+        return { kind: "tool_call_limit" };
+    }
+    const { errorType, errorMessage } = describeExecutionError(err, {
+        proxyMode: !!config.proxyEndpoint,
+        modelId: modelName,
+        provider: modelName ? (tryInferProvider(modelName) ?? undefined) : undefined,
+    });
+    console.error(`ExecuteDeepAgent failed: execution=${input.executionId}, [${errorType}] ${errorMessage}`);
+    return { kind: "failed", surface: "internal", message: `[${errorType}] ${errorMessage}`, cause: err };
+}
+/** Best-effort teardown: a failed close is logged and never masks the turn's outcome. */
+async function closeQuietly(executionId, what, close) {
+    try {
+        await close();
+    }
+    catch (err) {
+        console.warn(`ExecuteDeepAgent ${what} cleanup failed (non-fatal): execution=${executionId}, error=${err}`);
+    }
+}
+//# sourceMappingURL=turn.js.map

package/dist/activities/execute-deep-agent/turn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/turn.ts"],"names":[],"mappings":"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"}

package/dist/activities/execute-deep-agent/v3-event-recorder.d.ts

@@ -2,12 +2,13 @@
  * V3 event recorder for capturing raw LangGraph v3 ProtocolEvents.
  *
  * Activated by the V3_EVENT_RECORD_DIR environment variable. When set,
- * the v3 streaming loop records every raw protocol event and flushes
- * them atomically to a JSON file after the stream completes.
+ * the adapter's stream loop (`turn-stream.ts`) records every raw protocol
+ * event and flushes them atomically to a JSON file after the stream
+ * completes — the native twin of `execute-cursor/cursor-event-recorder.ts`.
  *
- * This is test/development infrastructure for the v3 streaming migration.
- * The captured events serve as ground-truth for building the
- * V3StatusBuilder and validating v3 event shape assumptions.
+ * Development infrastructure: the captured events are the ground truth the
+ * v3 fixtures (`__test-utils__/v3-event-fixtures.ts`) and the builder's
+ * tests were shaped from, and the way a new provider's event shape is read.
  */
 export interface V3EventRecorder {
     record(event: V3ProtocolEvent, seq: number): void;

package/dist/activities/execute-deep-agent/v3-event-recorder.js

@@ -2,12 +2,13 @@
  * V3 event recorder for capturing raw LangGraph v3 ProtocolEvents.
  *
  * Activated by the V3_EVENT_RECORD_DIR environment variable. When set,
- * the v3 streaming loop records every raw protocol event and flushes
- * them atomically to a JSON file after the stream completes.
+ * the adapter's stream loop (`turn-stream.ts`) records every raw protocol
+ * event and flushes them atomically to a JSON file after the stream
+ * completes — the native twin of `execute-cursor/cursor-event-recorder.ts`.
  *
- * This is test/development infrastructure for the v3 streaming migration.
- * The captured events serve as ground-truth for building the
- * V3StatusBuilder and validating v3 event shape assumptions.
+ * Development infrastructure: the captured events are the ground truth the
+ * v3 fixtures (`__test-utils__/v3-event-fixtures.ts`) and the builder's
+ * tests were shaped from, and the way a new provider's event shape is read.
  */
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";

package/dist/activities/execute-deep-agent/v3-event-recorder.js.map

@@ -1 +1 @@
-{"version":3,"file":"v3-event-recorder.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/v3-event-recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA8BjC;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAmB,EACnB,SAA6B;IAE7B,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,IAAI,mBAAmB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,mBAAmB;IAIJ;IACA;IAJF,MAAM,GAAsB,EAAE,CAAC;IAEhD,YACmB,WAAmB,EACnB,SAAiB;QADjB,gBAAW,GAAX,WAAW,CAAQ;QACnB,cAAS,GAAT,SAAS,CAAQ;IACjC,CAAC;IAEJ,MAAM,CAAC,KAAsB,EAAE,GAAW;QACxC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,GAAG;YACH,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS;YACjC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS;YACjC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI;YACvB,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;SACnC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAErC,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEjD,MAAM,QAAQ,GAAG,IAAI,CACnB,IAAI,CAAC,SAAS,EACd,GAAG,IAAI,CAAC,WAAW,iBAAiB,CACrC,CAAC;QAEF,MAAM,OAAO,GAAG;YACd,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC9B,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC;QAEF,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC;CACF;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/D,CAAC;QACD,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC;IACvC,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,KAAc;IAClD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAC9D,CAAC"}
+{"version":3,"file":"v3-event-recorder.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/v3-event-recorder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AA8BjC;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,WAAmB,EACnB,SAA6B;IAE7B,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAC;IACjC,OAAO,IAAI,mBAAmB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,mBAAmB;IAIJ;IACA;IAJF,MAAM,GAAsB,EAAE,CAAC;IAEhD,YACmB,WAAmB,EACnB,SAAiB;QADjB,gBAAW,GAAX,WAAW,CAAQ;QACnB,cAAS,GAAT,SAAS,CAAQ;IACjC,CAAC;IAEJ,MAAM,CAAC,KAAsB,EAAE,GAAW;QACxC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YACf,GAAG;YACH,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS;YACjC,SAAS,EAAE,KAAK,CAAC,MAAM,CAAC,SAAS;YACjC,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,IAAI;YACvB,IAAI,EAAE,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;SACnC,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAErC,MAAM,KAAK,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEjD,MAAM,QAAQ,GAAG,IAAI,CACnB,IAAI,CAAC,SAAS,EACd,GAAG,IAAI,CAAC,WAAW,iBAAiB,CACrC,CAAC;QAEF,MAAM,OAAO,GAAG;YACd,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACpC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;YAC9B,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC;QAEF,MAAM,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,CAAC;IACxE,CAAC;CACF;AAED,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/D,CAAC;QACD,OAAO,EAAE,mBAAmB,EAAE,IAAI,EAAE,CAAC;IACvC,CAAC;AACH,CAAC;AAED,SAAS,cAAc,CAAC,IAAY,EAAE,KAAc;IAClD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC;AAC9D,CAAC"}

package/dist/activities/execute-deep-agent/v3-events.d.ts

@@ -6,7 +6,7 @@
  * AgentExecutionStatus proto.
  *
  * This is a runner-internal contract (not persisted, not exposed to
- * clients). It isolates the StatusBuilder from LangGraph protocol
+ * clients). It isolates the V3StatusBuilder from LangGraph protocol
  * instability (field naming, delta shapes, channel semantics).
  *
  * ID conventions:

package/dist/activities/execute-deep-agent/v3-events.js

@@ -6,7 +6,7 @@
  * AgentExecutionStatus proto.
  *
  * This is a runner-internal contract (not persisted, not exposed to
- * clients). It isolates the StatusBuilder from LangGraph protocol
+ * clients). It isolates the V3StatusBuilder from LangGraph protocol
  * instability (field naming, delta shapes, channel semantics).
  *
  * ID conventions:

package/dist/activities/execute-deep-agent/v3-status-builder.d.ts

@@ -1,32 +1,77 @@
 /**
  * V3StatusBuilder — consumes StigmerRunEvents from the V3ProtocolNormalizer
- * and progressively builds the AgentExecutionStatus proto.
+ * and progressively builds the transcript half of the AgentExecutionStatus
+ * proto it is handed: messages, tool-call rows and their approval status,
+ * sub-agent rows, todos, artifacts, write-backs.
  *
- * Implements the same behavioral contract as the v2 StatusBuilder for all
- * 8 golden scenarios, using v3 event semantics (tool_call_id keying,
- * content-block-level deltas, explicit tool lifecycle).
+ * The one transcript builder of the native harness since S3 M2b: v3 event
+ * semantics (tool_call_id keying, content-block-level deltas, explicit tool
+ * lifecycle). Its predecessor, the v2 `StatusBuilder` over LangChain's
+ * `streamEvents` v2, was retired with the v2 stream (Q-S3-1); the eight
+ * golden sequences both once had to agree on are this builder's test's.
  *
- * Usage is accumulated on message_finish only (standalone usage events are
+ * What this builder deliberately does NOT write, and who does (the adapter
+ * contract's field ownership, `harness/types.ts` `TurnSink`): the phase,
+ * `startedAt` and `streamingUsage` are the turn runtime's. A gated tool
+ * start is reported as the {@link awaitingApproval} fact and the caller
+ * (`turn-stream.ts`) decides what that means for the turn; usage is reported
+ * raw through {@link V3StatusBuilderOptions.onUsage} and the caller prices
+ * it into the sink (until S3 M2a this builder flipped WAITING_FOR_APPROVAL
+ * itself and summed usage into `streamingUsage` — a second writer of each
+ * field beside the runtime's).
+ *
+ * Usage is reported on message_finish only (standalone usage events are
  * no-ops) to prevent double-counting — v3 emits both for the same turn.
+ * EVERY graph's usage is reported, the sub-agents' included (S3 M2b,
+ * Q-M2b-1): a sub-agent's `message_finish` fires the same hook before it is
+ * routed to the tracker, so the execution's usage — and the cost cap the
+ * runtime enforces over it — is the whole execution's spend. Until M2b the
+ * sub-agents' turns were discarded (S3 M2a finding F-M2a-12); the cost cap
+ * then lived inside the graph, where a middleware saw every model call.
  */
 import type { AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import type { ExecutionArtifact } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/artifact_pb";
 import type { WorkspaceWriteBack } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/writeback_pb";
 import type { ExecutionStatusWriter } from "../../shared/execution-status-writer.js";
-import type { ApprovalPolicyProvider } from "./status-builder.js";
-import type { StigmerRunEvent } from "./v3-events.js";
+import type { StigmerRunEvent, V3UsagePayload } from "./v3-events.js";
+import { type ApprovalPolicyProvider } from "./status-builder-shared.js";
+export interface V3StatusBuilderOptions {
+    /**
+     * Fired once per `message_finish` that carries usage — the parent graph's
+     * and every sub-agent's — with the payload exactly as the protocol
+     * delivered it. The builder never sums or prices: the caller accounts (the
+     * turn runtime through `TurnSink.reportUsage`, priced at the turn's model;
+     * a sub-agent on its own model is priced at the parent's rate, as the
+     * in-graph cost cap always did — per-sub-agent pricing is an S5 item).
+     */
+    readonly onUsage?: (usage: V3UsagePayload) => void;
+}
 export declare class V3StatusBuilder implements ExecutionStatusWriter {
     readonly executionId: string;
     private readonly state;
     private _forceNextUpdate;
+    private _awaitingApproval;
     private approvalProvider;
-    private readonly usageAccumulator;
+    private readonly onUsage;
     private readonly subAgentTracker;
     /** Progressive tool call arg accumulation keyed by callId. */
     private readonly toolArgBuffers;
-    constructor(executionId: string, initialStatus: AgentExecutionStatus);
+    /**
+     * Builds INTO `status`, by reference: its `messages` and
+     * `subAgentExecutions` arrays are the ones indexed and pushed into, never
+     * replaced, so a caller that wraps the same status (the write-back
+     * coordinator's writer, the runtime's chokepoint) keeps seeing every row.
+     */
+    constructor(executionId: string, status: AgentExecutionStatus, options?: V3StatusBuilderOptions);
     setApprovalProvider(provider: ApprovalPolicyProvider): void;
     get currentStatus(): AgentExecutionStatus;
+    /**
+     * True once a tool call this turn was gated and left WAITING_APPROVAL: the
+     * engine has interrupted (or will, at this step's end) and the turn should
+     * end awaiting a decision. A fact about the transcript, not a phase — the
+     * caller owns the phase.
+     */
+    get awaitingApproval(): boolean;
     get forceNextUpdate(): boolean;
     clearForceFlag(): void;
     processEvent(event: StigmerRunEvent): void;
@@ -50,19 +95,17 @@ export declare class V3StatusBuilder implements ExecutionStatusWriter {
     private checkApprovalRequirement;
     private ensureAiMessage;
     private ensureAiMessageForToolCall;
-    private accumulateV3Usage;
     /**
      * Check if a tool_call_id belongs to a tracked "task" tool invocation.
      * Used to route tool_finished/tool_error events to both parent and tracker.
      */
     private isTrackedTaskTool;
     /**
-     * Sync sub-agent executions into the proto for persistence.
-     * Called by the streaming orchestrator before each persist.
-     */
-    syncSubAgentExecutions(): void;
-    /**
-     * Cancel all in-progress sub-agents (called on parent cancellation).
+     * Clear the streaming flag on every sub-agent message still marked as
+     * streaming — what a turn that stopped mid-delegation owes the transcript
+     * beside the CANCELLED status the caller stamps on the row itself
+     * (`shared/subagent-rows.ts` `cancelInProgressSubAgentProtos`, the one
+     * home of that transition for every harness).
      */
-    cancelSubAgents(): void;
+    finalizeSubAgentStreaming(): void;
 }