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

package/README.md

@@ -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.

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