@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

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

@@ -27,7 +27,7 @@
  */
 import { InteractionMode, ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { Config } from "../../config.js";
-import type { AgentResolution } from "./session-lifecycle.js";
+import type { AgentResolution, AgentResolutionReason } from "./session-lifecycle.js";
 import { type ExecuteActivityInput } from "../../shared/activity-input.js";
 /**
  * Creates the activity functions bound to the runner config.
@@ -52,7 +52,11 @@ export interface BuildPromptInput {
     subAgents: import("@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb").SubAgent[];
     workspaceDirs: string[];
     workspaceFileRefs: string[];
-    attachmentPaths: string[];
+    /**
+     * This turn's resolved attachments for the `<input_files>` section —
+     * final paths plus duplicate-rename disclosure (attachment-resolver.ts).
+     */
+    attachments: import("./prompt-builder.js").AttachmentPromptEntry[];
     /**
      * Vision facts for the input-files section (T04): which attachments the
      * model sees inline and which degraded to path-only. PER-TURN like the
@@ -103,6 +107,15 @@ export interface BuildPromptInput {
      * usually blank.
      */
     conversationCatchup?: string;
+    /**
+     * The turn's recorded transcript rendered as digest lines
+     * (turn-recovery.ts), composed from `status.messages` at the call site.
+     * Consumed ONLY by the HITL-recovery shape — a fresh agent that replaced
+     * a lost one mid-HITL needs the story of the work it no longer remembers
+     * (issue #366); every other shape either has native context or no prior
+     * work to tell.
+     */
+    turnRecoveryDigest?: string;
 }
 /**
  * Select and build the appropriate prompt based on resolution reason and
@@ -113,20 +126,47 @@ export interface BuildPromptInput {
  * volume, or cloud server-side state) — there is no separate continuation
  * store. The prompt therefore depends only on how the agent was resolved:
  *
- * 1. HITL reinvocation        -> buildReinvocationPrompt (approval decisions;
- *                                 the resumed agent's native context carries
- *                                 the prior conversation)
- * 2. resumed_successfully      -> raw userMessage (native context carries it)
- * 3. first execution / fresh   -> buildEnhancedPrompt (full instructions +
+ * 1. HITL reinvocation,        -> buildReinvocationPrompt (approval decisions
+ *    resumed agent                 only; the resumed agent's native context
+ *                                  carries the prior conversation)
+ * 2. HITL reinvocation,        -> buildHitlRecoveryPrompt (full context +
+ *    fresh agent after            the turn's recorded transcript + decisions;
+ *    resume failure               the replacement agent's conversation is
+ *                                 empty, and both fresh-agent crossings —
+ *                                 resolution-time resume failure and mid-send
+ *                                 poisoned-handle recovery — land here by
+ *                                 keying on the reason, issue #366)
+ * 3. resumed_successfully      -> raw userMessage (native context carries it)
+ * 4. first execution / fresh   -> buildEnhancedPrompt (full instructions +
  *    agent after resume failure   skills; no prior conversation to inherit)
  */
 /**
  * Whether this activity invocation is a HITL re-invocation — the turn resumes
  * an agent purely to convey approval decisions, carrying NO user message.
- * The single discriminator for everything that must ride with the user's
- * message and nothing else: the reinvocation prompt shape (below) and the
- * vision payload (images accompany the message; a resumed agent already holds
- * them in its native conversation).
+ * Discriminates the two surfaces that depend on the agent already holding
+ * this turn's content natively — the prompt shape (below) and the primary
+ * send's vision payload — but never alone: both pair it with
+ * `resolution.reason`, because a FRESH agent mid-HITL holds nothing and
+ * needs the full re-delivery (issue #366).
  */
 export declare function isHitlReinvocation(approvalDecisions: Map<string, ApprovalAction> | undefined): approvalDecisions is Map<string, ApprovalAction>;
