@tangle-network/agent-provider-tangle 1.1.2 → 1.1.4

package/README.md

@@ -1,7 +1,7 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.34.6 <1.0.0`, and this package is developed and tested against 0.34.6.
+The peer range is `>=0.34.6 <1.0.0`, and this package is developed and tested against 0.37.0.
 The floor is 0.34.6 because exact interactive attachment needs the host receiver, and workspace branching needs keyed snapshots, durable restores, inventory recovery, and cleanup.
 The provider fails closed when the configured backend or its catalog entry cannot be read.
 Newer SDKs may also provide `getBackend()` as a lookup over the same catalog.
@@ -119,6 +119,7 @@ Each deployment flag this adapter reads gates the claims it backs, and no flag i
 | `runs.eventReplay`                | `streaming.replay`, `sessions.continue`, `retainedControl`, `session.cancelRun`                              |
 | `runs.executionScopedStatus`      | `sessions.continue`, `retainedControl`, `session.cancelRun`                                                  |
 | `interactions.responseDedupe`     | `interactions`, `environment.respondToInteraction`, `session.respondToInteraction`                           |
+| `interactiveAgent.*`              | `interactiveAgent`, exact control, and generation-fenced terminal input and resize                           |
 
 Detached dispatch carries the caller's exact reference and refuses a receipt that does not name the execution back, so it needs both `dispatch` flags and a session handle to reach the run through.
 `sessions.continue`, `retainedControl`, and `session.cancelRun` need every flag in the table, because the capability schema refuses a partial retained-control block and each identity rests on its own flag.
@@ -205,6 +206,11 @@ cannot prove the complete operation surface.
 Recovery reads the account inventory through Sandbox offset pages of at most
 1,000 sandboxes and continues until a short page proves the inventory is
 complete.
+If a live snapshot loses its marker tags, recovery reads the owner-scoped
+operation record by key and binds its stored result to that live snapshot id.
+The operation record alone never revives a deleted snapshot.
+An older Sandbox deployment that cannot answer the owner-scoped lookup returns
+`unknown` and does not create or mutate a checkpoint.
 The adapter also reads checkpoints from the previous marker format while writing only the current bounded format.
 Malformed, repeated, failed, or over-bound pages return `unknown` and do not
 mutate a resource.
@@ -328,6 +334,11 @@ Every reference states an expiry one detach window past the newest activity the
 `close()` reports `closed` only when the socket delivered an exit; Sandbox exposes no terminal delete, so an unproven close reports `unknown` rather than claiming a termination that did not happen.
 An attach whose runtime metadata lacks a name, shell, working directory, geometry, timestamps, running state, or detach window fails closed with `unknown`, because a reference cannot state facts the runtime did not report.
 
+The exact interactive adapter validates control before attach, prompt, and stop operations.
+An attached terminal sends input and resize operations through its authenticated terminal connection.
+The sidecar authorizes those mutations, so the provider does not add a second REST request before each operation.
+Terminal close only detaches the caller's socket, so it stays available after control moves to a newer coordinator.
+
 Pass `exactProcess: {}` only when the Sandbox deployment supports `agent: false` creates and reports `metadata.runtimeMode: "control"`.
 The optional capability creates an ephemeral sandbox with an authenticated control service but no managed agent workload or agent credentials, explicit resources, exact blocked/domain egress, bounded binary file reads, shell-free launch, and recoverable process output plus terminal reason.
 Set `teamId` inside `exactProcess` to scope create, lookup, and recovery to one team.

package/dist/tangle-interactive.js

@@ -186,7 +186,7 @@ export function createTangleInteractiveAgentRegistry(box, providerName, environm
                         await terminal.detach().catch(() => undefined);
                         throw error;
                     }
-                    return validatedTerminal(terminal, exactRequest.control, validateControl, ref);
+                    return validatedTerminal(terminal, exactRequest.control, ref);
                 },
                 async sendPrompt(command, options) {
                     assertOptionKeys(options, ["signal"], "Tangle interactive agent prompt");
@@ -246,7 +246,7 @@ function isSandboxInteractiveSession(value) {
         "stop",
     ].every((key) => typeof candidate[key] === "function");
 }
-function validatedTerminal(terminal, control, validate, expectedRef) {
+function validatedTerminal(terminal, control, expectedRef) {
     const boundControl = Object.freeze({ ...control });
     return {
         get ref() {
@@ -261,19 +261,12 @@ function validatedTerminal(terminal, control, validate, expectedRef) {
             return TerminalReplayWindowSchema.parse(terminal.cursors);
         },
         control: boundControl,
-        async input(input, options) {
-            await validate(boundControl, options);
-            await terminal.input(input, options);
-        },
-        async resize(resize, options) {
-            await validate(boundControl, options);
-            await terminal.resize(resize, options);
-        },
+        // The authenticated terminal transport authorizes input and resize.
+        // A REST preflight adds latency and can race the authoritative operation.
+        input: (input, options) => terminal.input(input, options),
+        resize: (resize, options) => terminal.resize(resize, options),
         detach: (options) => terminal.detach(options),
-        async close(options) {
-            await validate(boundControl, options);
-            return terminal.close(options);
-        },
+        close: (options) => terminal.close(options),
         events: (options) => terminal.events(options),
     };
 }

package/dist/tangle-workspace-branching.js

@@ -57,8 +57,8 @@ export function createTangleWorkspaceBranching(options) {
      *
      * The in-process record answers first; otherwise the Sandbox inventory and
      * operation ledger rebuild it after a restart. `absent` means the key has no
-     * resource this provider created, which is the only state where a caller may
-     * go on to create one.
+     * record, which is the only state where a caller may go on to create one.
+     * `retired` means the durable operation settled but its snapshot is gone.
      */
     const resolveCheckpoint = async (request, signal) => {
         const local = checkpoints.get(request.idempotencyKey);
@@ -70,30 +70,20 @@ export function createTangleWorkspaceBranching(options) {
                     existingRequestDigest: local.request.requestDigest,
                 };
         }
-        const recovered = await findCheckpointByKey(box, request.idempotencyKey, signal);
-        if (recovered === undefined) {
+        const recovered = await reconcileCheckpoint(box, provider, request, signal);
+        if (recovered.state === "undecided") {
             return {
                 state: "undecided",
-                message: "Sandbox checkpoint inventory is unavailable",
+                message: recovered.reason === "inventory_unavailable"
+                    ? "Sandbox checkpoint inventory is unavailable"
+                    : "Sandbox checkpoint metadata is invalid",
             };
         }
-        if (!recovered)
-            return { state: "absent" };
-        if (recovered.marker.requestDigest !== request.requestDigest) {
-            return {
-                state: "conflict",
-                existingRequestDigest: recovered.marker.requestDigest,
-            };
+        if (recovered.state === "found") {
+            checkpoints.set(request.idempotencyKey, recovered.record);
+            return { state: "known", record: recovered.record };
         }
-        const record = checkpointRecordFromSnapshot(recovered.marker.request, recovered.snapshot);
-        if (!record) {
-            return {
-                state: "undecided",
-                message: "Sandbox checkpoint metadata is invalid",
-            };
-        }
-        checkpoints.set(request.idempotencyKey, record);
-        return { state: "known", record };
+        return recovered;
     };
     /** The fork equivalent of {@link resolveCheckpoint}. */
     const resolveFork = async (request, signal) => {
@@ -153,17 +143,21 @@ export function createTangleWorkspaceBranching(options) {
         if (known.state === "undecided") {
             return checkpointUnknown(request, `${known.message}; retry after reconciliation`, true);
         }
+        if (known.state === "retired") {
+            return checkpointUnknown(request, "Sandbox checkpoint operation is settled but its snapshot is no longer present; the idempotency key cannot be reused", false);
+        }
         if (known.state === "known") {
             return checkpointSuccess(request, known.record.checkpoint, "replayed");
         }
         const tags = checkpointMarkerTags(request);
         let result;
         try {
+            operation?.signal?.throwIfAborted();
             result = await awaitWithSignal(box.snapshot?.({ tags, idempotencyKey: request.idempotencyKey }), operation?.signal);
         }
         catch (error) {
             operation?.signal?.throwIfAborted();
-            const conflict = await checkpointConflictFromRemote(box, request, operation?.signal);
+            const conflict = await checkpointConflictFromRemote(box, provider, request, operation?.signal);
             return (conflict ??
                 checkpointUnknown(request, `Sandbox checkpoint outcome is unresolved: ${safeError(error)}`, true));
         }
@@ -180,6 +174,26 @@ export function createTangleWorkspaceBranching(options) {
         if (resultMarker && resultMarker.requestDigest !== request.requestDigest) {
             return checkpointConflict(request, resultMarker.requestDigest);
         }
+        if (resultMarker &&
+            !checkpointMarkerBelongsToSource(resultMarker, provider, box.id)) {
+            return checkpointUnknown(request, "Sandbox checkpoint acknowledgement belongs to another source", false);
+        }
+        if (result.idempotency.outcome === "replayed") {
+            const recovered = await reconcileCheckpoint(box, provider, request, operation?.signal);
+            if (recovered.state === "retired" || recovered.state === "absent") {
+                return checkpointUnknown(request, "Sandbox replay acknowledged a checkpoint that is no longer present", false);
+            }
+            if (recovered.state === "undecided") {
+                return checkpointUnknown(request, recovered.reason === "metadata_invalid"
+                    ? "Sandbox replay returned invalid checkpoint metadata"
+                    : "Sandbox replay could not be reconciled with live checkpoint inventory", true);
+            }
+            if (recovered.state === "conflict") {
+                return checkpointConflict(request, recovered.existingRequestDigest);
+            }
+            checkpoints.set(request.idempotencyKey, recovered.record);
+            return checkpointSuccess(request, recovered.record.checkpoint, "replayed");
+        }
         if (!resultMarker) {
             return checkpointUnknown(request, "Sandbox checkpoint acknowledgement omitted its provider recovery marker", true);
         }
@@ -199,20 +213,13 @@ export function createTangleWorkspaceBranching(options) {
         if (known.state === "undecided") {
             return checkpointLookupUnknown(request, known.message, true);
         }
+        if (known.state === "retired") {
+            return checkpointNotFound(request);
+        }
         if (known.state === "known") {
             return checkpointFound(request, known.record.checkpoint);
         }
-        try {
-            const lookup = await awaitWithSignal(box.getSnapshotOperation?.(request.idempotencyKey, { tags: [] }), operation?.signal);
-            const settled = lookupOutcomeFromSandbox(lookup, "checkpoint");
-            return settled.absent
-                ? checkpointNotFound(request)
-                : checkpointLookupUnknown(request, settled.message, settled.retryable);
-        }
-        catch (error) {
-            operation?.signal?.throwIfAborted();
-            return checkpointLookupUnknown(request, `Sandbox checkpoint lookup failed: ${safeError(error)}`, true);
-        }
+        return checkpointNotFound(request);
     };
     const deleteCheckpoint = async (input, operation) => {
         const request = WorkspaceCleanupRequestSchema.parse(input);
@@ -731,6 +738,11 @@ function validSnapshotOperationResult(value) {
         safeIdentifier(value.snapshotId) !== undefined &&
         validOperationDate(value.createdAt));
 }
+function validTaggedSnapshotOperationResult(value) {
+    return (validSnapshotOperationResult(value) &&
+        Array.isArray(value.tags) &&
+        value.tags.every((tag) => safeString(tag) !== undefined));
+}
 function validForkOperationChildResult(value) {
     return (validOperationRecord(value) &&
         safeIdentifier(value.sandboxId ?? value.id) !== undefined &&
@@ -796,6 +808,7 @@ function forkMarkerMetadata(request, materialization = "snapshot") {
  * until the ledger reports the operation succeeded.
  */
 async function checkpointOperationLookup(box, marker, signal) {
+    signal?.throwIfAborted();
     const lookup = await awaitWithSignal(box.getSnapshotOperation?.(marker.idempotencyKey, {
         tags: marker.legacy
             ? legacyCheckpointMarkerTags(marker.request)
@@ -803,6 +816,11 @@ async function checkpointOperationLookup(box, marker, signal) {
     }), signal);
     return lookup;
 }
+/** Read the durable record by its owner-scoped key when no request body remains. */
+async function checkpointOperationLookupByKey(box, idempotencyKey, signal) {
+    signal?.throwIfAborted();
+    return await awaitWithSignal(box.getSnapshotOperation?.(idempotencyKey), signal);
+}
 async function checkpointOperationSucceeded(box, marker, signal) {
     const lookup = await checkpointOperationLookup(box, marker, signal);
     return (lookup?.outcome === "found" &&
@@ -850,9 +868,10 @@ function markerTags(kind, idempotencyKey, requestDigest, marker) {
         return tag;
     });
 }
-async function findCheckpointByKey(box, key, signal) {
+async function findCheckpointByKey(box, provider, key, signal) {
     let snapshots;
     try {
+        signal?.throwIfAborted();
         const listed = await awaitWithSignal(box.listSnapshots?.(), signal);
         if (!Array.isArray(listed))
             return undefined;
@@ -865,13 +884,21 @@ async function findCheckpointByKey(box, key, signal) {
     if (!Array.isArray(snapshots) || snapshots.length > MAX_LIST_RESULTS) {
         return undefined;
     }
+    const snapshotIds = new Set();
+    let found;
     let unresolved = false;
     for (const snapshot of snapshots) {
         if (!validSnapshotInfo(snapshot, box.id))
             return undefined;
+        if (snapshotIds.has(snapshot.snapshotId))
+            return undefined;
+        snapshotIds.add(snapshot.snapshotId);
         const marker = checkpointMarkerFromTags(snapshot.tags, key);
         if (!marker)
             continue;
+        if (!checkpointMarkerBelongsToSource(marker, provider, box.id)) {
+            return undefined;
+        }
         try {
             const lookup = await checkpointOperationLookup(box, marker, signal);
             if (lookup?.outcome === "found" &&
@@ -880,7 +907,10 @@ async function findCheckpointByKey(box, key, signal) {
                 const authoritative = snapshotFromOperationResult(snapshot, lookup);
                 if (authoritative === undefined)
                     return undefined;
-                return { snapshot: authoritative, marker };
+                if (found !== undefined)
+                    return undefined;
+                found = { state: "found", snapshot: authoritative, marker };
+                continue;
             }
             unresolved = true;
         }
@@ -889,7 +919,69 @@ async function findCheckpointByKey(box, key, signal) {
             return undefined;
         }
     }
-    return unresolved ? undefined : null;
+    if (found !== undefined)
+        return found;
+    if (unresolved)
+        return undefined;
+    // Some storage backends retain the snapshot but omit caller tags from a
+    // later inventory read. The owner-scoped operation record retains the exact
+    // acknowledgement, including those tags. Bind that record to a currently
+    // live snapshot id before recovering it; neither record is sufficient alone.
+    let lookup;
+    try {
+        lookup = await checkpointOperationLookupByKey(box, key, signal);
+    }
+    catch {
+        signal?.throwIfAborted();
+        return undefined;
+    }
+    if (lookup?.outcome === "not_found" && lookup.kind === "checkpoint") {
+        return null;
+    }
+    if (lookup?.outcome !== "found" ||
+        lookup.kind !== "checkpoint" ||
+        lookup.state !== "succeeded") {
+        return undefined;
+    }
+    if (snapshots.length === 0)
+        return { state: "retired" };
+    if (!validTaggedSnapshotOperationResult(lookup.result))
+        return undefined;
+    const live = snapshots.filter((snapshot) => snapshot.snapshotId === lookup.result?.snapshotId);
+    if (live.length === 0)
+        return { state: "retired" };
+    if (live.length !== 1)
+        return undefined;
+    const marker = checkpointMarkerFromTags(lookup.result.tags, key);
+    if (!marker ||
+        !checkpointMarkerBelongsToSource(marker, provider, box.id)) {
+        return undefined;
+    }
+    const authoritative = snapshotFromOperationResult(live[0], lookup);
+    return authoritative === undefined
+        ? undefined
+        : { state: "found", snapshot: authoritative, marker };
+}
+/** Normalize one remote checkpoint recovery attempt for every caller. */
+async function reconcileCheckpoint(box, provider, request, signal) {
+    const recovered = await findCheckpointByKey(box, provider, request.idempotencyKey, signal);
+    if (recovered === undefined) {
+        return { state: "undecided", reason: "inventory_unavailable" };
+    }
+    if (recovered === null)
+        return { state: "absent" };
+    if (recovered.state === "retired")
+        return recovered;
+    if (recovered.marker.requestDigest !== request.requestDigest) {
+        return {
+            state: "conflict",
+            existingRequestDigest: recovered.marker.requestDigest,
+        };
+    }
+    const record = checkpointRecordFromSnapshot(recovered.marker.request, recovered.snapshot);
+    return record === undefined
+        ? { state: "undecided", reason: "metadata_invalid" }
+        : { state: "found", record };
 }
 /**
  * Prefer the durable operation result over inventory metadata.
@@ -1177,6 +1269,10 @@ function markerBelongsToSource(marker, provider, sourceEnvironmentId) {
     return (marker.request.checkpoint.provider === provider &&
         marker.request.checkpoint.source.environmentId === sourceEnvironmentId);
 }
+function checkpointMarkerBelongsToSource(marker, provider, sourceEnvironmentId) {
+    return (marker.request.source.provider === provider &&
+        marker.request.source.environmentId === sourceEnvironmentId);
+}
 function checkpointMarkerFromTags(tags, key) {
     if (!Array.isArray(tags) ||
         tags.length > MAX_MARKER_CHUNKS + 3 ||
@@ -1324,19 +1420,19 @@ function forkMarkerFromMetadata(metadata, key) {
  * digest covers the Sandbox request body, not this interface's identity, so it
  * is never presented as an interface digest.
  */
-async function checkpointConflictFromRemote(box, request, signal) {
+async function checkpointConflictFromRemote(box, provider, request, signal) {
     signal?.throwIfAborted();
-    const recovered = await findCheckpointByKey(box, request.idempotencyKey, signal);
+    const recovered = await reconcileCheckpoint(box, provider, request, signal);
     signal?.throwIfAborted();
-    if (!recovered)
-        return undefined;
-    if (recovered.marker.requestDigest !== request.requestDigest) {
-        return checkpointConflict(request, recovered.marker.requestDigest);
+    if (recovered.state === "retired") {
+        return checkpointUnknown(request, "Sandbox checkpoint operation is settled but its snapshot is no longer present; the idempotency key cannot be reused", false);
     }
-    const record = checkpointRecordFromSnapshot(recovered.marker.request, recovered.snapshot);
-    return record === undefined
+    if (recovered.state === "conflict") {
+        return checkpointConflict(request, recovered.existingRequestDigest);
+    }
+    return recovered.state !== "found"
         ? undefined
-        : checkpointSuccess(request, record.checkpoint, "replayed");
+        : checkpointSuccess(request, recovered.record.checkpoint, "replayed");
 }
 /** The fork equivalent of {@link checkpointConflictFromRemote}. */
 async function forkConflictFromRemote(client, box, provider, request, verifier, signal) {
@@ -1355,10 +1451,10 @@ async function forkConflictFromRemote(client, box, provider, request, verifier,
         : forkSuccess(request, environment, "replayed");
 }
 /**
- * Read a ledger answer for a key that left no marked resource behind.
+ * Read a fork ledger answer for a key that left no marked resource behind.
  *
  * `absent` is the settled answer: a decided operation with no inventory marker
- * means the resource was cleaned after creation, and the provider must not
+ * means the child was cleaned after creation, and the provider must not
  * resurrect it from the ledger. Every other state is undecided for the caller.
  */
 function lookupOutcomeFromSandbox(lookup, kind) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -102,13 +102,13 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/agent-eval": "0.170.0",
-    "@tangle-network/agent-runtime": "0.184.0",
-    "@tangle-network/sandbox": "0.34.6",
-    "@types/node": "26.4.0",
+    "@tangle-network/agent-eval": "0.173.1",
+    "@tangle-network/agent-runtime": "0.192.2",
+    "@tangle-network/sandbox": "0.37.0",
+    "@types/node": "26.4.1",
     "typescript": "7.0.2",
     "vitest": "4.1.11",
-    "@tangle-network/agent-provider-testkit": "0.9.0"
+    "@tangle-network/agent-provider-testkit": "0.9.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",