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

package/dist/tangle-environment-values.js

@@ -0,0 +1,84 @@
+import { assertBoundedJson } from "./tangle-contract-safety.js";
+const MAX_IDENTIFIER_LENGTH = 512;
+export function nonEmptyString(value) {
+    return typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_IDENTIFIER_LENGTH &&
+        value.trim() === value
+        ? value
+        : undefined;
+}
+export function optionalNonEmptyString(value, label) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_IDENTIFIER_LENGTH ||
+        value.trim() !== value) {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    return value;
+}
+export function checkpointIdFromResult(result) {
+    assertBoundedJson(result);
+    const record = result && typeof result === "object" ? result : {};
+    const id = record.checkpointId ?? record.id;
+    if (typeof id !== "string" ||
+        id.length === 0 ||
+        id.length > MAX_IDENTIFIER_LENGTH ||
+        id.trim() !== id) {
+        throw new Error("sandbox checkpoint returned no checkpoint id");
+    }
+    return id;
+}
+export function placementInfoFromLoopPlacement(placement, box) {
+    if (!placement || typeof placement !== "object") {
+        return { kind: "sandbox", sandboxId: boundedId(box.id, "sandbox id") };
+    }
+    const record = placement;
+    if (record.kind !== "sandbox" && record.kind !== "fleet") {
+        throw new Error("Tangle placement returned an unsupported kind");
+    }
+    return {
+        kind: record.kind === "fleet" ? "fleet" : "sandbox",
+        sandboxId: record.kind === "fleet"
+            ? undefined
+            : boundedOptionalId(record.sandboxId, "sandbox id") ??
+                boundedId(box.id, "sandbox id"),
+        ...(record.kind === "fleet"
+            ? { fleetId: boundedId(record.fleetId, "fleet id") }
+            : {}),
+        ...(record.machineId !== undefined
+            ? { machineId: boundedId(record.machineId, "machine id") }
+            : {}),
+        ...(record.region !== undefined
+            ? { region: boundedId(record.region, "region") }
+            : {}),
+    };
+}
+function boundedId(value, label) {
+    if (typeof value !== "string" ||
+        value.length === 0 ||
+        value.length > MAX_IDENTIFIER_LENGTH ||
+        value.trim() !== value) {
+        throw new Error(`${label} must be a bounded non-empty string`);
+    }
+    return value;
+}
+function boundedOptionalId(value, label) {
+    return value === undefined ? undefined : boundedId(value, label);
+}
+export function statusFromUnknown(status) {
+    if (status === "pending" || status === "provisioning" || status === "running")
+        return status;
+    if (status === "stopped" || status === "failed" || status === "expired")
+        return status;
+    if (status === "completed" || status === "cancelled")
+        return "stopped";
+    return "unknown";
+}
+export function sessionStatusFromUnknown(status) {
+    if (status === "completed" || status === "cancelled")
+        return status;
+    return statusFromUnknown(status);
+}

package/dist/tangle-environment.d.ts

@@ -0,0 +1,3 @@
+import type { AgentEnvironment, AgentEnvironmentCapabilities } from "@tangle-network/agent-interface/environment-provider";
+import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
+export declare function sandboxInstanceAsEnvironment(box: SandboxInstanceLike, providerName: string, client: SandboxClientLike, declaredCapabilities: AgentEnvironmentCapabilities): AgentEnvironment;

package/dist/tangle-environment.js

