@tangle-network/agent-provider-tangle 0.14.3 → 1.0.0

package/README.md

@@ -1,9 +1,8 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.34.0 <1.0.0`, and this package is developed and tested against 0.34.3.
-The floor is 0.34.0 because workspace branching uses the keyed snapshot, fork,
-lookup, and cleanup operations added to that SDK.
+The peer range is `>=0.34.4 <1.0.0`, and this package is developed and tested against 0.34.4.
+The floor is 0.34.4 because exact interactive attachment needs the host receiver, and workspace branching needs keyed snapshot, fork, lookup, and cleanup operations.
 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.
 

package/dist/tangle-capabilities.js

@@ -72,7 +72,15 @@ export function defaultTangleSandboxCapabilities(harness) {
             eventIdentity: true,
             cancellationIdempotency: true,
         },
-        workspace: { read: true, write: true, exec: true, git: false, upload: true, download: true },
+        workspace: {
+            read: true,
+            write: true,
+            exec: true,
+            git: false,
+            upload: true,
+            download: true,
+            cwdBases: { repository: true, host: false },
+        },
         // The complete Sandbox SDK surface backs this contract. Narrowing below
         // removes every flag when any recovery or cleanup method is absent.
         branching: {

package/dist/tangle-create-options.d.ts

@@ -1,9 +1,9 @@
 import type { BackendType, CreateSandboxOptions } from "@tangle-network/sandbox";
-import type { CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
-export declare function sandboxOptionsFromCreateInput(input: CreateAgentEnvironmentInput, defaultBackend: BackendType): CreateSandboxOptions;
+import type { CreateAgentEnvironmentInput, WorkspaceRequest } from "@tangle-network/agent-interface/environment-provider";
+export declare function sandboxOptionsFromCreateInput(input: CreateAgentEnvironmentInput, defaultBackend: BackendType, parsedWorkspace?: WorkspaceRequest): CreateSandboxOptions;
 /** Reject value-bearing secret maps before any custom mapper can drop them. */
-export declare function assertNoInlineSecretValues(input: CreateAgentEnvironmentInput): void;
+export declare function assertNoInlineSecretValues(input: CreateAgentEnvironmentInput, parsedWorkspace?: WorkspaceRequest): void;
 /** A custom mapper must not smuggle a value map into the Sandbox request. */
 export declare function assertMappedSecretNames(options: CreateSandboxOptions): void;
-export declare function assertCreateInputShape(input: CreateAgentEnvironmentInput): void;
+export declare function assertCreateInputShape(input: CreateAgentEnvironmentInput, parsedWorkspace?: WorkspaceRequest): WorkspaceRequest | undefined;
 export declare function assertMappedCreateOptions(options: CreateSandboxOptions): void;

package/dist/tangle-create-options.js

@@ -1,8 +1,9 @@
+import { WorkspaceRequestSchema, workspaceCwdPathForBase, } from "@tangle-network/agent-interface/environment-provider";
 import { assertBoundedJson, boundedIdentifier, boundedString, MAX_ARRAY_LENGTH, MAX_MAP_ENTRIES, } from "./tangle-contract-safety.js";
 import { sandboxResourcesFromResourceRequest } from "./tangle-resources.js";
-export function sandboxOptionsFromCreateInput(input, defaultBackend) {
-    assertCreateInputShape(input);
-    assertNoInlineSecretValues(input);
+export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorkspace) {
+    const workspace = assertCreateInputShape(input, parsedWorkspace) ?? {};
+    assertNoInlineSecretValues(input, workspace);
     if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
         throw new Error("Tangle create providerOptions are not supported");
     }
@@ -19,23 +20,10 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend) {
         boundedIdentifier(input.backend, "Tangle backend");
     if (input.env !== undefined)
         assertStringRecord(input.env, "Tangle");
-    const workspace = input.workspace ?? {};
     if (workspace.providerOptions && Object.keys(workspace.providerOptions).length > 0) {
         throw new Error("Tangle workspace providerOptions are not supported");
     }
-    if (workspace.providerOptions)
-        assertBoundedRecord(workspace.providerOptions, "Tangle workspace providerOptions");
-    if (workspace.environment !== undefined) {
-        boundedIdentifier(workspace.environment, "Tangle workspace environment");
-    }
-    if (workspace.image !== undefined)
-        boundedString(workspace.image, "Tangle workspace image");
-    if (workspace.cwd !== undefined)
-        boundedString(workspace.cwd, "Tangle workspace cwd");
-    if (workspace.repoUrl !== undefined)
-        boundedString(workspace.repoUrl, "Tangle repository URL");
-    if (workspace.gitRef !== undefined)
-        boundedIdentifier(workspace.gitRef, "Tangle git ref");
+    const workspaceCwd = workspaceCwdPathForBase(workspace.cwd, "repository", "Tangle");
     if (input.resources?.providerOptions && Object.keys(input.resources.providerOptions).length > 0) {
         throw new Error("Tangle resource providerOptions are not supported");
     }
@@ -44,24 +32,16 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend) {
     if (input.idempotencyKey !== undefined) {
         boundedIdentifier(input.idempotencyKey, "Tangle idempotency key");
     }
-    if (input.workspace?.cwd === "")
-        throw new Error("Tangle workspace cwd cannot be empty");
-    if (workspace.image === "")
-        throw new Error("Tangle workspace image cannot be empty");
-    if (workspace.repoUrl === "")
-        throw new Error("Tangle repository URL cannot be empty");
     const resources = sandboxResourcesFromResourceRequest(input.resources);
-    if (workspace.environment !== undefined && workspace.image !== undefined) {
-        throw new Error("Tangle workspace cannot specify both environment and image");
-    }
     // Sandbox injects secrets by name from its own store. Accepting a name/value
     // record and dropping it would create an environment with no credentials and
     // no error, surfacing later as an unexplained tool failure.
     const environment = workspace.image ?? workspace.environment;
     const base = {};
-    return {
+    const mapped = {
         ...base,
         ...(environment !== undefined ? { environment } : {}),
+        ...(workspaceCwd === undefined ? {} : { cwd: workspaceCwd }),
         ...(workspace.repoUrl
             ? {
                 git: {
@@ -82,9 +62,10 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend) {
             profile: inlineAgentProfile(input.profile),
         },
     };
+    return mapped;
 }
 /** Reject value-bearing secret maps before any custom mapper can drop them. */
-export function assertNoInlineSecretValues(input) {
+export function assertNoInlineSecretValues(input, parsedWorkspace) {
     if (input.providerOptions !== undefined) {
         if (!input.providerOptions || typeof input.providerOptions !== "object" || Array.isArray(input.providerOptions)) {
             throw new Error("Tangle create providerOptions must be a JSON object");
@@ -95,11 +76,8 @@ export function assertNoInlineSecretValues(input) {
         }
     }
     if (input.workspace?.providerOptions !== undefined) {
-        if (!input.workspace.providerOptions || typeof input.workspace.providerOptions !== "object" || Array.isArray(input.workspace.providerOptions)) {
-            throw new Error("Tangle workspace providerOptions must be a JSON object");
-        }
-        assertBoundedJson(input.workspace.providerOptions);
-        if (Object.keys(input.workspace.providerOptions).length > 0) {
+        const workspace = parsedWorkspace ?? WorkspaceRequestSchema.parse(input.workspace);
+        if (workspace.providerOptions && Object.keys(workspace.providerOptions).length > 0) {
             throw new Error("Tangle workspace providerOptions are not supported");
         }
     }
@@ -136,7 +114,7 @@ export function assertMappedSecretNames(options) {
             boundedIdentifier(secret, "Tangle mapped secret name");
     }
 }
-export function assertCreateInputShape(input) {
+export function assertCreateInputShape(input, parsedWorkspace) {
     if (!input || typeof input !== "object" || Array.isArray(input)) {
         throw new Error("Tangle create input must be an object");
     }
@@ -166,16 +144,6 @@ export function assertCreateInputShape(input) {
         }
         assertBoundedJson(input.profile);
     }
-    if (input.workspace !== undefined) {
-        if (!input.workspace || typeof input.workspace !== "object" || Array.isArray(input.workspace)) {
-            throw new Error("Tangle workspace must be an object");
-        }
-        const workspaceKeys = new Set(Object.keys(input.workspace));
-        for (const key of ["environment", "image", "repoUrl", "gitRef", "cwd", "providerOptions"])
-            workspaceKeys.delete(key);
-        if (workspaceKeys.size > 0)
-            throw new Error("Tangle workspace contains unsupported fields");
-    }
     if (input.resources !== undefined) {
         if (!input.resources || typeof input.resources !== "object" || Array.isArray(input.resources)) {
             throw new Error("Tangle resources must be an object");
@@ -186,6 +154,11 @@ export function assertCreateInputShape(input) {
         if (resourceKeys.size > 0)
             throw new Error("Tangle resources contain unsupported fields");
     }
+    if (input.workspace === undefined)
+        return undefined;
+    const workspace = parsedWorkspace ?? WorkspaceRequestSchema.parse(input.workspace);
+    workspaceCwdPathForBase(workspace.cwd, "repository", "Tangle");
+    return workspace;
 }
 export function assertMappedCreateOptions(options) {
     if (!options || typeof options !== "object" || Array.isArray(options)) {

package/dist/tangle-environment-session.js

@@ -35,7 +35,6 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
         ? tangleInteractionResponder({
             session,
             sessionId: session.id,
-            provider,
             environmentId,
         })
         : undefined;

package/dist/tangle-environment.js

@@ -199,7 +199,6 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
                     return tangleInteractionResponder({
                         session,
                         sessionId,
-                        provider: providerName,
                         environmentId,
                     })(command, options);
                 },

package/dist/tangle-interaction-response.d.ts

@@ -4,7 +4,6 @@ export interface TangleInteractionResponderOptions {
     session: SandboxSessionLike;
     /** The session the bound ask must belong to. */
     sessionId: string;
-    provider: string;
     environmentId: string;
 }
 /**

package/dist/tangle-interaction-response.js

@@ -20,20 +20,22 @@ function acknowledge(command, status, extras = {}) {
     });
 }
 /**
- * The coordinates this environment can answer for. A command naming another
- * provider, environment, or session is refused here rather than sent, because
- * the Sandbox SDK rejects such a command by throwing, and a caller holding a
- * durable operation needs the refusal as an acknowledgement it can record.
+ * The coordinates this environment can answer for before the command reaches
+ * the deployment. Tangle hosts a backend adapter inside the sandbox, so the
+ * interaction binding's provider names that inner adapter (for example,
+ * `opencode`) rather than this outer provider. The deployment compares that
+ * provider with its durable interaction record. Environment and session are
+ * still checked here because the Sandbox SDK rejects those coordinates before
+ * it can return an acknowledgement.
  */
 function foreignBinding(command, options) {
     const binding = command.binding;
-    if (binding.provider === options.provider &&
-        binding.environmentId === options.environmentId &&
+    if (binding.environmentId === options.environmentId &&
         binding.sessionId === options.sessionId) {
         return undefined;
     }
     return acknowledge(command, "binding_mismatch", {
-        message: `response command binding names another provider, environment, or session than ${options.provider}/${options.environmentId}/${options.sessionId}`,
+        message: `response command binding names another environment or session than ${options.environmentId}/${options.sessionId}`,
     });
 }
 /**

package/dist/tangle-prompt.d.ts

@@ -8,7 +8,7 @@ export declare function promptOptionsFromTurnInput(input: AgentTurnInput, target
     environmentId: string;
     sessionId?: string;
 }): PromptOptions;
-type SandboxRunStatus = "success" | "failed" | "blocked_on_approval" | "awaiting_question" | "awaiting_plan_decision";
+type SandboxRunStatus = "success" | "failed" | "blocked_on_approval" | "awaiting_question" | "awaiting_interaction" | "awaiting_plan_decision";
 type ValidatedSandboxPromptResult = Record<string, unknown> & {
     success: boolean;
     status: SandboxRunStatus;

package/dist/tangle-prompt.js

@@ -97,6 +97,7 @@ export function validatedSandboxPromptResult(result) {
         "failed",
         "blocked_on_approval",
         "awaiting_question",
+        "awaiting_interaction",
         "awaiting_plan_decision",
     ]);
     if (typeof record.status !== "string" ||
@@ -134,6 +135,7 @@ export function validatedSandboxPromptResult(result) {
 const AWAITING_STATUSES = new Set([
     "blocked_on_approval",
     "awaiting_question",
+    "awaiting_interaction",
     "awaiting_plan_decision",
 ]);
 export function agentTurnResultFromPromptRecord(record, options = {}) {

package/dist/tangle-provider.js

@@ -43,9 +43,9 @@ export function createTangleProvider(options) {
     const resolveCapabilities = async () => narrowedProviderCapabilities(await resolveDeclaredCapabilities());
     const createRecords = new Map();
     const createEnvironment = async (input) => {
-        assertCreateInputShape(input);
+        const parsedWorkspace = assertCreateInputShape(input);
         input.signal?.throwIfAborted();
-        assertNoInlineSecretValues(input);
+        assertNoInlineSecretValues(input, parsedWorkspace);
         if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
             throw new Error("Tangle create providerOptions are not supported");
         }
@@ -55,7 +55,7 @@ export function createTangleProvider(options) {
         const declaredCapabilities = await resolveDeclaredCapabilities();
         narrowedProviderCapabilities(declaredCapabilities);
         const createOptions = options.mapCreateInput?.(input) ??
-            sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode");
+            sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode", parsedWorkspace);
         assertMappedCreateOptions(createOptions);
         if (input.idempotencyKey !== undefined &&
             createOptions.idempotencyKey !== input.idempotencyKey) {

package/dist/tangle-types.d.ts

@@ -202,6 +202,8 @@ export interface SandboxWorkspaceOperationLookupLike {
     outcome: "found" | "not_found" | "conflict" | "unknown";
     kind: "checkpoint" | "fork";
     state?: "pending" | "succeeded" | "failed";
+    /** The durable operation result, when the service records one. */
+    result?: Record<string, unknown>;
 }
 /** Fan-out acknowledgement returned by SandboxInstance.fork(). */
 export interface SandboxForkAcknowledgementLike {

package/dist/tangle-workspace-branching.js

@@ -116,7 +116,7 @@ export function createTangleWorkspaceBranching(options) {
                 message: "Sandbox fork child identity is incomplete",
             };
         }
-        const environment = await environmentFromChild(recovered.marker.request, child, provider, child.createdAt, options.confidentialAttestationVerifier, signal);
+        const environment = await environmentFromChild(recovered.marker.request, child, provider, recovered.createdAt ?? child.createdAt, options.confidentialAttestationVerifier, signal);
         if (!environment) {
             return {
                 state: "undecided",
@@ -699,6 +699,22 @@ function validForkResult(result) {
         result.materializedCount === result.children.length &&
         typeof result.complete === "boolean");
 }
+function validOperationRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function validOperationDate(value) {
+    return ((typeof value === "string" || value instanceof Date) && validDate(value));
+}
+function validSnapshotOperationResult(value) {
+    return (validOperationRecord(value) &&
+        safeIdentifier(value.snapshotId) !== undefined &&
+        validOperationDate(value.createdAt));
+}
+function validForkOperationChildResult(value) {
+    return (validOperationRecord(value) &&
+        safeIdentifier(value.sandboxId ?? value.id) !== undefined &&
+        validOperationDate(value.createdAt));
+}
 function checkpointMarkerTags(request) {
     const marker = {
         version: 1,
@@ -755,22 +771,30 @@ function forkMarkerMetadata(request) {
  * A marker only names a candidate resource. Nothing is returned to a caller
  * until the ledger reports the operation succeeded.
  */
-async function checkpointOperationSucceeded(box, marker, signal) {
+async function checkpointOperationLookup(box, marker, signal) {
     const lookup = await awaitWithSignal(box.getSnapshotOperation?.(marker.idempotencyKey, {
         tags: marker.legacy
             ? legacyCheckpointMarkerTags(marker.request)
             : checkpointMarkerTags(marker.request),
     }), signal);
+    return lookup;
+}
+async function checkpointOperationSucceeded(box, marker, signal) {
+    const lookup = await checkpointOperationLookup(box, marker, signal);
     return (lookup?.outcome === "found" &&
         lookup.kind === "checkpoint" &&
         lookup.state === "succeeded");
 }
 /** The fork equivalent of {@link checkpointOperationSucceeded}. */
-async function forkOperationSucceeded(box, marker, signal) {
+async function forkOperationLookup(box, marker, signal) {
     const lookup = await awaitWithSignal(box.getForkOperation?.(marker.idempotencyKey, {
         count: 1,
         metadata: forkMarkerMetadata(marker.request),
     }), signal);
+    return lookup;
+}
+async function forkOperationSucceeded(box, marker, signal) {
+    const lookup = await forkOperationLookup(box, marker, signal);
     return (lookup?.outcome === "found" &&
         lookup.kind === "fork" &&
         lookup.state === "succeeded");
@@ -818,8 +842,14 @@ async function findCheckpointByKey(box, key, signal) {
         if (!marker)
             continue;
         try {
-            if (await checkpointOperationSucceeded(box, marker, signal)) {
-                return { snapshot, marker };
+            const lookup = await checkpointOperationLookup(box, marker, signal);
+            if (lookup?.outcome === "found" &&
+                lookup.kind === "checkpoint" &&
+                lookup.state === "succeeded") {
+                const authoritative = snapshotFromOperationResult(snapshot, lookup);
+                if (authoritative === undefined)
+                    return undefined;
+                return { snapshot: authoritative, marker };
             }
             unresolved = true;
         }
@@ -830,6 +860,23 @@ async function findCheckpointByKey(box, key, signal) {
     }
     return unresolved ? undefined : null;
 }
+/**
+ * Prefer the durable operation result over inventory metadata.
+ *
+ * Snapshot inventory and the operation ledger can expose different creation
+ * timestamps. The ledger result is the acknowledgement returned by the
+ * idempotent operation, so recovery must rebuild the exact checkpoint ref
+ * from it when the service provides that result.
+ */
+function snapshotFromOperationResult(snapshot, lookup) {
+    if (lookup.result === undefined)
+        return snapshot;
+    if (!validSnapshotOperationResult(lookup.result) ||
+        lookup.result.snapshotId !== snapshot.snapshotId) {
+        return undefined;
+    }
+    return { ...snapshot, createdAt: lookup.result.createdAt };
+}
 /**
  * Confirm that one snapshot id is a settled checkpoint this provider created.
  *
@@ -877,8 +924,15 @@ async function findForkByKey(client, box, provider, key, signal) {
     let unresolved = false;
     for (const candidate of candidates) {
         try {
-            if (await forkOperationSucceeded(box, candidate.marker, signal))
-                return candidate;
+            const lookup = await forkOperationLookup(box, candidate.marker, signal);
+            if (lookup?.outcome === "found" &&
+                lookup.kind === "fork" &&
+                lookup.state === "succeeded") {
+                const authoritative = childFromOperationResult(candidate.child, lookup);
+                if (authoritative === undefined)
+                    return undefined;
+                return { ...authoritative, marker: candidate.marker };
+            }
             unresolved = true;
         }
         catch {
@@ -888,6 +942,29 @@ async function findForkByKey(client, box, provider, key, signal) {
     }
     return unresolved ? undefined : null;
 }
+/**
+ * Prefer the durable fork result over account-inventory metadata.
+ *
+ * Fork inventory can report a child timestamp from a later registry read. The
+ * operation ledger stores the original child acknowledgement, which is the
+ * stable value required to replay one exact fork reference after a restart.
+ */
+function childFromOperationResult(child, lookup) {
+    if (lookup.result === undefined) {
+        return { child, createdAt: child.createdAt };
+    }
+    const result = lookup.result;
+    if (!validOperationRecord(result))
+        return undefined;
+    const children = result.children;
+    if (!Array.isArray(children))
+        return undefined;
+    const operationChild = children.find((candidate) => validForkOperationChildResult(candidate) &&
+        (candidate.sandboxId ?? candidate.id) === child.id);
+    if (!operationChild)
+        return undefined;
+    return { child, createdAt: operationChild.createdAt };
+}
 async function findForkChildById(client, box, provider, id, signal) {
     try {
         if (typeof client.get !== "function")
@@ -1229,7 +1306,7 @@ async function forkConflictFromRemote(client, box, provider, request, verifier,
     const child = await completeForkChild(client, recovered.child, signal);
     if (!child)
         return undefined;
-    const environment = await environmentFromChild(recovered.marker.request, child, provider, child.createdAt, verifier, signal);
+    const environment = await environmentFromChild(recovered.marker.request, child, provider, recovered.createdAt ?? child.createdAt, verifier, signal);
     return environment === undefined
         ? undefined
         : forkSuccess(request, environment, "replayed");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.14.3",
+  "version": "1.0.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -89,10 +89,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^1.8.0"
+    "@tangle-network/agent-interface": "^2.0.0"
   },
   "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.34.0 <1.0.0"
+    "@tangle-network/sandbox": ">=0.34.6 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {
@@ -101,12 +101,12 @@
   },
   "devDependencies": {
     "@tangle-network/agent-eval": "0.170.0",
-    "@tangle-network/agent-runtime": "0.178.0",
-    "@tangle-network/sandbox": "0.34.3",
+    "@tangle-network/agent-runtime": "0.184.0",
+    "@tangle-network/sandbox": "0.34.6",
     "@types/node": "26.4.0",
     "typescript": "7.0.2",
     "vitest": "4.1.11",
-    "@tangle-network/agent-provider-testkit": "0.8.4"
+    "@tangle-network/agent-provider-testkit": "0.8.6"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",