@stigmer/runner 3.12.4 → 3.12.5

package/dist/.build-fingerprint

@@ -1 +1 @@
-{"hash":"30fa0c9a11a788e3","builtAt":"2026-08-14T07:34:03.879Z","fileCount":297}
+{"hash":"e77d58b2bc3277e6","builtAt":"2026-08-15T12:57:42.305Z","fileCount":298}

package/dist/activities/execute-cursor/cursor-mcp-config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The Cursor harness's MCP output adapter: maps the shared resolver's
+ * {@link ResolvedMcpServer} servers into the Cursor SDK's mcpServers config
+ * for Agent.create(), plus the harness's env pre-flight check.
+ *
+ * Resolution itself lives in shared/mcp-resolver.ts (oss#387 consolidated the
+ * near-duplicate resolver this file used to carry) — this module is the
+ * symmetric twin of the deep-agent harness's toMcpClientConfig in
+ * shared/mcp-manager.ts: both consume the identical intermediate, only the
+ * final SDK serialization differs.
+ */
+import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
+import type { ResolvedMcpServer } from "../../shared/mcp-resolver.js";
+/**
+ * Cursor SDK MCP server config shape (matches @cursor/sdk McpServerConfig).
+ * Defined here to avoid tight coupling to the SDK's internal types.
+ */
+export type CursorMcpServerConfig = {
+    type?: "stdio";
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+} | {
+    type?: "http" | "sse";
+    url: string;
+    headers?: Record<string, string>;
+};
+/**
+ * Transform resolved MCP servers into the Cursor SDK's mcpServers config
+ * for Agent.create().
+ *
+ * Call it ONCE, after the last mutation of the resolved-server list (backfill,
+ * synthesized-attachment injection): the config is a projection of that list,
+ * and building it early just creates a stale copy someone must remember to
+ * rebuild. The Cursor SDK config cannot hide tools, so enabledTools is NOT
+ * expressed here — the HITL hook enforces it (see ResolvedMcpServer.enabledTools).
+ */
+export declare function toCursorMcpConfig(servers: ResolvedMcpServer[]): Record<string, CursorMcpServerConfig>;
+/**
+ * Validate that resolved MCP servers have their required env vars populated.
+ * Returns a list of warnings for servers with empty/missing env.
+ * Used as a pre-flight check before agent.send() to surface config issues early.
+ */
+export declare function validateMcpServerEnv(servers: ResolvedMcpServer[], usages: McpServerUsage[]): string[];

package/dist/activities/execute-cursor/cursor-mcp-config.js

@@ -0,0 +1,76 @@
+/**
+ * The Cursor harness's MCP output adapter: maps the shared resolver's
+ * {@link ResolvedMcpServer} servers into the Cursor SDK's mcpServers config
+ * for Agent.create(), plus the harness's env pre-flight check.
+ *
+ * Resolution itself lives in shared/mcp-resolver.ts (oss#387 consolidated the
+ * near-duplicate resolver this file used to carry) — this module is the
+ * symmetric twin of the deep-agent harness's toMcpClientConfig in
+ * shared/mcp-manager.ts: both consume the identical intermediate, only the
+ * final SDK serialization differs.
+ */
+/**
+ * Transform resolved MCP servers into the Cursor SDK's mcpServers config
+ * for Agent.create().
+ *
+ * Call it ONCE, after the last mutation of the resolved-server list (backfill,
+ * synthesized-attachment injection): the config is a projection of that list,
+ * and building it early just creates a stale copy someone must remember to
+ * rebuild. The Cursor SDK config cannot hide tools, so enabledTools is NOT
+ * expressed here — the HITL hook enforces it (see ResolvedMcpServer.enabledTools).
+ */
+export function toCursorMcpConfig(servers) {
+    const result = {};
+    for (const server of servers) {
+        if (server.connectionType === "stdio") {
+            if (!server.command)
+                continue;
+            result[server.slug] = {
+                type: "stdio",
+                command: server.command,
+                args: server.args,
+                env: server.env,
+                cwd: server.cwd,
+            };
+        }
+        else {
+            if (!server.url)
+                continue;
+            result[server.slug] = {
+                type: server.connectionType,
+                url: server.url,
+                headers: server.headers,
+            };
+        }
+    }
+    return result;
+}
+/**
+ * Validate that resolved MCP servers have their required env vars populated.
+ * Returns a list of warnings for servers with empty/missing env.
+ * Used as a pre-flight check before agent.send() to surface config issues early.
+ */
+export function validateMcpServerEnv(servers, usages) {
+    const warnings = [];
+    for (const usage of usages) {
+        const slug = usage.mcpServerRef?.slug;
+        if (!slug)
+            continue;
+        const resolved = servers.find((s) => s.slug === slug);
+        if (!resolved) {
+            warnings.push(`MCP server '${slug}': failed to resolve (server may not exist or is inaccessible)`);
+            continue;
+        }
+        if (resolved.connectionType === "stdio" && resolved.env) {
+            const emptyKeys = Object.entries(resolved.env)
+                .filter(([, v]) => !v)
+                .map(([k]) => k);
+            if (emptyKeys.length > 0) {
+                warnings.push(`MCP server '${slug}': env vars [${emptyKeys.join(", ")}] are empty — ` +
+                    `server subprocess will likely fail to connect`);
+            }
+        }
+    }
+    return warnings;
+}
+//# sourceMappingURL=cursor-mcp-config.js.map

