impel-cli 0.20.36 → 0.20.37

package/RELEASE_NOTES.md

@@ -1,5 +1,14 @@
 # Release notes
 
+## 0.20.37 — Resume ambiguous native answers
+
+- Retries Next's typed ambiguous direct-answer response with the exact persisted
+  idempotency key, resuming the existing Eve answer instead of duplicating it.
+- Keeps retries bounded and cancellation-safe while rejecting incomplete or
+  untyped retry claims as definitive failures.
+- Preserves strict continuation handles for answer-only adapters and full run
+  handles for recovery-only adapters across every nonterminal resume.
+
 ## 0.20.36 — Restore Codex execution
 
 - Keeps Codex 0.147's stable code-mode host enabled instead of overriding it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "impel-cli",
-  "version": "0.20.36",
+  "version": "0.20.37",
   "description": "Prepare isolated Claude and Codex workspaces for every accessible Impel tenant",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -696,7 +696,7 @@ function retiredAdapterInstructions(tenantId, agent) {
     `You are a recovery-only transport adapter for retired Impel native-agent binding ${JSON.stringify(agent.agentId)} in tenant ${JSON.stringify(tenantId)}.`,
     `Collaboration tools are unavailable for this adapter. Never call send_message, followup_task, interrupt_agent, spawn_agent, or wait_agent. Return one final response to the caller only after the native-agent transport reaches terminal.`,
     `You cannot start new work. Never call run_native_agent and never perform or recreate the assigned task yourself.`,
-    `Call ${nativeToolName(NATIVE_AGENT_RECOVER_TOOL)} with {} to obtain integrity-validated pending handles for this fixed binding, then call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with the intended handle until it returns a terminal result. If multiple handles cannot be safely associated with the request, report them instead of choosing.`,
+    `Call ${nativeToolName(NATIVE_AGENT_RECOVER_TOOL)} with {} to obtain integrity-validated ${JSON.stringify("impel.native-agent-run.v1")} pending handles for this fixed binding, then call ${nativeToolName(NATIVE_AGENT_RESUME_TOOL)} with the intended complete handle. Every nonterminal resume returns the same handle schema; pass that complete returned handle unchanged to the next resume until terminal. If multiple handles cannot be safely associated with the request, report them instead of choosing.`,
     `Return successful finalText byte-for-byte. For failure, return the preserved runId, output, and error without inventing a replacement result.`,
   ].join(" ");
 }

package/src/nativeAgentTransport.js

@@ -65,6 +65,7 @@ const CIBI_START_IN_PROGRESS_MESSAGE = "The durable Eve drain workflow is still
 const CTOS_START_TIMEOUT_MESSAGE = `MCP tool call failed for ${NATIVE_AGENT_START_TOOL}: The operation was aborted due to timeout: mcp tool call failed`;
 const MANAGED_VIRTUAL_KEY_MISS_MESSAGE = "virtual key not found. The provided virtual key does not exist or has been revoked.";
 const MANAGED_VIRTUAL_KEY_MISS_RETRY_DELAY_MS = 250;
+const NEXT_AMBIGUOUS_ANSWER_CODE = "native_agent_answer_ambiguous";
 const MCP_TOOL_RESULT_ERROR = Symbol("native-agent MCP tool result error");
 const TERMINAL_STATUSES = new Set(["succeeded", "failed", "cancelled", "canceled"]);
 
