@tangle-network/agent-provider-tangle 1.1.3 → 1.1.5

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.36.4.
+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.
@@ -36,7 +36,9 @@ const provider = createTangleProvider({
   readyTimeoutMs: 180_000,
 });
 
-const environment = await provider.create({ profile: { name: "worker" } });
+const environment = await provider.create({
+  profile: { name: "worker", harness: "codex" },
+});
 for await (const event of environment.stream({ prompt: "run the task" })) {
   // The sandbox is running. No caller-side wait, poll, or retry stands here.
 }
@@ -50,6 +52,14 @@ A client that offers neither cannot prove readiness, so the sandbox it returned
 The adapter reads the platform's answer back rather than trusting the wait to have resolved for the right reason.
 A create call returns only a sandbox that reports `running`: `failed`, `stopped`, and `expired` are refused with the status named, and so is a wait that resolves while the sandbox still reports `provisioning`.
 
+The default create mapping selects `create()`'s `backend`, then the provider's `defaultBackend`, then the inline profile's `harness`.
+An inline profile therefore carries its own backend unless the caller records an execution override.
+Profiles without a harness retain the provider's legacy OpenCode fallback.
+A configured `mapCreateInput` owns the Sandbox options and may select another backend or profile.
+The created environment's capabilities use that mapping's backend; provider capabilities describe the configured default.
+`get(id)` reads the running sandbox's backend status.
+If that status is unavailable, the reconstructed environment advertises no backend-specific capabilities.
+
 ## Per-turn backend options
 
 `AgentTurnInput.providerOptions.backend` reaches `PromptOptions.backend` on the Sandbox prompt call.
@@ -119,6 +129,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.
@@ -333,6 +344,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-create-options.d.ts

@@ -1,6 +1,6 @@
-import type { BackendType, CreateSandboxOptions } from "@tangle-network/sandbox";
+import { type BackendType, type CreateSandboxOptions } from "@tangle-network/sandbox";
 import type { CreateAgentEnvironmentInput, WorkspaceRequest } from "@tangle-network/agent-interface/environment-provider";
-export declare function sandboxOptionsFromCreateInput(input: CreateAgentEnvironmentInput, defaultBackend: BackendType, parsedWorkspace?: WorkspaceRequest): CreateSandboxOptions;
+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, parsedWorkspace?: WorkspaceRequest): void;
 /** A custom mapper must not smuggle a value map into the Sandbox request. */

package/dist/tangle-create-options.js

@@ -1,8 +1,13 @@
+import { parseBackendType, } from "@tangle-network/sandbox";
 import { AgentEnvironmentEgressPolicySchema, 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, parsedWorkspace) {
     const workspace = assertCreateInputShape(input, parsedWorkspace) ?? {};
+    const profile = inlineAgentProfile(input.profile);
+    const backend = input.backend === undefined
+        ? parseBackendType(defaultBackend ?? profile.harness ?? "opencode")
+        : input.backend;
     assertNoInlineSecretValues(input, workspace);
     if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
         throw new Error("Tangle create providerOptions are not supported");
@@ -63,8 +68,8 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorks
         ...(input.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
         backend: {
             ...(base.backend ?? {}),
-            type: (input.backend ?? defaultBackend),
-            profile: inlineAgentProfile(input.profile),
+            type: backend,
+            profile,
         },
     };
     return mapped;

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-provider.js

@@ -1,4 +1,5 @@
 import { AgentEnvironmentCapabilitiesSchema, createAgentEnvironmentWithIdempotency, } from "@tangle-network/agent-interface/environment-provider";
+import { deepFreeze, harnessTypeSchema } from "@tangle-network/agent-interface";
 import { createTangleExactProcessProvider, } from "./exact-process.js";
 import { capabilitiesForClient, defaultTangleSandboxCapabilities, narrowTangleCapabilitiesToBackend, } from "./tangle-capabilities.js";
 import { sandboxInstanceAsEnvironment } from "./tangle-environment.js";
@@ -23,18 +24,19 @@ export function createTangleProvider(options) {
             readyTimeoutMs,
         })
         : undefined;
