@tangle-network/agent-provider-tangle 1.2.1 → 1.2.2

package/README.md

@@ -29,6 +29,37 @@ const provider = createTangleProvider({
 `Sandbox` requires an explicit `baseUrl`.
 Set `TANGLE_SANDBOX_URL` to use another deployment.
 
+## Named model credentials at creation
+
+`modelCredentials` sends a stored credential reference and explicit endpoint before Sandbox provisions the backend.
+This uses Sandbox's existing caller-owned model credential path instead of requesting a managed Router credential.
+The provider does not create, grant, copy, or renew secrets.
+Each create must list the named secret explicitly.
+
+```ts
+const provider = createTangleProvider({
+  client,
+  modelCredentials: {
+    apiKeyEnv: "RESEARCH_ROUTER_KEY",
+    baseUrl: "https://router.tangle.tools/v1",
+  },
+});
+const environment = await provider.create({
+  profile: researchProfile,
+  secrets: ["RESEARCH_ROUTER_KEY"],
+});
+```
+
+The configuration accepts only the reference and endpoint, not credential values or model selection.
+The authored profile, selected backend, runtime attachments, and create identity remain unchanged.
+The provider snapshots this configuration when constructed and refuses combining it with `mapCreateInput`.
+Omitting it preserves managed creation.
+The endpoint must use HTTP or HTTPS without credentials, query parameters, or fragments.
+
+Credential-only turns retain the created SDK handle's endpoint and attachments.
+Reconstructed handles leave omitted model settings to Sandbox's durable backend configuration.
+Keep the stored secret available and valid throughout execution and recovery.
+
 ## `create()` returns a ready environment
 
 `provider.create()` does not return until the sandbox reports `running`.

package/dist/tangle-create-options.d.ts

@@ -1,6 +1,8 @@
 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;
+import type { TangleProviderOptions } from "./tangle-types.js";
+export declare function captureModelCredentials(value: TangleProviderOptions["modelCredentials"]): TangleProviderOptions["modelCredentials"];
+export declare function sandboxOptionsFromCreateInput(input: CreateAgentEnvironmentInput, defaultBackend?: BackendType, parsedWorkspace?: WorkspaceRequest, modelCredentials?: TangleProviderOptions["modelCredentials"]): 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

@@ -3,13 +3,44 @@ import { AgentEnvironmentEgressPolicySchema, WorkspaceRequestSchema, workspaceCw
 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) {
+export function captureModelCredentials(value) {
+    if (value === undefined)
+        return undefined;
+    assertBoundedJson(value);
+    if (!value || typeof value !== "object" || Array.isArray(value) ||
+        Object.keys(value).some((key) => key !== "apiKeyEnv" && key !== "baseUrl")) {
+        throw new Error("Tangle modelCredentials accepts only apiKeyEnv and baseUrl");
+    }
+    const { apiKeyEnv, baseUrl } = value;
+    if (typeof apiKeyEnv !== "string" || apiKeyEnv.length > 128 ||
+        !/^[A-Z_][A-Z0-9_]*$/.test(apiKeyEnv)) {
+        throw new Error("Tangle modelCredentials apiKeyEnv must be a stored secret name");
+    }
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        throw new Error("Tangle modelCredentials baseUrl must be an HTTP(S) endpoint");
+    }
+    if (typeof baseUrl !== "string" || baseUrl.length > 2048 || /\s/.test(baseUrl) ||
+        !["http:", "https:"].includes(url.protocol) ||
+        url.username || url.password || url.search || url.hash) {
+        throw new Error("Tangle modelCredentials baseUrl must be an HTTP(S) endpoint without credentials, query, or fragment");
+    }
+    return Object.freeze({ apiKeyEnv, baseUrl });
+}
+export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorkspace, modelCredentials) {
     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 (modelCredentials !== undefined &&
+        (!Array.isArray(input.secrets) || !input.secrets.includes(modelCredentials.apiKeyEnv))) {
+        throw new Error("Tangle modelCredentials apiKeyEnv must be explicitly listed in create secrets");
+    }
     if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
         throw new Error("Tangle create providerOptions are not supported");
     }
@@ -71,6 +102,7 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend, parsedWorks
             ...(base.backend ?? {}),
             type: backend,
             profile,
+            ...(modelCredentials === undefined ? {} : { model: modelCredentials }),
             ...(input.runtimeAttachments === undefined ? {} : {
                 runtimeAttachments: tangleRuntimeAttachments(input.runtimeAttachments, profile),
             }),

package/dist/tangle-provider.js

@@ -4,12 +4,17 @@ import { createTangleExactProcessProvider, } from "./exact-process.js";
 import { capabilitiesForClient, defaultTangleSandboxCapabilities, narrowTangleCapabilitiesToBackend, } from "./tangle-capabilities.js";
 import { sandboxInstanceAsEnvironment } from "./tangle-environment.js";
 import { confidentialVerifierOption, createTangleWorkspaceBranching, } from "./tangle-workspace-branching.js";
-import { assertCreateInputShape, assertMappedCreateOptions, assertMappedSecretNames, assertNoInlineSecretValues, sandboxOptionsFromCreateInput } from "./tangle-create-options.js";
+import { assertCreateInputShape, assertMappedCreateOptions, assertMappedSecretNames, assertNoInlineSecretValues, captureModelCredentials, sandboxOptionsFromCreateInput } from "./tangle-create-options.js";
 import { statusFromUnknown } from "./tangle-environment-values.js";
 import { awaitSandboxRunning, DEFAULT_TANGLE_READY_TIMEOUT_MS, } from "./tangle-readiness.js";
 import { requestedResourceProfile } from "./tangle-resources.js";
 import { assertBoundedJson, attachCleanupHandle, awaitWithSignal, boundedIdentifier, boundedString, MAX_LIST_RESULTS, SANDBOX_LIST_PAGE_SIZE, } from "./tangle-contract-safety.js";
 export function createTangleProvider(options) {
+    const modelCredentials = captureModelCredentials(options.modelCredentials);
+    const mapCreateInput = options.mapCreateInput;
+    if (modelCredentials !== undefined && mapCreateInput !== undefined) {
+        throw new Error("Tangle modelCredentials cannot be combined with mapCreateInput");
+    }
     const providerName = options.name ?? "tangle-sandbox";
     boundedIdentifier(providerName, "Tangle provider name");
     const readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_TANGLE_READY_TIMEOUT_MS;
@@ -57,8 +62,8 @@ export function createTangleProvider(options) {
         if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
             throw new Error("Tangle create providerOptions are not supported");
         }
-        const mappedOptions = options.mapCreateInput?.(input) ??
-            sandboxOptionsFromCreateInput(input, options.defaultBackend, parsedWorkspace);
+        const mappedOptions = mapCreateInput?.(input) ??
+            sandboxOptionsFromCreateInput(input, options.defaultBackend, parsedWorkspace, modelCredentials);
         assertMappedCreateOptions(mappedOptions);
         const createOptions = deepFreeze(structuredClone(mappedOptions));
         if (input.idempotencyKey !== undefined &&

package/dist/tangle-types.d.ts

@@ -586,6 +586,15 @@ export interface TangleProviderOptions {
     name?: string;
     /** Overrides an inline profile's harness when create() names no backend. */
     defaultBackend?: BackendType;
+    /**
+     * Stored model credential and endpoint used by the default create mapping.
+     * Each create must explicitly list apiKeyEnv in its secrets.
+     * Cannot be combined with mapCreateInput; never accepts credential values.
+     */
+    modelCredentials?: {
+        apiKeyEnv: string;
+        baseUrl: string;
+    };
     capabilities?: AgentEnvironmentCapabilities | (() => AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>);
     validateProfile?: AgentEnvironmentProvider["validateProfile"];
     /** Replaces the default mapping, including its backend and profile selection. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",