@stigmer/runner 3.12.3 → 3.12.5

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

@@ -34,6 +34,7 @@ import { ExecutionPhase, FileChangeSetStatus, InteractionMode, MessageType, Appr
 import { StigmerClient } from "../../client/stigmer-client.js";
 import { describeExecutionError } from "../../shared/model-error.js";
 import { resolveAgentWithTransportRecovery } from "./session-lifecycle.js";
+import { cacheSessionAgent, computeAgentFingerprint, takeCachedAgent } from "./agent-session-cache.js";
 import { CursorMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
 import { determineCursorMode, isCloudMode } from "./cursor-mode.js";
 import { MessageAccumulator, cancelInProgressSubAgentProtos, collapseRedundantToolCallTwins } from "./message-translator.js";
@@ -44,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";
@@ -54,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";
@@ -62,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";
@@ -91,7 +94,8 @@ import { statusProtoWriter } from "../../shared/execution-status-writer.js";
 import { setInterceptorExecutionId, runWithExecutionContext } from "./fetch-interceptor.js";
 import { closeProxySessions } from "./http2-interceptor.js";
 import { resolveModelId, ensureLoaded as ensurePricingLoaded } from "./model-pricing.js";
-import { resolveEffectiveServiceTier, resolveServiceTierParams } from "./service-tier.js";
+import { resolveEffectiveServiceTier } from "../../shared/service-tier.js";
+import { resolveServiceTierParams } from "./service-tier.js";
 import { UsageAccumulator } from "./usage-accumulator.js";
 import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
 import { activityStarted, activityFinished } from "../../idle-watchdog.js";
@@ -101,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 }).
@@ -524,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
@@ -572,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
@@ -592,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
@@ -612,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"));
@@ -758,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,
@@ -882,20 +883,47 @@ turnSeq) {
         // is the largest user-visible setup segment; this split keeps its
         // historical meaning — the SDK call was already 98%+ of it).
         setupTiming.mark("prepare_agent");
-        let resolution = await resolveAgentWithTransportRecovery({
-            harnessStateId: threadId,
-            createOptions,
-            mode: agentMode,
-            timeoutMs: config.agentResolveTimeoutMs,
-            buildTimeoutMessage: (finalAttempt) => `Cursor agent ${threadId ? "resume" : "create"} timed out after ${resolveTimeoutSeconds}s ` +
-                `(${config.proxyEndpoint ? `via proxy ${config.proxyEndpoint}` : "direct Cursor API connection"}). ` +
-                `The transport connection is likely dead. ` +
-                (finalAttempt
-                    ? `An automatic retry on a fresh transport connection also timed out. ` +
-                        `Retry the message later; if this persists, check proxy and network health.`
-                    : `Resetting the transport and retrying automatically.`),
-            resetTransport: closeProxySessions,
-        });
+        // Phase 8a: Reuse the previous turn's agent when this session parked one
+        // (#215). A checkout hit skips Agent.resume() AND — the real win — keeps
+        // the SDK executor lease alive, so agent.send() below re-acquires the
+        // warm executor instead of re-spawning every stdio MCP server (the
+        // measured 2.2–3.2s `send_returned` tax). The fingerprint covers the
+        // full acquisition config, so any drift (rotated credential, edited MCP
+        // servers, model change) falls through to a fresh resolve.
+        const agentFingerprint = computeAgentFingerprint(createOptions);
+        const parkedAgent = takeCachedAgent(sessionId, agentFingerprint, threadId ?? "");
+        let resolution;
+        if (parkedAgent) {
+            console.log(`ExecuteCursor reusing parked session agent: execution=${executionId}, ` +
+                `session=${sessionId}, agentId=${parkedAgent.agentId}`);
+            resolution = {
+                agent: parkedAgent,
+                agentId: parkedAgent.agentId,
+                isNew: false,
+                resumed: true,
+                mode: agentMode,
+                // The parked handle IS the live conversation — every consumer of
+                // "resumed_successfully" (prompt selection, poisoned-handle
+                // recovery eligibility) wants exactly those semantics.
+                reason: "resumed_successfully",
+            };
+        }
+        else {
+            resolution = await resolveAgentWithTransportRecovery({
+                harnessStateId: threadId,
+                createOptions,
+                mode: agentMode,
+                timeoutMs: config.agentResolveTimeoutMs,
+                buildTimeoutMessage: (finalAttempt) => `Cursor agent ${threadId ? "resume" : "create"} timed out after ${resolveTimeoutSeconds}s ` +
+                    `(${config.proxyEndpoint ? `via proxy ${config.proxyEndpoint}` : "direct Cursor API connection"}). ` +
+                    `The transport connection is likely dead. ` +
+                    (finalAttempt
+                        ? `An automatic retry on a fresh transport connection also timed out. ` +
+                            `Retry the message later; if this persists, check proxy and network health.`
+                        : `Resetting the transport and retrying automatically.`),
+                resetTransport: closeProxySessions,
+            });
+        }
         console.log(`ExecuteCursor agent resolved: execution=${executionId}, ` +
             `reason=${resolution.reason}, mode=${resolution.mode}, ` +
             `agentId=${resolution.agentId}, resumed=${resolution.resumed}` +
@@ -960,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
@@ -1159,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
@@ -1234,18 +1271,21 @@ turnSeq) {
                     timestamp: utcTimestamp(),
                 }));
                 await persist(status);
