@tangle-network/agent-provider-tangle 0.12.3 → 0.13.1

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-environment-values.d.ts

@@ -1,5 +1,5 @@
-import type { AgentEnvironmentStatus, AgentSessionStatus, PlacementInfo } from "@tangle-network/agent-interface/environment-provider";
-import type { SandboxInstanceLike } from "./tangle-types.js";
+import type { AgentEnvironmentCreation, AgentEnvironmentStatus, AgentSessionStatus, PlacementInfo } from "@tangle-network/agent-interface/environment-provider";
+import type { SandboxCreateReceiptLike, SandboxInstanceLike } from "./tangle-types.js";
 export declare function nonEmptyString(value: unknown): string | undefined;
 export declare function optionalNonEmptyString(value: unknown, label: string): string | undefined;
 export declare function placementInfoFromLoopPlacement(placement: unknown, box: SandboxInstanceLike): PlacementInfo;
@@ -16,3 +16,9 @@ export declare function sessionStatusFromUnknown(status: unknown): AgentSessionS
  * "unknown" instead of fabricating an execution-scoped answer.
  */
 export declare function executionBoundSessionStatus(payload: unknown, executionId: string): AgentSessionStatus;
+/**
+ * Map the platform create receipt to the environment creation verdict. An
+ * `unknown` outcome, a null receipt, and an SDK without receipts all leave the
+ * verdict absent, so a consumer cannot read them as proof of creation.
+ */
+export declare function creationFromSandboxCreateReceipt(receipt: SandboxCreateReceiptLike | null | undefined): AgentEnvironmentCreation | undefined;

package/dist/tangle-environment-values.js

@@ -117,3 +117,24 @@ export function executionBoundSessionStatus(payload, executionId) {
         return sessionStatus;
     return "unknown";
 }
+/**
+ * Map the platform create receipt to the environment creation verdict. An
+ * `unknown` outcome, a null receipt, and an SDK without receipts all leave the
+ * verdict absent, so a consumer cannot read them as proof of creation.
+ */
+export function creationFromSandboxCreateReceipt(receipt) {
+    if (receipt === null || receipt === undefined)
+        return undefined;
+    switch (receipt.outcome) {
+        case "created":
+            return "created";
+        case "idempotent_replay":
+            return "replayed";
+        case "unknown":
+            return undefined;
+        default: {
+            const outcome = receipt.outcome;
+            throw new Error(`Tangle create receipt reported an unknown outcome: ${String(outcome)}`);
+        }
+    }
+}

package/dist/tangle-environment.js

@@ -3,7 +3,7 @@ import { AgentEnvironmentCapabilitiesSchema } from "@tangle-network/agent-interf
 import { environmentEventFromSandboxEvent } from "./tangle-events.js";
 import { executionIdFromTurnInput, promptFromTurnInput, promptOptionsFromTurnInput, } from "./tangle-prompt.js";
 import { resolveRetainedSessionControlRef } from "./tangle-session-control.js";
-import { placementInfoFromLoopPlacement, statusFromUnknown, } from "./tangle-environment-values.js";
+import { creationFromSandboxCreateReceipt, placementInfoFromLoopPlacement, statusFromUnknown, } from "./tangle-environment-values.js";
 import { execResultFromSandboxExecResult } from "./tangle-result-values.js";
 import { capabilitiesForSandbox, frozenCapabilityDocument, sandboxCapabilitySupport, } from "./tangle-capabilities.js";
 import { readDeploymentCapabilitySupport } from "./tangle-deployment-capabilities.js";
@@ -76,9 +76,11 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
         ...(options.signal ? { signal: options.signal } : {}),
         ...(options.controlRef ? { runControlRef: options.controlRef } : {}),
     });
+    const creation = creationFromSandboxCreateReceipt(box.createReceipt?.());
     return {
         id: environmentId,
         provider: providerName,
+        ...(creation === undefined ? {} : { creation }),
         ...(box.name ? { name: boundedString(box.name, "Tangle environment name") } : {}),
         ...(box.metadata ? { metadata: snapshotMetadata(box.metadata) } : {}),
         capabilities,

package/dist/tangle-provider.js

@@ -1,6 +1,6 @@
 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,12 +25,16 @@ 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.
@@ -184,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,6 +1,16 @@
-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";
+/**
+ * The platform verdict for the create call that returned a sandbox.
+ * `created` means the call allocated the sandbox; `idempotent_replay` means an
+ * earlier call with the same idempotency key allocated it; `unknown` means the
+ * platform cannot prove either outcome.
+ */
+export interface SandboxCreateReceiptLike {
+    outcome: "created" | "idempotent_replay" | "unknown";
+    idempotencyKeyApplied: boolean;
+}
 export interface TangleExactProcessOptions {
     teamId?: string;
 }
@@ -20,6 +30,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>;
@@ -363,6 +377,12 @@ export interface SandboxInstanceLike {
     resourceUsage?(): Promise<SandboxResourceUsageLike | null>;
     /** Interactive terminal transport. Absent on a client that cannot serve a PTY. */
     terminals?: SandboxTerminalsLike;
+    /**
+     * The platform verdict for the create call that returned this instance.
+     * Absent on a Sandbox SDK older than 0.30.1; null for an instance resolved
+     * by id or when the platform reported no receipt.
+     */
+    createReceipt?(): SandboxCreateReceiptLike | null;
     refresh?(options?: {
         signal?: AbortSignal;
     }): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.12.3",
+  "version": "0.13.1",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -85,10 +85,10 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^1.0.1"
+    "@tangle-network/agent-interface": "^1.4.0"
   },
   "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.3"
+    "@tangle-network/agent-provider-testkit": "0.8.4"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",