@@ -332,6 +333,7 @@ function readPrivateState(filePath, maxBytes) {
       "idempotencyKey",
       "startArguments",
       "upstreamRunId",
+      "answerRunId",
       "status",
       "startAttempts",
       "startMode",
@@ -365,6 +367,13 @@ function readPrivateState(filePath, maxBytes) {
       || (state.fence !== undefined && (!Number.isSafeInteger(state.fence) || state.fence < 0))
       || (state.sequence !== undefined && (!Number.isSafeInteger(state.sequence) || state.sequence < 0))
       || (state.version !== undefined && (!Number.isSafeInteger(state.version) || state.version < 0))
+      || (state.answerRunId !== undefined
+        && (state.startMode !== "answer"
+          || state.startAttempts < 1
+          || state.upstreamRunId !== null
+          || typeof state.answerRunId !== "string"
+          || !state.answerRunId.trim()
+          || state.answerRunId.length > 512))
       || (state.upstreamRunId !== null && (typeof state.upstreamRunId !== "string" || !state.upstreamRunId))) {
       throw new Error("invalid field");
     }
@@ -417,6 +426,22 @@ function continuationForState(state) {
   };
 }
 
+function attachmentHandleForState(state) {
+  return state.startMode === "answer"
+    ? continuationForState(state)
+    : handleForState(state);
+}
+
+function resumedHandleForState(state, incomingHandle) {
+  // The strict MCP surfaces use disjoint handle families: answer-only accepts
+  // continuation.v1, while recovery-only accepts run.v1. Preserve the
+  // validated incoming family across every nonterminal resume so either
+  // surface can continue the same persisted direct-answer state.
+  return incomingHandle.schema === NATIVE_AGENT_HANDLE_SCHEMA
+    ? handleForState(state)
+    : attachmentHandleForState(state);
+}
+
 function normalizeHandle(value) {
   if (value?.schema === NATIVE_AGENT_CONTINUATION_SCHEMA) {
     exactObject(value, ["schema", "invocationId"], "native-agent continuation");
@@ -642,6 +667,24 @@ function retryableManagedVirtualKeyMiss(error) {
     && error.message.includes(MANAGED_VIRTUAL_KEY_MISS_MESSAGE);
 }
 
+function retryableNativeAgentAnswerRunId(error) {
+  const data = error?.data;
+  if (!(error instanceof NativeAgentUpstreamError)
+    || error.code !== -32000
+    || !data
+    || typeof data !== "object"
+    || Array.isArray(data)
+    || data.code !== NEXT_AMBIGUOUS_ANSWER_CODE
+    || data.retryable !== true
+    || data.sameIdempotencyKeyRequired !== true
+    || typeof data.runId !== "string"
+    || !data.runId.trim()
+    || data.runId.length > 512) {
+    return null;
+  }
+  return data.runId;
+}
+
 export class NativeAgentUpstreamSession {
   constructor({
     gatewayUrl,
@@ -792,6 +835,14 @@ export class NativeAgentUpstreamSession {
               && error.message === CTOS_START_TIMEOUT_MESSAGE))) {
           error.ambiguous = true;
         }
+        if (name === NATIVE_AGENT_UPSTREAM_ANSWER_TOOL
+          && retryableNativeAgentAnswerRunId(error) !== null) {
+          // Next has confirmed that the direct-answer ledger remains live and
+          // that only an exact idempotent replay may resume it. Keep generic
+          // JSON-RPC errors definitive; this branch requires the complete
+          // typed resume contract.
+          error.ambiguous = true;
+        }
         throw error;
       }
     }
@@ -1826,7 +1877,7 @@ export class NativeAgentCompositeTransport {
       }, prepared.agent);
       state = await this.allocateState(startArguments, { startMode: "answer", signal: attachment.signal });
       lock = this.acquireLock(state.invocationId);
