@tangle-network/agent-provider-tangle 1.1.11 → 1.2.0

package/README.md

@@ -1,8 +1,16 @@
 # @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.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 peer range is `>=0.39.0 <1.0.0`, and this package is developed and tested against 0.39.0.
+The floor includes runtime MCP attachment transport and preservation across per-turn model credential overrides.
+
+Runtime MCP bindings travel through `CreateAgentEnvironmentInput.runtimeAttachments` to Sandbox's `backend.runtimeAttachments`.
+They remain separate from the authored profile and its digest.
+The adapter checks the selected backend catalog before provisioning and refuses missing attachment support.
+Disabled attachments and aliases present in the profile are refused, including disabled profile aliases.
+Per-turn backend overrides accept the same canonical attachment contract.
+Remote managers still require an authenticated coordination URL reachable from the Sandbox.
+Catalog support does not establish successful tool execution against a particular deployment.
 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.
 

package/dist/tangle-capabilities.d.ts

@@ -21,7 +21,7 @@ export declare function defaultTangleSandboxCapabilities(harness?: HarnessType):
  * 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;
+export declare function narrowTangleCapabilitiesToBackend(declared: AgentEnvironmentCapabilities, backend: BackendRegistryEntry | undefined, backendSelected?: boolean): 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

@@ -100,6 +100,7 @@ export function defaultTangleSandboxCapabilities(harness) {
         create: {
             egress: ["open", "strict", "blocked"],
             billingOwner: true,
+            runtimeAttachments: { mcp: true },
         },
         // This is intent only. Narrowing requires both raw TEE evidence and the
         // caller's external provider-key verifier before the flag survives.
@@ -144,7 +145,11 @@ export function defaultTangleSandboxCapabilities(harness) {
  * 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) {
+export function narrowTangleCapabilitiesToBackend(declared, backend, backendSelected = true) {
+    if (backendSelected && backend?.capabilities.runtimeAttachments?.mcp !== true && declared.create?.runtimeAttachments !== undefined) {
+        const { runtimeAttachments: _runtimeAttachments, ...create } = declared.create;
+        declared = { ...declared, create };
+    }
     if (declared.interactions === undefined || backend === undefined) {
         if (declared.interactions === undefined)
             return declared;

package/dist/tangle-create-options.js

@@ -2,6 +2,7 @@ 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";
+import { tangleRuntimeAttachments } from "./tangle-runtime-attachments.js";
 export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorkspace) {
     const workspace = assertCreateInputShape(input, parsedWorkspace) ?? {};
     const profile = inlineAgentProfile(input.profile);
@@ -70,6 +71,9 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorks
             ...(base.backend ?? {}),
             type: backend,
             profile,
+            ...(input.runtimeAttachments === undefined ? {} : {
+                runtimeAttachments: tangleRuntimeAttachments(input.runtimeAttachments, profile),
+            }),
         },
     };
     return mapped;
@@ -164,10 +168,14 @@ export function assertCreateInputShape(input, parsedWorkspace) {
         "idempotencyKey",
         "signal",
         "providerOptions",
+        "runtimeAttachments",
     ])
         keys.delete(key);
     if (keys.size > 0)
         throw new Error("Tangle create input contains unsupported fields");
+    if (input.runtimeAttachments !== undefined) {
+        tangleRuntimeAttachments(input.runtimeAttachments, typeof input.profile === "object" ? input.profile : undefined);
+    }
     if (typeof input.profile === "string") {
         boundedIdentifier(input.profile, "Tangle profile reference");
     }
@@ -198,6 +206,9 @@ export function assertMappedCreateOptions(options) {
         throw new Error("Tangle mapped create options must be an object");
     }
     assertBoundedJson(options);
+    if (options.backend?.runtimeAttachments !== undefined) {
+        tangleRuntimeAttachments(options.backend.runtimeAttachments, options.backend.profile);
+    }
     if (Object.hasOwn(options, "providerOptions")) {
         throw new Error("Tangle mapped create providerOptions are not supported");
     }

package/dist/tangle-prompt.d.ts

@@ -17,7 +17,7 @@ export declare function promptOptionsFromTurnInput(input: AgentTurnInput, target
  * anywhere, which is the silent substitution the SDK's own `model` field
  * exists to prevent.
  */
-declare const SANDBOX_BACKEND_FIELD_LIST: readonly ["type", "profile", "model", "server", "interactions", "metadata"];
+declare const SANDBOX_BACKEND_FIELD_LIST: readonly ["runtimeAttachments", "type", "profile", "model", "server", "interactions", "metadata"];
 /**
  * The `BackendConfig["model"]` fields the Sandbox prompt options declare.
  *

package/dist/tangle-prompt.js

@@ -1,6 +1,7 @@
 import { agentProfileSchema, CONTRACT_MAX_JSON_BYTES, boundedEventContentRecordSchema, isBoundedEventContentJson, AgentExactRunControlRefSchema, AgentTurnInputSchema, ContextTransferReceiptSchema, contextTransferResultMatchesRequest, } from "@tangle-network/agent-interface";
 import { tokenUsageFromData } from "./tangle-result-values.js";
 import { assertBoundedJson, boundedString } from "./tangle-contract-safety.js";
+import { tangleRuntimeAttachments } from "./tangle-runtime-attachments.js";
 export function promptFromTurnInput(input) {
     AgentTurnInputSchema.parse(input);
     if (input.parts)
@@ -67,6 +68,7 @@ export function promptOptionsFromTurnInput(input, target) {
  * exists to prevent.
  */
 const SANDBOX_BACKEND_FIELD_LIST = [
+    "runtimeAttachments",
     "type",
     "profile",
     "model",
@@ -138,6 +140,11 @@ function sandboxPromptBackend(value) {
             ? {}
             : { metadata: sandboxPromptBackendMetadata(present.metadata) }),
     };
+    if (present.runtimeAttachments !== undefined) {
+        Object.assign(backend, {
+            runtimeAttachments: tangleRuntimeAttachments(present.runtimeAttachments, backend.profile),
+        });
+    }
     assertBoundedJson(backend);
     return backend;
 }

package/dist/tangle-provider.js

@@ -1,5 +1,5 @@
 import { AgentEnvironmentCapabilitiesSchema, createAgentEnvironmentWithIdempotency, } from "@tangle-network/agent-interface/environment-provider";
-import { deepFreeze, harnessTypeSchema } from "@tangle-network/agent-interface";
+import { canonicalCandidateDigest, 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";
@@ -34,10 +34,10 @@ export function createTangleProvider(options) {
         if (!exactProcess && configured.exactProcess) {
             throw new Error("Tangle capabilities cannot advertise exactProcess without exactProcess configuration");
         }
-        const backend = configured.interactions === undefined
+        const backend = configured.interactions === undefined && configured.create?.runtimeAttachments === undefined
             ? undefined
             : await resolveBackend(options.client, backendType);
-        const narrowed = narrowTangleCapabilitiesToBackend(configured, backend);
+        const narrowed = narrowTangleCapabilitiesToBackend(configured, backend, backendType !== undefined);
         return exactProcess
             ? {
                 ...narrowed,
@@ -66,10 +66,20 @@ export function createTangleProvider(options) {
             throw new Error("Tangle mapped create options must preserve input idempotencyKey");
         }
         assertMappedSecretNames(createOptions);
+        if (input.runtimeAttachments !== undefined &&
+            (createOptions.backend?.runtimeAttachments === undefined ||
+                canonicalCandidateDigest(input.runtimeAttachments) !== canonicalCandidateDigest(createOptions.backend.runtimeAttachments))) {
+            throw new Error("Tangle mapped create options must preserve runtime attachments");
+        }
         // 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);
+        if (createOptions.backend?.runtimeAttachments !== undefined) {
+            if (createOptions.backend.type === undefined || declaredCapabilities.create?.runtimeAttachments?.mcp !== true) {
+                throw new Error("Tangle runtime attachments are not supported by the selected backend deployment");
+            }
+        }
         input.signal?.throwIfAborted();
         const createPromise = options.client.create(createOptions, input.signal ? { signal: input.signal } : undefined);
         let box;

package/dist/tangle-runtime-attachments.d.ts

@@ -0,0 +1,3 @@
+import { type AgentProfile, type AgentRuntimeAttachments } from "@tangle-network/agent-interface";
+/** Runtime bindings retain their own identity and cannot replace profile tools. */
+export declare function tangleRuntimeAttachments(value: unknown, profile?: AgentProfile): AgentRuntimeAttachments;

package/dist/tangle-runtime-attachments.js

@@ -0,0 +1,14 @@
+import { AgentRuntimeAttachmentsSchema, } from "@tangle-network/agent-interface";
+/** Runtime bindings retain their own identity and cannot replace profile tools. */
+export function tangleRuntimeAttachments(value, profile) {
+    const attachments = AgentRuntimeAttachmentsSchema.parse(value);
+    for (const [alias, server] of Object.entries(attachments.mcp)) {
+        if (server.enabled === false) {
+            throw new Error(`Tangle runtime MCP attachment cannot be disabled: ${alias}`);
+        }
+        if (Object.hasOwn(profile?.mcp ?? {}, alias)) {
+            throw new Error(`Tangle runtime MCP attachment conflicts with profile: ${alias}`);
+        }
+    }
+    return attachments;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.1.11",
+  "version": "1.2.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -43,6 +43,8 @@
     "dist/tangle-deployment-capabilities.js",
     "dist/tangle-create-options.d.ts",
     "dist/tangle-create-options.js",
+    "dist/tangle-runtime-attachments.d.ts",
+    "dist/tangle-runtime-attachments.js",
     "dist/tangle-environment-values.d.ts",
     "dist/tangle-environment-values.js",
     "dist/tangle-environment.d.ts",
@@ -98,7 +100,7 @@
     "@tangle-network/agent-interface": "^2.6.1"
   },
   "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.34.6 <1.0.0"
+    "@tangle-network/sandbox": ">=0.39.0 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {
@@ -108,7 +110,7 @@
   "devDependencies": {
     "@tangle-network/agent-eval": "0.173.1",
     "@tangle-network/agent-runtime": "0.192.2",
-    "@tangle-network/sandbox": "0.37.0",
+    "@tangle-network/sandbox": "0.39.0",
     "@types/node": "26.4.1",
     "typescript": "7.0.2",
     "vitest": "4.1.11",