@stigmer/runner 3.10.0 → 3.11.0

package/src/activities/execute-cursor/__tests__/mcp-resolver.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { resolveMcpServers } from "../mcp-resolver.js";
+
+function makeUsage(
+  slug: string,
+  enabledTools: string[] = [],
+  toolApprovalOverrides: Array<{ toolName: string; requiresApproval: boolean }> = [],
+) {
+  return {
+    mcpServerRef: { slug, org: "test-org", kind: 0 },
+    enabledTools,
+    toolApprovalOverrides,
+  } as any;
+}
+
+function httpMcpServer(slug: string, defaultEnabledTools: string[] = []) {
+  return {
+    metadata: { id: `id-${slug}`, slug },
+    spec: {
+      serverType: { case: "http", value: { url: "https://mcp.example.com/mcp", headers: {} } },
+      env: {},
+      defaultEnabledTools,
+    },
+    status: undefined,
+  } as any;
+}
+
+function clientReturning(serversBySlug: Record<string, unknown>) {
+  return {
+    getMcpServerByReference: vi.fn(async (ref: { slug: string }) => {
+      const server = serversBySlug[ref.slug];
+      if (!server) throw new Error(`not found: ${ref.slug}`);
+      return server;
+    }),
+  } as any;
+}
+
+// The effective-list semantics live in shared/mcp-enabled-tools.ts (tested
+// there); these tests pin the CURSOR resolver's threading — the near-duplicate
+// of shared/mcp-resolver.ts that must mirror it until oss#387 consolidates.
+describe("resolveMcpServers (cursor) — enabled_tools threading (issue #350)", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  it("carries the usage's enabled_tools as the effective allow-list", async () => {
+    const client = clientReturning({ github: httpMcpServer("github") });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github", ["create_pr"])], {}, "stdio-forbidden",
+    );
+
+    expect(result.resolvedServers[0].enabledTools).toEqual(["create_pr"]);
+  });
+
+  it("falls back to default_enabled_tools for an empty usage list", async () => {
+    const client = clientReturning({
+      github: httpMcpServer("github", ["search_code"]),
+    });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github")], {}, "stdio-forbidden",
+    );
+
+    expect(result.resolvedServers[0].enabledTools).toEqual(["search_code"]);
+  });
+
+  it("resolves unrestricted (absent field) when both lists are empty", async () => {
+    const client = clientReturning({ github: httpMcpServer("github") });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github")], {}, "stdio-forbidden",
+    );
+
+    expect(result.resolvedServers[0].enabledTools).toBeUndefined();
+  });
+
+  it("never narrows the Cursor SDK config — the SDK has no allow-list field; enforcement is the hook's disabled arm", async () => {
+    const client = clientReturning({ github: httpMcpServer("github") });
+
+    const result = await resolveMcpServers(
+      client, [makeUsage("github", ["create_pr"])], {}, "stdio-forbidden",
+    );
+
+    expect(result.cursorConfig.github).toEqual({
+      type: "http",
+      url: "https://mcp.example.com/mcp",
+      headers: undefined,
+    });
+  });
+});
+
+describe("resolveMcpServers (cursor) — tool_approval_overrides threading (issue #349)", () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  it("carries the usage's overrides on its own resolved server only", async () => {
+    // Riding the server is the scoping mechanism: an override can no longer
+    // reach a same-named tool on another server, because it never exists
+    // anywhere but its own server's object.
+    const client = clientReturning({
+      github: httpMcpServer("github"),
+      slack: httpMcpServer("slack"),
+    });
+
+    const result = await resolveMcpServers(
+      client,
+      [
+        makeUsage("github", [], [{ toolName: "delete_item", requiresApproval: false }]),
+        makeUsage("slack"),
+      ],
+      {},
+      "stdio-forbidden",
+    );
+
+    const bySlug = new Map(result.resolvedServers.map((s) => [s.slug, s]));
+    expect(bySlug.get("github")!.toolApprovalOverrides).toEqual([
+      { toolName: "delete_item", requiresApproval: false },
+    ]);
+    expect(bySlug.get("slack")!.toolApprovalOverrides).toEqual([]);
+  });
+});