-                try {
-                    resolution.agent.close();
-                }
-                catch { /* best effort */ }
+                // Clean terminal: the conversation continues on the next message,
+                // so park the healthy agent for that turn (#215).
+                cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
                 console.warn(`ExecuteCursor terminated (cost cap): execution=${executionId}, ` +
                     `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();
@@ -1296,10 +1336,8 @@ turnSeq) {
                     timestamp: utcTimestamp(),
                 }));
                 await persist(status);
-                try {
-                    resolution.agent.close();
-                }
-                catch { /* best effort */ }
+                // Clean terminal — park for the session's next turn (#215).
+                cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
                 console.log(`ExecuteCursor completed (platform stop): execution=${executionId}`);
                 return { kind: "return" };
             }
@@ -1343,6 +1381,12 @@ turnSeq) {
         const enterApprovalPause = async (boundary) => {
             status.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
             await persist(status);
+            // The approval-resume reinvocation is the cache's best case: park the
+            // agent so the resumed turn skips the full executor rebuild (#215).
+            // (This path previously dropped the handle without close() — the
+            // lease leaked; parking makes the lifetime explicit.) An absent
+            // sessionId falls back to "" — the cache closes the lease immediately.
+            cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
             console.log(`ExecuteCursor returning WAITING_FOR_APPROVAL: ${boundary.deniedToolCallCount} gated tool(s), ` +
                 `${boundary.capturedChangeCount} file card(s) pending`);
             return slimStatus(status);
@@ -1542,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,
@@ -1755,11 +1800,12 @@ turnSeq) {
         console.log(`ExecuteCursor completed: execution=${executionId}, phase=${ExecutionPhase[status.phase]}, ` +
             `hasStructuredOutput=${structuredOutput !== undefined}` +
             (status.error ? `, error=${status.error}` : ""));
-        // Release SDK executor lease to prevent cache buildup across workflow tasks
-        try {
-            resolution.agent.close();
-        }
-        catch { /* best effort */ }
+        // Park the agent (with its executor lease) for the session's next turn
+        // instead of closing it — the idle TTL / shutdown hooks in
+        // agent-session-cache own the eventual release, so cache buildup across
+        // sessions stays bounded while turns of ONE session stop paying the
+        // executor + MCP re-spawn tax (#215).
+        cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
         const slim = slimStatus(status);
         if (finalText !== undefined) {
             slim.final_text = finalText;
@@ -1772,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.";
@@ -2076,6 +2125,7 @@ export function buildPrompt(input) {
                 contextBridge: input.contextBridge,
                 senderIdentity: input.senderIdentity,
                 sessionContext: input.sessionContext,
+                declaredPreferences: input.declaredPreferences,
                 conversationCatchup,
             }, {
                 turnDigest: input.turnRecoveryDigest,
@@ -2134,6 +2184,7 @@ export function buildPrompt(input) {
         contextBridge: input.contextBridge,
         senderIdentity: input.senderIdentity,
         sessionContext: input.sessionContext,
+        declaredPreferences: input.declaredPreferences,
         conversationCatchup,
     });
 }