-      if (!lock) return handleForState(state);
+      if (!lock) return continuationForState(state);
       const result = await this.attach(state, prepared, {
         signal: attachment.signal,
         lock,
@@ -1936,13 +1987,18 @@ export class NativeAgentCompositeTransport {
       const prepared = state.upstreamRunId
         ? await this.prepareExistingSession(attachment.signal)
         : await this.preparePersistedStartSession(attachment.signal, state);
-      return await this.attach(state, prepared, {
+      const resumed = await this.attach(state, prepared, {
         signal: attachment.signal,
         onProgress,
         lock,
       });
+      return resumed?.schema === NATIVE_AGENT_RESULT_SCHEMA
+        ? resumed
+        : resumedHandleForState(state, handle);
     } catch (error) {
-      if (error?.name === "AbortError") return handle;
+      if (error?.name === "AbortError") {
+        return validated ? resumedHandleForState(state, handle) : handle;
+      }
       if (validated && !state?.upstreamRunId && error?.code === "LOCAL_POLICY_CHANGED_BEFORE_START") {
         this.compactTerminalFailure(
           state,
@@ -1959,7 +2015,7 @@ export class NativeAgentCompositeTransport {
         } catch {
           // Never write after losing ownership of the bounded lease.
         }
-        return handle;
+        return resumedHandleForState(state, handle);
       }
       throw error;
     } finally {
@@ -2078,6 +2134,7 @@ export class NativeAgentCompositeTransport {
     }
     const runId = boundedString(payload.runId, "native-agent runId", 512);
     const next = structuredClone(state);
+    delete next.answerRunId;
     next.upstreamRunId = runId;
     next.status = typeof payload.status === "string"
       && payload.status.length <= 160
@@ -2151,10 +2208,22 @@ export class NativeAgentCompositeTransport {
             break;
           } catch (error) {
             if (error?.name === "AbortError") throw error;
+            const answerRunId = state.startMode === "answer"
+              ? retryableNativeAgentAnswerRunId(error)
+              : null;
+            if (answerRunId !== null) {
+              if (state.answerRunId && state.answerRunId !== answerRunId) {
+                this.persistDiagnostic(state, new Error(
+                  "native-agent answer retry contract returned a different runId",
+                ), lock);
+                return attachmentHandleForState(state);
+              }
+              state.answerRunId = answerRunId;
+            }
             if (!error?.ambiguous) {
               if (startOutcomeUncertain) {
                 this.persistDiagnostic(state, error, lock);
-                return handleForState(state);
+                return attachmentHandleForState(state);
               }
               this.compactTerminalFailure(
                 state,
@@ -2169,7 +2238,15 @@ export class NativeAgentCompositeTransport {
             this.persistDiagnostic(state, error, lock);
           }
         }
-        if (!started) return handleForState(state);
+        if (!started) return attachmentHandleForState(state);
+        if (state.startMode === "answer"
+          && state.answerRunId
+          && started.runId !== state.answerRunId) {
+          this.persistDiagnostic(state, new Error(
+            "native-agent answer retry returned a different runId",
+          ), lock);
+          return attachmentHandleForState(state);
+        }
 
         // Persist the upstream identity before accepting any optional or large
         // response fields. From this point every attachment failure is safely
@@ -2184,7 +2261,7 @@ export class NativeAgentCompositeTransport {
       for (let poll = 0; poll < this.maxPolls; poll += 1) {
         throwIfAborted(signal);
         const remainingMs = deadline - this.now();
-        if (remainingMs <= 1_500) return handleForState(state);
+        if (remainingMs <= 1_500) return attachmentHandleForState(state);
         const boundedWait = Math.max(1, Math.min(waitSeconds, Math.floor((remainingMs - 1_000) / 1000)));
         const observed = await session.call(NATIVE_AGENT_READ_TOOL, {
           runId: state.upstreamRunId,
@@ -2197,7 +2274,7 @@ export class NativeAgentCompositeTransport {
         result = resultForState(state);
         if (result.schema === NATIVE_AGENT_RESULT_SCHEMA) return result;
       }
-      return state.startMode === "answer" ? continuationForState(state) : handleForState(state);
+      return attachmentHandleForState(state);
     } catch (error) {
       if (!state.upstreamRunId) throw error;
       try {
@@ -2206,7 +2283,7 @@ export class NativeAgentCompositeTransport {
         // A lost lease forbids stale writes. The already-persisted handle is
         // still the only safe return value.
       }
-      return handleForState(state);
+      return attachmentHandleForState(state);
     }
   }
 }