@@ -0,0 +1,216 @@
+import { AgentTurnInputSchema } from "@tangle-network/agent-interface";
+import { environmentEventFromSandboxEvent } from "./tangle-events.js";
+import { executionIdFromTurnInput, promptFromTurnInput, promptOptionsFromTurnInput, } from "./tangle-prompt.js";
+import { resolveRetainedSessionControlRef } from "./tangle-session-control.js";
+import { checkpointIdFromResult, placementInfoFromLoopPlacement, statusFromUnknown, } from "./tangle-environment-values.js";
+import { execResultFromSandboxExecResult } from "./tangle-result-values.js";
+import { capabilitiesForSandbox, sandboxCapabilitySupport } from "./tangle-capabilities.js";
+import { attachCleanupHandle, awaitWithSignal, assertBoundedJson, boundedIdentifier, boundedString, } from "./tangle-contract-safety.js";
+import { assertCheckpointOptions, assertCheckpointRef, assertExecOptions, assertForkOptions, assertOptionKeys, } from "./tangle-environment-validation.js";
+import { interruptExecutionAfterAbort, } from "./tangle-environment-control.js";
+import { dispatchEnvironmentRun } from "./tangle-environment-dispatch.js";
+import { sandboxSessionAsAgentSession } from "./tangle-environment-session.js";
+export function sandboxInstanceAsEnvironment(box, providerName, client, declaredCapabilities) {
+    const environmentId = boundedIdentifier(box.id, "Tangle environment id");
+    boundedIdentifier(providerName, "Tangle provider name");
+    if (box.metadata !== undefined) {
+        if (!box.metadata || typeof box.metadata !== "object" || Array.isArray(box.metadata)) {
+            throw new Error("Tangle environment metadata must be a JSON object");
+        }
+        assertBoundedJson(box.metadata);
+    }
+    const support = sandboxCapabilitySupport(box, client);
+    const capabilities = capabilitiesForSandbox(declaredCapabilities, support);
+    return {
+        id: environmentId,
+        provider: providerName,
+        ...(box.name ? { name: boundedString(box.name, "Tangle environment name") } : {}),
+        async status(options) {
+            assertOptionKeys(options, ["signal"], "Tangle environment status");
+            await awaitWithSignal(box.refresh?.(options), options?.signal);
+            return statusFromUnknown(box.status);
+        },
+        async *stream(input) {
+            AgentTurnInputSchema.parse(input);
+            input.signal?.throwIfAborted();
+            const expectedExecutionId = executionIdFromTurnInput(input);
+            const expectedSessionId = input.sessionId ?? input.controlRef?.sessionId;
+            const iterator = box.streamPrompt(promptFromTurnInput(input), promptOptionsFromTurnInput(input, {
+                provider: providerName,
+                environmentId,
+            }))[Symbol.asyncIterator]();
+            let completed = false;
+            try {
+                while (true) {
+                    const next = await awaitWithSignal(iterator.next(), input.signal);
+                    if (next.done) {
+                        completed = true;
+                        break;
+                    }
+                    input.signal?.throwIfAborted();
+                    const converted = environmentEventFromSandboxEvent(next.value, {
+                        executionId: expectedExecutionId,
+                        sessionId: expectedSessionId,
+                    });
+                    input.signal?.throwIfAborted();
+                    yield converted;
+                }
+            }
+            catch (error) {
+                if (input.signal?.aborted &&
+                    expectedSessionId !== undefined &&
+                    expectedExecutionId !== undefined) {
+                    void interruptExecutionAfterAbort(box, expectedSessionId, expectedExecutionId);
+                }
+                throw error;
+            }
+            finally {
+                if (!completed) {
+                    void Promise.resolve(iterator.return?.()).catch(() => undefined);
+                }
+            }
+            input.signal?.throwIfAborted();
+        },
+        ...(capabilities.streaming.detach && box.dispatchPrompt
+            ? { dispatch: dispatchEnvironmentRun(box, providerName, environmentId) }
+            : {}),
+        ...((capabilities.sessions.continue || capabilities.streaming.replay || capabilities.streaming.detach) &&
+            box.session
+            ? {
+                session(id, options) {
+                    boundedIdentifier(id, "Tangle session id");
+                    assertOptionKeys(options, ["controlRef", "signal"], "Tangle session");
+                    options?.signal?.throwIfAborted();
+                    const session = box.session?.(id, options?.signal ? { signal: options.signal } : undefined);
+                    if (!session)
+                        throw new Error("sandbox session(id) returned undefined");
+                    options?.signal?.throwIfAborted();
+                    boundedIdentifier(session.id, "Tangle session id");
+                    if (session.id !== id) {
+                        throw new Error("sandbox session(id) returned an unrelated session");
+                    }
+                    return sandboxSessionAsAgentSession(session, resolveRetainedSessionControlRef(options?.controlRef, id, providerName, environmentId), providerName, environmentId);
+                },
+            }
+            : {}),
+        ...(capabilities.workspace.read && box.read
+            ? {
+                async read(path, options) {
+                    boundedString(path, "Tangle path");
+                    assertOptionKeys(options, ["sessionId", "signal"], "Tangle read");
+                    if (options?.sessionId !== undefined)
+                        boundedIdentifier(options.sessionId, "Tangle read session id");
+                    options?.signal?.throwIfAborted();
+                    const content = await awaitWithSignal(box.read?.(path, options), options?.signal);
+                    options?.signal?.throwIfAborted();
+                    return boundedString(content, "Tangle file content");
+                },
+            }
+            : {}),
+        ...(capabilities.workspace.write && box.write
+            ? {
+                async write(path, content, options) {
+                    boundedString(path, "Tangle path");
+                    boundedString(content, "Tangle file content");
+                    assertOptionKeys(options, ["sessionId", "signal"], "Tangle write");
+                    if (options?.sessionId !== undefined)
+                        boundedIdentifier(options.sessionId, "Tangle write session id");
+                    options?.signal?.throwIfAborted();
+                    await awaitWithSignal(box.write?.(path, content, options), options?.signal);
+                    options?.signal?.throwIfAborted();
+                },
+            }
+            : {}),
+        ...(capabilities.workspace.exec && box.exec
+            ? {
+                async exec(command, options) {
+                    boundedString(command, "Tangle command");
+                    assertExecOptions(options);
+                    options?.signal?.throwIfAborted();
+                    const result = await awaitWithSignal(box.exec?.(command, options), options?.signal);
+                    options?.signal?.throwIfAborted();
+                    return execResultFromSandboxExecResult(result);
+                },
+            }
+            : {}),
+        ...(capabilities.branching.checkpoint && box.checkpoint
+            ? {
+                async checkpoint(options) {
+                    assertCheckpointOptions(options);
+                    options?.signal?.throwIfAborted();
+                    const result = await awaitWithSignal(box.checkpoint?.(options), options?.signal);
+                    options?.signal?.throwIfAborted();
+                    return { id: checkpointIdFromResult(result), provider: providerName };
+                },
+            }
+            : {}),
+        ...(capabilities.branching.fork && box.fork
+            ? {
+                async fork(checkpoint, options) {
+                    assertCheckpointRef(checkpoint);
+                    assertForkOptions(options);
+                    if (checkpoint.provider !== undefined && checkpoint.provider !== providerName) {
+                        throw new Error("Tangle fork checkpoint belongs to another provider");
+                    }
+                    boundedIdentifier(checkpoint.id, "Tangle checkpoint id");
+                    options?.signal?.throwIfAborted();
+                    const forked = await awaitWithSignal(box.fork?.(checkpoint.id, options), options?.signal);
+                    if (!forked)
+                        throw new Error("sandbox fork returned no environment");
+                    try {
+                        options?.signal?.throwIfAborted();
+                        if (boundedIdentifier(forked.id, "Tangle fork environment id") === environmentId) {
+                            throw new Error("Tangle fork returned the source environment");
+                        }
+                        return sandboxInstanceAsEnvironment(forked, providerName, client, capabilities);
+                    }
+                    catch (error) {
+                        if (!forked.delete) {
+                            const baseError = error instanceof Error ? error : new Error(String(error));
+                            attachCleanupHandle(baseError, forked);
+                            throw baseError;
+                        }
+                        try {
+                            await forked.delete();
+                        }
+                        catch (cleanupError) {
+                            const combined = new AggregateError([error, cleanupError], "Tangle fork validation and cleanup both failed");
+                            attachCleanupHandle(combined, forked, cleanupError);
+                            throw combined;
+                        }
+                        throw error;
+                    }
+                },
+            }
+            : {}),
+        ...(capabilities.placement
+            ? {
+                async placement(options) {
+                    assertOptionKeys(options, ["signal"], "Tangle placement");
+                    options?.signal?.throwIfAborted();
+                    const placement = await awaitWithSignal(Promise.resolve(client.describePlacement?.(box)), options?.signal);
+                    options?.signal?.throwIfAborted();
+                    return placementInfoFromLoopPlacement(placement, box);
+                },
+            }
+            : {}),
+        async refresh(options) {
+            assertOptionKeys(options, ["signal"], "Tangle refresh");
+            options?.signal?.throwIfAborted();
+            await awaitWithSignal(box.refresh?.(options), options?.signal);
+            options?.signal?.throwIfAborted();
+        },
+        ...(support.destroy
+            ? {
+                async destroy(options) {
+                    if (!box.delete)
+                        throw new Error("Tangle sandbox client cannot delete this environment");
+                    assertOptionKeys(options, ["signal"], "Tangle destroy");
+                    options?.signal?.throwIfAborted();
+                    await awaitWithSignal(box.delete(options), options?.signal);
+                    options?.signal?.throwIfAborted();
+                },
+            }
+            : {}),
+    };
+}