package/dist/activities/execute-cursor/cursor-mcp-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-mcp-config.js","sourceRoot":"","sources":["../../../src/activities/execute-cursor/cursor-mcp-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAuBH;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA4B;IAE5B,MAAM,MAAM,GAA0C,EAAE,CAAC;IAEzD,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,cAAc,KAAK,OAAO,EAAE,CAAC;YACtC,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,SAAS;YAC9B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG;gBACpB,IAAI,EAAE,OAAO;gBACb,OAAO,EAAE,MAAM,CAAC,OAAO;gBACvB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,GAAG,EAAE,MAAM,CAAC,GAAG;aAChB,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,CAAC,GAAG;gBAAE,SAAS;YAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG;gBACpB,IAAI,EAAE,MAAM,CAAC,cAAc;gBAC3B,GAAG,EAAE,MAAM,CAAC,GAAG;gBACf,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA4B,EAC5B,MAAwB;IAExB,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,EAAE,IAAI,CAAC;QACtC,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;QACtD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC,eAAe,IAAI,gEAAgE,CAAC,CAAC;YACnG,SAAS;QACX,CAAC;QAED,IAAI,QAAQ,CAAC,cAAc,KAAK,OAAO,IAAI,QAAQ,CAAC,GAAG,EAAE,CAAC;YACxD,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;iBAC3C,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;iBACrB,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;YACnB,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,QAAQ,CAAC,IAAI,CACX,eAAe,IAAI,gBAAgB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,gBAAgB;oBACvE,+CAA+C,CAChD,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/activities/execute-cursor/index.d.ts