+/**
+ * Whether the PRIMARY send delivers the turn's vision payload. The invariant
+ * is "images accompany the user's turn message, wherever the conversation
+ * does not already hold them" — so the only send that skips them is a HITL
+ * re-invocation of a successfully RESUMED agent, whose native conversation
+ * carries the images from the original send. A fresh agent mid-HITL
+ * (resolution-time resume failure — issue #366's vision corollary) holds
+ * nothing and needs the re-delivery. The mid-send recovery retries always
+ * run on a fresh agent, so their send sites carry the payload
+ * unconditionally rather than consulting this.
+ */
+export declare function primarySendCarriesImages(approvalDecisions: Map<string, ApprovalAction> | undefined, reason: AgentResolutionReason): boolean;
+/**
+ * Append the structured-output contract to a prompt when the execution
+ * requests one. A per-turn directive (the buildFromPlan rule): it must ride
+ * every prompt this turn sends — the primary send AND the poisoned-handle
+ * recovery rebuild, which previously lost it (issue #366 ride-along).
+ */
+export declare function appendStructuredOutputDirective(basePrompt: string, schema: Record<string, unknown> | undefined): string;
 export declare function buildPrompt(input: BuildPromptInput): string;

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

@@ -62,6 +62,7 @@ import { readChannelConversationId, synthesizeConversationAttachment, } from "..
 import { injectSynthesizedAttachment } from "../../shared/synthesized-attachment.js";
 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 { resolveExecutionEnv } from "./env-resolver.js";
 import { resolveBlueprint } from "./blueprint-resolver.js";
@@ -69,7 +70,8 @@ import { buildCursorSubAgentDefinitions } from "./subagent-config.js";
 import { resolveSkills } from "./skill-resolver.js";
 import { removeStigmerSymlink } from "../../shared/workspace/stigmer-link.js";
 import { resolveAttachments } from "./attachment-resolver.js";
-import { buildEnhancedPrompt, buildReinvocationPrompt, formatConversationCatchupSection, formatInputFiles, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
+import { buildEnhancedPrompt, buildHitlRecoveryPrompt, buildReinvocationPrompt, formatConversationCatchupSection, formatInputFiles, formatInteractionModePrefix, formatImplementPlanSection } from "./prompt-builder.js";
+import { composeTurnRecoveryDigest } from "./turn-recovery.js";
 import { installHitlGate, removeHitlGate } from "./workspace-setup.js";
 import { ensureHitlDir } from "../../shared/workspace/platform-dir.js";
 import { acquireWorkspaceLock, WorkspaceLockCancelledError, WorkspaceLockTimeoutError, } from "../../shared/workspace/workspace-lock.js";
@@ -96,7 +98,7 @@ import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/
 import { activityStarted, activityFinished } from "../../idle-watchdog.js";
 import { normalizeActivityInput } from "../../shared/activity-input.js";
 import { getCapturedRejection, clearCapturedRejection } from "./rejection-capture.js";
-import { synthesizeError, formatClassifiedError, shouldRetryWithFreshAgent } from "./error-classifier.js";
+import { synthesizeError, formatClassifiedError, shouldRetryWithFreshAgent, extractRunErrorSources } from "./error-classifier.js";
 import { createAgent, createCloudAgent } from "./session-lifecycle.js";
 import { setMaxListeners } from "node:events";
 import { startHeartbeat } from "../../shared/heartbeat.js";
@@ -536,8 +538,20 @@ turnSeq) {
         // the messaging reach; undefined lets a cloud sandbox runner's
         // ambient session-scoped token or OSS's no-auth apply). The
         // attachment header falls back to the ambient credential where no
-        // exchange happens.
-        const exchangedRunnerToken = await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+        // exchange happens. Unlike the env read (which hard-fails on a broken
+        // exchange — secrets are load-bearing there), this exchange is
+        // opportunistic: every consumer below degrades to an empty answer by
+        // contract, and the server refuses the ambient fallback safely, so a
+        // failed exchange must not kill the run.
+        let exchangedRunnerToken;
+        try {
+            exchangedRunnerToken =
+                await client.acquireScopedRunnerToken({ agentExecutionId: executionId });
+        }
+        catch (err) {
+            console.warn("[execute-cursor] Scoped-token exchange failed for attachment/discovery " +
+                `reads; degrading to the ambient credential: ${err instanceof Error ? err.message : err}`);
+        }
         const attachmentCredential = exchangedRunnerToken
             ?? config.stigmerTokenRef?.current
             ?? config.stigmerToken;
@@ -612,9 +626,10 @@ turnSeq) {
         // them as auto-approved); the global bypass empties the map entirely.
         const leases = deriveActiveLeases(execution);
         const globalBypass = leases.global;
-        const agentOverrides = blueprint.mergedMcpServerUsages
-            .flatMap((u) => u.toolApprovalOverrides ?? []);
-        const mergedPolicies = mergeApprovalPolicies(mcpResolution.resolvedServers, agentOverrides, leases);
+        // 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);
         heartbeat();
         // Phase 4c: Validate MCP server env health (diagnostic, non-blocking)
         const mcpWarnings = validateMcpServerEnv(mcpResolution.resolvedServers, blueprint.mergedMcpServerUsages, envVars);
@@ -650,7 +665,10 @@ turnSeq) {
             storage: artifactStorage,
             visionBudget,
         });
