@tangle-network/agent-provider-tangle 0.2.0 → 0.3.0

package/README.md

@@ -10,3 +10,25 @@ const provider = createTangleProvider({
   client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
 })
 ```
+
+Pass `exactProcess: {}` only when the Sandbox deployment supports `agent: false` creates and reports `metadata.runtimeMode: "control"`.
+The optional capability creates an ephemeral sandbox with an authenticated control service but no managed agent workload or agent credentials, explicit resources, exact blocked/domain egress, bounded binary file reads, shell-free launch, and recoverable process output plus terminal reason.
+Set `teamId` inside `exactProcess` to scope create, lookup, and recovery to one team.
+
+```ts
+const provider = createTangleProvider({
+  client: new Sandbox({ apiKey: process.env.TANGLE_API_KEY }),
+  exactProcess: {},
+})
+
+const environment = await provider.exactProcess!.create({
+  image: 'ghcr.io/acme/agent@sha256:<64-hex-manifest-digest>',
+  egress: { mode: 'blocked' },
+  maxLifetimeMs: 120_000,
+  resources: { cpu: 1, memoryMb: 1024, diskMb: 1024 },
+  metadata: { executionId: 'run-1' },
+  idempotencyKey: 'run-1',
+})
+```
+
+The adapter rejects ordinary sandboxes during create, recovery, and list operations.

package/dist/exact-process.d.ts

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

package/dist/exact-process.js

@@ -0,0 +1,323 @@
+import { isAbsolute } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+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;
+    const get = client.get;
+    const list = client.list;
+    if (!get || !list) {
+        throw new Error("Tangle exact process provider requires get() and list()");
+    }
+    return {
+        async create(createInput) {
+            assertSupportedProviderOptions(createInput.providerOptions);
+            assertUnreservedMetadata(createInput.metadata);
+            const box = await client.create(exactSandboxOptions(createInput, options), {
+                ...(createInput.signal ? { signal: createInput.signal } : {}),
+                ...(createInput.provisionTimeoutMs === undefined
+                    ? {}
+                    : { timeoutMs: createInput.provisionTimeoutMs }),
+            });
+            try {
+                assertExactProcessSandbox(box);
+                return sandboxInstanceAsExactProcessEnvironment(box, providerName);
+            }
+            catch (error) {
+                if (!box.delete)
+                    throw error;
+                try {
+                    await box.delete();
+                }
+                catch (cleanupError) {
+                    throw new AggregateError([error, cleanupError], "Tangle exact process validation and cleanup both failed");
+                }
+                throw error;
+            }
+        },
+        async get(id) {
+            const box = await get.call(client, id);
+            if (!box || !isExactProcessSandbox(box))
+                return null;
+            return sandboxInstanceAsExactProcessEnvironment(box, providerName);
+        },
+        async list(query) {
+            assertSupportedProviderOptions(query?.providerOptions);
+            const matches = [];
+            for (let offset = 0; offset <= MAX_LIST_OFFSET; offset += LIST_PAGE_SIZE) {
+                const page = await list.call(client, {
+                    ...(options.teamId
+                        ? { scope: `team:${options.teamId}` }
+                        : { scope: "personal" }),
+                    limit: LIST_PAGE_SIZE,
+                    offset,
+                });
+                for (const box of page) {
+                    if (isExactProcessSandbox(box) &&
+                        metadataMatches(box.metadata, query?.metadata)) {
+                        matches.push(sandboxInstanceAsExactProcessEnvironment(box, providerName));
+                    }
+                }
+                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) {
+    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) {
+        throw new Error("Tangle exact process maxLifetimeMs must be a positive whole number of seconds");
+    }
+    if (input.provisionTimeoutMs !== undefined &&
+        (!Number.isSafeInteger(input.provisionTimeoutMs) ||
+            input.provisionTimeoutMs < 1)) {
+        throw new Error("exact process provisionTimeoutMs must be a positive integer");
+    }
+    if (input.egress.mode === "strict" &&
+        input.egress.allowDomains.length === 0) {
+        throw new Error("strict exact process egress requires at least one domain");
+    }
+    const resources = sandboxResourcesFromRequest(input.resources);
+    return {
+        image: input.image,
+        agent: false,
+        driver: { type: "host-agent", runtimeBackend: "docker" },
+        publicEdge: false,
+        ephemeral: true,
+        sshEnabled: false,
+        webTerminalEnabled: false,
+        secrets: [],
+        capabilities: [],
+        egressPolicy: input.egress.mode === "blocked"
+            ? { mode: "blocked" }
+            : {
+                mode: "strict",
+                allowDomains: [...input.egress.allowDomains],
+                includeImplicitDomains: false,
+            },
+        maxLifetimeSeconds: input.maxLifetimeMs / 1_000,
+        idempotencyKey: input.idempotencyKey,
+        metadata: {
+            ...input.metadata,
+            [EXACT_PROCESS_METADATA_KEY]: true,
+        },
+        ...(defaults.teamId ? { teamId: defaults.teamId } : {}),
+        resources,
+    };
+}
+function sandboxResourcesFromRequest(requested) {
+    if (!Number.isFinite(requested.cpu) || requested.cpu <= 0) {
+        throw new Error("Tangle exact process CPU must be positive and finite");
+    }
+    if (!Number.isSafeInteger(requested.memoryMb) || requested.memoryMb < 1) {
+        throw new Error("Tangle exact process memoryMb must be a positive integer");
+    }
+    if (!Number.isSafeInteger(requested.diskMb) ||
+        requested.diskMb < 1 ||
+        requested.diskMb % 1_024 !== 0) {
+        throw new Error("Tangle exact process diskMb must be a positive whole number of gibibytes");
+    }
+    return {
+        cpuCores: requested.cpu,
+        memoryMB: requested.memoryMb,
+        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");
+    }
+    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,12 +1,45 @@
 import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 import type { 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): Promise<SandboxInstanceLike>;
+    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;
@@ -23,6 +56,33 @@ export interface SandboxInstanceLike {
         sessionId?: string;
     }): Promise<void>;
     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>;
@@ -46,6 +106,7 @@ export interface TangleProviderOptions {
     capabilities?: AgentEnvironmentCapabilities | (() => AgentEnvironmentCapabilities | Promise<AgentEnvironmentCapabilities>);
     validateProfile?: AgentEnvironmentProvider["validateProfile"];
     mapCreateInput?: (input: CreateAgentEnvironmentInput) => CreateSandboxOptions;
+    exactProcess?: TangleExactProcessOptions;
 }
 export declare function createTangleProvider(options: TangleProviderOptions): AgentEnvironmentProvider;
 export declare function defaultTangleSandboxCapabilities(): AgentEnvironmentCapabilities;

package/dist/index.js

@@ -1,11 +1,28 @@
+import { createTangleExactProcessProvider, } from "./exact-process.js";
 export function createTangleProvider(options) {
     const providerName = options.name ?? "tangle-sandbox";
+    const exactProcess = options.exactProcess
+        ? createTangleExactProcessProvider({
+            client: options.client,
+            options: options.exactProcess,
+            providerName,
+        })
+        : undefined;
     return {
         name: providerName,
+        ...(exactProcess ? { exactProcess } : {}),
         capabilities: async () => {
-            if (!options.capabilities)
-                return defaultTangleSandboxCapabilities();
-            return typeof options.capabilities === "function" ? options.capabilities() : options.capabilities;
+            const capabilities = options.capabilities
+                ? typeof options.capabilities === "function"
+                    ? await options.capabilities()
+                    : options.capabilities
+                : defaultTangleSandboxCapabilities();
+            if (!exactProcess && capabilities.exactProcess) {
+                throw new Error("Tangle capabilities cannot advertise exactProcess without exactProcess configuration");
+            }
+            return exactProcess
+                ? { ...capabilities, exactProcess: { egress: ["blocked", "strict"] } }
+                : capabilities;
         },
         ...(options.validateProfile ? { validateProfile: options.validateProfile } : {}),
         async create(input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -25,14 +25,16 @@
   "files": [
     "dist/index.d.ts",
     "dist/index.js",
+    "dist/exact-process.d.ts",
+    "dist/exact-process.js",
     "README.md",
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.14.0"
+    "@tangle-network/agent-interface": "0.32.0"
   },
   "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.8.0 <1.0.0"
+    "@tangle-network/sandbox": ">=0.11.1 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {
@@ -40,16 +42,16 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/sandbox": "^0.8.2",
+    "@tangle-network/sandbox": "^0.11.1",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@tangle-network/agent-provider-testkit": "0.2.0"
+    "@tangle-network/agent-provider-testkit": "0.3.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "check-types": "tsc --noEmit",
     "clean": "rm -rf dist",
-    "test": "vitest run"
+    "test": "vitest run src"
   }
 }