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

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.4",
+  "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.4 <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.4",
+    "@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",