package/dist/tangle-events.d.ts

@@ -0,0 +1,6 @@
+import type { SandboxEvent } from "@tangle-network/sandbox";
+import type { AgentEnvironmentEvent } from "@tangle-network/agent-interface/environment-provider";
+export declare function environmentEventFromSandboxEvent(event: SandboxEvent, expected?: {
+    executionId?: string;
+    sessionId?: string;
+}): AgentEnvironmentEvent;

package/dist/tangle-events.js

@@ -0,0 +1,111 @@
+import { assertBoundedJson } from "./tangle-contract-safety.js";
+import { optionalNonEmptyString } from "./tangle-environment-values.js";
+import { tokenUsageFromData } from "./tangle-result-values.js";
+export function environmentEventFromSandboxEvent(event, expected = {}) {
+    if (!event || typeof event !== "object") {
+        throw new Error("Tangle Sandbox emitted a non-object event");
+    }
+    const record = event;
+    if (typeof record.type !== "string" || record.type.length === 0) {
+        throw new Error("Tangle Sandbox event omitted its type");
+    }
+    if (record.type.length > 512 || record.type.trim() !== record.type) {
+        throw new Error("Tangle Sandbox event type exceeded its bound");
+    }
+    if (!record.data ||
+        typeof record.data !== "object" ||
+        Array.isArray(record.data)) {
+        throw new Error("Tangle Sandbox event omitted its object data");
+    }
+    if (record.id !== undefined &&
+        (typeof record.id !== "string" ||
+            record.id.length === 0 ||
+            record.id.length > 512 ||
+            record.id.trim() !== record.id)) {
+        throw new Error("Tangle Sandbox event contained an invalid event id");
+    }
+    const data = record.data;
+    assertBoundedRecord(data);
+    assertBoundedJson(record);
+    if (Object.prototype.hasOwnProperty.call(data, "contextTransferReceipt")) {
+        throw new Error("Tangle Sandbox emitted an unsolicited context transfer receipt");
+    }
+    const eventExecutionId = optionalNonEmptyString(data.executionId, "Tangle Sandbox event executionId");
+    const eventSessionId = optionalNonEmptyString(data.sessionId, "Tangle Sandbox event sessionId");
+    if (expected.executionId !== undefined &&
+        (eventExecutionId === undefined || eventExecutionId !== expected.executionId)) {
+        throw new Error("Tangle exact session event identified a different executionId");
+    }
+    if (expected.sessionId !== undefined &&
+        (eventSessionId === undefined || eventSessionId !== expected.sessionId)) {
+        throw new Error("Tangle exact session event identified a different sessionId");
+    }
+    const usage = tokenUsageFromData(data);
+    return {
+        type: record.type,
+        data,
+        ...(typeof record.id === "string" ? { id: record.id } : {}),
+        // Absent rather than zeroed: an event that reported no usage must not
+        // contribute a total to whatever sums these events.
+        ...(usage ? { usage } : {}),
+        providerEvent: event,
+    };
+}
+function assertBoundedRecord(value) {
+    if (Object.keys(value).length > 256) {
+        throw new Error("Tangle Sandbox event data has too many fields");
+    }
+    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 > 8_192)
+            throw new Error("Tangle Sandbox event data has too many JSON nodes");
+        const current = item.value;
+        if (item.leave) {
+            ancestors.delete(current);
+            continue;
+        }
+        if (current === null || typeof current === "boolean")
+            continue;
+        if (typeof current === "string" || typeof current === "number") {
+            if (typeof current === "string" && current.length > 16_384) {
+                throw new Error("Tangle Sandbox event data exceeded its string bound");
+            }
+            if (typeof current === "number" && !Number.isFinite(current)) {
+                throw new Error("Tangle Sandbox event data contained a non-finite number");
+            }
+            continue;
+        }
+        if (typeof current !== "object" || item.depth >= 16 || ancestors.has(current)) {
+            throw new Error("Tangle Sandbox event data exceeded its JSON bound");
+        }
+        ancestors.add(current);
+        pending.push({ value: current, depth: item.depth, leave: true });
+        if (Array.isArray(current)) {
+            if (current.length > 1_024) {
+                throw new Error("Tangle Sandbox event data has too many array entries");
+            }
+            for (const entry of current)
+                pending.push({ value: entry, depth: item.depth + 1 });
+            continue;
+        }
+        if (Object.getPrototypeOf(current) !== Object.prototype && Object.getPrototypeOf(current) !== null) {
+            throw new Error("Tangle Sandbox event data must be plain JSON");
+        }
+        const keys = Object.keys(current);
+        if (keys.length > 256)
+            throw new Error("Tangle Sandbox event map is too large");
+        for (const key of keys) {
+            if (key.length > 512)
+                throw new Error("Tangle Sandbox event key is too long");
+            pending.push({ value: current[key], depth: item.depth + 1 });
+        }
+    }
+}