package/src/activities/execute-cursor/__tests__/prompt-builder-delegation.test.ts

@@ -70,7 +70,7 @@ describe("buildEnhancedPrompt delegation integration", () => {
     skills: [],
     subAgents: [],
     workspaceFileRefs: [],
-    attachmentPaths: [],
+    attachments: [],
   };
 
   it("includes exploration guidance when a workspace dir is present", () => {

package/src/activities/execute-cursor/__tests__/turn-stream.test.ts

@@ -222,6 +222,19 @@ describe("consumeCursorTurnStream", () => {
     expect(state.streamErrorMessage).toBe("boom");
   });
 
+  it("does not capture a non-string stream ERROR message (oss#299 hardening)", async () => {
+    // message is untyped at runtime; a structured value assigned here would
+    // crash classifyText downstream (.toLowerCase() on a non-string).
+    const { deps, state } = buildDeps();
+
+    await consumeCursorTurnStream(
+      mockRun([ev({ type: "status", status: "ERROR", message: { code: 14 } })]),
+      deps,
+    );
+
+    expect(state.streamErrorMessage).toBeUndefined();
+  });
+
   describe("first-denial early stop", () => {
     let hitlDir: string;
 

package/src/activities/execute-cursor/approval-state.ts

@@ -13,6 +13,7 @@
  *   "mcpToolPolicies": {
  *     "apply_cloud_resource": { "requiresApproval": true, "message": "..." }
  *   },
+ *   "mcpServerEnabledTools": { "planton": ["get_cloud_resource"] },
  *   "approvedGrants": [{ "toolName": "edit", "mcpServerSlug": "", "key": "write", "salient": "a.txt", "contentDigest": "<sha256>" }],
  *   "approvedGrantTokens": ["<base64(key\nsalient[\ncontentDigest])>"]
  * }
@@ -174,6 +175,21 @@ export interface ApprovalStateFile {
    */
   leasedCategories: string[];
   mcpToolPolicies: Record<string, McpToolPolicyEntry>;
+  /**
+   * Per-server effective enabled_tools allow-lists (issue #350), keyed by
+   * MCP server slug — ONLY restricted servers appear (an absent slug means
+   * unrestricted, so the common case stays an empty object). The Cursor SDK
+   * config cannot hide a server's tools, so the hook enforces the manifest
+   * instead: on beforeMCPExecution it matches the payload's mcp_server_name
+   * against this map and denies a non-listed tool with the non-pausing,
+   * permanent "disabled" kind — BEFORE autoApproveAll and grants, because
+   * enabled_tools is a capability manifest, not an approval gate (no bypass
+   * may resurrect a disabled tool, and no human may be offered "approve" on
+   * one). Unlike mcpToolPolicies (name-keyed, server-blind), this map is
+   * server-scoped: the hook payload carries the server identity, so equal
+   * tool names on different servers cannot cross-grant.
+   */
+  mcpServerEnabledTools: Record<string, string[]>;
   approvedGrants: ApprovalGrant[];
   approvedGrantTokens: string[];
   /**
@@ -381,6 +397,8 @@ function parseArgs(argsPreview: string): Record<string, unknown> | undefined {
  * - leasedCategories: built-in categories with a run-lifetime lease
  * - mcpToolPolicies: per-tool policy for MCP tools requiring approval (leased
  *   servers are already absent — dropped upstream by mergeApprovalPolicies)
+ * - mcpServerEnabledTools: per-server enabled_tools allow-lists (issue #350,
+ *   restricted servers only) for the hook's permanent "disabled" arm
  * - approvedGrants / approvedGrantTokens: tools approved in the current HITL
  *   cycle, allowed through on reinvocation
  *
@@ -396,6 +414,7 @@ export function buildApprovalState(
   captureIgnored = false,
   gitWorkspace = true,
   unattendedSkip = false,
+  mcpServerEnabledTools: Record<string, string[]> = {},
 ): ApprovalStateFile {
   const approvedGrants = grants ?? [];
 
@@ -411,6 +430,7 @@ export function buildApprovalState(
     autoApproveAll: globalBypass,
     leasedCategories: [...leasedCategories],
     mcpToolPolicies,
+    mcpServerEnabledTools,
     approvedGrants,
     // The hook matches a tool call's PRIMARY token (content when it can compute a
     // digest from tool_input, else coarse). A content-identified grant authorizes
@@ -474,12 +494,18 @@ const DENIAL_LEDGER_FILE = "denials.jsonl";
  *                     classification may never have run).
  * - `fail-closed`   — the approval state file was missing, so everything gated
  *                     denied. A turn-level "the gate itself was broken" fact.
+ * - `disabled`      — the agent's enabled_tools manifest excludes this MCP
+ *                     tool (issue #350). Permanent for the run and
+ *                     mode-independent: NOT an approval (a human must never be
+ *                     offered "approve" on a manifest-disabled tool), so it is
+ *                     non-pausing and the model adapts — the same consumer
+ *                     semantics as `secret`.
  *
  * An unknown kind string is preserved as-is: it is treated as non-pausing (an
  * unknown deny must never manufacture an approval) but still attributes the
  * blocked call to our own hook.
  */
-export type DenialKind = "approval" | "unattended" | "secret" | "capture-error" | "fail-closed";
+export type DenialKind = "approval" | "unattended" | "secret" | "capture-error" | "fail-closed" | "disabled";
 
 /** The one kind that pauses the run for user approval. */
 export const APPROVAL_DENIAL_KIND: DenialKind = "approval";
@@ -487,6 +513,9 @@ export const APPROVAL_DENIAL_KIND: DenialKind = "approval";
 /** The unattended-mode resolution kind (non-pausing; stamped SKIPPED). */
 export const UNATTENDED_DENIAL_KIND: DenialKind = "unattended";
 
+/** The enabled_tools manifest denial kind (non-pausing, permanent; issue #350). */
+export const DISABLED_DENIAL_KIND: DenialKind = "disabled";
+
 /**
  * One denial recorded by the preToolUse hook. `token` is the call's identity in
  * the same space as grantToken() (base64 of `toolName \n salientArg`), used to

package/src/activities/execute-cursor/attachment-resolver.ts

@@ -22,6 +22,13 @@
  * directives are built from the RESOLVED paths, so prompt and filesystem can
  * never disagree.
  *
+ * Duplicate filenames are renamed, never overwritten (issue #364): because
+ * placement keys purely on the filename, two attachments with the same name
+ * contend for one path — the later one takes the platform's `stem-2.ext`
+ * rename (shared/attachment-naming.ts, same semantics as the deep-agent
+ * injector and the React composer) and the rename is disclosed in the
+ * prompt's `<input_files>` section via {@link ResolvedAttachment.renamedFrom}.
+ *
  * Error model: fail-hard, matching the native harness's attachment injector.
  * Attachments are explicit user inputs — an execution that silently runs
  * without one produces silently incorrect results (the "plan file wasn't
@@ -33,6 +40,7 @@ import { mkdir, copyFile, readFile, stat, writeFile } from "node:fs/promises";
 import { join, basename } from "node:path";
 import type { Attachment } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ArtifactStorage } from "../../shared/artifact-storage.js";
+import { allocateUniqueName } from "../../shared/attachment-naming.js";
 import {
   isVisionCandidate,
   type VisionBudget,
@@ -46,9 +54,16 @@ import { ensureStigmerSymlink, STIGMER_LOCAL_STATE_DIR } from "../../shared/work
 const INPUTS_SUBDIR = "inputs";
 
 export interface ResolvedAttachment {
+  /** The final on-disk basename — after any duplicate rename. */
   filename: string;
   /** Workspace-relative path the agent reads (`.stigmer/inputs/{filename}`). */
   relativePath: string;
+  /**
+   * The attachment's original filename, present only when a duplicate name
+   * was renamed (shared/attachment-naming.ts) — rendered as disclosure in
+   * the prompt's `<input_files>` section.
+   */
+  renamedFrom?: string;
   /** Present when the attachment was accepted into the turn's vision payload. */
   vision?: VisionImage;
   /**
@@ -111,9 +126,13 @@ export async function resolveAttachments(
   // it, but only when the agent has skills).
   await ensureStigmerSymlink(options.primaryWorkspaceDir, platformDir);
 
+  // Placement keys purely on the filename, so this set is the whole
+  // collision domain — sequential resolution means each attachment sees
+  // every name claimed before it (see module doc on duplicate handling).
+  const takenNames = new Set<string>();
   const results: ResolvedAttachment[] = [];
   for (const attachment of attachments) {
-    results.push(await resolveAttachment(attachment, inputsDir, options));
+    results.push(await resolveAttachment(attachment, inputsDir, takenNames, options));
   }
 
   console.log(
@@ -127,11 +146,15 @@ export async function resolveAttachments(
 async function resolveAttachment(
   attachment: Attachment,
   inputsDir: string,
+  takenNames: Set<string>,
   options: AttachmentResolverOptions,
 ): Promise<ResolvedAttachment> {
   // Local-mode fast path: the file is already on this machine's disk.
   if (options.mode === "local" && attachment.localPath) {
-    const filename = safeInputName(attachment.filename || attachment.localPath);
+    const { name: filename, renamedFrom } = allocateUniqueName(
+      safeInputName(attachment.filename || attachment.localPath),
+      takenNames,
+    );
     let vision: VisionOutcome | undefined;
     try {
       vision = await materializeLocalFile(attachment, filename, inputsDir, options.visionBudget);
@@ -145,6 +168,7 @@ async function resolveAttachment(
     return {
       filename,
       relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+      ...(renamedFrom !== undefined ? { renamedFrom } : {}),
       ...visionOutcomeFields(vision),
     };
   }
@@ -164,7 +188,10 @@ async function resolveAttachment(
     );
   }
 
-  const filename = safeInputName(attachment.filename || attachment.storageKey);
+  const { name: filename, renamedFrom } = allocateUniqueName(
+    safeInputName(attachment.filename || attachment.storageKey),
+    takenNames,
+  );
   let content: Buffer;
   try {
     content = await options.storage.download(attachment.storageKey);
@@ -185,6 +212,7 @@ async function resolveAttachment(
   return {
     filename,
     relativePath: join(STIGMER_LOCAL_STATE_DIR, INPUTS_SUBDIR, filename),
+    ...(renamedFrom !== undefined ? { renamedFrom } : {}),
     ...visionOutcomeFields(vision),
   };
 }

package/src/activities/execute-cursor/blueprint-resolver.ts

@@ -20,6 +20,13 @@ import type { SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/
 import type { WorkspaceEntry } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
 import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import type { CloudRepo } from "./session-lifecycle.js";
+import { mergeMcpServerUsages } from "../../shared/mcp-resolver.js";
+
+// Both harnesses must merge agent + session usages identically (session wins
+// per slug — the usage whose enabled_tools the enforcement honors), so the
+// merge lives in shared/mcp-resolver.ts. Re-exported here for its historical
+// home alongside mergeSkillRefs.
+export { mergeMcpServerUsages } from "../../shared/mcp-resolver.js";
 
 /**
  * Path segments that identify runner-internal directories. Any workspace dir
@@ -130,33 +137,6 @@ export function resolveCloudRepos(workspaceEntries: WorkspaceEntry[]): CloudRepo
 // MCP and skill merging
 // ---------------------------------------------------------------------------
 
-/**
- * Merge MCP server usages from agent (base) and session (overlay).
- *
- * Replicates session_context_merge.py::merge_mcp_server_usages():
- * - Agent-level usages are the base set
- * - Session-level usages extend or override by mcp_server_ref.slug
- * - If both reference the same slug, session-level takes precedence
- */
-export function mergeMcpServerUsages(
-  agentUsages: McpServerUsage[],
-  sessionUsages: McpServerUsage[],
-): McpServerUsage[] {
-  const bySlug = new Map<string, McpServerUsage>();
-
-  for (const usage of agentUsages) {
-    const slug = usage.mcpServerRef?.slug;
-    if (slug) bySlug.set(slug, usage);
-  }
-
-  for (const usage of sessionUsages) {
-    const slug = usage.mcpServerRef?.slug;
-    if (slug) bySlug.set(slug, usage);
-  }
-
-  return [...bySlug.values()];
-}
-
 /**
  * Merge skill refs from agent and session.
  *

package/src/activities/execute-cursor/env-resolver.ts

@@ -25,7 +25,9 @@ export async function resolveExecutionEnv(
 ): Promise<EnvResult> {
   // A desktop runner exchanges its bootstrap credential for a token scoped to
   // this execution's session, so cloud's decrypt gate binds the read (#156).
-  // No-op for cloud sandbox and OSS runners.
+  // No-op for cloud sandbox and OSS runners. A failed exchange throws and
+  // fails the activity: the bootstrap credential no longer decrypts
+  // (stigmer-cloud#218), so proceeding would resolve redacted placeholders.
   const scopedToken = await client.acquireScopedRunnerToken({
     agentExecutionId: executionId,
   });

package/src/activities/execute-cursor/error-classifier.ts

@@ -7,8 +7,9 @@
  * 3. Surface isRetryable for future workflow-level retry decisions
  *
  * Error detail can come from several sources (in priority order):
- * - A thrown CursorSdkError's structured fields (highest fidelity)
- * - run.wait().result (SDK-provided string, often bare/generic)
+ * - Structured fields, either from a thrown CursorSdkError or lifted from a
+ *   structured run.wait() error value (highest fidelity)
+ * - run.wait() error text (SDK-provided string, often bare/generic)
  * - SDKStatusMessage with status "ERROR" from the stream
  * - ConnectError captured from process unhandledRejection
  * - Text extracted from the failing run.conversation() turn
@@ -39,7 +40,8 @@ export interface ClassifiedError {
 
 /**
  * Structured fields lifted from a thrown CursorSdkError (errors.d.ts:
- * { code, status, isRetryable, cause, endpoint, requestId, operation }).
+ * { code, status, isRetryable, cause, endpoint, requestId, operation }) or
+ * from a structured run.wait() error value (see extractRunErrorSources).
  * Only the fields used for classification are retained.
  */
 export interface SdkErrorFields {
@@ -48,6 +50,87 @@ export interface SdkErrorFields {
   message?: string;
 }
 
+/**
+ * What String() produces for any plain object. Carries zero signal, so it is
+ * refused everywhere: extraction never emits it, and classifyFromSources
+ * treats it as absent should any other producer leak it through.
+ */
+const OBJECT_JUNK_STRING = "[object Object]";
+
+/**
+ * Error detail lifted from a run.wait() result, split by fidelity: structured
+ * values land in sdkError, plain text in sdkResultFields. At most one of the
+ * two is set; both undefined means the result carried nothing usable and the
+ * classifier's lower-priority sources should decide.
+ */
+export interface RunErrorSources {
+  sdkError: SdkErrorFields | undefined;
+  sdkResultFields: string | undefined;
+}
+
+const NO_RUN_ERROR_SOURCES: RunErrorSources = {
+  sdkError: undefined,
+  sdkResultFields: undefined,
+};
+
+/**
+ * Lift error detail from a run.wait() result whose status is "error".
+ *
+ * The SDK types RunResult.result as `string`, but structured values (Error
+ * instances, { code, message } objects) have been observed at runtime, both
+ * in `result` and in the undeclared error/message/reason fields (oss#299).
+ * A bare String() on those yields "[object Object]", which both destroys the
+ * message users see and — worse — shadows the lower-priority classifier
+ * sources (stream, rejection, conversation introspection) that often hold
+ * the real reason.
+ *
+ * Walks the candidate fields in order and answers from the FIRST one that
+ * yields usable content: strings keep flowing to the string channel
+ * (sdkResultFields), structured values are lifted into the same structured
+ * channel a thrown CursorSdkError uses (sdkError), and hopeless values are
+ * skipped so a later candidate — or the classifier's fallback sources — can
+ * win. (The previous `??` chain stopped at the first non-nullish value, so a
+ * hopeless object or empty string hid usable text one field later.)
+ *
+ * Deliberately NO JSON.stringify fallback for unrecognized object shapes:
+ * the error arm already logs the raw result in full server-side, and a JSON
+ * blob shown to the user would shadow the introspection sources that exist
+ * precisely to recover the real reason.
+ */
+export function extractRunErrorSources(result: unknown): RunErrorSources {
+  if (result === null || typeof result !== "object") return NO_RUN_ERROR_SOURCES;
+  const r = result as Record<string, unknown>;
+  for (const candidate of [r.result, r.error, r.message, r.reason]) {
+    const extracted = extractFromCandidate(candidate);
+    if (extracted) return extracted;
+  }
+  return NO_RUN_ERROR_SOURCES;
+}
+
+function extractFromCandidate(v: unknown): RunErrorSources | undefined {
+  if (v == null) return undefined;
+  if (typeof v === "string") {
+    if (v.length === 0 || v === OBJECT_JUNK_STRING) return undefined;
+    return { sdkError: undefined, sdkResultFields: v };
+  }
+  if (typeof v === "object") {
+    // Covers Error instances too: their message (and, on SDK/Node error
+    // shapes, code/status) are readable as plain properties.
+    const o = v as Record<string, unknown>;
+    const fields: SdkErrorFields = {};
+    if (typeof o.code === "string" && o.code.length > 0) fields.code = o.code;
+    if (typeof o.status === "number") fields.status = o.status;
+    if (typeof o.message === "string" && o.message.length > 0) fields.message = o.message;
+    if (fields.code !== undefined || fields.status !== undefined || fields.message !== undefined) {
+      return { sdkError: fields, sdkResultFields: undefined };
+    }
+    return undefined;
+  }
+  // Remaining primitives (number, boolean, ...) stringify losslessly.
+  const text = String(v);
+  return text.length > 0 ? { sdkError: undefined, sdkResultFields: text } : undefined;
+}
+
 const AUTH_PATTERNS = [
   "unauthenticated", "unauthorized", "401", "forbidden",
   "permission_denied", "invalid api key", "not logged in",
@@ -168,7 +251,11 @@ function classifyFromSources(opts: SynthesizeErrorOpts): ClassifiedError {
   }
 
   if (opts.sdkResultFields) {
-    const isBareGeneric = opts.sdkResultFields === "Cursor run failed";
+    // "Cursor run failed" is the SDK's bare generic; "[object Object]" is
+    // String()-coerced junk from any producer that bypassed the shape-aware
+    // extraction. Neither carries signal — fall through to better sources.
+    const isBareGeneric = opts.sdkResultFields === "Cursor run failed"
+      || opts.sdkResultFields === OBJECT_JUNK_STRING;
     if (!isBareGeneric) {
       const { category, retryable } = classifyText(opts.sdkResultFields);
       return {

package/src/activities/execute-cursor/extract-structured-output.ts

@@ -0,0 +1,72 @@
+/**
+ * Tier-2 structured-output extraction for the Cursor harness.
+ *
+ * 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 (rather than inside execute-cursor/index.ts) so
+ * the LangChain construction path stays out of the Cursor activity's module
+ * graph until a run actually needs tier 2 — index.ts 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";
+import { getEconomyModel } from "../../shared/model-registry.js";
+import { buildChatModel } from "../../shared/model-client.js";
+import { checkDirectCredentials } from "../../shared/llm-backend.js";
+import { tryInferProvider } from "../../shared/llm-proxy.js";
+import { jsonSchemaToZod } from "../../shared/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.
+ *
+ * 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: string,
+  schema: Record<string, unknown>,
+  config: Config,
+  primaryModel: string,
+): Promise<unknown | null> {
+  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.stigmerToken ?? undefined,
+    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;
+}