@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/activities/execute-deep-agent/__test-utils__/v3-event-fixtures.js

@@ -0,0 +1,195 @@
+/**
+ * V3 protocol event factories for the translator's and the builder's arms.
+ *
+ * Shapes are derived from real recordings in /tmp/stigmer-v3-provider/
+ * captured from live runs with Claude claude-sonnet-4-6.
+ *
+ * Namespaces default to LangGraph 1.3.2's REAL shape (since #1097): a model
+ * event arrives under `["model_request:<uuid>"]` and a tool
+ * event under `["tools:<uuid>"]` — one segment each, a fresh uuid per LLM
+ * call / tool run. Until then the model factories defaulted to `[]`, so the
+ * arms never saw the namespace miss the hermetic goldens showed (found in
+ * #1096: the root builder filed text under the raw namespace and
+ * looked a tool's parent up under `""`). A sub-agent's events pass their own
+ * `namespace` (`["tools:<taskUuid>", "model_request:<inner>"]`).
+ */
+/** The namespace a root model event carries: the model node's segment, per LLM call. */
+function modelNamespace(runId) {
+    return [`model_request:${runId}`];
+}
+let seqCounter = 0;
+export function resetSeq() { seqCounter = 0; }
+function nextSeq() { return seqCounter++; }
+// ── Core Factory ──────────────────────────────────────────────────
+export function makeProtocolEvent(method, data, opts) {
+    return {
+        type: "event",
+        seq: opts?.seq ?? nextSeq(),
+        method,
+        params: {
+            namespace: opts?.namespace ?? [],
+            timestamp: opts?.timestamp ?? Date.now(),
+            node: opts?.node,
+            data,
+        },
+    };
+}
+// ── Lifecycle ─────────────────────────────────────────────────────
+export function makeLifecycleRunning(graphName = "root") {
+    return makeProtocolEvent("lifecycle", { event: "running", graph_name: graphName });
+}
+export function makeLifecycleStarted(graphName, ns) {
+    return makeProtocolEvent("lifecycle", { event: "started", graph_name: graphName }, { namespace: ns });
+}
+export function makeLifecycleCompleted(graphName, ns) {
+    return makeProtocolEvent("lifecycle", { event: "completed", graph_name: graphName }, { namespace: ns });
+}
+// ── Messages: message-start / message-finish ──────────────────────
+export function makeMessageStart(runId, opts) {
+    return makeProtocolEvent("messages", {
+        event: "message-start",
+        id: opts?.messageId ?? `msg_${runId}`,
+        usage: opts?.usage,
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: opts?.node ?? "model_request" });
+}
+export function makeMessageFinish(runId, opts) {
+    return makeProtocolEvent("messages", {
+        event: "message-finish",
+        reason: opts?.reason ?? "end_turn",
+        usage: opts?.usage,
+        metadata: opts?.metadata,
+        responseMetadata: opts?.metadata,
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: opts?.node ?? "model_request" });
+}
+// ── Messages: content-block-start/delta/finish ────────────────────
+export function makeContentBlockStartText(runId, index = 0, opts) {
+    return makeProtocolEvent("messages", {
+        event: "content-block-start",
+        index,
+        content: { type: "text", text: "" },
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: "model_request" });
+}
+export function makeTextDelta(runId, text, opts) {
+    return makeProtocolEvent("messages", {
+        event: "content-block-delta",
+        index: opts?.index ?? 0,
+        delta: { type: "text-delta", text },
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: "model_request" });
+}
+export function makeReasoningDelta(runId, text, opts) {
+    return makeProtocolEvent("messages", {
+        event: "content-block-delta",
+        index: opts?.index ?? 0,
+        delta: { type: "reasoning-delta", reasoning: text },
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: "model_request" });
+}
+export function makeToolCallArgDelta(runId, callId, args, opts) {
+    return makeProtocolEvent("messages", {
+        event: "content-block-delta",
+        index: opts?.index ?? 0,
+        delta: {
+            type: "block-delta",
+            fields: { type: "tool_call_chunk", id: callId, args },
+        },
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: "model_request" });
+}
+export function makeContentBlockFinish(runId, index = 0, opts) {
+    return makeProtocolEvent("messages", {
+        event: "content-block-finish",
+        index,
+        content: opts?.content ?? { type: "text", text: "" },
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: "model_request" });
+}
+// ── Messages: usage / provider ────────────────────────────────────
+export function makeUsageEvent(runId, usage, opts) {
+    return makeProtocolEvent("messages", {
+        event: "usage",
+        usage,
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: "model_request" });
+}
+export function makeProviderEvent(runId, provider, model, opts) {
+    return makeProtocolEvent("messages", {
+        event: "provider",
+        provider,
+        name: "message_start",
+        payload: { model, id: `msg_${runId}` },
+        run_id: runId,
+    }, { namespace: opts?.namespace ?? modelNamespace(runId), node: "model_request" });
+}
+// ── Tools ─────────────────────────────────────────────────────────
+export function makeToolStarted(callId, toolName, input = "{}", opts) {
+    return makeProtocolEvent("tools", {
+        event: "tool-started",
+        tool_call_id: callId,
+        tool_name: toolName,
+        input,
+    }, { namespace: opts?.namespace ?? [`tools:${callId}`] });
+}
+export function makeToolFinished(callId, output = "ok", opts) {
+    const wrappedOutput = typeof output === "string"
+        ? {
+            lc: 1, type: "constructor",
+            id: ["langchain_core", "messages", "ToolMessage"],
+            kwargs: { status: "success", content: output, tool_call_id: callId, name: "tool" },
+        }
+        : output;
+    return makeProtocolEvent("tools", {
+        event: "tool-finished",
+        tool_call_id: callId,
+        output: wrappedOutput,
+    }, { namespace: opts?.namespace ?? [`tools:${callId}`] });
+}
+export function makeToolError(callId, message, opts) {
+    return makeProtocolEvent("tools", {
+        event: "tool-error",
+        tool_call_id: callId,
+        message,
+    }, { namespace: opts?.namespace ?? [`tools:${callId}`] });
+}
+export function makeToolOutputDelta(callId, delta, opts) {
+    return makeProtocolEvent("tools", {
+        event: "tool-output-delta",
+        tool_call_id: callId,
+        delta,
+    }, { namespace: opts?.namespace ?? [`tools:${callId}`] });
+}
+// ── Ignored channels (for translator completeness tests) ──────────
+export function makeCheckpointEvent() {
+    return makeProtocolEvent("checkpoints", {
+        id: "ckpt_001",
+        parent_id: "ckpt_000",
+        step: 1,
+        source: "loop",
+    });
+}
+export function makeTasksEvent() {
+    return makeProtocolEvent("tasks", {
+        id: "task_001",
+        name: "model_request",
+        input: {},
+        triggers: [],
+        interrupts: [],
+    });
+}
+export function makeValuesEvent() {
+    return makeProtocolEvent("values", {
+        messages: [],
+        todos: [],
+        files: {},
+    });
+}
+export function makeUpdatesEvent(node = "model_request") {
+    return makeProtocolEvent("updates", {
+        node,
+        values: {},
+    }, { node });
+}
+//# sourceMappingURL=v3-event-fixtures.js.map