-    const resolveDeclaredCapabilities = async () => {
+    const resolveDeclaredCapabilities = async (backendType) => {
+        const harness = harnessTypeSchema.safeParse(backendType);
         const configured = options.capabilities
             ? typeof options.capabilities === "function"
                 ? await options.capabilities()
                 : options.capabilities
-            : defaultTangleSandboxCapabilities();
+            : defaultTangleSandboxCapabilities(harness.success ? harness.data : undefined);
         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);
+            : await resolveBackend(options.client, backendType);
         const narrowed = narrowTangleCapabilitiesToBackend(configured, backend);
         return exactProcess
             ? {
@@ -46,7 +48,7 @@ export function createTangleProvider(options) {
     // 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, confidentialVerifierOption(options.confidentialAttestationVerifier)));
-    const resolveCapabilities = async () => narrowedProviderCapabilities(await resolveDeclaredCapabilities());
+    const resolveCapabilities = async () => narrowedProviderCapabilities(await resolveDeclaredCapabilities(options.defaultBackend));
     const createRecords = new Map();
     const createEnvironment = async (input) => {
         const parsedWorkspace = assertCreateInputShape(input);
@@ -55,19 +57,19 @@ export function createTangleProvider(options) {
         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", parsedWorkspace);
-        assertMappedCreateOptions(createOptions);
+        const mappedOptions = options.mapCreateInput?.(input) ??
+            sandboxOptionsFromCreateInput(input, options.defaultBackend, parsedWorkspace);
+        assertMappedCreateOptions(mappedOptions);
+        const createOptions = deepFreeze(structuredClone(mappedOptions));
         if (input.idempotencyKey !== undefined &&
             createOptions.idempotencyKey !== input.idempotencyKey) {
             throw new Error("Tangle mapped create options must preserve input idempotencyKey");
         }
         assertMappedSecretNames(createOptions);
+        // Backend selection belongs to the create projection. The provider-wide
+        // default cannot describe a sandbox that this projection routes elsewhere.
+        const declaredCapabilities = await resolveDeclaredCapabilities(createOptions.backend?.type);
+        narrowedProviderCapabilities(declaredCapabilities);
         input.signal?.throwIfAborted();
         const createPromise = options.client.create(createOptions, input.signal ? { signal: input.signal } : undefined);
         let box;
@@ -155,21 +157,43 @@ export function createTangleProvider(options) {
         ...(workspaceBranching === undefined ? {} : { workspaceBranching }),
         capabilities: resolveCapabilities,
         ...(options.validateProfile ? { validateProfile: options.validateProfile } : {}),
-        create(input) {
-            return createAgentEnvironmentWithIdempotency(createRecords, input, () => createEnvironment(input));
+        async create(input) {
+            const { signal, ...material } = input;
+            signal?.throwIfAborted();
+            assertCreateInputShape(input);
+            assertNoInlineSecretValues(input);
+            for (const value of Object.values(material)) {
+                if (value !== undefined)
+                    assertBoundedJson(value);
+            }
+            const acceptedInput = Object.freeze({
+                ...deepFreeze(structuredClone(material)),
+                ...(signal === undefined ? {} : { signal }),
+            });
+            return createAgentEnvironmentWithIdempotency(createRecords, acceptedInput, createEnvironment);
         },
         ...(options.client.get
             ? {
                 async get(id, operation) {
                     assertProviderOperationOptions(operation, "Tangle get");
                     boundedIdentifier(id, "Tangle environment id");
-                    const declaredCapabilities = await resolveDeclaredCapabilities();
-                    narrowedProviderCapabilities(declaredCapabilities);
+                    await resolveCapabilities();
                     operation?.signal?.throwIfAborted();
                     const box = await awaitWithSignal(options.client.get?.(id, operation), operation?.signal);
                     operation?.signal?.throwIfAborted();
                     if (!box || boundedIdentifier(box.id, "Tangle environment id") !== id)
                         return null;
+                    let backendType;
+                    if (box.status === "running" && box.backend) {
+                        try {
+                            const status = await awaitWithSignal(box.backend.status(), operation?.signal);
+                            backendType = boundedIdentifier(status.type, "Tangle current backend");
+                        }
+                        catch {
+                            operation?.signal?.throwIfAborted();
+                        }
+                    }
+                    const declaredCapabilities = await resolveDeclaredCapabilities(backendType);
                     return await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, operation?.signal ? { signal: operation.signal } : undefined, confidentialVerifierOption(options.confidentialAttestationVerifier));
                 },
             }
@@ -246,16 +270,16 @@ export function createTangleProvider(options) {
             : {}),
     };
 }
-async function resolveDefaultBackend(client, defaultBackend) {
-    if (defaultBackend === undefined)
+async function resolveBackend(client, backendType) {
+    if (backendType === undefined)
         return undefined;
     try {
         if (client.getBackend)
-            return await client.getBackend(defaultBackend);
+            return await client.getBackend(backendType);
         if (!client.listBackends)
             return undefined;
         const catalog = await client.listBackends();
-        return catalog.backends.find((backend) => backend.type === defaultBackend);
+        return catalog.backends.find((backend) => backend.type === backendType);
     }
     catch {
         return undefined;

package/dist/tangle-types.d.ts

@@ -391,6 +391,12 @@ export interface SandboxInstanceLike {
     name?: string;
     status?: unknown;
     metadata?: Record<string, unknown>;
+    /** Current backend reported by this sandbox's runtime. */
+    backend?: {
+        status(): Promise<{
+            type: string;
+        }>;
+    };
     /** Network location of the sandbox runtime, without its bearer. */
     connection?: SandboxConnectionLike;
     /** When the platform retires this sandbox, when it set a lifetime. */
@@ -578,9 +584,11 @@ export interface SandboxInteractionCommandResultLike {
 export interface TangleProviderOptions {
     client: SandboxClientLike;
     name?: string;
+    /** Overrides an inline profile's harness when create() names no backend. */
     defaultBackend?: BackendType;
     capabilities?: AgentEnvironmentCapabilities | (() => AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>);
     validateProfile?: AgentEnvironmentProvider["validateProfile"];
+    /** Replaces the default mapping, including its backend and profile selection. */
     mapCreateInput?: (input: CreateAgentEnvironmentInput) => CreateSandboxOptions;
     exactProcess?: TangleExactProcessOptions;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -91,7 +91,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^2.3.0"
+    "@tangle-network/agent-interface": "^2.3.1"
   },
   "peerDependencies": {
     "@tangle-network/sandbox": ">=0.34.6 <1.0.0"
@@ -102,13 +102,13 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/agent-eval": "0.173.0",
-    "@tangle-network/agent-runtime": "0.190.0",
-    "@tangle-network/sandbox": "0.36.4",
-    "@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.1"
+    "@tangle-network/agent-provider-testkit": "0.9.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",