impel-cli 0.20.12 → 0.20.14

package/RELEASE_NOTES.md

@@ -1,5 +1,23 @@
 # Release notes
 
+## 0.20.14 — Opaque direct-answer continuations
+
+- Returns a minimal local continuation locator for read-only direct answers,
+  so wrapper models no longer need to copy policy or request fingerprints.
+- Resolves the locator against integrity-validated tenant-local state and the
+  MCP server's fixed agent binding; durable and write-capable handles retain
+  their full fail-closed validation.
+- Adds a regression test for the production case where Claude shortened a
+  request fingerprint while preserving the invocation id.
+
+## 0.20.13 — Allocation publication race
+
+- Retries allocation when a competing process moves the published lock between
+  the expected create collision and inspection.
+- Prevents a harmless `ENOENT` publication race from escaping as an MCP error
+  or consuming an agent inference turn.
+- Adds a deterministic regression test for the exact production interleaving.
+
 ## 0.20.12 — Internal admission retry
 
 - Absorbs brief local run-allocation lock contention inside the transport

package/package.json

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

package/src/nativeAgentTransport.js

@@ -31,6 +31,7 @@ export {
   NATIVE_AGENT_RUN_TOOL,
 };
 export const NATIVE_AGENT_HANDLE_SCHEMA = "impel.native-agent-run.v1";
+export const NATIVE_AGENT_CONTINUATION_SCHEMA = "impel.native-agent-continuation.v1";
 export const NATIVE_AGENT_RESULT_SCHEMA = "impel.native-agent-result.v1";
 export const NATIVE_AGENT_RECOVERY_SCHEMA = "impel.native-agent-recovery.v1";
 
@@ -390,7 +391,21 @@ function handleForState(state) {
   };
 }
 
+function continuationForState(state) {
+  return {
+    schema: NATIVE_AGENT_CONTINUATION_SCHEMA,
+    invocationId: state.invocationId,
+  };
+}
+
 function normalizeHandle(value) {
+  if (value?.schema === NATIVE_AGENT_CONTINUATION_SCHEMA) {
+    exactObject(value, ["schema", "invocationId"], "native-agent continuation");
+    if (typeof value.invocationId !== "string" || !SAFE_INVOCATION_RE.test(value.invocationId)) {
+      throw new Error("native-agent continuation invocationId is invalid");
+    }
+    return { ...value };
+  }
   exactObject(value, [
     "schema",
     "tenantId",
@@ -1388,7 +1403,13 @@ export class NativeAgentCompositeTransport {
           throw error;
         }
         fs.rmSync(generationPath, { recursive: true, force: true });
-        const stat = fs.lstatSync(lockPath);
+        let stat;
+        try {
+          stat = fs.lstatSync(lockPath);
+        } catch (statError) {
+          if (statError?.code === "ENOENT") continue;
+          throw statError;
+        }
         if (stat.isSymbolicLink()) throw new Error("refusing to use symlinked native-agent run lock");
         let current = null;
         let legacy = null;
@@ -1558,6 +1579,18 @@ export class NativeAgentCompositeTransport {
   }
 
   validateBoundState(state, handle) {
+    if (handle.schema === NATIVE_AGENT_CONTINUATION_SCHEMA) {
+      if (state.startMode !== "answer") {
+        throw new Error("native-agent continuation does not identify a direct-answer run");
+      }
+      if (state.tenantId !== this.tenantId
+        || state.agentId !== this.agentId
+        || state.scopeParam !== this.scopeParam
+        || state.policyFingerprint !== this.policyFingerprint) {
+        throw new Error("native-agent continuation does not match this fixed binding");
+      }
+      return;
+    }
     const expected = {
       tenantId: this.tenantId,
       agentId: this.agentId,
@@ -1774,7 +1807,9 @@ export class NativeAgentCompositeTransport {
           runId: state.upstreamRunId,
         };
       }
-      return result;
+      return result?.schema === NATIVE_AGENT_HANDLE_SCHEMA
+        ? continuationForState(state)
+        : result;
     } catch (error) {
       if (!state) throw error;
       if (lock) {
@@ -1784,7 +1819,7 @@ export class NativeAgentCompositeTransport {
           // The persisted handle remains authoritative after a lost lease.
         }
       }
-      return handleForState(state);
+      return continuationForState(state);
     } finally {
       lock?.release();
       attachment.dispose();
@@ -1805,11 +1840,14 @@ export class NativeAgentCompositeTransport {
       // upstream byte is sent.
       lock = this.acquireLock(state.invocationId);
       if (!lock) return handleForState(state);
-      return await this.attach(state, prepared, {
+      const result = await this.attach(state, prepared, {
         signal: attachment.signal,
         onProgress,
         lock,
       });
+      return state.startMode === "answer" && result?.schema === NATIVE_AGENT_HANDLE_SCHEMA
+        ? continuationForState(state)
+        : result;
     } catch (error) {
       // Once state exists, cancellation or the local attachment deadline must
       // hand the caller the only handle that can resume it.
@@ -1828,7 +1866,7 @@ export class NativeAgentCompositeTransport {
     exactObject(args, ["handle"], "resume_native_agent_run arguments");
     if (!Object.hasOwn(args, "handle")) throw new Error("resume_native_agent_run requires a handle");
     const handle = normalizeHandle(args.handle);
-    if (handle.tenantId !== this.tenantId) {
+    if (handle.schema === NATIVE_AGENT_HANDLE_SCHEMA && handle.tenantId !== this.tenantId) {
       throw new Error("native-agent run handle does not match this fixed tenant");
     }
     this.ensureRoots();
@@ -2124,7 +2162,7 @@ export class NativeAgentCompositeTransport {
         result = resultForState(state);
         if (result.schema === NATIVE_AGENT_RESULT_SCHEMA) return result;
       }
-      return handleForState(state);
+      return state.startMode === "answer" ? continuationForState(state) : handleForState(state);
     } catch (error) {
       if (!state.upstreamRunId) throw error;
       try {
@@ -2161,6 +2199,19 @@ const HANDLE_SCHEMA = {
   },
 };
 
+const ANSWER_RESUME_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["schema", "invocationId"],
+  properties: {
+    ...HANDLE_SCHEMA.properties,
+    schema: {
+      type: "string",
+      enum: [NATIVE_AGENT_CONTINUATION_SCHEMA, NATIVE_AGENT_HANDLE_SCHEMA],
+    },
+  },
+};
+
 export function nativeAgentCompositeTools({ mode = "durable" } = {}) {
   if (!["durable", "recovery", "answer"].includes(mode)) throw new Error("invalid native-agent MCP mode");
   const answerTool = {
@@ -2227,7 +2278,14 @@ export function nativeAgentCompositeTools({ mode = "durable" } = {}) {
     // continuation handle. Once that handle exists, resume is the only valid
     // next action; exposing recovery here gives the wrapper model an
     // unnecessary branch and can add a fifth inference round to healthy runs.
-    return [answerTool, tools.find(({ name }) => name === NATIVE_AGENT_RESUME_TOOL)];
+    const resumeTool = tools.find(({ name }) => name === NATIVE_AGENT_RESUME_TOOL);
+    return [answerTool, {
+      ...resumeTool,
+      inputSchema: {
+        ...resumeTool.inputSchema,
+        properties: { handle: ANSWER_RESUME_SCHEMA },
+      },
+    }];
   }
   return mode === "recovery" ? tools.filter(({ name }) => name !== NATIVE_AGENT_RUN_TOOL) : tools;
 }