package/dist/activities/execute-deep-agent/__test-utils__/v3-event-fixtures.js.map

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

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

@@ -0,0 +1,41 @@
+/**
+ * The native deep-agent harness as a `HarnessAdapter` — the worker- and
+ * session-lifetime half of its LangGraph slice, behind the turn runtime's
+ * contract (`harness/types.ts`). One engine turn is `turn.ts`'s
+ * `runDeepAgentTurn`; this module boots and delegates.
+ *
+ * What this adapter owns: the deepagents harness profiles (worker lifetime,
+ * registered once before the first `createDeepAgent`), and one engine turn
+ * (`runTurn`, through `turn.ts`). Everything else about a turn is the
+ * runtime's (`harness/run-turn.ts`).
+ *
+ * THIS MODULE'S STATIC GRAPH IS SDK-FREE, ON PURPOSE. The composition roots
+ * import the harness table (`src/harness-adapters.ts`) BEFORE they boot it,
+ * and that table's static graph must stay connect- and SDK-free (the Cursor
+ * adapter's boot patches `node:http2` before anything dials the control
+ * plane). So `deepagents` and `@langchain/*` — this harness's whole engine —
+ * are loaded with a dynamic import INSIDE `boot`, after the profiles are
+ * registered; a worker that does not serve this harness never pays for
+ * LangChain. `__tests__/adapter-graph-is-sdk-free.test.ts` pins it.
+ *
+ * Nothing is parked per session, and the header says so where the contract
+ * asks: the sqlite saver is opened and closed per turn and the MCP
+ * subprocesses are connected and closed per turn (`turn.ts`), so
+ * `shutdown` and `releaseSession` resolve as no-ops.
+ *
+ * What this adapter never does: throw out of `runTurn` (an engine failure is
+ * `failed` on the `internal` surface; the recursion limit is
+ * `tool_call_limit`; a `CancelledFailure` never exists here), branch on why
+ * `stopSignal` aborted, write a phase or a terminal copy, bind a state id
+ * (the thread id is the runtime's, `deterministic`), or import
+ * `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
+ *
+ * Extracted from `index.ts` `createDeepAgentActivities` in #1096 on the
+ * Cursor adapter's layout (`execute-cursor/adapter.ts`).
+ */
+import type { Config } from "../../config.js";
+import type { HarnessAdapter } from "../../harness/types.js";
+import type { DeepAgentAdapterConfig } from "./turn-setup.js";
+/** The config slice this adapter reads per turn, taken at `boot`; a whole `Config` satisfies it. */
+export declare function resolveDeepAgentConfig(config: Config): DeepAgentAdapterConfig;
+export declare function createDeepAgentAdapter(): HarnessAdapter;

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

