@tangle-network/agent-provider-tangle 0.12.2 → 0.13.0

package/README.md

@@ -1,11 +1,10 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.23.0 <1.0.0`, and this package is developed and tested against 0.23.0.
-The floor is 0.23.0 because the response path needs `session.respondToInteraction`, which first shipped there.
-The adapter feature-detects that method, so an older SDK claims no interactions rather than failing to load.
-The floor stands anyway: the earlier answer path resolves the session's first outstanding question rather than the one a response names, so a response meant for one ask resolves another and reports success.
-This adapter never falls back to it.
+The peer range is `>=0.30.1 <1.0.0`, and this package is developed and tested against 0.30.1.
+The floor is 0.30.1 because interaction claims use the Sandbox backend catalog exposed by `listBackends()`.
+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.
 
 ```ts
 import { Sandbox } from '@tangle-network/sandbox'

package/dist/tangle-capabilities.d.ts

@@ -1,4 +1,5 @@
 import type { AgentEnvironmentCapabilities, HarnessType } from "@tangle-network/agent-interface";
+import type { BackendRegistryEntry } from "@tangle-network/sandbox";
 import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
 import type { DeploymentCapabilitySupport } from "./tangle-deployment-capabilities.js";
 import type { ResourceProfile } from "@tangle-network/agent-interface";
@@ -13,6 +14,13 @@ import { type ObservationSurfaceSupport } from "./tangle-observation.js";
  * nothing backs becomes an action the caller selects and finds missing.
  */
 export declare function defaultTangleSandboxCapabilities(harness?: HarnessType): AgentEnvironmentCapabilities;
+/**
+ * Keep only interaction kinds the selected Sandbox backend advertises.
+ *
+ * The backend catalog is the authority for harness-specific interactions.
+ * An absent entry means the provider cannot prove any interaction support.
+ */
+export declare function narrowTangleCapabilitiesToBackend(declared: AgentEnvironmentCapabilities, backend: BackendRegistryEntry | undefined): AgentEnvironmentCapabilities;
 /**
  * Adapter-surface facts that gate declared capabilities: which methods this
  * process can actually call. Every fact defaults to false when it cannot be

package/dist/tangle-capabilities.js

@@ -114,6 +114,35 @@ export function defaultTangleSandboxCapabilities(harness) {
         },
     };
 }
+/**
+ * Keep only interaction kinds the selected Sandbox backend advertises.
+ *
+ * The backend catalog is the authority for harness-specific interactions.
+ * An absent entry means the provider cannot prove any interaction support.
+ */
+export function narrowTangleCapabilitiesToBackend(declared, backend) {
+    if (declared.interactions === undefined || backend === undefined) {
+        if (declared.interactions === undefined)
+            return declared;
+        const narrowed = { ...declared };
+        delete narrowed.interactions;
+        return narrowed;
+    }
+    const supportedKinds = new Set(backend.capabilities.interactions);
+    const kinds = declared.interactions.kinds.filter((kind) => supportedKinds.has(kind));
+    if (kinds.length === 0) {
+        const narrowed = { ...declared };
+        delete narrowed.interactions;
+        return narrowed;
+    }
+    return {
+        ...declared,
+        interactions: {
+            ...declared.interactions,
+            kinds,
+        },
+    };
+}
 // One reserved id names both probe handles; neither ever reaches the service.
 const CAPABILITY_PROBE_ID = "__tangle-capability-probe__";
 export function sandboxCapabilitySupport(box, client, requestedResources) {

package/dist/tangle-provider.js

@@ -1,6 +1,6 @@
-import { AgentEnvironmentCapabilitiesSchema } from "@tangle-network/agent-interface/environment-provider";
+import { AgentEnvironmentCapabilitiesSchema, createAgentEnvironmentWithIdempotency, } from "@tangle-network/agent-interface/environment-provider";
 import { createTangleExactProcessProvider, } from "./exact-process.js";
-import { capabilitiesForClient, defaultTangleSandboxCapabilities, } from "./tangle-capabilities.js";
+import { capabilitiesForClient, defaultTangleSandboxCapabilities, narrowTangleCapabilitiesToBackend, } from "./tangle-capabilities.js";
 import { sandboxInstanceAsEnvironment } from "./tangle-environment.js";
 import { assertCreateInputShape, assertMappedCreateOptions, assertMappedSecretNames, assertNoInlineSecretValues, sandboxOptionsFromCreateInput } from "./tangle-create-options.js";
 import { statusFromUnknown } from "./tangle-environment-values.js";
@@ -25,85 +25,97 @@ export function createTangleProvider(options) {
         if (!exactProcess && configured.exactProcess) {
             throw new Error("Tangle capabilities cannot advertise exactProcess without exactProcess configuration");
         }
+        const backend = configured.interactions === undefined
+            ? undefined
+            : await resolveDefaultBackend(options.client, options.defaultBackend);
+        const narrowed = narrowTangleCapabilitiesToBackend(configured, backend);
         return exactProcess
             ? {
-                ...configured,
+                ...narrowed,
                 exactProcess: { egress: ["blocked", "strict"] },
             }
-            : configured;
+            : narrowed;
     };
     // Provider-boundary document: client-stage facts only. It also validates
     // the configured document, so create() and get() call it before any effect.
     const narrowedProviderCapabilities = (declared) => AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForClient(declared, options.client));
     const resolveCapabilities = async () => narrowedProviderCapabilities(await resolveDeclaredCapabilities());
