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

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

@@ -0,0 +1,150 @@
+import { awaitWithSignal, boundedIdentifier, boundedString, MAX_ARRAY_LENGTH, MAX_EXACT_FILE_BYTES, } from "./tangle-contract-safety.js";
+import { assertAbsoluteFilePath } from "./tangle-exact-process-validation.js";
+export function validateExactProcessLaunch(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Tangle exact process launch must be an object");
+    }
+    const unsupported = new Set(Object.keys(input));
+    for (const key of ["executable", "args", "cwd", "env", "stdin", "timeoutMs"]) {
+        unsupported.delete(key);
+    }
+    if (unsupported.size > 0)
+        throw new Error("Tangle exact process launch contains unsupported fields");
+    const executable = boundedProcessString(input.executable, "Tangle exact process executable");
+    if (!Array.isArray(input.args) || input.args.length > MAX_ARRAY_LENGTH)
+        throw new Error("Tangle exact process has too many arguments");
+    for (const argument of input.args)
+        boundedProcessString(argument, "Tangle exact process argument");
+    if (!input.env || typeof input.env !== "object" || Array.isArray(input.env) || Object.keys(input.env).length > MAX_ARRAY_LENGTH)
+        throw new Error("Tangle exact process environment has too many entries");
+    for (const [key, value] of Object.entries(input.env)) {
+        boundedIdentifier(key, "Tangle exact process environment key");
+        assertNoProcessNul(key, "Tangle exact process environment key");
+        boundedProcessString(value, "Tangle exact process environment value");
+    }
+    if (!executable || (!executable.startsWith("/") && !input.env.PATH?.trim())) {
+        throw new Error("Tangle exact process executable must be absolute unless env.PATH is supplied");
+    }
+    if (executable.startsWith("/"))
+        assertAbsoluteFilePath(executable);
+    assertAbsoluteFilePath(input.cwd);
+    if (input.stdin !== undefined)
+        boundedProcessString(input.stdin, "Tangle exact process stdin");
+    if (!Number.isSafeInteger(input.timeoutMs) || input.timeoutMs < 0 || input.timeoutMs > MAX_EXACT_FILE_BYTES) {
+        throw new Error("Tangle exact process timeoutMs must be a non-negative integer");
+    }
+}
+export function sandboxProcessAsExactProcess(process) {
+    assertProcessId(process.pid);
+    return {
+        pid: process.pid,
+        async status(options = {}) {
+            assertSignalOptions(options, "Tangle exact process status");
+            options.signal?.throwIfAborted();
+            const status = await awaitWithSignal(process.status(), options.signal);
+            options.signal?.throwIfAborted();
+            return exactProcessStatusFromSandbox(status);
+        },
+        async wait(options = {}) {
+            assertSignalOptions(options, "Tangle exact process wait");
+            options.signal?.throwIfAborted();
+            await awaitWithSignal(process.wait(), options.signal);
+            const status = exactProcessStatusFromSandbox(await awaitWithSignal(process.status(), options.signal));
+            if (!status.termination)
+                throw new Error("Tangle exact process remained running after wait()");
+            return status.termination;
+        },
+        async kill(options = {}) {
+            assertSignalOptions(options, "Tangle exact process kill");
+            options.signal?.throwIfAborted();
+            await awaitWithSignal(process.kill("SIGKILL", { tree: true }), options.signal);
+            options.signal?.throwIfAborted();
+        },
+        async *stdout(options = {}) {
+            assertSignalOptions(options, "Tangle exact process stdout");
+            options.signal?.throwIfAborted();
+            yield* boundedProcessOutput(process.stdout(), options.signal, "Tangle exact process stdout");
+        },
+        async *stderr(options = {}) {
+            assertSignalOptions(options, "Tangle exact process stderr");
+            options.signal?.throwIfAborted();
+            yield* boundedProcessOutput(process.stderr(), options.signal, "Tangle exact process stderr");
+        },
+    };
+}
+async function* boundedProcessOutput(source, signal, label) {
+    const iterator = source[Symbol.asyncIterator]();
+    let completed = false;
+    let bytes = 0;
+    try {
+        while (true) {
+            const next = await awaitWithSignal(iterator.next(), signal);
+            if (next.done) {
+                completed = true;
+                break;
+            }
+            signal?.throwIfAborted();
+            const bounded = boundedString(next.value, label);
+            bytes += Buffer.byteLength(bounded, "utf8");
+            if (bytes > MAX_EXACT_FILE_BYTES) {
+                throw new Error(`${label} exceeded its byte bound`);
+            }
+            yield bounded;
+        }
+    }
+    finally {
+        if (!completed) {
+            void Promise.resolve(iterator.return?.()).catch(() => undefined);
+        }
+    }
+}
+export function exactProcessStatusFromSandbox(status) {
+    if (!status || typeof status !== "object")
+        throw new Error("Tangle exact process returned no status");
+    assertProcessId(status.pid);
+    if (typeof status.running !== "boolean")
+        throw new Error("Tangle exact process status has no running flag");
+    if (!Number.isSafeInteger(status.exitCode))
+        throw new Error("Tangle exact process status has an invalid exit code");
+    if (status.running ? status.exitCode !== -1 : status.exitCode < 0) {
+        throw new Error("Tangle exact process status has an invalid exit state");
+    }
+    if (status.exitSignal !== undefined)
+        boundedIdentifier(status.exitSignal, "Tangle exact process exit signal");
+    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 assertProcessId(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        throw new Error("Tangle exact process pid is invalid");
+}
+function boundedProcessString(value, label) {
+    const bounded = boundedString(value, label);
+    assertNoProcessNul(bounded, label);
+    return bounded;
+}
+function assertNoProcessNul(value, label) {
+    if (value.includes("\0"))
+        throw new Error(`${label} contains a NUL byte`);
+}
+function assertSignalOptions(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${label} options must be an object`);
+    for (const key of Object.keys(value)) {
+        if (key !== "signal")
+            throw new Error(`${label} options contain unsupported field ${key}`);
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { SandboxInstanceLike } from "./tangle-types.js";
+export declare const EXACT_PROCESS_METADATA_KEY = "tangle.exactProcess";
+export declare function assertExactProcessSandbox(box: SandboxInstanceLike, providerName: string, teamId?: string, requestDigest?: `sha256:${string}`): void;
+export declare function isExactProcessSandbox(box: SandboxInstanceLike, providerName: string, teamId?: string, requestDigest?: `sha256:${string}`): boolean;
+export declare function isExactProcessRequestConflict(box: SandboxInstanceLike, providerName: string, teamId: string | undefined, idempotencyKey: string, requestDigest: `sha256:${string}`): boolean;
+export declare function assertUnreservedMetadata(metadata: Record<string, unknown>): void;
+export declare function assertSupportedProviderOptions(providerOptions: Record<string, unknown> | undefined): void;
+export declare function assertAbsoluteFilePath(path: string): void;
+export declare function assertSignalOptions(value: {
+    signal?: AbortSignal;
+}, label: string): void;
+export declare function assertFileOptions(value: {
+    mode?: number;
+    maxBytes?: number;
+    signal?: AbortSignal;
+}, label: string): void;
+export declare function metadataMatches(actual: Record<string, unknown> | undefined, expected: Record<string, unknown> | undefined): boolean;

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

@@ -0,0 +1,123 @@
+import { isDeepStrictEqual } from "node:util";
+import { assertBoundedJson, boundedIdentifier, boundedString, isBoundedJson, } from "./tangle-contract-safety.js";
+export const EXACT_PROCESS_METADATA_KEY = "tangle.exactProcess";
+export function assertExactProcessSandbox(box, providerName, teamId, requestDigest) {
+    if (!isExactProcessSandbox(box, providerName, teamId, requestDigest)) {
+        throw new Error("Tangle Sandbox did not create the requested process-only runtime");
+    }
+}
+export function isExactProcessSandbox(box, providerName, teamId, requestDigest) {
+    try {
+        boundedIdentifier(box.id, "exact process environment id");
+    }
+    catch {
+        return false;
+    }
+    if (box.metadata !== undefined && !isBoundedJson(box.metadata))
+        return false;
+    if (!box.metadata ||
+        !Object.hasOwn(box.metadata, EXACT_PROCESS_METADATA_KEY) ||
+        !Object.hasOwn(box.metadata, "runtimeMode"))
+        return false;
+    const marker = box.metadata[EXACT_PROCESS_METADATA_KEY];
+    if (!marker || typeof marker !== "object" || Array.isArray(marker))
+        return false;
+    const record = marker;
+    return (box.metadata.runtimeMode === "control" &&
+        Object.hasOwn(record, "version") && record.version === 1 &&
+        Object.hasOwn(record, "provider") && record.provider === providerName &&
+        (teamId === undefined
+            ? !Object.hasOwn(record, "teamId")
+            : Object.hasOwn(record, "teamId") && record.teamId === teamId) &&
+        Object.hasOwn(record, "idempotencyKey") &&
+        typeof record.idempotencyKey === "string" &&
+        record.idempotencyKey.length > 0 &&
+        record.idempotencyKey.length <= 512 &&
+        record.idempotencyKey.trim() === record.idempotencyKey &&
+        Object.hasOwn(record, "requestDigest") &&
+        typeof record.requestDigest === "string" &&
+        /^sha256:[a-f0-9]{64}$/.test(record.requestDigest) &&
+        (requestDigest === undefined || record.requestDigest === requestDigest));
+}
+export function isExactProcessRequestConflict(box, providerName, teamId, idempotencyKey, requestDigest) {
+    if (!box.metadata ||
+        !isBoundedJson(box.metadata) ||
+        box.metadata.runtimeMode !== "control")
+        return false;
+    const marker = box.metadata?.[EXACT_PROCESS_METADATA_KEY];
+    if (!marker || typeof marker !== "object" || Array.isArray(marker))
+        return false;
+    const record = marker;
+    if (record.idempotencyKey !== idempotencyKey)
+        return false;
+    return (record.provider !== providerName ||
+        (teamId === undefined
+            ? Object.hasOwn(record, "teamId")
+            : record.teamId !== teamId) ||
+        record.requestDigest !== requestDigest);
+}
+export function assertUnreservedMetadata(metadata) {
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        throw new Error("exact process metadata must be a JSON object");
+    }
+    assertBoundedJson(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");
+    }
+}
+export function assertSupportedProviderOptions(providerOptions) {
+    if (providerOptions !== undefined &&
+        (!providerOptions || typeof providerOptions !== "object" || Array.isArray(providerOptions))) {
+        throw new Error("Tangle exact process providerOptions must be a JSON object");
+    }
+    if (providerOptions && !isBoundedJson(providerOptions)) {
+        throw new Error("Tangle exact process providerOptions exceed their bound");
+    }
+    if (providerOptions && Object.keys(providerOptions).length > 0) {
+        throw new Error("Tangle exact process providerOptions are not supported");
+    }
+}
+export function assertAbsoluteFilePath(path) {
+    boundedString(path, "Tangle exact process file path");
+    if (!path.startsWith("/") ||
+        path.includes("\0") ||
+        path.includes("\\") ||
+        path.split("/").some((segment) => segment === "." || segment === "..")) {
+        throw new Error("Tangle exact process file path must be absolute");
+    }
+}
+export function assertSignalOptions(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} options must be an object`);
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== "signal")
+            throw new Error(`${label} options contain unsupported field ${key}`);
+    }
+}
+export function assertFileOptions(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} options must be an object`);
+    }
+    const allowed = new Set(["mode", "maxBytes", "signal"]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw new Error(`${label} options contain unsupported field ${key}`);
+    }
+}
+export function metadataMatches(actual, expected) {
+    if (!expected)
+        return true;
+    if (!actual)
+        return false;
+    return Object.entries(expected).every(([key, value]) => Object.hasOwn(actual, key) && isDeepStrictEqual(actual[key], value));
+}

package/dist/tangle-prompt.d.ts

@@ -0,0 +1,24 @@
+import type { PromptOptions, PromptResult } from "@tangle-network/sandbox";
+import type { AgentTurnInput, AgentTurnResult } from "@tangle-network/agent-interface/environment-provider";
+import type { InputPart } from "@tangle-network/agent-interface";
+export declare function promptFromTurnInput(input: AgentTurnInput): string | InputPart[];
+export declare function executionIdFromTurnInput(input: AgentTurnInput): string | undefined;
+export declare function promptOptionsFromTurnInput(input: AgentTurnInput, target: {
+    provider: string;
+    environmentId: string;
+    sessionId?: string;
+}): PromptOptions;
+type SandboxRunStatus = "success" | "failed" | "blocked_on_approval" | "awaiting_question" | "awaiting_plan_decision";
+type ValidatedSandboxPromptResult = Record<string, unknown> & {
+    success: boolean;
+    status: SandboxRunStatus;
+    durationMs: number;
+    executionId?: string;
+};
+export declare function validatedSandboxPromptResult(result: PromptResult): ValidatedSandboxPromptResult;
+export declare function agentTurnResultFromPromptRecord(record: ValidatedSandboxPromptResult, options?: {
+    contextTransferRequested?: boolean;
+    contextTransferRequest?: import("@tangle-network/agent-interface").ContextTransferRequest;
+    sessionId?: string;
+}): AgentTurnResult;
+export {};

package/dist/tangle-prompt.js

@@ -0,0 +1,166 @@
+import { AgentExactRunControlRefSchema, AgentTurnInputSchema, ContextTransferReceiptSchema, contextTransferResultMatchesRequest, } from "@tangle-network/agent-interface";
+import { tokenUsageFromData } from "./tangle-result-values.js";
+import { assertBoundedJson } from "./tangle-contract-safety.js";
+export function promptFromTurnInput(input) {
+    AgentTurnInputSchema.parse(input);
+    if (input.parts)
+        return input.parts;
+    return input.prompt ?? "";
+}
+export function executionIdFromTurnInput(input) {
+    return input.executionId ?? input.controlRef?.executionId;
+}
+export function promptOptionsFromTurnInput(input, target) {
+    if (input.contextTransfer !== undefined) {
+        throw new Error("Tangle provider does not yet support portable context transfer");
+    }
+    if (input.nativeContinuation !== undefined) {
+        throw new Error("Tangle provider does not yet support verified native continuation");
+    }
+    AgentTurnInputSchema.parse(input);
+    const controlRef = input.controlRef
+        ? AgentExactRunControlRefSchema.parse(input.controlRef)
+        : undefined;
+    if (controlRef) {
+        if (controlRef.provider !== target.provider ||
+            controlRef.environmentId !== target.environmentId ||
+            (target.sessionId !== undefined &&
+                controlRef.sessionId !== target.sessionId)) {
+            throw new Error("Tangle control reference does not match this target");
+        }
+        if (controlRef.sessionId === undefined || controlRef.executionId === undefined) {
+            throw new Error("Tangle control reference requires exact sessionId and executionId");
+        }
+        if (controlRef.runId !== controlRef.executionId) {
+            throw new Error("Tangle control reference requires runId to equal executionId");
+        }
+        if (input.sessionId !== undefined &&
+            input.sessionId !== controlRef.sessionId) {
+            throw new Error("Tangle sessionId conflicts with the control reference");
+        }
+        if (input.executionId !== undefined &&
+            input.executionId !== controlRef.executionId) {
+            throw new Error("Tangle executionId conflicts with the control reference");
+        }
+    }
+    if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
+        throw new Error("Tangle prompt providerOptions are not supported");
+    }
+    const sessionId = input.sessionId ?? controlRef?.sessionId;
+    const executionId = input.executionId ?? controlRef?.executionId;
+    return {
+        ...(sessionId ? { sessionId } : {}),
+        ...(input.model ? { model: input.model } : {}),
+        ...(input.timeoutMs !== undefined ? { timeoutMs: input.timeoutMs } : {}),
+        ...(input.context ? { context: input.context } : {}),
+        ...(input.signal ? { signal: input.signal } : {}),
+        ...(executionId ? { executionId } : {}),
+        ...(input.lastEventId ? { lastEventId: input.lastEventId } : {}),
+        ...(input.turnId ? { turnId: input.turnId } : {}),
+        ...(input.detach !== undefined ? { detach: input.detach } : {}),
+    };
+}
+export function validatedSandboxPromptResult(result) {
+    if (!result || typeof result !== "object" || Array.isArray(result)) {
+        throw new Error("Tangle prompt returned no result object");
+    }
+    const record = result;
+    if (Object.hasOwn(record, "contextTransferReceipt") &&
+        record.contextTransferReceipt === undefined) {
+        throw new Error("Tangle prompt result returned a context receipt for a turn that requested no transfer");
+    }
+    assertBoundedJson(record);
+    if (typeof record.success !== "boolean") {
+        throw new Error("Tangle prompt result omitted its success status");
+    }
+    const statuses = new Set([
+        "success",
+        "failed",
+        "blocked_on_approval",
+        "awaiting_question",
+        "awaiting_plan_decision",
+    ]);
+    if (typeof record.status !== "string" ||
+        !statuses.has(record.status)) {
+        throw new Error("Tangle prompt result contained an invalid run status");
+    }
+    if (record.success !== (record.status === "success")) {
+        throw new Error("Tangle prompt result success flag conflicts with its run status");
+    }
+    if (typeof record.durationMs !== "number" ||
+        !Number.isFinite(record.durationMs) ||
+        record.durationMs < 0) {
+        throw new Error("Tangle prompt result contained an invalid duration");
+    }
+    for (const field of [
+        "executionId",
+        "response",
+        "text",
+        "finalText",
+        "error",
+        "errorCode",
+        "traceId",
+    ]) {
+        if (record[field] !== undefined && typeof record[field] !== "string") {
+            throw new Error(`Tangle prompt result contained an invalid ${field}`);
+        }
+    }
+    if (record.executionId === "") {
+        throw new Error("Tangle prompt result contained an empty executionId");
+    }
+    tokenUsageFromData(record);
+    return record;
+}
+/** Statuses that mean the run is waiting for a human, not that it failed. */
+const AWAITING_STATUSES = new Set([
+    "blocked_on_approval",
+    "awaiting_question",
+    "awaiting_plan_decision",
+]);
+export function agentTurnResultFromPromptRecord(record, options = {}) {
+    const text = typeof record.response === "string"
+        ? record.response
+        : typeof record.text === "string"
+            ? record.text
+            : typeof record.finalText === "string"
+                ? record.finalText
+                : "";
+    // A receipt with no transfer behind it would let the caller record a handoff
+    // that never happened, so it is refused rather than passed through.
+    const hasContextTransferReceipt = Object.hasOwn(record, "contextTransferReceipt");
+    if (hasContextTransferReceipt && options.contextTransferRequested !== true) {
+        throw new Error("Tangle prompt result returned a context receipt for a turn that requested no transfer");
+    }
+    const rawContextTransferReceipt = hasContextTransferReceipt
+        ? record.contextTransferReceipt
+        : undefined;
+    const contextTransferReceipt = ContextTransferReceiptSchema.safeParse(rawContextTransferReceipt);
+    if (hasContextTransferReceipt && !contextTransferReceipt.success) {
+        throw new Error("Tangle prompt result contained an invalid context receipt");
+    }
+    if (contextTransferReceipt.success &&
+        options.contextTransferRequest !== undefined &&
+        !contextTransferResultMatchesRequest(options.contextTransferRequest, contextTransferReceipt.data)) {
+        throw new Error("Tangle prompt result context receipt does not match its request");
+    }
+    const usage = tokenUsageFromData(record);
+    const awaiting = AWAITING_STATUSES.has(record.status);
+    return {
+        text,
+        success: record.success,
+        ...(options.sessionId ? { sessionId: options.sessionId } : {}),
+        ...(typeof record.error === "string" ? { error: record.error } : {}),
+        ...(usage ? { usage } : {}),
+        // A waiting run is not a terminal failure. Dropping the status here made
+        // "the agent is asking you something" indistinguishable from "the turn
+        // failed", while the sandbox stayed alive waiting for an answer.
+        metadata: {
+            status: record.status,
+            awaitingInteraction: awaiting,
+            terminal: !awaiting,
+        },
+        ...(contextTransferReceipt.success
+            ? { contextTransferReceipt: contextTransferReceipt.data }
+            : {}),
+    };
+}

package/dist/tangle-provider.d.ts

@@ -0,0 +1,3 @@
+import type { AgentEnvironmentProvider } from "@tangle-network/agent-interface/environment-provider";
+import type { TangleProviderOptions } from "./tangle-types.js";
+export declare function createTangleProvider(options: TangleProviderOptions): AgentEnvironmentProvider;