@@ -0,0 +1,79 @@
+/**
+ * The native deep-agent harness as a `HarnessAdapter` — the worker- and
+ * session-lifetime half of its LangGraph slice, behind the turn runtime's
+ * contract (`harness/types.ts`). One engine turn is `turn.ts`'s
+ * `runDeepAgentTurn`; this module boots and delegates.
+ *
+ * What this adapter owns: the deepagents harness profiles (worker lifetime,
+ * registered once before the first `createDeepAgent`), and one engine turn
+ * (`runTurn`, through `turn.ts`). Everything else about a turn is the
+ * runtime's (`harness/run-turn.ts`).
+ *
+ * THIS MODULE'S STATIC GRAPH IS SDK-FREE, ON PURPOSE. The composition roots
+ * import the harness table (`src/harness-adapters.ts`) BEFORE they boot it,
+ * and that table's static graph must stay connect- and SDK-free (the Cursor
+ * adapter's boot patches `node:http2` before anything dials the control
+ * plane). So `deepagents` and `@langchain/*` — this harness's whole engine —
+ * are loaded with a dynamic import INSIDE `boot`, after the profiles are
+ * registered; a worker that does not serve this harness never pays for
+ * LangChain. `__tests__/adapter-graph-is-sdk-free.test.ts` pins it.
+ *
+ * Nothing is parked per session, and the header says so where the contract
+ * asks: the sqlite saver is opened and closed per turn and the MCP
+ * subprocesses are connected and closed per turn (`turn.ts`), so
+ * `shutdown` and `releaseSession` resolve as no-ops.
+ *
+ * What this adapter never does: throw out of `runTurn` (an engine failure is
+ * `failed` on the `internal` surface; the recursion limit is
+ * `tool_call_limit`; a `CancelledFailure` never exists here), branch on why
+ * `stopSignal` aborted, write a phase or a terminal copy, bind a state id
+ * (the thread id is the runtime's, `deterministic`), or import
+ * `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
+ *
+ * Extracted from `index.ts` `createDeepAgentActivities` in #1096 on the
+ * Cursor adapter's layout (`execute-cursor/adapter.ts`).
+ */
+import { DEEP_AGENT_CAPABILITIES } from "./deep-agent-capabilities.js";
+/** The config slice this adapter reads per turn, taken at `boot`; a whole `Config` satisfies it. */
+export function resolveDeepAgentConfig(config) {
+    return {
+        checkpointerType: config.checkpointerType,
+        checkpointerProxyEndpoint: config.checkpointerProxyEndpoint,
+        stigmerTokenRef: config.stigmerTokenRef,
+        proxyEndpoint: config.proxyEndpoint,
+        mode: config.mode,
+        cursorStreamStallTimeoutMs: config.cursorStreamStallTimeoutMs,
+    };
+}
+export function createDeepAgentAdapter() {
+    let booted;
+    return {
+        name: "deep-agent",
+        capabilities: DEEP_AGENT_CAPABILITIES,
+        /**
+         * Register the harness profiles (deepagents would otherwise auto-inject
+         * an ungated `general-purpose` sub-agent into every graph), then load
+         * the engine slice. Idempotent: a re-boot re-reads the slice; the
+         * registration is once-guarded.
+         */
+        async boot(bootConfig) {
+            // `deepagents-profiles.ts` imports the SDK to register against it, so
+            // it too is loaded here and not at the top of this module.
+            const { registerStigmerDeepagentsProfiles } = await import("./deepagents-profiles.js");
+            registerStigmerDeepagentsProfiles();
+            const { runDeepAgentTurn } = await import("./turn.js");
+            booted = { config: resolveDeepAgentConfig(bootConfig), runDeepAgentTurn };
+        },
+        /** Nothing is held across turns (see the header). */
+        async shutdown() { },
+        /** Nothing is parked per session (see the header); an unknown id is a no-op by construction. */
+        async releaseSession(_sessionId) { },
+        async runTurn(input, sink) {
+            if (booted === undefined) {
+                throw new Error("deep-agent adapter: runTurn before boot (the registry boots every adapter before the worker polls)");
+            }
+            return booted.runDeepAgentTurn(input, sink, booted.config);
+        },
+    };
+}
+//# sourceMappingURL=adapter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAIH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,oGAAoG;AACpG,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,OAAO;QACL,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;QACzC,yBAAyB,EAAE,MAAM,CAAC,yBAAyB;QAC3D,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,0BAA0B,EAAE,MAAM,CAAC,0BAA0B;KAC9D,CAAC;AACJ,CAAC;AAQD,MAAM,UAAU,sBAAsB;IACpC,IAAI,MAA0C,CAAC;IAE/C,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,YAAY,EAAE,uBAAuB;QAErC;;;;;WAKG;QACH,KAAK,CAAC,IAAI,CAAC,UAAkB;YAC3B,sEAAsE;YACtE,2DAA2D;YAC3D,MAAM,EAAE,iCAAiC,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;YACvF,iCAAiC,EAAE,CAAC;YACpC,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC;YACvD,MAAM,GAAG,EAAE,MAAM,EAAE,sBAAsB,CAAC,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;QAC5E,CAAC;QAED,qDAAqD;QACrD,KAAK,CAAC,QAAQ,KAAmB,CAAC;QAElC,gGAAgG;QAChG,KAAK,CAAC,cAAc,CAAC,UAAkB,IAAkB,CAAC;QAE1D,KAAK,CAAC,OAAO,CAAC,KAAgB,EAAE,IAAc;YAC5C,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;gBACzB,MAAM,IAAI,KAAK,CAAC,oGAAoG,CAAC,CAAC;YACxH,CAAC;YACD,OAAO,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7D,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/activities/execute-deep-agent/approval-file-change.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Pre-execution args capture for the HITL approval gate (native harness).
+ *
+ * When the graph pauses for approval — before the tool runs — this recovers
+ * the proposed call's arguments so the gate can show the proposed change. It
+ * owns only the native-specific seam: correlating a gated `tool_call_id` to
+ * its arguments from graph state (the authoritative single source of truth at
+ * the interrupt, since the streamed input cache is empty and the interrupt
+ * value carries only a few fields). The approval card renders the proposed
+ * write/edit content from these args; there is no separate captured
+ * `file_changes` (removed — the args are the single
+ * source, and the Cursor deny-gate's exact-apply reads the same args on
+ * resume; see shared/exact-apply.ts). The row's `args_preview` is the
+ * builder's to write from these args (since #1097; until then this module
+ * rendered it too, a second call of the one sanitizer).
+ */
+/** What the gate capture contributes to a `WAITING_APPROVAL` `ToolCall`. */
+export interface ApprovalCaptureResult {
+    /**
+     * The secret-redacted args object, for stamping `ToolCall.args` on the
+     * proposed row. Without it the row carried ONLY the preview string, so
+     * every args-driven UI read — the row header's filename-first path above
+     * all — rendered nothing for a pending gate (issue #754). Redacted (never
+     * raw): the row must not widen the exposure the preview sanitizer bounds.
+     */
+    readonly args?: Record<string, unknown>;
+}
+/**
+ * Correlate a gated `tool_call_id` to its arguments by scanning graph-state
+ * messages for the AI-message tool call that emitted it.
+ *
+ * Matching keys on the presence of a `tool_calls` array, which is robust to
+ * whether the message is a hydrated LangChain class instance or a plain
+ * serialized object: a `ToolMessage` carries a singular `tool_call_id`, never a
+ * `tool_calls` array, so it cannot be mistaken for the emitting AI message.
+ *
+ * Returns the args object (possibly empty when the tool call took no arguments),
+ * or `undefined` when no message in scope emitted this id — e.g. a tool call
+ * whose AI message lives only inside a nested sub-agent state, which this
+ * parent-scope scan does not reach. That degrades the gate to an args-less
+ * preview for that one interrupt, exactly as today.
+ */
+export declare function findAiMessageToolCallArgs(messages: readonly unknown[], toolCallId: string): Record<string, unknown> | undefined;
+/**
+ * Capture the gate's redacted args from a single correlation lookup, keeping
+ * the call site thin.
+ *
+ * Returns an empty result when the tool call cannot be correlated or took no
+ * arguments, so the proposed row carries no args for that interrupt.
+ */
+export declare function captureApprovalArtifacts(opts: {
+    readonly toolCallId: string;
+    readonly messages: readonly unknown[];
+}): ApprovalCaptureResult;