-    return {
-        name: providerName,
-        ...(exactProcess ? { exactProcess } : {}),
-        capabilities: resolveCapabilities,
-        ...(options.validateProfile ? { validateProfile: options.validateProfile } : {}),
-        async create(input) {
-            assertCreateInputShape(input);
-            input.signal?.throwIfAborted();
-            assertNoInlineSecretValues(input);
-            if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
-                throw new Error("Tangle create providerOptions are not supported");
+    const createRecords = new Map();
+    const createEnvironment = async (input) => {
+        assertCreateInputShape(input);
+        input.signal?.throwIfAborted();
+        assertNoInlineSecretValues(input);
+        if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
+            throw new Error("Tangle create providerOptions are not supported");
+        }
+        // The sandbox stage narrows from the declared document, not the
+        // provider-boundary one: the client stage cannot observe box-scoped
+        // facts, so measured instance facts must decide them per sandbox.
+        const declaredCapabilities = await resolveDeclaredCapabilities();
+        narrowedProviderCapabilities(declaredCapabilities);
+        const createOptions = options.mapCreateInput?.(input) ??
+            sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode");
+        assertMappedCreateOptions(createOptions);
+        if (input.idempotencyKey !== undefined &&
+            createOptions.idempotencyKey !== input.idempotencyKey) {
+            throw new Error("Tangle mapped create options must preserve input idempotencyKey");
+        }
+        assertMappedSecretNames(createOptions);
+        input.signal?.throwIfAborted();
+        const createPromise = options.client.create(createOptions, input.signal ? { signal: input.signal } : undefined);
+        let box;
+        try {
+            box = await awaitWithSignal(createPromise, input.signal);
+        }
+        catch (error) {
+            if (input.signal?.aborted) {
+                void createPromise
+                    .then(async (lateBox) => {
+                    if (!lateBox.delete) {
+                        attachCleanupHandle(error, lateBox);
+                        return;
+                    }
+                    try {
+                        await lateBox.delete();
+                    }
+                    catch (cleanupError) {
+                        attachCleanupHandle(error, lateBox, cleanupError);
+                    }
+                })
+                    .catch((lateError) => attachCleanupHandle(error, undefined, lateError));
             }
-            // The sandbox stage narrows from the declared document, not the
-            // provider-boundary one: the client stage cannot observe box-scoped
-            // facts, so measured instance facts must decide them per sandbox.
-            const declaredCapabilities = await resolveDeclaredCapabilities();
-            narrowedProviderCapabilities(declaredCapabilities);
-            const createOptions = options.mapCreateInput?.(input) ??
-                sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode");
-            assertMappedCreateOptions(createOptions);
-            assertMappedSecretNames(createOptions);
+            throw error;
+        }
+        try {
             input.signal?.throwIfAborted();
-            const createPromise = options.client.create(createOptions, input.signal ? { signal: input.signal } : undefined);
-            let box;
-            try {
-                box = await awaitWithSignal(createPromise, input.signal);
-            }
-            catch (error) {
-                if (input.signal?.aborted) {
-                    void createPromise
-                        .then(async (lateBox) => {
-                        if (!lateBox.delete) {
-                            attachCleanupHandle(error, lateBox);
-                            return;
-                        }
-                        try {
-                            await lateBox.delete();
-                        }
-                        catch (cleanupError) {
-                            attachCleanupHandle(error, lateBox, cleanupError);
-                        }
-                    })
-                        .catch((lateError) => attachCleanupHandle(error, undefined, lateError));
-                }
-                throw error;
+            const requestedResources = requestedResourceProfile(input.resources);
+            const environment = await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, input.signal ? { signal: input.signal } : undefined, requestedResources === undefined ? undefined : { resources: requestedResources });
+            input.signal?.throwIfAborted();
+            return environment;
+        }
+        catch (error) {
+            if (!box.delete) {
+                const baseError = error instanceof Error ? error : new Error(String(error));
+                throw Object.assign(baseError, { cleanupHandle: box });
             }
             try {
-                input.signal?.throwIfAborted();
-                const requestedResources = requestedResourceProfile(input.resources);
-                const environment = await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, input.signal ? { signal: input.signal } : undefined, requestedResources === undefined ? undefined : { resources: requestedResources });
-                input.signal?.throwIfAborted();
-                return environment;
+                await box.delete();
             }
-            catch (error) {
-                if (!box.delete) {
-                    const baseError = error instanceof Error ? error : new Error(String(error));
-                    throw Object.assign(baseError, { cleanupHandle: box });
-                }
-                try {
-                    await box.delete();
-                }
-                catch (cleanupError) {
-                    const combined = new AggregateError([error, cleanupError], "Tangle environment validation and cleanup both failed");
-                    attachCleanupHandle(combined, box, cleanupError);
-                    throw combined;
-                }
-                throw error;
+            catch (cleanupError) {
+                const combined = new AggregateError([error, cleanupError], "Tangle environment validation and cleanup both failed");
+                attachCleanupHandle(combined, box, cleanupError);
+                throw combined;
             }
+            throw error;
+        }
+    };
+    return {
+        name: providerName,
+        ...(exactProcess ? { exactProcess } : {}),
+        capabilities: resolveCapabilities,
+        ...(options.validateProfile ? { validateProfile: options.validateProfile } : {}),
+        create(input) {
+            return createAgentEnvironmentWithIdempotency(createRecords, input, () => createEnvironment(input));
         },
         ...(options.client.get
             ? {
@@ -176,6 +188,21 @@ export function createTangleProvider(options) {
             : {}),
     };
 }
+async function resolveDefaultBackend(client, defaultBackend) {
+    if (defaultBackend === undefined)
+        return undefined;
+    try {
+        if (client.getBackend)
+            return await client.getBackend(defaultBackend);
+        if (!client.listBackends)
+            return undefined;
+        const catalog = await client.listBackends();
+        return catalog.backends.find((backend) => backend.type === defaultBackend);
+    }
+    catch {
+        return undefined;
+    }
+}
 function assertProviderOperationOptions(options, label) {
     if (options === undefined)
         return;

package/dist/tangle-types.d.ts

@@ -1,4 +1,4 @@
-import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
+import type { BackendRegistryEntry, BackendRegistryResponse, BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
 import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, AgentExecutionPreparationReceipt, AgentInteractiveSessionControlClaim, AgentInteractiveSessionControlClaimAcknowledgement, AgentInteractiveSessionControlClaimRequest, AgentInteractiveSessionPromptAcknowledgement, AgentInteractiveSessionPromptCommand, AgentInteractiveSessionStopAcknowledgement, AgentInteractiveSessionStopCommand, AgentProfile, InputPart, InteractionRequest, InteractionResponseCommand } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 export interface TangleExactProcessOptions {
@@ -20,6 +20,10 @@ export interface SandboxClientLike {
     fetch?(path: string, options?: RequestInit, fetchOptions?: {
         timeoutMs?: number;
     }): Promise<Response>;
+    /** Canonical backend catalog served by authenticated `/v1/backends`. */
+    listBackends?(): Promise<BackendRegistryResponse>;
+    /** Lookup over the same canonical backend catalog, when the SDK provides it. */
+    getBackend?(type: string): Promise<BackendRegistryEntry | undefined>;
     get?(id: string, requestOptions?: {
         signal?: AbortSignal;
     }): Promise<SandboxInstanceLike | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -85,10 +85,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^1.0.0"
+    "@tangle-network/agent-interface": "^1.0.1"
   },
   "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.23.0 <1.0.0"
+    "@tangle-network/sandbox": ">=0.30.1 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {
@@ -96,13 +96,13 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/agent-eval": "0.145.15",
-    "@tangle-network/agent-runtime": "0.135.3",
-    "@tangle-network/sandbox": "0.27.0",
+    "@tangle-network/agent-eval": "0.149.0",
+    "@tangle-network/agent-runtime": "0.142.3",
+    "@tangle-network/sandbox": "0.30.1",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@tangle-network/agent-provider-testkit": "0.8.2"
+    "@tangle-network/agent-provider-testkit": "0.8.3"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",