@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

package/dist/shared/exact-apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exact-apply.js","sourceRoot":"","sources":["../../src/shared/exact-apply.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kDAAkD,CAAC;AAclG;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,IAAuB;IAEvB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAElC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAChC,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC,wBAAwB,CAAC,EAAE,CAAC;gBAAE,SAAS;YAE5C,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC;YAC5B,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;YACtC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,iEAAiE;gBACjE,+CAA+C;gBAC/C,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,2BAA2B,CAAC,CAAC;gBAC3D,SAAS;YACX,CAAC;YACD,4EAA4E;YAC5E,6EAA6E;YAC7E,iBAAiB;YACjB,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,oBAAoB,CACnD,OAAO,EACP,IAAI,CAAC,gBAAgB,CAAC,OAAO;YAC7B,iBAAiB,CAAC,KAAK,CACxB,CAAC;YACF,IAAI,CAAC,iBAAiB,CAAC,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,EAAE,CAAC;gBACnD,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,6BAA6B,MAAM,EAAE,CAAC,CAAC;gBACrE,SAAS;YACX,CAAC;YAED,MAAM,OAAO,GAAG,+BAA+B,CAAC,EAAE,CAAC,CAAC;YACpD,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;gBACrB,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,mCAAmC,CAAC,CAAC;gBACnE,SAAS;YACX,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,gBAAgB,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACzD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CACL,IAAI,CAAC,WAAW,EAChB,EAAE,EACF,iBAAiB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CACpE,CAAC;gBACF,SAAS;YACX,CAAC;YAED,2EAA2E;YAC3E,4EAA4E;YAC5E,0EAA0E;YAC1E,wEAAwE;YACxE,oEAAoE;YACpE,EAAE,CAAC,MAAM,GAAG,cAAc,CAAC,mBAAmB,CAAC;YAC/C,IAAI,CAAC,EAAE,CAAC,WAAW;gBAAE,EAAE,CAAC,WAAW,GAAG,YAAY,EAAE,CAAC;YACrD,EAAE,CAAC,KAAK,GAAG,EAAE,CAAC;YACd,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;YACnB,OAAO,CAAC,GAAG,CACT,yCAAyC,MAAM,GAAG;gBAChD,SAAS,EAAE,CAAC,EAAE,mDAAmD;gBACjE,uBAAuB,IAAI,CAAC,WAAW,EAAE,CAC5C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,wBAAwB,CACtC,oBAAgD,EAChD,kBAAuC;IAEvC,OAAO,oBAAoB,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC;AACrF,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,+BAA+B,CAAC,EAAY;IAC1D,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;IACpD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,cAAc;QAAE,OAAO,OAAO,CAAC;IACnE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,wBAAwB,CAAC,EAAY;IAC5C,IAAI,EAAE,CAAC,MAAM,KAAK,cAAc,CAAC,0BAA0B;QAAE,OAAO,KAAK,CAAC;IAC1E,IACE,EAAE,CAAC,cAAc,KAAK,cAAc,CAAC,OAAO;QAC5C,EAAE,CAAC,cAAc,KAAK,cAAc,CAAC,WAAW,EAChD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,mBAAmB,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC;AACtD,CAAC;AAED,mFAAmF;AACnF,SAAS,UAAU,CAAC,EAAY;IAC9B,OAAO,EAAE,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ;QAC3C,CAAC,CAAE,EAAE,CAAC,IAAgC;QACtC,CAAC,CAAC,EAAE,CAAC;AACT,CAAC;AAED,iFAAiF;AACjF,SAAS,iBAAiB,CACxB,SAAiB,EACjB,aAAgC;IAEhC,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAClC,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QAChC,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACjC,MAAM,GAAG,GAAG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACnC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,OAAO,CAAC,WAAmB,EAAE,EAAY,EAAE,MAAc;IAChE,OAAO,CAAC,GAAG,CACT,8DAA8D;QAC5D,QAAQ,EAAE,CAAC,EAAE,YAAY,MAAM,eAAe,WAAW,EAAE,CAC9D,CAAC;AACJ,CAAC"}