package/dist/activities/execute-deep-agent/approval-file-change.js

@@ -0,0 +1,68 @@
+/**
+ * Pre-execution args capture for the HITL approval gate (native harness).
+ *
+ * When the graph pauses for approval — before the tool runs — this recovers
+ * the proposed call's arguments so the gate can show the proposed change. It
+ * owns only the native-specific seam: correlating a gated `tool_call_id` to
+ * its arguments from graph state (the authoritative single source of truth at
+ * the interrupt, since the streamed input cache is empty and the interrupt
+ * value carries only a few fields). The approval card renders the proposed
+ * write/edit content from these args; there is no separate captured
+ * `file_changes` (removed — the args are the single
+ * source, and the Cursor deny-gate's exact-apply reads the same args on
+ * resume; see shared/exact-apply.ts). The row's `args_preview` is the
+ * builder's to write from these args (since #1097; until then this module
+ * rendered it too, a second call of the one sanitizer).
+ */
+import { redactSensitiveArgs } from "../../shared/args-preview.js";
+/**
+ * Correlate a gated `tool_call_id` to its arguments by scanning graph-state
+ * messages for the AI-message tool call that emitted it.
+ *
+ * Matching keys on the presence of a `tool_calls` array, which is robust to
+ * whether the message is a hydrated LangChain class instance or a plain
+ * serialized object: a `ToolMessage` carries a singular `tool_call_id`, never a
+ * `tool_calls` array, so it cannot be mistaken for the emitting AI message.
+ *
+ * Returns the args object (possibly empty when the tool call took no arguments),
+ * or `undefined` when no message in scope emitted this id — e.g. a tool call
+ * whose AI message lives only inside a nested sub-agent state, which this
+ * parent-scope scan does not reach. That degrades the gate to an args-less
+ * preview for that one interrupt, exactly as today.
+ */
+export function findAiMessageToolCallArgs(messages, toolCallId) {
+    for (const msg of messages) {
+        if (!msg || typeof msg !== "object")
+            continue;
+        const toolCalls = msg.tool_calls;
+        if (!Array.isArray(toolCalls))
+            continue;
+        for (const tc of toolCalls) {
+            if (!tc || typeof tc !== "object")
+                continue;
+            const entry = tc;
+            if (entry.id !== toolCallId)
+                continue;
+            return entry.args &&
+                typeof entry.args === "object" &&
+                !Array.isArray(entry.args)
+                ? entry.args
+                : {};
+        }
+    }
+    return undefined;
+}
+/**
+ * Capture the gate's redacted args from a single correlation lookup, keeping
+ * the call site thin.
+ *
+ * Returns an empty result when the tool call cannot be correlated or took no
+ * arguments, so the proposed row carries no args for that interrupt.
+ */
+export function captureApprovalArtifacts(opts) {
+    const args = findAiMessageToolCallArgs(opts.messages, opts.toolCallId);
+    if (!args || Object.keys(args).length === 0)
+        return {};
+    return { args: redactSensitiveArgs(args) };
+}
+//# sourceMappingURL=approval-file-change.js.map