-        const attachmentPaths = attachmentResults.map((a) => a.relativePath);
+        const attachmentEntries = attachmentResults.map((a) => ({
+            path: a.relativePath,
+            ...(a.renamedFrom !== undefined ? { renamedFrom: a.renamedFrom } : {}),
+        }));
         // Vision facts, derived once from the single resolution result: the
         // images the model will see inline (in attachment order) and the ones
         // that degraded to path-only, disclosed in the prompt.
@@ -751,7 +769,12 @@ turnSeq) {
         // approval denials with the non-pausing "unattended" kind, so the
         // first-denial stop never fires and the turn boundary settles the denied
         // calls as SKIPPED instead of pausing a turn nobody can approve.
-        const approvalState = buildApprovalState(mergedPolicies, globalBypass, leases.categories, approvalGrants, captureMode, captureIgnored, gitWorkspace, isUnattendedApprovalMode(execution));
+        const approvalState = buildApprovalState(mergedPolicies, globalBypass, leases.categories, approvalGrants, captureMode, captureIgnored, gitWorkspace, isUnattendedApprovalMode(execution), 
+        // The enabled_tools capability manifest (issue #350): restricted
+        // 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));
         const hitlGate = await installHitlGate({
             workspaceRoot: primaryWorkspaceDir,
             hitlDir,
@@ -944,7 +967,7 @@ turnSeq) {
             subAgents: blueprint.subAgents,
             workspaceDirs: blueprint.workspaceDirs,
             workspaceFileRefs: spec.workspaceFileRefs ?? [],
-            attachmentPaths,
+            attachments: attachmentEntries,
             vision: visionPromptInfo,
             pendingApprovals: adjudicatedApprovals,
             appliedToolCallIds,
@@ -954,25 +977,36 @@ turnSeq) {
             senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
             sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
             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
+            // shape — reached from HERE when the stored handle failed to resume
+            // at resolution time (issue #366 crossing 2).
+            turnRecoveryDigest: isReinvocation
+                ? composeTurnRecoveryDigest(status.messages)
+                : undefined,
         });
-        // Phase 10a: Inject structured output instruction for Cursor harness
-        let effectivePrompt = prompt;
-        if (structuredOutputSchema) {
-            const schemaStr = JSON.stringify(structuredOutputSchema, null, 2);
-            effectivePrompt += `\n\n---\nCRITICAL OUTPUT REQUIREMENT:\nYour final response MUST be a single valid JSON object (no markdown, no commentary, no code fences) that matches this schema:\n${schemaStr}\n\nRespond with ONLY the JSON object. Nothing else.`;
-        }
+        // Phase 10a: Inject the structured output instruction for the Cursor
+        // harness. A per-turn directive, so like buildFromPlan it must ride every
+        // prompt this turn sends — the primary AND the poisoned-handle recovery
+        // rebuild (the transport retry re-sends effectivePrompt and inherits it).
+        const withStructuredOutputDirective = (basePrompt) => appendStructuredOutputDirective(basePrompt, structuredOutputSchema);
+        const effectivePrompt = withStructuredOutputDirective(prompt);
         // Phase 10a1: The turn's vision payload. The invariant is "images
-        // accompany the user's turn message — where the message goes, they go":
-        // every send that delivers this turn's message carries them (the primary
-        // send and both fresh-agent recovery retries, whose empty conversations
-        // genuinely need the re-send), while a HITL re-invocation — whose prompt
-        // carries no user message and whose resumed agent already holds the
-        // images in its native conversation — carries none. Computed ONCE here so
-        // all send sites agree by construction.
-        const turnImages = isHitlReinvocation(approvalDecisions)
-            ? []
-            : toCursorImages(visionImages);
-        const toSendMessage = (sendPrompt) => turnImages.length > 0 ? { text: sendPrompt, images: turnImages } : sendPrompt;
+        // accompany the user's turn message, wherever the conversation does not
+        // already hold them" (primarySendCarriesImages): the ONLY send that
+        // skips them is a HITL re-invocation of a successfully RESUMED agent,
+        // whose native conversation carries the images from the original send.
+        // Every send that starts an empty conversation re-delivers them — the
+        // ordinary first/fresh-agent primary send, the HITL primary send after a
+        // resolution-time resume failure, and both mid-send recovery retries
+        // (which always run on a fresh agent, so their sites pass turnImages
+        // unconditionally). Attachments re-resolve on every invocation
+        // (Phase 5b), so the bytes are in hand even on a re-invocation.
+        const turnImages = toCursorImages(visionImages);
+        const primarySendImages = primarySendCarriesImages(approvalDecisions, resolution.reason)
+            ? turnImages
+            : [];
+        const toSendMessage = (sendPrompt, images) => images.length > 0 ? { text: sendPrompt, images } : sendPrompt;
         // Phase 10a2: Log Stigmer preamble size for context trimming diagnostics
         const promptChars = effectivePrompt.length;
         const promptEstimatedTokens = Math.ceil(promptChars / 4);
@@ -1073,7 +1107,7 @@ turnSeq) {
         // The stall watchdog is armed inside consumeCursorTurnStream (it needs the
         // run to cancel), stored on turnState.stallWatchdog so this shared onDelta can
         // reset it and the activity's finally can stop it as a backstop.
-        const run = await resolution.agent.send(toSendMessage(effectivePrompt), {
+        const run = await resolution.agent.send(toSendMessage(effectivePrompt, primarySendImages), {
             onDelta: (event) => {
                 if (!turnFirstEventEmitted) {
                     turnFirstEventEmitted = true;
@@ -1390,10 +1424,11 @@ turnSeq) {
             // poisoned-handle path leaked the fresh agent — it closed the stale one.)
             resolution = { ...resolution, agent: freshAgent, agentId: freshAgent.agentId, isNew: true };
             turnState.streamErrorMessage = undefined;
-            // The retry carries the turn's images too (same toSendMessage): the
-            // fresh agent's conversation is empty, so skipping them here would
-            // silently lose the user's photo on a recovered turn.
-            const retryRun = await freshAgent.send(toSendMessage(retryPrompt), {
+            // The retry always carries the turn's full image payload — never the
+            // primary send's HITL-trimmed set: the fresh agent's conversation is
+            // empty, so skipping them here would silently lose the user's photo on
+            // a recovered turn (issue #366's vision corollary).
+            const retryRun = await freshAgent.send(toSendMessage(retryPrompt, turnImages), {
                 onDelta: makeCursorTurnOnDelta(onDeltaDeps),
             });
             await consumeCursorTurnStream(retryRun, streamDeps);
@@ -1450,12 +1485,10 @@ turnSeq) {
                 status.phase = ExecutionPhase.EXECUTION_COMPLETED;
                 break;
             case "error": {
-                const resultAny = result;
-                const sdkError = result.result
-                    ?? resultAny.error
-                    ?? resultAny.message
-                    ?? resultAny.reason;
-                const sdkErrorStr = sdkError ? String(sdkError) : undefined;
+                // Shape-aware extraction, NOT String(): the result's error fields are
+                // structured at runtime often enough that a bare coercion showed users
+                // "[object Object]" and shadowed every fallback source below (oss#299).
+                const runErrorSources = extractRunErrorSources(result);
                 // The SDK frequently resolves run.wait() to a bare { status: "error" }
                 // while the real reason (e.g. the original grpc-status 12 routing
                 // failure) lives on the failing conversation turn. Capture it here so
@@ -1465,7 +1498,8 @@ turnSeq) {
                 if (capturedRejection)
                     clearCapturedRejection(executionId);
                 const classified = synthesizeError({
-                    sdkResultFields: sdkErrorStr,
+                    sdkError: runErrorSources.sdkError,
+                    sdkResultFields: runErrorSources.sdkResultFields,
                     streamErrorMessage: turnState.streamErrorMessage,
                     capturedRejection,
                     conversationErrorText,
@@ -1508,9 +1542,13 @@ turnSeq) {
                         subAgents: blueprint.subAgents,
                         workspaceDirs: blueprint.workspaceDirs,
                         workspaceFileRefs: spec.workspaceFileRefs ?? [],
-                        attachmentPaths,
+                        attachments: attachmentEntries,
                         vision: visionPromptInfo,
                         pendingApprovals: adjudicatedApprovals,
+                        // Without the applied set, the HITL-recovery prompt would tell
+                        // the fresh agent to carry out writes the runner already
+                        // exact-applied (the primary call at Phase 10 passes it too).
+                        appliedToolCallIds,
                         interactionMode,
                         // buildFromPlan was silently dropped here until T03 Sitting 3 —
                         // a build turn that hit handle recovery lost its directive. The
@@ -1521,6 +1559,10 @@ turnSeq) {
                         senderIdentity: readSenderIdentity(blueprint.sessionSpec.metadata),
                         sessionContext: readSessionContext(blueprint.sessionSpec.metadata),
                         conversationCatchup: readConversationCatchup(spec.conversationCatchup),
+                        // Composed fresh (not reused from Phase 10): the failed primary
+                        // stream may have appended partial work onto status.messages,
+                        // and the replacement agent should know about that too.
+                        turnRecoveryDigest: composeTurnRecoveryDigest(status.messages),
                     });
                     console.log(`ExecuteCursor retry with fresh agent: execution=${executionId}, ` +
                         `newAgentId=${freshAgent.agentId}`);
@@ -1533,7 +1575,11 @@ turnSeq) {
                     catch (updateErr) {
                         console.warn("Failed to update session with fresh agentId (non-fatal):", updateErr);
                     }
-                    const outcome = await runRecoveryStream(freshAgent, freshPrompt);
+                    // Same per-turn directive rule as buildFromPlan above: a
+                    // structured-output turn keeps its output contract on the rebuilt
+                    // prompt (the transport retry re-sends effectivePrompt and
+                    // inherits it without help).
+                    const outcome = await runRecoveryStream(freshAgent, withStructuredOutputDirective(freshPrompt));
                     if (!outcome.proceeded) {
                         if (outcome.terminal.kind === "return")
                             return slimStatus(status);
@@ -1564,8 +1610,14 @@ turnSeq) {
                     if (retryRejection)
                         clearCapturedRejection(executionId);
                     const retryConversationErrorText = await introspectConversation(retryRun, executionId);
+                    // Same shape-aware extraction as the primary error arm — the retry
+                    // previously String()-coerced result.result alone, so a structured
+                    // retry failure both read "[object Object]" and ignored the
+                    // error/message/reason fields the primary arm consults.
+                    const retryErrorSources = extractRunErrorSources(retryResult);
                     const retryClassified = synthesizeError({
-                        sdkResultFields: retryResult.result ? String(retryResult.result) : undefined,
+                        sdkError: retryErrorSources.sdkError,
+                        sdkResultFields: retryErrorSources.sdkResultFields,
                         streamErrorMessage: turnState.streamErrorMessage,
                         capturedRejection: retryRejection,
                         conversationErrorText: retryConversationErrorText,
@@ -1661,6 +1713,7 @@ turnSeq) {
                     console.log(`ExecuteCursor text extraction failed, trying LLM extraction: execution=${executionId}, ` +
                         `finalTextLength=${finalText.length}`);
                     try {
+                        const { extractStructuredOutput } = await import("./extract-structured-output.js");
                         structuredOutput = await extractStructuredOutput(finalText, structuredOutputSchema, config, requestedModel);
                         if (structuredOutput !== undefined) {
                             console.log(`ExecuteCursor structured output extracted (LLM): execution=${executionId}`);
@@ -1949,40 +2002,6 @@ function seedCursorTranscriptFromExecution(status, execution) {
     }
     return persisted.subAgentExecutions.map((sub) => clone(SubAgentExecutionSchema, sub));
 }
-// ---------------------------------------------------------------------------
-// Structured Output Extraction (Cursor Harness Tier 2)
-// ---------------------------------------------------------------------------
-/**
- * Extract structured data from an agent's free-text response using an
- * economy-tier LLM with withStructuredOutput (function-calling).
- * Guarantees schema-conformant JSON output via the API's tool-use mechanism.
- *
- * 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.
- */
-async function extractStructuredOutput(agentResponse, schema, config, primaryModel) {
-    const { getEconomyModel } = await import("../../shared/model-registry.js");
-    const { buildChatModel } = await import("../../shared/model-client.js");
-    const extractionModel = await getEconomyModel(primaryModel);
-    const proxyEndpoint = config.proxyEndpoint ?? config.stigmerBackendEndpoint;
-    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;
-}
-// Re-export for use within this module; shared implementation eliminates
-// the three duplicate converters that previously drifted independently.
-import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
 /**
  * Select and build the appropriate prompt based on resolution reason and
  * HITL state.
@@ -1992,30 +2011,95 @@ import { jsonSchemaToZod } from "../../shared/json-schema-to-zod.js";
  * volume, or cloud server-side state) — there is no separate continuation
  * store. The prompt therefore depends only on how the agent was resolved:
  *
- * 1. HITL reinvocation        -> buildReinvocationPrompt (approval decisions;
- *                                 the resumed agent's native context carries
- *                                 the prior conversation)
- * 2. resumed_successfully      -> raw userMessage (native context carries it)
- * 3. first execution / fresh   -> buildEnhancedPrompt (full instructions +
+ * 1. HITL reinvocation,        -> buildReinvocationPrompt (approval decisions
+ *    resumed agent                 only; the resumed agent's native context
+ *                                  carries the prior conversation)
+ * 2. HITL reinvocation,        -> buildHitlRecoveryPrompt (full context +
+ *    fresh agent after            the turn's recorded transcript + decisions;
+ *    resume failure               the replacement agent's conversation is
+ *                                 empty, and both fresh-agent crossings —
+ *                                 resolution-time resume failure and mid-send
+ *                                 poisoned-handle recovery — land here by
+ *                                 keying on the reason, issue #366)
+ * 3. resumed_successfully      -> raw userMessage (native context carries it)
+ * 4. first execution / fresh   -> buildEnhancedPrompt (full instructions +
  *    agent after resume failure   skills; no prior conversation to inherit)
  */
 /**
  * Whether this activity invocation is a HITL re-invocation — the turn resumes
  * an agent purely to convey approval decisions, carrying NO user message.
- * The single discriminator for everything that must ride with the user's
- * message and nothing else: the reinvocation prompt shape (below) and the
- * vision payload (images accompany the message; a resumed agent already holds
- * them in its native conversation).
+ * Discriminates the two surfaces that depend on the agent already holding
+ * this turn's content natively — the prompt shape (below) and the primary
+ * send's vision payload — but never alone: both pair it with
+ * `resolution.reason`, because a FRESH agent mid-HITL holds nothing and
+ * needs the full re-delivery (issue #366).
  */
 export function isHitlReinvocation(approvalDecisions) {
     return approvalDecisions !== undefined && approvalDecisions.size > 0;
 }
+/**
+ * Whether the PRIMARY send delivers the turn's vision payload. The invariant
+ * is "images accompany the user's turn message, wherever the conversation
+ * does not already hold them" — so the only send that skips them is a HITL
+ * re-invocation of a successfully RESUMED agent, whose native conversation
+ * carries the images from the original send. A fresh agent mid-HITL
+ * (resolution-time resume failure — issue #366's vision corollary) holds
+ * nothing and needs the re-delivery. The mid-send recovery retries always
+ * run on a fresh agent, so their send sites carry the payload
+ * unconditionally rather than consulting this.
+ */
+export function primarySendCarriesImages(approvalDecisions, reason) {
+    return !(isHitlReinvocation(approvalDecisions) && reason === "resumed_successfully");
+}
+/**
+ * Append the structured-output contract to a prompt when the execution
+ * requests one. A per-turn directive (the buildFromPlan rule): it must ride
+ * every prompt this turn sends — the primary send AND the poisoned-handle
+ * recovery rebuild, which previously lost it (issue #366 ride-along).
+ */
+export function appendStructuredOutputDirective(basePrompt, schema) {
+    if (!schema)
+        return basePrompt;
+    const schemaStr = JSON.stringify(schema, null, 2);
+    return basePrompt + `\n\n---\nCRITICAL OUTPUT REQUIREMENT:\nYour final response MUST be a single valid JSON object (no markdown, no commentary, no code fences) that matches this schema:\n${schemaStr}\n\nRespond with ONLY the JSON object. Nothing else.`;
+}
 export function buildPrompt(input) {
-    const { resolution, approvalDecisions, instructions, userMessage, skills, subAgents, workspaceDirs, workspaceFileRefs, attachmentPaths, interactionMode, buildFromPlan, conversationCatchup, } = input;
-    // HITL reinvocation: the agent is resumed, so its native context carries the
-    // prior conversation; the reinvocation prompt conveys the approval decisions
-    // (and which approved writes the runner already exact-applied).
+    const { resolution, approvalDecisions, instructions, userMessage, skills, subAgents, workspaceDirs, workspaceFileRefs, attachments, interactionMode, buildFromPlan, conversationCatchup, } = input;
+    // HITL reinvocation: the decisions-only prompt is correct ONLY while the
+    // agent's native context still carries the prior conversation — which only
+    // resumed_successfully guarantees. Any other reason means a fresh agent
+    // mid-HITL (in practice created_after_resume_failure: the stored handle
+    // failed to resume, or a poisoned handle was replaced mid-send), which
+    // gets the full recovery shape instead — enhanced context + the turn's
+    // recorded transcript + the same decisions — because the bare decisions on
+    // an empty conversation strand the agent with instructions and no story,
+    // and the session inherits that amnesia permanently (issue #366).
     if (isHitlReinvocation(approvalDecisions)) {
+        if (resolution.reason !== "resumed_successfully") {
+            return buildHitlRecoveryPrompt({
+                instructions,
+                userMessage,
+                skills,
+                datastoreUsages: input.datastoreUsages ?? [],
+                channelMessaging: input.channelMessaging ?? [],
+                subAgents,
+                workspaceDirs,
+                workspaceFileRefs,
+                attachments,
+                vision: input.vision,
+                interactionMode,
+                buildFromPlan,
+                contextBridge: input.contextBridge,
+                senderIdentity: input.senderIdentity,
+                sessionContext: input.sessionContext,
+                conversationCatchup,
+            }, {
+                turnDigest: input.turnRecoveryDigest,
+                pendingApprovals: input.pendingApprovals,
+                approvalDecisions,
+                appliedToolCallIds: input.appliedToolCallIds,
+            });
+        }
         return buildReinvocationPrompt(input.pendingApprovals, approvalDecisions, input.appliedToolCallIds);
     }
     // A successfully resumed agent carries its own conversation context via the
@@ -2035,9 +2119,9 @@ export function buildPrompt(input) {
     if (resolution.reason === "resumed_successfully") {
         const prefixes = [
             formatInteractionModePrefix(interactionMode),
-            formatImplementPlanSection(buildFromPlan, attachmentPaths),
-            attachmentPaths.length > 0
-                ? formatInputFiles(attachmentPaths, input.vision)
+            formatImplementPlanSection(buildFromPlan, attachments),
+            attachments.length > 0
+                ? formatInputFiles(attachments, input.vision)
                 : undefined,
             conversationCatchup !== undefined
                 ? formatConversationCatchupSection(conversationCatchup)
@@ -2059,7 +2143,7 @@ export function buildPrompt(input) {
         subAgents,
         workspaceDirs,
         workspaceFileRefs,
-        attachmentPaths,
+        attachments,
         vision: input.vision,
         interactionMode,
         buildFromPlan,