@tangle-network/agent-provider-tangle 0.5.1 → 0.6.0

package/dist/tangle-capabilities.d.ts

@@ -0,0 +1,39 @@
+import type { AgentEnvironmentCapabilities, HarnessType } from "@tangle-network/agent-interface";
+import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
+/**
+ * The full capability document this adapter supports when the Sandbox client
+ * implements every optional method.
+ *
+ * This is an upper bound, not a claim. `capabilitiesForSandbox()` narrows it
+ * to what a specific client actually exposes, because a capability the client
+ * cannot back becomes an action the caller selects and finds missing.
+ */
+export declare function defaultTangleSandboxCapabilities(harness?: HarnessType): AgentEnvironmentCapabilities;
+/** Optional methods whose absence must clear the matching declared capability. */
+export interface SandboxCapabilitySupport {
+    dispatchPrompt: boolean;
+    session: boolean;
+    read: boolean;
+    write: boolean;
+    exec: boolean;
+    checkpoint: boolean;
+    fork: boolean;
+    placement: boolean;
+    destroy: boolean;
+}
+export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, client: SandboxClientLike): SandboxCapabilitySupport;
+/**
+ * Narrow provider-level claims to capabilities the client can actually back.
+ *
+ * A client without placement metadata cannot satisfy placement(), and this
+ * adapter has no durable branching, interaction, or native-continuation
+ * implementation regardless of an overly broad configured document.
+ */
+export declare function capabilitiesForClient(declared: AgentEnvironmentCapabilities, client: SandboxClientLike): AgentEnvironmentCapabilities;
+/**
+ * Narrow a declared capability document to what this Sandbox instance backs.
+ *
+ * Braid derives product actions from these flags, so an over-claimed flag is
+ * an offered action that throws at the moment the user selects it.
+ */
+export declare function capabilitiesForSandbox(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport): AgentEnvironmentCapabilities;

package/dist/tangle-capabilities.js

@@ -0,0 +1,140 @@
+import { harnessSystemPromptIntents } from "@tangle-network/agent-interface";
+/**
+ * The full capability document this adapter supports when the Sandbox client
+ * implements every optional method.
+ *
+ * This is an upper bound, not a claim. `capabilitiesForSandbox()` narrows it
+ * to what a specific client actually exposes, because a capability the client
+ * cannot back becomes an action the caller selects and finds missing.
+ */
+export function defaultTangleSandboxCapabilities(harness) {
+    return {
+        profile: {
+            namedProfiles: true,
+            systemPrompt: harnessSystemPromptIntents(harness),
+            instructions: true,
+            tools: true,
+            permissions: true,
+            mcp: true,
+            subagents: true,
+            resources: {
+                files: true,
+                instructions: true,
+                tools: true,
+                skills: true,
+                agents: true,
+                commands: true,
+            },
+            hooks: true,
+            modes: true,
+            runtimeUpdate: true,
+            validation: true,
+        },
+        streaming: { live: true, replay: true, detach: true, turnIdempotency: true },
+        // A Sandbox session id is not a Braid context-boundary proof. Native
+        // continuation stays unavailable until this adapter can verify one.
+        sessions: { continue: false, list: false, messages: false },
+        workspace: { read: true, write: true, exec: true, git: false, upload: true, download: true },
+        branching: { checkpoint: false, fork: false },
+        placement: true,
+        usage: false,
+        // Confidential execution needs verified attestation evidence, which this
+        // adapter does not yet obtain, so it is never declared by default.
+        confidential: false,
+    };
+}
+export function sandboxCapabilitySupport(box, client) {
+    return {
+        dispatchPrompt: typeof box.dispatchPrompt === "function",
+        session: typeof box.session === "function",
+        read: typeof box.read === "function",
+        write: typeof box.write === "function",
+        exec: typeof box.exec === "function",
+        checkpoint: typeof box.checkpoint === "function",
+        fork: typeof box.fork === "function",
+        placement: typeof client.describePlacement === "function",
+        destroy: typeof box.delete === "function",
+    };
+}
+/**
+ * Narrow provider-level claims to capabilities the client can actually back.
+ *
+ * A client without placement metadata cannot satisfy placement(), and this
+ * adapter has no durable branching, interaction, or native-continuation
+ * implementation regardless of an overly broad configured document.
+ */
+export function capabilitiesForClient(declared, client) {
+    const narrowed = {
+        ...declared,
+        streaming: {
+            ...declared.streaming,
+            replay: declared.streaming.replay,
+            detach: declared.streaming.detach,
+            turnIdempotency: declared.streaming.turnIdempotency,
+        },
+        sessions: { ...declared.sessions, continue: false, list: false, messages: false },
+        workspace: { ...declared.workspace, git: false },
+        usage: false,
+        branching: {
+            ...declared.branching,
+            checkpoint: false,
+            fork: false,
+            ...(declared.branching.retrySafe !== undefined ? { retrySafe: false } : {}),
+            ...(declared.branching.lookup !== undefined ? { lookup: false } : {}),
+            ...(declared.branching.cleanup !== undefined ? { cleanup: false } : {}),
+        },
+        placement: declared.placement && typeof client.describePlacement === "function",
+    };
+    delete narrowed.interactions;
+    delete narrowed.retainedControl;
+    delete narrowed.nativeContinuation;
+    return narrowed;
+}
+/**
+ * Narrow a declared capability document to what this Sandbox instance backs.
+ *
+ * Braid derives product actions from these flags, so an over-claimed flag is
+ * an offered action that throws at the moment the user selects it.
+ */
+export function capabilitiesForSandbox(declared, support) {
+    const narrowed = { ...declared };
+    delete narrowed.interactions;
+    delete narrowed.retainedControl;
+    delete narrowed.nativeContinuation;
+    return {
+        ...narrowed,
+        streaming: {
+            ...declared.streaming,
+            detach: declared.streaming.detach && support.dispatchPrompt,
+            replay: declared.streaming.replay && support.session,
+            turnIdempotency: declared.streaming.turnIdempotency && support.session,
+        },
+        sessions: {
+            ...declared.sessions,
+            continue: false,
+            list: false,
+            messages: false,
+        },
+        workspace: {
+            ...declared.workspace,
+            read: declared.workspace.read && support.read,
+            write: declared.workspace.write && support.write,
+            exec: declared.workspace.exec && support.exec,
+            git: false,
+            upload: declared.workspace.upload && support.write,
+            download: declared.workspace.download && support.read,
+        },
+        branching: {
+            ...narrowed.branching,
+            checkpoint: false,
+            fork: false,
+            ...(declared.branching.retrySafe !== undefined
+                ? { retrySafe: false }
+                : {}),
+            ...(declared.branching.lookup !== undefined ? { lookup: false } : {}),
+            ...(declared.branching.cleanup !== undefined ? { cleanup: false } : {}),
+        },
+        placement: narrowed.placement && support.placement,
+        usage: false,
+    };
+}