package/dist/shared/execution-context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * The execution-scoped context — "this async work belongs to execution X" —
+ * as an `AsyncLocalStorage` the turn runtime enters once around the WHOLE
+ * activity, and the transport layer reads per request.
+ *
+ * Why it is the runtime's and not a harness's: every proxy-bound request the
+ * runner makes carries `x-stigmer-execution-id` from this store (the Cursor
+ * fetch and HTTP/2 interceptors stamp it; `rejection-capture.ts` correlates
+ * unhandled rejections by it), and a large share of those requests are made
+ * OUTSIDE any engine stretch — attachment downloads and status offload
+ * through the artifact proxy, the memory selection, the structured-output
+ * extraction and the plan-artifact publish in the epilogue, and in a cloud
+ * sandbox the control-plane writes themselves. Under `maxConcurrentActivities
+ * > 1` the fallback (a module-level id, `fetch-interceptor.ts`
+ * `setInterceptorExecutionId`) is whichever turn set it last; this store is
+ * what makes concurrent turns not overwrite each other's headers.
+ *
+ * In the agent host the store also carries the turn's key, which the runner
+ * minted for this turn alone (`agent-host/remote-adapter.ts`): every call
+ * the host makes through the runner's local proxy stamps it beside the
+ * execution id ({@link TURN_KEY_HEADER}), and the proxy admits a call only
+ * for the turn whose key it carries (`agent-proxy/server.ts`).
+ *
+ * Moved from `activities/execute-cursor/fetch-interceptor.ts` (#1070)
+ * so `harness/run-turn.ts` can enter it without importing the
+ * adapter; the interceptors import it from here. No harness enters it: the
+ * contract lists it among the things deliberately NOT on `TurnSink`.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface ExecutionContextStore {
+    readonly executionId: string;
+    /** The turn's key at the runner's local proxy; only in the agent host. */
+    readonly turnKey?: string;
+}
+/** The header a hosted turn's calls carry its key in. */
+export declare const TURN_KEY_HEADER = "x-stigmer-turn-key";
+/** The turn-key header for the current turn, when there is one: for a client to spread into its headers. */
+export declare function turnKeyHeader(): Record<string, string>;
+/** The store, for readers that stamp or correlate by execution id. */
+export declare function getExecutionContext(): AsyncLocalStorage<ExecutionContextStore>;
+/**
+ * Run an async function with execution-scoped context. The executionId is
+ * propagated through the async call chain via AsyncLocalStorage, ensuring
+ * concurrent activities on the same runner process don't overwrite each
+ * other's proxy headers.
+ */
+export declare function runWithExecutionContext<T>(executionId: string, fn: () => Promise<T>, turnKey?: string): Promise<T>;

package/dist/shared/execution-context.js

@@ -0,0 +1,51 @@
+/**
+ * The execution-scoped context — "this async work belongs to execution X" —
+ * as an `AsyncLocalStorage` the turn runtime enters once around the WHOLE
+ * activity, and the transport layer reads per request.
+ *
+ * Why it is the runtime's and not a harness's: every proxy-bound request the
+ * runner makes carries `x-stigmer-execution-id` from this store (the Cursor
+ * fetch and HTTP/2 interceptors stamp it; `rejection-capture.ts` correlates
+ * unhandled rejections by it), and a large share of those requests are made
+ * OUTSIDE any engine stretch — attachment downloads and status offload
+ * through the artifact proxy, the memory selection, the structured-output
+ * extraction and the plan-artifact publish in the epilogue, and in a cloud
+ * sandbox the control-plane writes themselves. Under `maxConcurrentActivities
+ * > 1` the fallback (a module-level id, `fetch-interceptor.ts`
+ * `setInterceptorExecutionId`) is whichever turn set it last; this store is
+ * what makes concurrent turns not overwrite each other's headers.
+ *
+ * In the agent host the store also carries the turn's key, which the runner
+ * minted for this turn alone (`agent-host/remote-adapter.ts`): every call
+ * the host makes through the runner's local proxy stamps it beside the
+ * execution id ({@link TURN_KEY_HEADER}), and the proxy admits a call only
+ * for the turn whose key it carries (`agent-proxy/server.ts`).
+ *
+ * Moved from `activities/execute-cursor/fetch-interceptor.ts` (#1070)
+ * so `harness/run-turn.ts` can enter it without importing the
+ * adapter; the interceptors import it from here. No harness enters it: the
+ * contract lists it among the things deliberately NOT on `TurnSink`.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/** The header a hosted turn's calls carry its key in. */
+export const TURN_KEY_HEADER = "x-stigmer-turn-key";
+/** The turn-key header for the current turn, when there is one: for a client to spread into its headers. */
+export function turnKeyHeader() {
+    const key = executionContext.getStore()?.turnKey;
+    return key === undefined ? {} : { [TURN_KEY_HEADER]: key };
+}
+const executionContext = new AsyncLocalStorage();
+/** The store, for readers that stamp or correlate by execution id. */
+export function getExecutionContext() {
+    return executionContext;
+}
+/**
+ * Run an async function with execution-scoped context. The executionId is
+ * propagated through the async call chain via AsyncLocalStorage, ensuring
+ * concurrent activities on the same runner process don't overwrite each
+ * other's proxy headers.
+ */
+export function runWithExecutionContext(executionId, fn, turnKey) {
+    return executionContext.run(turnKey === undefined ? { executionId } : { executionId, turnKey }, fn);
+}
+//# sourceMappingURL=execution-context.js.map

package/dist/shared/execution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-context.js","sourceRoot":"","sources":["../../src/shared/execution-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAQrD,yDAAyD;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,oBAAoB,CAAC;AAEpD,4GAA4G;AAC5G,MAAM,UAAU,aAAa;IAC3B,MAAM,GAAG,GAAG,gBAAgB,CAAC,QAAQ,EAAE,EAAE,OAAO,CAAC;IACjD,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,eAAe,CAAC,EAAE,GAAG,EAAE,CAAC;AAC7D,CAAC;AAED,MAAM,gBAAgB,GAAG,IAAI,iBAAiB,EAAyB,CAAC;AAExE,sEAAsE;AACtE,MAAM,UAAU,mBAAmB;IACjC,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAI,WAAmB,EAAE,EAAoB,EAAE,OAAgB;IACpG,OAAO,gBAAgB,CAAC,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;AACtG,CAAC"}

package/dist/shared/execution-target.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The one reading of an execution's `target` oneof the runner needs: the
+ * session a turn runs in. By the time a turn is dispatched the server has
+ * created any new session the turn started and recorded it on the target's
+ * session_id arm, so the runner never reads the session_spec arm. An unset
+ * target and a session_id arm holding an empty string both read as "", so
+ * no reader spells the oneof's empty case its own way.
+ *
+ * Pinned by shared/__tests__/execution-target.test.ts.
+ */
+import type { RunSpec } from "@stigmer/apis/ai/stigmer/agentic/run/v1/spec_pb";
+/** The session a turn runs in, or "" when its target names none. */
+export declare function sessionIdOf(spec: RunSpec | undefined): string;

package/dist/shared/execution-target.js

@@ -0,0 +1,15 @@
+/**
+ * The one reading of an execution's `target` oneof the runner needs: the
+ * session a turn runs in. By the time a turn is dispatched the server has
+ * created any new session the turn started and recorded it on the target's
+ * session_id arm, so the runner never reads the session_spec arm. An unset
+ * target and a session_id arm holding an empty string both read as "", so
+ * no reader spells the oneof's empty case its own way.
+ *
+ * Pinned by shared/__tests__/execution-target.test.ts.
+ */
+/** The session a turn runs in, or "" when its target names none. */
+export function sessionIdOf(spec) {
+    return spec?.target.case === "sessionId" ? spec.target.value : "";
+}
+//# sourceMappingURL=execution-target.js.map

package/dist/shared/execution-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-target.js","sourceRoot":"","sources":["../../src/shared/execution-target.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,oEAAoE;AACpE,MAAM,UAAU,WAAW,CAAC,IAAyB;IACnD,OAAO,IAAI,EAAE,MAAM,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AACpE,CAAC"}

package/dist/shared/extract-json.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Extract JSON from agent text responses.
+ *
+ * Three-tier extraction with end-first scanning:
+ *
+ *   Tier 1:    JSON.parse on the full trimmed text.
+ *   Tier 1.5:  Code-fence extraction — scan fences last-to-first,
+ *              only attempt parse when content starts with { or [.
+ *   Tier 1.75: Last-brace extraction — find the last balanced {...}
+ *              by scanning backwards from the end of the text.
+ *
+ * End-first scanning aligns with the prompt injection contract that
+ * tells the agent to put JSON as its "final response." When multiple
+ * JSON fragments exist (e.g. intermediate debug output followed by
+ * the actual result), the last fragment is overwhelmingly the correct
+ * one. If the heuristic picks wrong, downstream schema validation
+ * catches it and the caller falls through to LLM-based extraction.
+ *
+ * Trailing-comma repair (stripTrailingCommas) is applied before every
+ * JSON.parse attempt across all tiers.
+ */
+/**
+ * Extract JSON from agent text. Returns the parsed value on success,
+ * or undefined so the caller can fall through to LLM-based extraction.
+ */
+export declare function extractJsonFromText(text: string): unknown | undefined;

package/dist/shared/extract-json.js

@@ -0,0 +1,140 @@
+/**
+ * Extract JSON from agent text responses.
+ *
+ * Three-tier extraction with end-first scanning:
+ *
+ *   Tier 1:    JSON.parse on the full trimmed text.
+ *   Tier 1.5:  Code-fence extraction — scan fences last-to-first,
+ *              only attempt parse when content starts with { or [.
+ *   Tier 1.75: Last-brace extraction — find the last balanced {...}
+ *              by scanning backwards from the end of the text.
+ *
+ * End-first scanning aligns with the prompt injection contract that
+ * tells the agent to put JSON as its "final response." When multiple
+ * JSON fragments exist (e.g. intermediate debug output followed by
+ * the actual result), the last fragment is overwhelmingly the correct
+ * one. If the heuristic picks wrong, downstream schema validation
+ * catches it and the caller falls through to LLM-based extraction.
+ *
+ * Trailing-comma repair (stripTrailingCommas) is applied before every
+ * JSON.parse attempt across all tiers.
+ */
+/**
+ * Extract JSON from agent text. Returns the parsed value on success,
+ * or undefined so the caller can fall through to LLM-based extraction.
+ */
+export function extractJsonFromText(text) {
+    if (!text)
+        return undefined;
+    const trimmed = text.trim();
+    // Tier 1: full text is valid JSON
+    const direct = tryParse(trimmed);
+    if (direct !== undefined)
+        return direct;
+    // Tier 1.5: JSON inside a code fence
+    const fenced = extractFromCodeFences(trimmed);
+    if (fenced !== undefined)
+        return fenced;
+    // Tier 1.75: last balanced {...} in the text
+    const braced = extractLastJsonObject(trimmed);
+    if (braced !== undefined)
+        return braced;
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Tier 1.5 — code-fence extraction (last-to-first)
+// ---------------------------------------------------------------------------
+const CODE_FENCE_RE = /```(?:json|JSON)?\s*\n([\s\S]*?)```/g;
+function extractFromCodeFences(text) {
+    const fences = [];
+    let match;
+    while ((match = CODE_FENCE_RE.exec(text)) !== null) {
+        fences.push(match[1]);
+    }
+    CODE_FENCE_RE.lastIndex = 0;
+    // Scan last-to-first — the final fence is most likely the structured output
+    for (let i = fences.length - 1; i >= 0; i--) {
+        const content = fences[i].trim();
+        if (!content.startsWith("{") && !content.startsWith("["))
+            continue;
+        const result = tryParse(content);
+        if (result !== undefined)
+            return result;
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Tier 1.75 — last balanced brace extraction
+// ---------------------------------------------------------------------------
+function extractLastJsonObject(text) {
+    const lastClose = text.lastIndexOf("}");
+    if (lastClose === -1)
+        return undefined;
+    // Walk backwards from lastClose to find the matching open brace,
+    // respecting nesting and string literals.
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = lastClose; i >= 0; i--) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "}") {
+            depth++;
+        }
+        else if (ch === "{") {
+            depth--;
+            if (depth === 0) {
+                const candidate = text.slice(i, lastClose + 1);
+                return tryParse(candidate);
+            }
+        }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function tryParse(candidate) {
+    try {
+        return JSON.parse(candidate);
+    }
+    catch {
+        // fall through
+    }
+    const repaired = stripTrailingCommas(candidate);
+    if (repaired !== candidate) {
+        try {
+            return JSON.parse(repaired);
+        }
+        catch {
+            // repair didn't help
+        }
+    }
+    return undefined;
+}
+/**
+ * Remove trailing commas before } and ] — a common LLM quirk that
+ * produces invalid JSON. Only removes commas that are followed by
+ * optional whitespace and a closing delimiter.
+ */
+function stripTrailingCommas(json) {
+    return json.replace(/,\s*([}\]])/g, "$1");
+}
+//# sourceMappingURL=extract-json.js.map

package/dist/shared/extract-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-json.js","sourceRoot":"","sources":["../../src/shared/extract-json.ts"],"names":[],"mappings":"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"}

package/dist/shared/extract-structured-output.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tier-2 structured-output extraction for a harness turn.
+ *
+ * Harness-agnostic, and called from one place: the turn runtime's epilogue
+ * (`harness/run-turn.ts` `extractStructuredOutputFromText`), so both
+ * harnesses have it — Cursor since #1070, native since #1096 (pinned by the
+ * native hermetic `structured-output` tier-2 arm).
+ *
+ * When tier-1 text extraction (shared/extract-json.ts) cannot find JSON in
+ * the agent's free-text response, this tier asks an economy-tier LLM to
+ * extract it via withStructuredOutput (function-calling), which guarantees
+ * schema-conformant output through the API's tool-use mechanism.
+ *
+ * Lives in its own module so the LangChain construction path stays out of
+ * the runtime's module graph until a run actually needs tier 2 — the
+ * runtime imports this module lazily at the call site, mirroring its tier-1
+ * import, which is what bundle-slim's deferred evaluation preserves.
+ */
+import type { Config } from "../config.js";
+/**
+ * Extract structured data from an agent's free-text response using an
+ * economy-tier LLM with withStructuredOutput (function-calling).
+ *
+ * Construction (registry-id resolution, provider inference, proxy wiring) is
+ * delegated to the shared buildChatModel so the economy model's registry id
+ * is always resolved to a provider API id before the call.
+ *
+ * The call is scoped to the run it serves (`executionId`), as session
+ * titling's is: a proxy that requires a run scope on every call refuses one
+ * without it, and the scope is what meters the call to that run
+ * (stigmer#2060).
+ *
+ * Throws when no LLM is reachable (no proxy and no credential path for the
+ * extraction model's provider) — the caller treats any throw here as "tier 2
+ * unavailable", logs it, and returns the agent's text without structured
+ * output, so the failure mode is a diagnosable log line, never a lost run.
+ */
+export declare function extractStructuredOutput(agentResponse: string, schema: Record<string, unknown>, config: Config, primaryModel: string, executionId: string): Promise<unknown | null>;

package/dist/shared/extract-structured-output.js

@@ -0,0 +1,68 @@
+/**
+ * Tier-2 structured-output extraction for a harness turn.
+ *
+ * Harness-agnostic, and called from one place: the turn runtime's epilogue
+ * (`harness/run-turn.ts` `extractStructuredOutputFromText`), so both
+ * harnesses have it — Cursor since #1070, native since #1096 (pinned by the
+ * native hermetic `structured-output` tier-2 arm).
+ *
+ * When tier-1 text extraction (shared/extract-json.ts) cannot find JSON in
+ * the agent's free-text response, this tier asks an economy-tier LLM to
+ * extract it via withStructuredOutput (function-calling), which guarantees
+ * schema-conformant output through the API's tool-use mechanism.
+ *
+ * Lives in its own module so the LangChain construction path stays out of
+ * the runtime's module graph until a run actually needs tier 2 — the
+ * runtime imports this module lazily at the call site, mirroring its tier-1
+ * import, which is what bundle-slim's deferred evaluation preserves.
+ */
+import { getEconomyModel } from "./model-registry.js";
+import { buildChatModel } from "./model-client.js";
+import { checkDirectCredentials } from "./llm-backend.js";
+import { tryInferProvider } from "./llm-proxy.js";
+import { jsonSchemaToZod } from "./json-schema-to-zod.js";
+/**
+ * Extract structured data from an agent's free-text response using an
+ * economy-tier LLM with withStructuredOutput (function-calling).
+ *
+ * Construction (registry-id resolution, provider inference, proxy wiring) is
+ * delegated to the shared buildChatModel so the economy model's registry id
+ * is always resolved to a provider API id before the call.
+ *
+ * The call is scoped to the run it serves (`executionId`), as session
+ * titling's is: a proxy that requires a run scope on every call refuses one
+ * without it, and the scope is what meters the call to that run
+ * (stigmer#2060).
+ *
+ * Throws when no LLM is reachable (no proxy and no credential path for the
+ * extraction model's provider) — the caller treats any throw here as "tier 2
+ * unavailable", logs it, and returns the agent's text without structured
+ * output, so the failure mode is a diagnosable log line, never a lost run.
+ */
+export async function extractStructuredOutput(agentResponse, schema, config, primaryModel, executionId) {
+    const extractionModel = await getEconomyModel(primaryModel);
+    const proxyEndpoint = config.proxyEndpoint ?? undefined;
+    if (!proxyEndpoint) {
+        const provider = tryInferProvider(extractionModel);
+        const missing = provider === null ? null : checkDirectCredentials(provider);
+        if (missing !== null) {
+            throw new Error(`Structured-output extraction needs the ${provider} model ` +
+                `'${extractionModel}' but has no credential path. ${missing}`);
+        }
+    }
+    const { model: llm } = await buildChatModel({
+        modelName: extractionModel,
+        proxyEndpoint,
+        stigmerToken: config.stigmerTokenRef.current ?? undefined,
+        headerScope: { executionId },
+        maxTokens: 4096,
+    });
+    const zodSchema = jsonSchemaToZod(schema);
+    const structured = llm.withStructuredOutput(zodSchema);
+    const result = await structured.invoke([
+        { role: "system", content: "Extract the structured data from the agent's response. Return only the data that matches the schema." },
+        { role: "user", content: agentResponse },
+    ]);
+    return result ?? null;
+}
+//# sourceMappingURL=extract-structured-output.js.map

package/dist/shared/extract-structured-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-structured-output.js","sourceRoot":"","sources":["../../src/shared/extract-structured-output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,aAAqB,EACrB,MAA+B,EAC/B,MAAc,EACd,YAAoB,EACpB,WAAmB;IAEnB,MAAM,eAAe,GAAG,MAAM,eAAe,CAAC,YAAY,CAAC,CAAC;IAC5D,MAAM,aAAa,GAAG,MAAM,CAAC,aAAa,IAAI,SAAS,CAAC;IAExD,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;QAC5E,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,0CAA0C,QAAQ,SAAS;gBAC3D,IAAI,eAAe,iCAAiC,OAAO,EAAE,CAC9D,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,MAAM,cAAc,CAAC;QAC1C,SAAS,EAAE,eAAe;QAC1B,aAAa;QACb,YAAY,EAAE,MAAM,CAAC,eAAe,CAAC,OAAO,IAAI,SAAS;QACzD,WAAW,EAAE,EAAE,WAAW,EAAE;QAC5B,SAAS,EAAE,IAAI;KAChB,CAAC,CAAC;IAEH,MAAM,SAAS,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,UAAU,GAAG,GAAG,CAAC,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAEvD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC;QACrC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,sGAAsG,EAAE;QACnI,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE;KACzC,CAAC,CAAC;IAEH,OAAO,MAAM,IAAI,IAAI,CAAC;AACxB,CAAC"}

package/dist/shared/file-change.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure path + binary-detection helpers shared by the native (deepagents) and
+ * Cursor harnesses' file-review capture.
+ *
+ * Deliberately dependency-free and side-effect-free: no file IO, no diff
+ * computation, no proto knowledge. `resolveWorkspacePath` normalizes a touched
+ * path to (display path, absolute path); `looksBinary`/`bytesLookBinary` are the
+ * single definition of "binary" across every capture substrate.
+ */
+/**
+ * Heuristic binary detection: a NUL byte never appears in valid UTF-8 text. This
+ * is a safety net, not a feature — the native edit/write tools are string-based,
+ * so captured content is text in practice.
+ */
+export declare function looksBinary(content: string): boolean;
+/**
+ * Byte-level binary detection: a NUL byte never appears in valid UTF-8 text. The
+ * single definition of "binary" shared by every substrate that reads raw bytes
+ * (the git substrate's blob reads and the CAS substrate's captured bodies), so
+ * "what is binary" is decided one way across the whole file-review subsystem.
+ *
+ * Prefer this over {@link looksBinary} whenever the raw bytes are in hand: it is
+ * exact, whereas scanning a UTF-8-decoded string can miss a NUL that a lossy
+ * decode dropped.
+ */
+export declare function bytesLookBinary(bytes: Uint8Array): boolean;
+/**
+ * Derive the workspace-root-relative display path and the absolute on-disk path
+ * for a file a tool touched.
+ *
+ * `virtualRoot` distinguishes the two harness path conventions:
+ *  - native (deepagents) addresses files against a virtual root where a leading
+ *    "/" denotes the workspace root — mirrors `InlinePublisher.normalizePath`;
+ *  - Cursor passes real filesystem paths that may be absolute.
+ *
+ * A path that is absolute but outside `rootDir` is displayed as-is (we never
+ * surface an escaping `../../` relative path).
+ */
+export declare function resolveWorkspacePath(rawPath: string, rootDir: string, virtualRoot: boolean): {
+    path: string;
+    absolutePath: string;
+};

package/dist/shared/file-change.js

@@ -0,0 +1,55 @@
+/**
+ * Pure path + binary-detection helpers shared by the native (deepagents) and
+ * Cursor harnesses' file-review capture.
+ *
+ * Deliberately dependency-free and side-effect-free: no file IO, no diff
+ * computation, no proto knowledge. `resolveWorkspacePath` normalizes a touched
+ * path to (display path, absolute path); `looksBinary`/`bytesLookBinary` are the
+ * single definition of "binary" across every capture substrate.
+ */
+import { isAbsolute, join, relative } from "node:path";
+/**
+ * Heuristic binary detection: a NUL byte never appears in valid UTF-8 text. This
+ * is a safety net, not a feature — the native edit/write tools are string-based,
+ * so captured content is text in practice.
+ */
+export function looksBinary(content) {
+    return content.includes("\u0000");
+}
+/**
+ * Byte-level binary detection: a NUL byte never appears in valid UTF-8 text. The
+ * single definition of "binary" shared by every substrate that reads raw bytes
+ * (the git substrate's blob reads and the CAS substrate's captured bodies), so
+ * "what is binary" is decided one way across the whole file-review subsystem.
+ *
+ * Prefer this over {@link looksBinary} whenever the raw bytes are in hand: it is
+ * exact, whereas scanning a UTF-8-decoded string can miss a NUL that a lossy
+ * decode dropped.
+ */
+export function bytesLookBinary(bytes) {
+    return bytes.includes(0);
+}
+/**
+ * Derive the workspace-root-relative display path and the absolute on-disk path
+ * for a file a tool touched.
+ *
+ * `virtualRoot` distinguishes the two harness path conventions:
+ *  - native (deepagents) addresses files against a virtual root where a leading
+ *    "/" denotes the workspace root — mirrors `InlinePublisher.normalizePath`;
+ *  - Cursor passes real filesystem paths that may be absolute.
+ *
+ * A path that is absolute but outside `rootDir` is displayed as-is (we never
+ * surface an escaping `../../` relative path).
+ */
+export function resolveWorkspacePath(rawPath, rootDir, virtualRoot) {
+    if (virtualRoot || !isAbsolute(rawPath)) {
+        const rel = rawPath.replace(/^\/+/, "").replace(/^\.\//, "");
+        return { path: rel, absolutePath: join(rootDir, rel) };
+    }
+    const rel = relative(rootDir, rawPath);
+    if (rel && !rel.startsWith("..") && !isAbsolute(rel)) {
+        return { path: rel, absolutePath: rawPath };
+    }
+    return { path: rawPath, absolutePath: rawPath };
+}
+//# sourceMappingURL=file-change.js.map

package/dist/shared/file-change.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-change.js","sourceRoot":"","sources":["../../src/shared/file-change.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEvD;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,KAAiB;IAC/C,OAAO,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAe,EACf,OAAe,EACf,WAAoB;IAEpB,IAAI,WAAW,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QAC7D,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACvC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACrD,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC;AAClD,CAAC"}

package/dist/shared/file-tools.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Introspection of file-modifying tools, shared by every runner surface that
+ * reacts to a file edit: the native (deepagents) streaming side-effects (publish,
+ * git writeback, post-exec file-change capture), the Cursor streaming capture,
+ * and BOTH harnesses' approval-gate pre-execution capture (shared/gate-file-change.ts).
+ *
+ * This is the single source of truth for "which tools mutate files" and "where
+ * their path / whole-file content / edit replacement lives in the tool
+ * arguments". It is deliberately pure — no IO, no proto knowledge — so the same
+ * identification logic is used whether args come from a streamed `on_tool_*`
+ * event, a v3 protocol event, an AI-message tool call read out of graph state at
+ * an interrupt, or the Cursor preToolUse hook's captured `tool_input`.
+ *
+ * Both taxonomies are covered in one place on purpose: the deepagents harness
+ * names a file write `write_file`/`write`, the Cursor SDK stream names it
+ * `edit`/`write`, and the Cursor preToolUse hook names it `Write`/`StrReplace`/
+ * `EditNotebook`. The four extractors below span every arg-field name these
+ * surfaces use, so a single capture path is correct for all of them.
+ */
+/**
+ * The file-modifying tools, across both harness taxonomies.
+ *
+ * - deepagents (native): `write_file`/`edit_file`/`create_file` (stream) and
+ *   `write`/`edit`/`create`/`str_replace_editor` (SDK names);
+ * - Cursor: `write`/`edit` (SDK stream, shared with native) and
+ *   `Write`/`StrReplace`/`EditNotebook` (preToolUse hook + tool names).
+ *
+ * Delete is intentionally absent: it has no whole-file content or hunk to
+ * preview, so it is not "file-modifying" in the diff-capture sense.
+ */
+export declare const FILE_MODIFYING_TOOLS: ReadonlySet<string>;
+/** Whether `toolName` is a file-modifying tool in either harness taxonomy. */
+export declare function isFileModifyingTool(toolName: string): boolean;
+/**
+ * Extract the target file path from a file-modifying tool's arguments. Returns
+ * `null` when no recognized path key is present. The key set is the union across
+ * both taxonomies: deepagents/Cursor write+edit use `path`/`file_path`; a Cursor
+ * notebook edit uses `target_notebook`; the rest are defensive against drift.
+ */
+export declare function extractFilePath(args: Record<string, unknown>): string | null;
+/**
+ * Top-level arg keys, in priority order, that carry a write-family tool's
+ * WHOLE-FILE body, across both harness taxonomies (Cursor `Write` uses
+ * `content`; the SDK stream uses `contents`). Exported so the generated Cursor
+ * hook injects the SAME list into its inline content-digest extractor — the
+ * field names diverge across the hook/stream layers, so a single shared list is
+ * what keeps the runner-side and hook-side digests byte-identical.
+ */
+export declare const WRITE_CONTENT_FIELDS: readonly ["content", "contents", "file_content"];
+/**
+ * Extract the WHOLE-FILE content from a write-family tool's arguments. Returns
+ * `null` for an edit-family call (which carries `old_string`/`new_string`, not a
+ * whole-file body) or when no content key is present. An empty string is a real
+ * value (an empty file) and is preserved.
+ *
+ * Critical: this is kept strictly separate from {@link extractEditNewString}.
+ * `new_string` is an edit replacement fragment, NOT whole-file content;
+ * conflating the two would make an edit look like a whole-file capture and read
+ * the wrong `before` at the gate.
+ */
+export declare function extractWriteContent(args: Record<string, unknown>): string | null;
+/**
+ * Top-level arg keys for an edit-family tool's pre-/post-edit fragments, across
+ * both taxonomies. Exported for the same reason as {@link WRITE_CONTENT_FIELDS}:
+ * the Cursor hook injects them into its inline digest extractor so its content
+ * digest matches the runner's byte-for-byte.
+ */
+export declare const EDIT_OLD_FIELDS: readonly ["old_string", "old_text", "oldText"];
+export declare const EDIT_NEW_FIELDS: readonly ["new_string", "new_text", "newText", "replacement"];
+/**
+ * Extract an edit-family tool's pre-edit fragment (`old_string` and its
+ * variants). Returns `null` when absent; an empty string is preserved (an
+ * insertion has an empty `old_string`), matching the native gate capture.
+ */
+export declare function extractEditOldString(args: Record<string, unknown>): string | null;
+/**
+ * Extract an edit-family tool's post-edit fragment (`new_string` and its
+ * variants, including `replacement`). Returns `null` when absent; an empty
+ * string is preserved (a deletion has an empty `new_string`).
+ */
+export declare function extractEditNewString(args: Record<string, unknown>): string | null;
+/**
+ * Stable content digest of a file-mutating tool call's arguments — the content
+ * discriminator the deny-only Cursor HITL identity adds on top of
+ * (category, path) so a DIFFERENT edit to the same file re-gates rather than
+ * riding an earlier approval through.
+ *
+ * It hashes ONLY the edit content, never the path (the path is the identity's
+ * "salient" already). A whole-file write hashes its body; an edit hashes its
+ * (old, new) fragment pair. Returns "" for a call with no recoverable edit
+ * content — a shell command, a delete, a read, an MCP tool, or the hook's
+ * grep-fallback denial — which keep the coarse (category, salient) identity
+ * (already content-exact for a command / delete path).
+ *
+ * THE FORMAT IS A CROSS-LAYER CONTRACT. The Cursor preToolUse hook recomputes
+ * this digest inline from `tool_input`, running the SAME Node binary as the
+ * runner (see buildContentDigestScript in execute-cursor/hook-script.ts), so the
+ * two values must be byte-identical — any change here MUST be mirrored there.
+ * JSON.stringify of a fixed-shape string array is deterministic and identical on
+ * both sides; the leading tag ("w"/"e") keeps a write body from ever colliding
+ * with an edit pair, and the union field lists above are injected into the hook
+ * so both extract the same value despite the file_path/path & content/contents
+ * cross-layer name divergence.
+ */
+export declare function contentDigest(args: Record<string, unknown>): string;