package/dist/tangle-exact-process-environment.d.ts

@@ -0,0 +1,3 @@
+import type { AgentExactProcessEnvironment } from "@tangle-network/agent-interface/environment-provider";
+import type { SandboxInstanceLike } from "./tangle-types.js";
+export declare function sandboxInstanceAsExactProcessEnvironment(box: SandboxInstanceLike, providerName: string): AgentExactProcessEnvironment;

package/dist/tangle-exact-process-environment.js

@@ -0,0 +1,184 @@
+import { attachCleanupHandle, awaitWithSignal, MAX_EXACT_FILE_BYTES, MAX_LIST_RESULTS, } from "./tangle-contract-safety.js";
+import { exactProcessStatusFromSandbox, sandboxProcessAsExactProcess, validateExactProcessLaunch, } from "./tangle-exact-process-runtime.js";
+import { assertAbsoluteFilePath, assertFileOptions, assertSignalOptions, } from "./tangle-exact-process-validation.js";
+export 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: box.id,
+        provider: providerName,
+        ...(box.metadata ? { metadata: box.metadata } : {}),
+        process: {
+            async list(options = {}) {
+                assertSignalOptions(options, "Tangle exact process list");
+                options.signal?.throwIfAborted();
+                const statuses = await awaitWithSignal(process.list(), options.signal);
+                options.signal?.throwIfAborted();
+                if (!Array.isArray(statuses) || statuses.length > MAX_LIST_RESULTS) {
+                    throw new Error("Tangle exact process status list exceeded its result bound");
+                }
+                return statuses.map(exactProcessStatusFromSandbox);
+            },
+            async get(pid, options = {}) {
+                if (!Number.isSafeInteger(pid) || pid < 1) {
+                    throw new Error("Tangle exact process pid is invalid");
+                }
+                assertSignalOptions(options, "Tangle exact process get");
+                options.signal?.throwIfAborted();
+                const handle = await awaitWithSignal(process.get(pid), options.signal);
+                options.signal?.throwIfAborted();
+                if (!handle || handle.pid !== pid)
+                    return null;
+                return sandboxProcessAsExactProcess(handle);
+            },
+            async spawn(launch, operation = {}) {
+                assertSignalOptions(operation, "Tangle exact process spawn");
+                operation.signal?.throwIfAborted();
+                validateExactProcessLaunch(launch);
+                let handle;
+                const spawnPromise = 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 } : {}),
+                });
+                try {
+                    handle = await awaitWithSignal(spawnPromise, operation.signal);
+                    operation.signal?.throwIfAborted();
+                    return sandboxProcessAsExactProcess(handle);
+                }
+                catch (error) {
+                    if (!handle && operation.signal?.aborted) {
+                        void spawnPromise
+                            .then(async (lateHandle) => {
+                            try {
+                                await lateHandle.kill("SIGKILL", { tree: true });
+                            }
+                            catch (cleanupError) {
+                                attachCleanupHandle(error, lateHandle, cleanupError);
+                            }
+                        })
+                            .catch((lateError) => attachCleanupHandle(error, undefined, lateError));
+                        throw error;
+                    }
+                    if (!handle)
+                        throw error;
+                    try {
+                        await handle.kill("SIGKILL", { tree: true });
+                    }
+                    catch (cleanupError) {
+                        throw new AggregateError([error, cleanupError], "Tangle exact process spawn and cleanup both failed");
+                    }
+                    throw error;
+                }
+            },
+        },
+        async writeFile(path, bytes, options) {
+            assertFileOptions(options, "Tangle exact process write");
+            options.signal?.throwIfAborted();
+            assertAbsoluteFilePath(path);
+            if (!(bytes instanceof Uint8Array)) {
+                throw new Error("Tangle exact process write requires Uint8Array bytes");
+            }
+            if (bytes.byteLength > MAX_EXACT_FILE_BYTES) {
+                throw new Error("Tangle exact process write exceeds its byte bound");
+            }
+            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 awaitWithSignal(fs.write(path, Buffer.from(bytes).toString("base64"), {
+                encoding: "base64",
+                mode: options.mode,
+            }), options.signal);
+            options.signal?.throwIfAborted();
+        },
+        async readFile(path, options) {
+            assertFileOptions(options, "Tangle exact process read");
+            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");
+            }
+            if (options.maxBytes > MAX_EXACT_FILE_BYTES) {
+                throw new Error("Tangle exact process maxBytes exceeds its bound");
+            }
+            const stat = await awaitWithSignal(fs.stat(path), options.signal);
+            options.signal?.throwIfAborted();
+            if (!stat ||
+                typeof stat !== "object" ||
+                typeof stat.isFile !== "boolean" ||
+                !Number.isSafeInteger(stat.size) ||
+                stat.size < 0 ||
+                stat.size > MAX_EXACT_FILE_BYTES) {
+                throw new Error("Tangle exact process file stat returned an invalid size");
+            }
+            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 awaitWithSignal(fs.readBatch([path], { encoding: "base64" }), options.signal);
+            options.signal?.throwIfAborted();
+            if (!result ||
+                !Array.isArray(result.files) ||
+                result.files.length > 1 ||
+                !Array.isArray(result.errors) ||
+                result.errors.length > 256) {
+                throw new Error("Tangle exact process file read returned an invalid result");
+            }
+            for (const error of result.errors) {
+                if (!error ||
+                    typeof error !== "object" ||
+                    typeof error.path !== "string" ||
+                    error.path.length > 512 ||
+                    typeof error.error !== "string" ||
+                    error.error.length > 16_384 ||
+                    (error.code !== undefined &&
+                        (typeof error.code !== "string" || error.code.length > 512))) {
+                    throw new Error("Tangle exact process file read returned an invalid error");
+                }
+            }
+            const file = result.files[0];
+            if (result.errors.length !== 0 ||
+                result.files.length !== 1 ||
+                !file ||
+                file.path !== path ||
+                file.encoding !== "base64" ||
+                typeof file.content !== "string" ||
+                !Number.isSafeInteger(file.size) ||
+                file.size < 0 ||
+                file.size > MAX_EXACT_FILE_BYTES ||
+                file.content.length > Math.ceil((MAX_EXACT_FILE_BYTES / 3) * 4) ||
+                file.content.length % 4 !== 0 ||
+                !/^[A-Za-z0-9+/]*={0,2}$/.test(file.content)) {
+                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(options = {}) {
+            assertSignalOptions(options, "Tangle exact process destroy");
+            options.signal?.throwIfAborted();
+            await awaitWithSignal(destroy(), options.signal);
+            options.signal?.throwIfAborted();
+        },
+    };
+}

package/dist/tangle-exact-process-runtime.d.ts

@@ -0,0 +1,5 @@
+import type { AgentExactProcess, AgentExactProcessLaunch, AgentExactProcessStatus } from "@tangle-network/agent-interface/environment-provider";
+import type { SandboxProcessLike, SandboxProcessStatusLike } from "./tangle-types.js";
+export declare function validateExactProcessLaunch(input: AgentExactProcessLaunch): void;
+export declare function sandboxProcessAsExactProcess(process: SandboxProcessLike): AgentExactProcess;
+export declare function exactProcessStatusFromSandbox(status: SandboxProcessStatusLike): AgentExactProcessStatus;