package/dist/tangle-contract-safety.d.ts

@@ -0,0 +1,19 @@
+import type { CreateAgentExactProcessEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import type { TangleExactProcessOptions } from "./tangle-types.js";
+export declare const MAX_EXACT_FILE_BYTES: number;
+export declare const MAX_LIST_RESULTS = 100000;
+export declare const MAX_IDENTIFIER_LENGTH = 512;
+export declare const MAX_STRING_LENGTH = 16384;
+export declare const MAX_ARRAY_LENGTH = 1024;
+export declare const MAX_MAP_ENTRIES = 256;
+export declare const MAX_JSON_DEPTH = 16;
+export declare const MAX_JSON_NODES = 8192;
+export declare function boundedIdentifier(value: unknown, label: string): string;
+export declare function boundedString(value: unknown, label: string): string;
+export declare function isBoundedJson(value: unknown): boolean;
+export declare function assertBoundedJson(value: unknown): void;
+/** Keep a late-created provider handle reachable when an abort wins the race. */
+export declare function attachCleanupHandle(error: unknown, handle: unknown, cleanupError?: unknown): void;
+export declare function exactProcessRequestDigest(input: CreateAgentExactProcessEnvironmentInput, providerName: string, options: TangleExactProcessOptions): `sha256:${string}`;
+export declare function validateExactProcessCreateInput(input: CreateAgentExactProcessEnvironmentInput, providerName: string, options: TangleExactProcessOptions): void;
+export declare function awaitWithSignal<T>(operation: Promise<T> | T | undefined, signal?: AbortSignal): Promise<T>;

package/dist/tangle-contract-safety.js

@@ -0,0 +1,240 @@
+import { canonicalCandidateDigest } from "@tangle-network/agent-interface";
+export const MAX_EXACT_FILE_BYTES = 64 * 1024 * 1024;
+export const MAX_LIST_RESULTS = 100_000;
+export const MAX_IDENTIFIER_LENGTH = 512;
+export const MAX_STRING_LENGTH = 16_384;
+export const MAX_ARRAY_LENGTH = 1_024;
+export const MAX_MAP_ENTRIES = 256;
+export const MAX_JSON_DEPTH = 16;
+export const MAX_JSON_NODES = 8_192;
+const IMMUTABLE_TANGLE_IMAGE = /^(?:sha256:[a-f0-9]{64}|\S+@sha256:[a-f0-9]{64})$/i;
+export function boundedIdentifier(value, label) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_IDENTIFIER_LENGTH ||
+        value.trim() !== value) {
+        throw new Error(`${label} is invalid`);
+    }
+    return value;
+}
+export function boundedString(value, label) {
+    if (typeof value !== "string" || value.length > MAX_STRING_LENGTH) {
+        throw new Error(`${label} exceeds its bound`);
+    }
+    return value;
+}
+export function isBoundedJson(value) {
+    const pending = [
+        { value, depth: 0 },
+    ];
+    const ancestors = new Set();
+    let nodes = 0;
+    while (pending.length > 0) {
+        const item = pending.pop();
+        if (!item)
+            continue;
+        nodes += 1;
+        if (nodes > MAX_JSON_NODES)
+            return false;
+        const current = item.value;
+        if (item.leave) {
+            ancestors.delete(current);
+            continue;
+        }
+        if (current === undefined)
+            return false;
+        if (current === null || typeof current === "boolean")
+            continue;
+        if (typeof current === "string") {
+            if (current.length > MAX_STRING_LENGTH)
+                return false;
+            continue;
+        }
+        if (typeof current === "number") {
+            if (!Number.isFinite(current))
+                return false;
+            continue;
+        }
+        if (typeof current !== "object" ||
+            item.depth >= MAX_JSON_DEPTH ||
+            ancestors.has(current))
+            return false;
+        ancestors.add(current);
+        pending.push({ value: current, depth: item.depth, leave: true });
+        if (Array.isArray(current)) {
+            if (current.length > MAX_ARRAY_LENGTH)
+                return false;
+            for (const entry of current)
+                pending.push({ value: entry, depth: item.depth + 1 });
+            continue;
+        }
+        if (Object.getPrototypeOf(current) !== Object.prototype && Object.getPrototypeOf(current) !== null)
+            return false;
+        const keys = Object.keys(current);
+        if (keys.length > MAX_MAP_ENTRIES ||
+            keys.some((key) => key.length > MAX_IDENTIFIER_LENGTH))
+            return false;
+        for (const key of keys)
+            pending.push({ value: current[key], depth: item.depth + 1 });
+    }
+    return true;
+}
+export function assertBoundedJson(value) {
+    if (!isBoundedJson(value))
+        throw new Error("value exceeds its JSON bound");
+}
+/** Keep a late-created provider handle reachable when an abort wins the race. */
+export function attachCleanupHandle(error, handle, cleanupError) {
+    if ((typeof error !== "object" || error === null) &&
+        typeof error !== "function")
+        return;
+    try {
+        Object.assign(error, {
+            cleanupHandle: handle,
+            ...(cleanupError === undefined ? {} : { cleanupError }),
+        });
+    }
+    catch {
+        // A non-extensible provider error cannot carry the handle; the operation
+        // still remains rejected rather than pretending cleanup completed.
+    }
+}
+export function exactProcessRequestDigest(input, providerName, options) {
+    validateExactProcessCreateInput(input, providerName, options);
+    assertBoundedJson(input.metadata);
+    return canonicalCandidateDigest({
+        provider: providerName,
+        image: input.image,
+        egress: input.egress,
+        maxLifetimeMs: input.maxLifetimeMs,
+        resources: input.resources,
+        metadata: input.metadata,
+        idempotencyKey: input.idempotencyKey,
+        ...(options.teamId === undefined ? {} : { teamId: options.teamId }),
+        ...(input.provisionTimeoutMs === undefined
+            ? {}
+            : { provisionTimeoutMs: input.provisionTimeoutMs }),
+    });
+}
+export function validateExactProcessCreateInput(input, providerName, options) {
+    const inputKeys = new Set(Object.keys(input));
+    for (const key of [
+        "image",
+        "egress",
+        "maxLifetimeMs",
+        "provisionTimeoutMs",
+        "resources",
+        "metadata",
+        "idempotencyKey",
+        "signal",
+        "providerOptions",
+    ])
+        inputKeys.delete(key);
+    if (inputKeys.size > 0)
+        throw new Error("exact process input contains unsupported fields");
+    boundedIdentifier(providerName, "Tangle exact process provider");
+    if (options.teamId !== undefined) {
+        boundedIdentifier(options.teamId, "Tangle exact process team id");
+    }
+    boundedString(input.image, "exact process image");
+    if (!input.image.trim() || !IMMUTABLE_TANGLE_IMAGE.test(input.image)) {
+        throw new Error("Tangle exact process image must include a sha256 manifest digest");
+    }
+    boundedIdentifier(input.idempotencyKey, "exact process idempotencyKey");
+    if (!input.metadata || typeof input.metadata !== "object" || Array.isArray(input.metadata)) {
+        throw new Error("exact process metadata must be a JSON object");
+    }
+    assertBoundedJson(input.metadata);
+    if (input.providerOptions !== undefined) {
+        if (!input.providerOptions || typeof input.providerOptions !== "object" || Array.isArray(input.providerOptions)) {
+            throw new Error("Tangle exact process providerOptions must be a JSON object");
+        }
+        assertBoundedJson(input.providerOptions);
+        if (Object.keys(input.providerOptions).length > 0) {
+            throw new Error("Tangle exact process providerOptions are not supported");
+        }
+    }
+    if (!input.egress || typeof input.egress !== "object" || Array.isArray(input.egress)) {
+        throw new Error("exact process egress policy is required");
+    }
+    if (input.egress.mode !== "blocked" && input.egress.mode !== "strict") {
+        throw new Error("exact process egress mode is unsupported");
+    }
+    const egressKeys = new Set(Object.keys(input.egress));
+    egressKeys.delete("mode");
+    if (input.egress.mode === "blocked") {
+        if (egressKeys.size > 0)
+            throw new Error("blocked exact process egress has unsupported fields");
+    }
+    else {
+        egressKeys.delete("allowDomains");
+        if (egressKeys.size > 0)
+            throw new Error("strict exact process egress has unsupported fields");
+    }
+    if (input.egress.mode === "strict") {
+        if (!Array.isArray(input.egress.allowDomains)) {
+            throw new Error("exact process egress allowDomains must be an array");
+        }
+        if (input.egress.allowDomains.length > MAX_ARRAY_LENGTH) {
+            throw new Error("exact process egress allowDomains has too many entries");
+        }
+        if (input.egress.allowDomains.length === 0) {
+            throw new Error("strict exact process egress requires at least one domain");
+        }
+        for (const domain of input.egress.allowDomains) {
+            boundedIdentifier(domain, "exact process egress domain");
+        }
+    }
+    if (!Number.isSafeInteger(input.maxLifetimeMs) ||
+        input.maxLifetimeMs < 1 ||
+        input.maxLifetimeMs % 1_000 !== 0) {
+        throw new Error("exact process maxLifetimeMs must be a positive safe integer");
+    }
+    if (input.provisionTimeoutMs !== undefined &&
+        (!Number.isSafeInteger(input.provisionTimeoutMs) || input.provisionTimeoutMs < 1)) {
+        throw new Error("exact process provisionTimeoutMs must be a positive safe integer");
+    }
+    if (!input.resources || typeof input.resources !== "object" || Array.isArray(input.resources)) {
+        throw new Error("exact process resources are required");
+    }
+    const resourceKeys = new Set(Object.keys(input.resources));
+    for (const key of ["cpu", "memoryMb", "diskMb"])
+        resourceKeys.delete(key);
+    if (resourceKeys.size > 0)
+        throw new Error("exact process resources contain unsupported fields");
+    if (!Number.isFinite(input.resources.cpu) || input.resources.cpu <= 0) {
+        throw new Error("exact process CPU must be positive and finite");
+    }
+    for (const [name, value] of [
+        ["memoryMb", input.resources.memoryMb],
+        ["diskMb", input.resources.diskMb],
+    ]) {
+        if (!Number.isSafeInteger(value) || value < 1) {
+            throw new Error(`exact process ${name} must be a positive safe integer`);
+        }
+    }
+    if (input.resources.diskMb % 1_024 !== 0) {
+        throw new Error("exact process diskMb must be a whole number of gibibytes");
+    }
+}
+export async function awaitWithSignal(operation, signal) {
+    signal?.throwIfAborted();
+    if (operation === undefined)
+        return undefined;
+    if (!signal)
+        return await operation;
+    let listener;
+    try {
+        return await Promise.race([
+            Promise.resolve(operation),
+            new Promise((_, reject) => {
+                listener = () => reject(new DOMException("The operation was aborted", "AbortError"));
+                signal.addEventListener("abort", listener, { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (listener)
+            signal.removeEventListener("abort", listener);
+    }
+}

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

@@ -0,0 +1,9 @@
+import type { BackendType, CreateSandboxOptions } from "@tangle-network/sandbox";
+import type { CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+export declare function sandboxOptionsFromCreateInput(input: CreateAgentEnvironmentInput, defaultBackend: BackendType): CreateSandboxOptions;
+/** Reject value-bearing secret maps before any custom mapper can drop them. */
+export declare function assertNoInlineSecretValues(input: CreateAgentEnvironmentInput): void;
+/** A custom mapper must not smuggle a value map into the Sandbox request. */
+export declare function assertMappedSecretNames(options: CreateSandboxOptions): void;
+export declare function assertCreateInputShape(input: CreateAgentEnvironmentInput): void;
+export declare function assertMappedCreateOptions(options: CreateSandboxOptions): void;