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

package/dist/exact-process.d.ts

@@ -1,8 +1,5 @@
 import type { AgentExactProcessProvider } from "@tangle-network/agent-interface/environment-provider";
-import type { SandboxClientLike } from "./index.js";
-export interface TangleExactProcessOptions {
-    teamId?: string;
-}
+import type { SandboxClientLike, TangleExactProcessOptions } from "./tangle-types.js";
 export declare function createTangleExactProcessProvider(input: {
     client: SandboxClientLike;
     options: TangleExactProcessOptions;

package/dist/exact-process.js

@@ -1,11 +1,14 @@
-import { isAbsolute } from "node:path";
-import { isDeepStrictEqual } from "node:util";
+import { assertBoundedJson, attachCleanupHandle, awaitWithSignal, boundedIdentifier, boundedString, exactProcessRequestDigest, isBoundedJson, MAX_LIST_RESULTS, } from "./tangle-contract-safety.js";
+import { sandboxInstanceAsExactProcessEnvironment } from "./tangle-exact-process-environment.js";
+import { assertExactProcessSandbox, assertSupportedProviderOptions, assertUnreservedMetadata, EXACT_PROCESS_METADATA_KEY, isExactProcessRequestConflict, isExactProcessSandbox, metadataMatches, assertSignalOptions, } from "./tangle-exact-process-validation.js";
 const IMMUTABLE_TANGLE_IMAGE = /^(?:sha256:[a-f0-9]{64}|\S+@sha256:[a-f0-9]{64})$/i;
-const EXACT_PROCESS_METADATA_KEY = "tangle.exactProcess";
 const LIST_PAGE_SIZE = 1_000;
-const MAX_LIST_OFFSET = 1_000;
 export function createTangleExactProcessProvider(input) {
     const { client, options, providerName } = input;
+    boundedIdentifier(providerName, "Tangle exact process provider");
+    if (options.teamId !== undefined) {
+        boundedIdentifier(options.teamId, "Tangle exact process team id");
+    }
     const get = client.get;
     const list = client.list;
     if (!get || !list) {
@@ -13,69 +16,137 @@ export function createTangleExactProcessProvider(input) {
     }
     return {
         async create(createInput) {
+            createInput.signal?.throwIfAborted();
             assertSupportedProviderOptions(createInput.providerOptions);
             assertUnreservedMetadata(createInput.metadata);
-            const box = await client.create(exactSandboxOptions(createInput, options), {
+            const identityDigest = exactProcessRequestDigest(createInput, providerName, options);
+            createInput.signal?.throwIfAborted();
+            const createPromise = client.create(exactSandboxOptions(createInput, options, providerName, identityDigest), {
                 ...(createInput.signal ? { signal: createInput.signal } : {}),
                 ...(createInput.provisionTimeoutMs === undefined
                     ? {}
                     : { timeoutMs: createInput.provisionTimeoutMs }),
             });
+            let box;
+            try {
+                box = await awaitWithSignal(createPromise, createInput.signal);
+            }
+            catch (error) {
+                if (createInput.signal?.aborted) {
+                    void createPromise
+                        .then(async (lateBox) => {
+                        if (!lateBox.delete) {
+                            attachCleanupHandle(error, lateBox);
+                            return;
+                        }
+                        try {
+                            await lateBox.delete();
+                        }
+                        catch (cleanupError) {
+                            attachCleanupHandle(error, lateBox, cleanupError);
+                        }
+                    })
+                        .catch((lateError) => attachCleanupHandle(error, undefined, lateError));
+                }
+                throw error;
+            }
             try {
-                assertExactProcessSandbox(box);
+                createInput.signal?.throwIfAborted();
+                assertExactProcessSandbox(box, providerName, options.teamId, identityDigest);
                 return sandboxInstanceAsExactProcessEnvironment(box, providerName);
             }
             catch (error) {
-                if (!box.delete)
-                    throw error;
+                if (isExactProcessRequestConflict(box, providerName, options.teamId, createInput.idempotencyKey, identityDigest)) {
+                    throw new Error("Tangle exact process idempotency key conflicts with an existing request", { cause: error });
+                }
+                if (!box.delete) {
+                    const baseError = error instanceof Error ? error : new Error(String(error));
+                    throw Object.assign(baseError, {
+                        cleanupHandle: box,
+                        message: `${error instanceof Error ? error.message : String(error)}; provider returned no cleanup handle`,
+                    });
+                }
                 try {
                     await box.delete();
                 }
                 catch (cleanupError) {
-                    throw new AggregateError([error, cleanupError], "Tangle exact process validation and cleanup both failed");
+                    const combined = new AggregateError([error, cleanupError], "Tangle exact process validation and cleanup both failed");
+                    attachCleanupHandle(combined, box, cleanupError);
+                    throw combined;
                 }
                 throw error;
             }
         },
-        async get(id) {
-            const box = await get.call(client, id);
-            if (!box || !isExactProcessSandbox(box))
+        async get(id, operation = {}) {
+            assertSignalOptions(operation, "Tangle exact process get");
+            boundedIdentifier(id, "exact process environment id");
+            operation.signal?.throwIfAborted();
+            const box = await awaitWithSignal(get.call(client, id, operation.signal ? { signal: operation.signal } : undefined), operation.signal);
+            operation.signal?.throwIfAborted();
+            if (!box ||
+                boundedIdentifier(box.id, "exact process environment id") !== id ||
+                (box.metadata !== undefined && !isBoundedJson(box.metadata)) ||
+                !isExactProcessSandbox(box, providerName, options.teamId))
                 return null;
             return sandboxInstanceAsExactProcessEnvironment(box, providerName);
         },
-        async list(query) {
+        async list(query, operation = {}) {
+            assertSignalOptions(operation, "Tangle exact process list");
+            query?.signal?.throwIfAborted();
+            operation.signal?.throwIfAborted();
+            const signal = query?.signal ?? operation.signal;
             assertSupportedProviderOptions(query?.providerOptions);
+            assertExactProcessListQuery(query);
             const matches = [];
-            for (let offset = 0; offset <= MAX_LIST_OFFSET; offset += LIST_PAGE_SIZE) {
-                const page = await list.call(client, {
+            for (let offset = 0;; offset += LIST_PAGE_SIZE) {
+                if (offset > MAX_LIST_RESULTS) {
+                    throw new Error("Tangle exact process list exceeded its page bound");
+                }
+                signal?.throwIfAborted();
+                const page = await awaitWithSignal(list.call(client, {
                     ...(options.teamId
                         ? { scope: `team:${options.teamId}` }
                         : { scope: "personal" }),
                     limit: LIST_PAGE_SIZE,
                     offset,
-                });
+                    ...(signal ? { signal } : {}),
+                }), signal);
+                if (!Array.isArray(page) || page.length > LIST_PAGE_SIZE) {
+                    throw new Error("Tangle exact process list returned an invalid page size");
+                }
+                if (offset + page.length > MAX_LIST_RESULTS) {
+                    throw new Error("Tangle exact process list exceeded its result bound");
+                }
+                signal?.throwIfAborted();
                 for (const box of page) {
-                    if (isExactProcessSandbox(box) &&
+                    signal?.throwIfAborted();
+                    boundedIdentifier(box.id, "exact process environment id");
+                    if (box.metadata !== undefined && !isBoundedJson(box.metadata)) {
+                        throw new Error("Tangle exact process metadata exceeds its bound");
+                    }
+                    if (isExactProcessSandbox(box, providerName, options.teamId) &&
                         metadataMatches(box.metadata, query?.metadata)) {
                         matches.push(sandboxInstanceAsExactProcessEnvironment(box, providerName));
+                        if (matches.length > MAX_LIST_RESULTS) {
+                            throw new Error("Tangle exact process list exceeded its result bound");
+                        }
                     }
                 }
                 if (page.length < LIST_PAGE_SIZE)
                     return matches;
             }
-            throw new Error("Tangle exact process lookup exceeds the Sandbox list pagination limit");
         },
     };
 }
-function exactSandboxOptions(input, defaults) {
+function exactSandboxOptions(input, defaults, providerName, identityDigest) {
+    boundedString(input.image, "exact process image");
+    boundedIdentifier(input.idempotencyKey, "exact process idempotencyKey");
+    assertBoundedJson(input.metadata);
     if (!input.image.trim())
         throw new Error("exact process image is required");
     if (!IMMUTABLE_TANGLE_IMAGE.test(input.image)) {
         throw new Error("Tangle exact process image must include a sha256 manifest digest");
     }
-    if (!input.idempotencyKey.trim()) {
-        throw new Error("exact process idempotencyKey is required");
-    }
     if (!Number.isSafeInteger(input.maxLifetimeMs) ||
         input.maxLifetimeMs < 1 ||
         input.maxLifetimeMs % 1_000 !== 0) {
@@ -111,7 +182,13 @@ function exactSandboxOptions(input, defaults) {
         idempotencyKey: input.idempotencyKey,
         metadata: {
             ...input.metadata,
-            [EXACT_PROCESS_METADATA_KEY]: true,
+            [EXACT_PROCESS_METADATA_KEY]: {
+                version: 1,
+                provider: providerName,
+                ...(defaults.teamId ? { teamId: defaults.teamId } : {}),
+                idempotencyKey: input.idempotencyKey,
+                requestDigest: identityDigest,
+            },
         },
         ...(defaults.teamId ? { teamId: defaults.teamId } : {}),
         resources,
@@ -135,188 +212,28 @@ function sandboxResourcesFromRequest(requested) {
         diskGB: requested.diskMb / 1_024,
     };
 }
-function sandboxInstanceAsExactProcessEnvironment(box, providerName) {
-    if (!box.fs ||
-        box.fs.supportsWriteMode !== true ||
-        !box.process ||
-        !box.delete) {
-        throw new Error("Tangle sandbox does not expose exact files, processes, and deletion");
-    }
-    const process = box.process;
-    const fs = box.fs;
-    const destroy = box.delete.bind(box);
-    return {
-        id: String(box.id),
-        provider: providerName,
-        ...(box.metadata ? { metadata: box.metadata } : {}),
-        process: {
-            async list() {
-                return (await process.list()).map(exactProcessStatusFromSandbox);
-            },
-            async get(pid) {
-                const handle = await process.get(pid);
-                return handle ? sandboxProcessAsExactProcess(handle) : null;
-            },
-            async spawn(launch, operation = {}) {
-                operation.signal?.throwIfAborted();
-                validateExactProcessLaunch(launch);
-                const handle = await process.spawnExact(launch.executable, launch.args, {
-                    cwd: launch.cwd,
-                    env: { ...launch.env },
-                    inheritEnv: false,
-                    ...(launch.stdin === undefined ? {} : { stdin: launch.stdin }),
-                    timeoutMs: launch.timeoutMs,
-                    ...(operation.signal ? { signal: operation.signal } : {}),
-                });
-                operation.signal?.throwIfAborted();
-                return sandboxProcessAsExactProcess(handle);
-            },
-        },
-        async writeFile(path, bytes, options) {
-            options.signal?.throwIfAborted();
-            assertAbsoluteFilePath(path);
-            if (!Number.isSafeInteger(options.mode) ||
-                options.mode < 0 ||
-                options.mode > 0o7777) {
-                throw new Error("Tangle exact process file mode must be between 0 and 07777");
-            }
-            await fs.write(path, Buffer.from(bytes).toString("base64"), {
-                encoding: "base64",
-                mode: options.mode,
-            });
-            options.signal?.throwIfAborted();
-        },
-        async readFile(path, options) {
-            options.signal?.throwIfAborted();
-            assertAbsoluteFilePath(path);
-            if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 1) {
-                throw new Error("Tangle exact process maxBytes must be a positive integer");
-            }
-            const stat = await fs.stat(path);
-            options.signal?.throwIfAborted();
-            if (!stat.isFile) {
-                throw new Error("Tangle exact process path is not a regular file");
-            }
-            if (stat.size > options.maxBytes) {
-                throw new Error("Tangle exact process file exceeds maxBytes");
-            }
-            const result = await fs.readBatch([path], { encoding: "base64" });
-            options.signal?.throwIfAborted();
-            const file = result.files[0];
-            if (result.errors.length !== 0 ||
-                result.files.length !== 1 ||
-                !file ||
-                file.path !== path ||
-                file.encoding !== "base64") {
-                throw new Error(result.errors[0]?.error ??
-                    "Tangle exact process file read returned an invalid result");
-            }
-            const bytes = Uint8Array.from(Buffer.from(file.content, "base64"));
-            if (bytes.byteLength !== file.size ||
-                bytes.byteLength !== stat.size ||
-                bytes.byteLength > options.maxBytes) {
-                throw new Error("Tangle exact process file read violated its byte bound");
-            }
-            return bytes;
-        },
-        async destroy() {
-            await destroy();
-        },
-    };
-}
-function validateExactProcessLaunch(input) {
-    if (!input.executable ||
-        (!isAbsolute(input.executable) && !input.env.PATH?.trim())) {
-        throw new Error("Tangle exact process executable must be absolute unless env.PATH is supplied");
+function assertExactProcessListQuery(query) {
+    if (query !== undefined &&
+        (!query ||
+            typeof query !== "object" ||
+            Array.isArray(query) ||
+            (Object.getPrototypeOf(query) !== Object.prototype &&
+                Object.getPrototypeOf(query) !== null))) {
+        throw new Error("Tangle exact process list query must be a plain object");
+    }
+    if (query?.metadata !== undefined) {
+        if (!query.metadata ||
+            typeof query.metadata !== "object" ||
+            Array.isArray(query.metadata) ||
+            !isBoundedJson(query.metadata)) {
+            throw new Error("Tangle exact process metadata query exceeds its bound");
+        }
+    }
+    if (query !== undefined) {
+        const keys = new Set(Object.keys(query));
+        for (const key of ["metadata", "providerOptions", "signal"])
+            keys.delete(key);
+        if (keys.size > 0)
+            throw new Error("Tangle exact process list query contains unsupported fields");
     }
-    if (!input.cwd)
-        throw new Error("Tangle exact process cwd is required");
-    if (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 0) {
-        throw new Error("Tangle exact process timeoutMs must be a non-negative integer");
-    }
-}
-function sandboxProcessAsExactProcess(process) {
-    return {
-        pid: process.pid,
-        async status() {
-            return exactProcessStatusFromSandbox(await process.status());
-        },
-        async wait() {
-            await process.wait();
-            const status = exactProcessStatusFromSandbox(await process.status());
-            if (!status.termination) {
-                throw new Error("Tangle exact process remained running after wait()");
-            }
-            return status.termination;
-        },
-        async kill() {
-            await process.kill("SIGKILL", { tree: true });
-        },
-        async *stdout() {
-            yield* process.stdout();
-        },
-        async *stderr() {
-            yield* process.stderr();
-        },
-    };
-}
-function exactProcessStatusFromSandbox(status) {
-    if (status.running && status.exitSignal) {
-        throw new Error("Tangle exact process reported an exit signal while running");
-    }
-    const termination = processTermination(status);
-    return {
-        pid: status.pid,
-        running: status.running,
-        exitCode: status.exitCode,
-        ...(status.exitSignal ? { exitSignal: status.exitSignal } : {}),
-        ...(termination ? { termination } : {}),
-    };
-}
-function processTermination(status) {
-    if (status.running)
-        return undefined;
-    return status.exitSignal
-        ? { kind: "signal", signal: status.exitSignal }
-        : { kind: "exit", exitCode: status.exitCode };
-}
-function assertExactProcessSandbox(box) {
-    if (!isExactProcessSandbox(box)) {
-        throw new Error("Tangle Sandbox did not create the requested process-only runtime");
-    }
-}
-function isExactProcessSandbox(box) {
-    return (box.metadata?.runtimeMode === "control" &&
-        box.metadata[EXACT_PROCESS_METADATA_KEY] === true);
-}
-function assertUnreservedMetadata(metadata) {
-    const reserved = [
-        "capabilities",
-        "customer_id",
-        "exactProcess",
-        "integrationLaunch",
-        "runtimeMode",
-        "teamId",
-        EXACT_PROCESS_METADATA_KEY,
-    ];
-    if (reserved.some((name) => Object.hasOwn(metadata, name))) {
-        throw new Error("exact process ownership metadata is reserved by Tangle");
-    }
-}
-function assertSupportedProviderOptions(providerOptions) {
-    if (providerOptions && Object.keys(providerOptions).length > 0) {
-        throw new Error("Tangle exact process providerOptions are not supported");
-    }
-}
-function assertAbsoluteFilePath(path) {
-    if (!isAbsolute(path)) {
-        throw new Error("Tangle exact process file path must be absolute");
-    }
-}
-function metadataMatches(actual, expected) {
-    if (!expected)
-        return true;
-    if (!actual)
-        return false;
-    return Object.entries(expected).every(([key, value]) => isDeepStrictEqual(actual[key], value));
 }

package/dist/index.d.ts

@@ -1,126 +1,4 @@
-import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import { type AgentEnvironmentCapabilities, type AgentEnvironmentProvider, type CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
-import type { HarnessType, InputPart } from "@tangle-network/agent-interface";
-import { type TangleExactProcessOptions } from "./exact-process.js";
-export type { TangleExactProcessOptions } from "./exact-process.js";
-export interface SandboxClientLike {
-    create(options?: CreateSandboxOptions, requestOptions?: {
-        signal?: AbortSignal;
-        timeoutMs?: number;
-    }): Promise<SandboxInstanceLike>;
-    get?(id: string): Promise<SandboxInstanceLike | null>;
-    list?(options?: unknown): Promise<SandboxInstanceLike[]>;
-    describePlacement?(box: SandboxInstanceLike): unknown;
-}
-export interface SandboxProcessStatusLike {
-    pid: number;
-    running: boolean;
-    exitCode: number;
-    exitSignal?: string;
-}
-export interface SandboxProcessLike {
-    readonly pid: number;
-    status(): Promise<SandboxProcessStatusLike>;
-    wait(): Promise<number>;
-    kill(signal?: "SIGKILL", options?: {
-        tree?: boolean;
-    }): Promise<void>;
-    stdout(): AsyncIterable<string>;
-    stderr(): AsyncIterable<string>;
-}
-export interface SandboxProcessManagerLike {
-    list(): Promise<SandboxProcessStatusLike[]>;
-    get(pid: number): Promise<SandboxProcessLike | null>;
-    spawnExact(executable: string, args: readonly string[], options?: {
-        cwd?: string;
-        env?: Record<string, string>;
-        inheritEnv?: boolean;
-        stdin?: string;
-        timeoutMs?: number;
-        signal?: AbortSignal;
-    }): Promise<SandboxProcessLike>;
-}
-export interface SandboxInstanceLike {
-    id: string;
-    name?: string;
-    status?: unknown;
-    metadata?: Record<string, unknown>;
-    streamPrompt(message: string | InputPart[], options?: PromptOptions): AsyncIterable<SandboxEvent>;
-    prompt?(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
-    dispatchPrompt?(message: string | InputPart[], options?: PromptOptions): Promise<unknown>;
-    session?(id: string): SandboxSessionLike;
-    read?(path: string, options?: {
-        sessionId?: string;
-    }): Promise<string>;
-    write?(path: string, content: string, options?: {
-        sessionId?: string;
-    }): Promise<unknown>;
-    exec?(command: string, options?: unknown): Promise<SandboxExecResult>;
-    fs?: {
-        supportsWriteMode?: true;
-        stat(path: string): Promise<{
-            size: number;
-            isFile: boolean;
-        }>;
-        readBatch(paths: string[], options?: {
-            encoding?: "utf8" | "base64";
-        }): Promise<{
-            files: Array<{
-                path: string;
-                content: string;
-                encoding: "utf8" | "base64";
-                size: number;
-            }>;
-            errors: Array<{
-                path: string;
-                error: string;
-                code?: string;
-            }>;
-        }>;
-        write(path: string, content: string, options: {
-            encoding: "base64";
-            mode: number;
-        }): Promise<unknown>;
-    };
-    process?: SandboxProcessManagerLike;
-    checkpoint?(options?: unknown): Promise<unknown>;
-    fork?(checkpointId: string, options?: unknown): Promise<SandboxInstanceLike>;
-    refresh?(): Promise<void>;
-    delete?(): Promise<void>;
-}
-export interface SandboxSessionLike {
-    readonly id: string;
-    status(): Promise<unknown | null>;
-    events(options?: {
-        since?: string;
-        executionId?: string;
-        signal?: AbortSignal;
-    }): AsyncIterable<SandboxEvent>;
-    result(options?: {
-        executionId?: string;
-    }): Promise<PromptResult>;
-    prompt(message: string | InputPart[], options?: PromptOptions): Promise<PromptResult>;
-    interrupt(options?: {
-        executionId?: string;
-    }): Promise<{
-        cancelled: boolean;
-    }>;
-}
-export interface TangleProviderOptions {
-    client: SandboxClientLike;
-    name?: string;
-    defaultBackend?: BackendType;
-    capabilities?: AgentEnvironmentCapabilities | (() => AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>);
-    validateProfile?: AgentEnvironmentProvider["validateProfile"];
-    mapCreateInput?: (input: CreateAgentEnvironmentInput) => CreateSandboxOptions;
-    exactProcess?: TangleExactProcessOptions;
-}
-export declare function createTangleProvider(options: TangleProviderOptions): AgentEnvironmentProvider;
-/**
- * @param harness The harness the sandbox will materialize the profile with. The prompt intents are
- * that harness's, not this adapter's: forwarding the whole profile on the wire makes both fields
- * *expressible*, but the sandbox's materializer refuses the intent its harness has no control for
- * (opencode has no replacement, codex and gemini no addition). Omit it and both intents declare
- * `false` — an adapter that cannot name its harness cannot promise either one.
- */
-export declare function defaultTangleSandboxCapabilities(harness?: HarnessType): AgentEnvironmentCapabilities;
+export type { TangleExactProcessOptions } from "./tangle-types.js";
+export * from "./tangle-types.js";
+export { createTangleProvider } from "./tangle-provider.js";
+export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";