package/dist/activities/execute-deep-agent/approval-file-change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-file-change.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/approval-file-change.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAcH,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,yBAAyB,CACvC,QAA4B,EAC5B,UAAkB;IAElB,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;QAC3B,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,SAAS;QAC9C,MAAM,SAAS,GAAI,GAAgC,CAAC,UAAU,CAAC;QAC/D,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;YAAE,SAAS;QAExC,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YAC3B,IAAI,CAAC,EAAE,IAAI,OAAO,EAAE,KAAK,QAAQ;gBAAE,SAAS;YAC5C,MAAM,KAAK,GAAG,EAAsC,CAAC;YACrD,IAAI,KAAK,CAAC,EAAE,KAAK,UAAU;gBAAE,SAAS;YAEtC,OAAO,KAAK,CAAC,IAAI;gBACf,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;gBAC9B,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC1B,CAAC,CAAE,KAAK,CAAC,IAAgC;gBACzC,CAAC,CAAC,EAAE,CAAC;QACT,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAGxC;IACC,MAAM,IAAI,GAAG,yBAAyB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IACvE,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEvD,OAAO,EAAE,IAAI,EAAE,mBAAmB,CAAC,IAAI,CAAC,EAAE,CAAC;AAC7C,CAAC"}

package/dist/activities/execute-deep-agent/auto-publish.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Post-stream safety net for artifact publishing.
+ *
+ * Scans completed tool calls for file-modifying operations (write, edit,
+ * create) and publishes any files that were not already published inline.
+ * This catches files modified by paths not triggered during streaming
+ * (e.g., shell commands, race conditions in fire-and-forget publish).
+ */
+import type { TurnRows } from "../../gen/turn/ai/stigmer/runner/turn/v1/rows_pb.js";
+import type { InlinePublisher } from "./inline-publisher.js";
+/**
+ * Scan the turn's tool calls for file-modifying operations and publish any
+ * files that were not already published inline.
+ *
+ * Returns the count of additionally published artifacts.
+ */
+export declare function autoPublishWrittenFiles(rows: Pick<TurnRows, "messages">, inlinePublisher: InlinePublisher): Promise<number>;