@@ -99,10 +99,19 @@ export interface BuildPromptInput {
      * turn.
      */
     sessionContext?: string;
+    /**
+     * Platform-declared standing preferences from the execution spec's
+     * `declared_preferences` (stigmer/stigmer#293). Like the bridge, only
+     * the enhanced-prompt path consumes it — deliberately frozen per Cursor
+     * session (DD-002 D3): the first turn delivers it into the agent's own
+     * conversation store, and repeating it on resumed turns would bloat the
+     * store with identical content.
+     */
+    declaredPreferences?: import("../../shared/declared-preferences.js").DeclaredPreferencesContent;
     /**
      * Conversation catchup from the execution spec's `conversation_catchup`
      * (cloud DD-006): what happened on the channel conversation that the
-     * agent has not seen. PER-TURN, so unlike the three standing values
+     * agent has not seen. PER-TURN, so unlike the standing values
      * above it rides BOTH prompt paths — the enhanced prompt and a resumed
      * turn's prefix (the `interaction_mode` shape). Handback lands
      * mid-session on a resumed agent: the resumed path is the one that

package/dist/activities/execute-cursor/index.js

@@ -45,6 +45,7 @@ import { readConversationCatchup } from "../../shared/conversation-catchup.js";
 import { readSenderIdentity } from "../../shared/sender-identity.js";
 import { injectCallerIdentityEnv, resolveCallerIdentity, } from "../../shared/caller-identity.js";
 import { readSessionContext } from "../../shared/session-context.js";
+import { readDeclaredPreferences } from "../../shared/declared-preferences.js";
 import { withholdSecretContentFromMessages } from "../../shared/tool-row.js";
 import { StallTimeoutError, formatStallFailure } from "../../shared/stall-watchdog.js";
 import { resolveUsableArtifactStorage, loadArtifactStorageConfig } from "../../shared/artifact-storage.js";
@@ -55,7 +56,8 @@ import { DeltaEnricher } from "./delta-enricher.js";
 import { TodoTracker } from "./todo-tracker.js";
 import { StreamingUpdateScheduler, loadStreamingConfig } from "../../shared/streaming-scheduler.js";
 import { createCursorEventRecorder } from "./cursor-event-recorder.js";
-import { resolveMcpServers, toCursorMcpConfig, validateMcpServerEnv } from "./mcp-resolver.js";
+import { resolveMcpServers } from "../../shared/mcp-resolver.js";
+import { toCursorMcpConfig, validateMcpServerEnv } from "./cursor-mcp-config.js";
 import { resolveMcpTransportPosture } from "../../shared/mcp-transport-guard.js";
 import { discoverChannelMessaging, synthesizeChannelAttachment, } from "../../shared/channel-attachment.js";
 import { readChannelConversationId, synthesizeConversationAttachment, } from "../../shared/conversation-attachment.js";
@@ -63,7 +65,7 @@ import { injectSynthesizedAttachment } from "../../shared/synthesized-attachment
 import { mergeApprovalPolicies } from "./approval-policy.js";
 import { deriveActiveLeases, isUnattendedApprovalMode } from "../../shared/approval-policy.js";
 import { enabledToolsBySlug } from "../../shared/mcp-enabled-tools.js";
-import { backfillMcpServersIfNeeded } from "./connect-backfill.js";
+import { backfillMcpServersIfNeeded } from "../../shared/connect-backfill.js";
 import { resolveExecutionEnv } from "./env-resolver.js";
 import { resolveBlueprint } from "./blueprint-resolver.js";
 import { buildCursorSubAgentDefinitions } from "./subagent-config.js";
@@ -103,7 +105,7 @@ import { synthesizeError, formatClassifiedError, shouldRetryWithFreshAgent, extr
 import { createAgent, createCloudAgent } from "./session-lifecycle.js";
 import { setMaxListeners } from "node:events";
 import { startHeartbeat } from "../../shared/heartbeat.js";
-import { getShutdownSignalForQueue } from "../../runner-manager.js";
+import { classifyTurnInterruption, getShutdownSignalForQueue } from "../../shared/worker-shutdown.js";
 /**
  * Creates the activity functions bound to the runner config.
  * Returned object is passed to Temporal Worker.create({ activities }).
@@ -526,12 +528,15 @@ turnSeq) {
         await reportSetupProgress(client, executionId, "Resolving MCP servers");
         const transportPosture = resolveMcpTransportPosture(config.mode);
         const mcpEnvVars = injectCallerIdentityEnv(envVars, resolveCallerIdentity(blueprint.sessionSpec.metadata, session.status?.audit?.specAudit?.createdBy), sessionId);
-        let mcpResolution = await resolveMcpServers(client, blueprint.mergedMcpServerUsages, mcpEnvVars, transportPosture);
+        // The resolved-server list mutates through backfill and attachment
+        // injection below; the Cursor SDK config is projected from it exactly
+        // once, after the last mutation (see toCursorMcpConfig).
+        let resolvedMcpServers = (await resolveMcpServers(client, blueprint.mergedMcpServerUsages, mcpEnvVars, transportPosture)).resolvedServers;
         setupTiming.mark("resolve_mcp_servers");
         // Phase 4a: Connect backfill for undiscovered MCP servers
         heartbeatPhase = "resolving_mcp_servers";
         const sessionOrg = session.metadata?.org ?? "";
-        mcpResolution = await backfillMcpServersIfNeeded(client, mcpResolution, blueprint.mergedMcpServerUsages, mcpEnvVars, sessionOrg, transportPosture, heartbeat, secretKeys);
+        resolvedMcpServers = await backfillMcpServersIfNeeded(client, resolvedMcpServers, blueprint.mergedMcpServerUsages, mcpEnvVars, sessionOrg, transportPosture, heartbeat, secretKeys);
         setupTiming.mark("backfill_mcp");
         // The synthesized attachments' credential story (DD-006 D4): the
         // exchanged token authenticates the discovery reads per-call (a
@@ -574,11 +579,7 @@ turnSeq) {
                 backendEndpoint: config.stigmerBackendEndpoint,
             });
             if (attachment) {
-                const resolvedServers = injectSynthesizedAttachment(mcpResolution.resolvedServers, attachment, "channel messaging");
-                mcpResolution = {
-                    resolvedServers,
-                    cursorConfig: toCursorMcpConfig(resolvedServers),
-                };
+                resolvedMcpServers = injectSynthesizedAttachment(resolvedMcpServers, attachment, "channel messaging");
             }
         }
         // Phase 4a4: Synthesize the conversation participation attachment
@@ -594,13 +595,11 @@ turnSeq) {
             backendEndpoint: config.stigmerBackendEndpoint,
         });
         if (conversationAttachment) {
-            const resolvedServers = injectSynthesizedAttachment(mcpResolution.resolvedServers, conversationAttachment, "conversation participation");
-            mcpResolution = {
-                resolvedServers,
-                cursorConfig: toCursorMcpConfig(resolvedServers),
-            };
+            resolvedMcpServers = injectSynthesizedAttachment(resolvedMcpServers, conversationAttachment, "conversation participation");
         }
-        const mcpConfig = mcpResolution.cursorConfig;
+        // The one projection point: every mutation above is now visible in the
+        // Cursor SDK config by construction (no per-mutation rebuild to forget).
+        const mcpConfig = toCursorMcpConfig(resolvedMcpServers);
         // Phase 4b: Merge approval policies from all layers.
         //
         // Two bypasses (see ActiveLeases, shared with the native harness): the
@@ -614,10 +613,10 @@ turnSeq) {
         // Layer-3 overrides ride each resolved server from its merged usage —
         // see ResolvedMcpServer.toolApprovalOverrides (issue #349) — so there
         // is no separate override input to pass here.
-        const mergedPolicies = mergeApprovalPolicies(mcpResolution.resolvedServers, leases);
+        const mergedPolicies = mergeApprovalPolicies(resolvedMcpServers, leases);
         heartbeat();
         // Phase 4c: Validate MCP server env health (diagnostic, non-blocking)
-        const mcpWarnings = validateMcpServerEnv(mcpResolution.resolvedServers, blueprint.mergedMcpServerUsages, envVars);
+        const mcpWarnings = validateMcpServerEnv(resolvedMcpServers, blueprint.mergedMcpServerUsages);
         if (mcpWarnings.length > 0) {
             console.warn(`ExecuteCursor MCP pre-flight warnings: execution=${executionId}\n` +
                 mcpWarnings.map((w) => `  - ${w}`).join("\n"));
@@ -760,7 +759,7 @@ turnSeq) {
         // servers' allow-lists, enforced by the hook's "disabled" arm ahead of
         // every approval bypass. The Cursor SDK config cannot hide a server's
         // tools, so this deny-at-call is the harness's enforcement.
-        enabledToolsBySlug(mcpResolution.resolvedServers));
+        enabledToolsBySlug(resolvedMcpServers));
         const hitlGate = await installHitlGate({
             workspaceRoot: primaryWorkspaceDir,
             hitlDir,
@@ -989,6 +988,7 @@ turnSeq) {
             contextBridge: readContextBridge(blueprint.sessionSpec.metadata),
             senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
             sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
+            declaredPreferences: readDeclaredPreferences(spec.declaredPreferences),
             conversationCatchup: readConversationCatchup(spec.conversationCatchup),
             // The turn's recorded transcript, seeded from the persisted execution
             // on a reinvocation (Phase 3). Consumed only by the HITL-recovery
@@ -1188,14 +1188,22 @@ turnSeq) {
         // classifies a shutdown from the shutdown signal directly (in
         // resolvePreBoundaryTerminal). The heartbeat timer may set `cancelled` before
         // the AbortSignal microtask propagates; the direct signal check catches that.
-        const isShutdown = periodicHeartbeat.workerShutdown || (shutdownSignal?.aborted ?? false);
-        if (isShutdown) {
+        // The decision table (including #776's grace-window guard: an aborted
+        // shutdown signal with NO interruption evidence stays "none") lives in
+        // classifyTurnInterruption — shared/worker-shutdown.ts.
+        const interruption = classifyTurnInterruption({
+            heartbeatCancelled: periodicHeartbeat.cancelled,
+            heartbeatWorkerShutdown: periodicHeartbeat.workerShutdown,
+            cancellationSignalAborted: Context.current().cancellationSignal.aborted,
+            shutdownSignalAborted: shutdownSignal?.aborted ?? false,
+        });
+        if (interruption === "worker-shutdown") {
             turnState.pauseDetected = false;
         }
-        else if (periodicHeartbeat.cancelled) {
+        else if (interruption === "pause") {
             turnState.pauseDetected = true;
         }
-        workerShutdownDetected = isShutdown;
+        workerShutdownDetected = interruption === "worker-shutdown";
         // Post-stream finalize, shared by the primary turn and both recovery retries:
         // finalize the transcript + streaming flags, mark any in-flight sub-agent
         // CANCELLED on an aborted turn, snapshot usage, flush the recorder, and
@@ -1270,10 +1278,14 @@ turnSeq) {
                     `estimatedCostUsd=${estimated.toFixed(4)}, maxCostUsd=${maxCostUsd.toFixed(2)}`);
                 return { kind: "return" };
             }
-            // Worker shutdown: the runner-manager aborted the shutdown signal. NOT a
+            // Worker shutdown: the runner/manager aborted the shutdown signal. NOT a
             // user pause. Checked via the shutdown signal directly so a retry (whose
-            // periodic heartbeat is already stopped) still classifies it correctly.
-            if (workerShutdownDetected || (shutdownSignal?.aborted ?? false)) {
+            // periodic heartbeat is already stopped) still classifies it correctly —
+            // but only alongside a delivered cancellation: a retry that completed
+            // normally inside the drain grace window must stay a completion (#776's
+            // grace-window guard, mirroring the primary's `interrupted` gate).
+            if (workerShutdownDetected ||
+                ((shutdownSignal?.aborted ?? false) && Context.current().cancellationSignal.aborted)) {
                 status.phase = ExecutionPhase.EXECUTION_FAILED;
                 status.error = "Execution interrupted: runner worker was shut down. Retry or resume.";
                 status.completedAt = utcTimestamp();
@@ -1574,6 +1586,7 @@ turnSeq) {
                         contextBridge: readContextBridge(blueprint.sessionSpec.metadata),
                         senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
                         sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
+                        declaredPreferences: readDeclaredPreferences(spec.declaredPreferences),
                         conversationCatchup: readConversationCatchup(spec.conversationCatchup),
                         // Composed fresh (not reused from Phase 10): the failed primary
                         // stream may have appended partial work onto status.messages,
@@ -1805,9 +1818,12 @@ turnSeq) {
     catch (err) {
         periodicHeartbeat?.stop();
         if (err instanceof CancelledFailure) {
-            // workerShutdownDetected means the runner-manager signaled shutdown
-            // before the worker drained. This is infrastructure failure, not pause.
-            if (workerShutdownDetected) {
+            // Worker shutdown is infrastructure failure, not pause. The direct
+            // signal check covers a CancelledFailure thrown BEFORE the post-stream
+            // classification ran (workerShutdownDetected still false); no extra
+            // interruption-evidence gate is needed here — the caught
+            // CancelledFailure IS the evidence (#776).
+            if (workerShutdownDetected || (shutdownSignal?.aborted ?? false)) {
                 console.log(`ExecuteCursor cancelled (worker shutdown) for execution ${executionId}`);
                 status.phase = ExecutionPhase.EXECUTION_FAILED;
                 status.error = "Execution interrupted: runner worker was shut down. Retry or resume.";
@@ -2109,6 +2125,7 @@ export function buildPrompt(input) {
                 contextBridge: input.contextBridge,
                 senderIdentity: input.senderIdentity,
                 sessionContext: input.sessionContext,
+                declaredPreferences: input.declaredPreferences,
                 conversationCatchup,
             }, {
                 turnDigest: input.turnRecoveryDigest,
@@ -2167,6 +2184,7 @@ export function buildPrompt(input) {
         contextBridge: input.contextBridge,
         senderIdentity: input.senderIdentity,
         sessionContext: input.sessionContext,
+        declaredPreferences: input.declaredPreferences,
         conversationCatchup,
     });
 }