package/dist/activities/execute-deep-agent/auto-publish.js

@@ -0,0 +1,71 @@
+/**
+ * Post-stream safety net for artifact publishing.
+ *
+ * Scans completed tool calls for file-modifying operations (write, edit,
+ * create) and publishes any files that were not already published inline.
+ * This catches files modified by paths not triggered during streaming
+ * (e.g., shell commands, race conditions in fire-and-forget publish).
+ */
+const FILE_MODIFYING_TOOLS = new Set([
+    "write_file",
+    "edit_file",
+    "create_file",
+    "write",
+    "edit",
+    "create",
+    "str_replace_editor",
+]);
+/**
+ * Scan the turn's tool calls for file-modifying operations and publish any
+ * files that were not already published inline.
+ *
+ * Returns the count of additionally published artifacts.
+ */
+export async function autoPublishWrittenFiles(rows, inlinePublisher) {
+    const alreadyPublished = inlinePublisher.publishedPaths;
+    const pathsToPublish = [];
+    for (const message of rows.messages) {
+        for (const tc of message.toolCalls) {
+            if (!FILE_MODIFYING_TOOLS.has(tc.name))
+                continue;
+            const filePath = extractFilePath(tc.args);
+            if (!filePath)
+                continue;
+            const normalized = filePath.replace(/^\/+/, "");
+            if (alreadyPublished.has(normalized))
+                continue;
+            if (pathsToPublish.includes(normalized))
+                continue;
+            pathsToPublish.push(normalized);
+        }
+    }
+    let count = 0;
+    for (const path of pathsToPublish) {
+        try {
+            await inlinePublisher.publish(path);
+            count++;
+        }
+        catch {
+            // InlinePublisher.publish already swallows errors internally.
+            // This catch is defense-in-depth.
+        }
+    }
+    if (count > 0) {
+        console.log(`[autoPublish] Published ${count} additional artifact(s) via safety net`);
+    }
+    return count;
+}
+function extractFilePath(args) {
+    if (!args)
+        return null;
+    if (typeof args.path === "string")
+        return args.path;
+    if (typeof args.file_path === "string")
+        return args.file_path;
+    if (typeof args.filename === "string")
+        return args.filename;
+    if (typeof args.file === "string")
+        return args.file;
+    return null;
+}
+//# sourceMappingURL=auto-publish.js.map

package/dist/activities/execute-deep-agent/auto-publish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-publish.js","sourceRoot":"","sources":["../../../src/activities/execute-deep-agent/auto-publish.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC;IACnC,YAAY;IACZ,WAAW;IACX,aAAa;IACb,OAAO;IACP,MAAM;IACN,QAAQ;IACR,oBAAoB;CACrB,CAAC,CAAC;AAEH;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,IAAgC,EAChC,eAAgC;IAEhC,MAAM,gBAAgB,GAAG,eAAe,CAAC,cAAc,CAAC;IACxD,MAAM,cAAc,GAAa,EAAE,CAAC;IAEpC,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACnC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC;gBAAE,SAAS;YAEjD,MAAM,QAAQ,GAAG,eAAe,CAAC,EAAE,CAAC,IAA2C,CAAC,CAAC;YACjF,IAAI,CAAC,QAAQ;gBAAE,SAAS;YAExB,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAChD,IAAI,gBAAgB,CAAC,GAAG,CAAC,UAAU,CAAC;gBAAE,SAAS;YAC/C,IAAI,cAAc,CAAC,QAAQ,CAAC,UAAU,CAAC;gBAAE,SAAS;YAElD,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,IAAI,IAAI,cAAc,EAAE,CAAC;QAClC,IAAI,CAAC;YACH,MAAM,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACpC,KAAK,EAAE,CAAC;QACV,CAAC;QAAC,MAAM,CAAC;YACP,8DAA8D;YAC9D,kCAAkC;QACpC,CAAC;IACH,CAAC;IAED,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,OAAO,CAAC,GAAG,CACT,2BAA2B,KAAK,wCAAwC,CACzE,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,eAAe,CAAC,IAAyC;IAChE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IAEvB,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IACpD,IAAI,OAAO,IAAI,CAAC,SAAS,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC;IAC9D,IAAI,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;IAC5D,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAEpD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/activities/execute-deep-agent/cas-capture-backend.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CAS-capturing deepagents backends for the native harness.
+ *
+ * WHY A BACKEND WRAPPER, NOT THE APPROVAL GATE
+ * --------------------------------------------
+ * Capture is a property of the TURN, not of authorization — exactly like the git
+ * substrate, which snapshots the working tree at the turn boundary regardless of
+ * how or whether a tool was gated. File review opens even under the global bypass
+ * (`spec.auto_approve_all`), where the approval gate is not installed at all, so
+ * sourcing the before-bytes from the gate would let gitignored edits silently
+ * escape review under auto-approve-all. Observing at the backend keeps CAS
+ * capture gate-independent, so it is symmetric with the git-tracked path.
+ *
+ * SHELL VS PLAN MODE
+ * ------------------
+ * Outside plan mode the harness uses {@link CasCaptureShellBackend} (deepagents
+ * LocalShellBackend + CAS observation) so the `execute` tool is available and
+ * approval-gated. Plan mode keeps {@link CasCaptureFilesystemBackend} because
+ * deepagents rejects filesystem `permissions` combined with an execution-capable
+ * backend — plan mode is read-only by construction, so no shell tool there.
+ *
+ * The observed mutations are `write` (create, or since deepagents 1.12 a
+ * whole-file overwrite — `recordBefore` reads the existing bytes either way)
+ * and `edit` (modify), so this observes CREATE and MODIFY. deepagents 1.13
+ * added a recursive backend `delete` and a `delete` tool over it; the native
+ * harness does not expose that tool (`deepagents-profiles.ts`), and these
+ * backends refuse a backend delete outright, so a graph whose model no profile
+ * resolves cannot delete a subtree behind the observer's back. Deleting stays
+ * on the shell (`rm`), which the approval gate holds as always, and a
+ * delete-category tool from elsewhere has its before-bytes recorded by the gate
+ * at authorization time (`captureDeleteBefore`, issue #303).
+ *
+ * VIRTUAL ROOT — THE ONE PATH DIALECT (issue #754)
+ * ------------------------------------------------
+ * Every backend here is constructed with `virtualMode: true`: a leading "/"
+ * denotes the WORKSPACE ROOT, traversal (`..`, `~`) is rejected, and every
+ * resolution stays inside `rootDir` by construction. This is the same dialect
+ * the rest of the harness already speaks — the system prompt's path-resolution
+ * directive, `resolveWorkspacePath(..., virtualRoot=true)` in the CAS observer
+ * and turn-boundary capture, `InlinePublisher.normalizePath`, and the approval
+ * gate's capturability checks. Before this flag, deepagents' legacy default
+ * passed absolute paths through to the REAL filesystem: a `write_file("/tmp/x")`
+ * escaped the session workspace onto the host AND escaped review entirely
+ * (auto-approved as capture-mode flow, but the observer/boundary/publisher all
+ * looked inside the workspace and found nothing). Read-side, the same legacy
+ * pass-through was why plan mode needed rule-based read fencing at all. Do not
+ * remove this flag: workspace confinement is structural, not policy.
+ */
+import { FilesystemBackend, LocalShellBackend } from "deepagents";
+import type { DeleteResult, LocalShellBackendOptions } from "deepagents";
+import type { CasCaptureObserver } from "./cas-capture-observer.js";
+export type { CasBeforeMap } from "./cas-capture-observer.js";
+type FilesystemBackendOptions = NonNullable<ConstructorParameters<typeof FilesystemBackend>[0]>;
+type CasCaptureDeps = {
+    readonly observer: CasCaptureObserver;
+};
+export declare class CasCaptureFilesystemBackend extends FilesystemBackend {
+    private readonly observer;
+    constructor(options: FilesystemBackendOptions, deps: CasCaptureDeps);
+    write(filePath: string, content: string): Promise<import("deepagents").WriteResult>;
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<import("deepagents").EditResult>;
+    delete(filePath: string): Promise<DeleteResult>;
+}
+export declare class CasCaptureShellBackend extends LocalShellBackend {
+    private readonly observer;
+    constructor(options: LocalShellBackendOptions, deps: CasCaptureDeps);
+    write(filePath: string, content: string): Promise<import("deepagents").WriteResult>;
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): Promise<import("deepagents").EditResult>;
+    delete(filePath: string): Promise<DeleteResult>;
+}
+export type CasCaptureBackend = CasCaptureFilesystemBackend | CasCaptureShellBackend;
+export interface CreateCasCaptureBackendOptions {
+    readonly rootDir: string;
+    readonly observer: CasCaptureObserver;
+    /** When set, builds a shell-capable backend with this env for `execute`. */
+    readonly shellEnv?: Record<string, string>;
+}
+/**
+ * Construct the CAS-observing backend for a deepagents agent graph.
+ *
+ * Shell-capable when `shellEnv` is provided; otherwise filesystem-only (plan mode).
+ * Shell backends honor LocalShellBackend's documented initialize contract.
+ */
+export declare function createCasCaptureBackend(options: CreateCasCaptureBackendOptions): Promise<CasCaptureBackend>;