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

package/dist/tangle-create-options.js

@@ -0,0 +1,243 @@
+import { assertBoundedJson, boundedIdentifier, boundedString, MAX_ARRAY_LENGTH, MAX_MAP_ENTRIES, } from "./tangle-contract-safety.js";
+export function sandboxOptionsFromCreateInput(input, defaultBackend) {
+    assertCreateInputShape(input);
+    assertNoInlineSecretValues(input);
+    if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
+        throw new Error("Tangle create providerOptions are not supported");
+    }
+    if (input.providerOptions)
+        assertBoundedRecord(input.providerOptions, "Tangle create providerOptions");
+    if (input.metadata)
+        assertBoundedRecord(input.metadata, "Tangle metadata");
+    if (input.name !== undefined) {
+        boundedString(input.name, "Tangle environment name");
+        if (!input.name)
+            throw new Error("Tangle environment name cannot be empty");
+    }
+    if (input.backend !== undefined)
+        boundedIdentifier(input.backend, "Tangle backend");
+    if (input.env !== undefined)
+        assertStringRecord(input.env, "Tangle");
+    const workspace = input.workspace ?? {};
+    if (workspace.providerOptions && Object.keys(workspace.providerOptions).length > 0) {
+        throw new Error("Tangle workspace providerOptions are not supported");
+    }
+    if (workspace.providerOptions)
+        assertBoundedRecord(workspace.providerOptions, "Tangle workspace providerOptions");
+    if (workspace.environment !== undefined) {
+        boundedIdentifier(workspace.environment, "Tangle workspace environment");
+    }
+    if (workspace.image !== undefined)
+        boundedString(workspace.image, "Tangle workspace image");
+    if (workspace.cwd !== undefined)
+        boundedString(workspace.cwd, "Tangle workspace cwd");
+    if (workspace.repoUrl !== undefined)
+        boundedString(workspace.repoUrl, "Tangle repository URL");
+    if (workspace.gitRef !== undefined)
+        boundedIdentifier(workspace.gitRef, "Tangle git ref");
+    if (input.resources?.providerOptions && Object.keys(input.resources.providerOptions).length > 0) {
+        throw new Error("Tangle resource providerOptions are not supported");
+    }
+    if (input.resources?.providerOptions)
+        assertBoundedRecord(input.resources.providerOptions, "Tangle resource providerOptions");
+    if (input.resources?.gpu !== undefined)
+        boundedIdentifier(input.resources.gpu, "Tangle GPU");
+    if (input.idempotencyKey !== undefined) {
+        boundedIdentifier(input.idempotencyKey, "Tangle idempotency key");
+    }
+    if (input.workspace?.cwd === "")
+        throw new Error("Tangle workspace cwd cannot be empty");
+    if (workspace.image === "")
+        throw new Error("Tangle workspace image cannot be empty");
+    if (workspace.repoUrl === "")
+        throw new Error("Tangle repository URL cannot be empty");
+    for (const [name, value] of Object.entries(input.resources ?? {})) {
+        if (name === "providerOptions" || name === "gpu")
+            continue;
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 1)) {
+            throw new Error(`Tangle resource ${name} must be a positive safe integer`);
+        }
+    }
+    if (workspace.environment !== undefined && workspace.image !== undefined) {
+        throw new Error("Tangle workspace cannot specify both environment and image");
+    }
+    // Sandbox injects secrets by name from its own store. Accepting a name/value
+    // record and dropping it would create an environment with no credentials and
+    // no error, surfacing later as an unexplained tool failure.
+    const environment = workspace.image ?? workspace.environment;
+    const base = {};
+    return {
+        ...base,
+        ...(environment !== undefined ? { environment } : {}),
+        ...(workspace.repoUrl
+            ? {
+                git: {
+                    url: boundedString(workspace.repoUrl, "Tangle repository URL"),
+                    ...(workspace.gitRef ? { ref: boundedIdentifier(workspace.gitRef, "Tangle git ref") } : {}),
+                },
+            }
+            : {}),
+        ...(input.resources ? { resources: input.resources } : {}),
+        ...(input.env ? { env: input.env } : {}),
+        ...(Array.isArray(input.secrets) ? { secrets: input.secrets } : {}),
+        ...(input.metadata ? { metadata: input.metadata } : {}),
+        ...(input.name === undefined ? {} : { name: input.name }),
+        ...(input.idempotencyKey === undefined ? {} : { idempotencyKey: input.idempotencyKey }),
+        backend: {
+            ...(base.backend ?? {}),
+            type: (input.backend ?? defaultBackend),
+            profile: inlineAgentProfile(input.profile),
+        },
+    };
+}
+/** Reject value-bearing secret maps before any custom mapper can drop them. */
+export function assertNoInlineSecretValues(input) {
+    if (input.providerOptions !== undefined) {
+        if (!input.providerOptions || typeof input.providerOptions !== "object" || Array.isArray(input.providerOptions)) {
+            throw new Error("Tangle create providerOptions must be a JSON object");
+        }
+        assertBoundedJson(input.providerOptions);
+        if (Object.keys(input.providerOptions).length > 0) {
+            throw new Error("Tangle create providerOptions are not supported");
+        }
+    }
+    if (input.workspace?.providerOptions !== undefined) {
+        if (!input.workspace.providerOptions || typeof input.workspace.providerOptions !== "object" || Array.isArray(input.workspace.providerOptions)) {
+            throw new Error("Tangle workspace providerOptions must be a JSON object");
+        }
+        assertBoundedJson(input.workspace.providerOptions);
+        if (Object.keys(input.workspace.providerOptions).length > 0) {
+            throw new Error("Tangle workspace providerOptions are not supported");
+        }
+    }
+    if (input.resources?.providerOptions !== undefined) {
+        if (!input.resources.providerOptions || typeof input.resources.providerOptions !== "object" || Array.isArray(input.resources.providerOptions)) {
+            throw new Error("Tangle resource providerOptions must be a JSON object");
+        }
+        assertBoundedJson(input.resources.providerOptions);
+        if (Object.keys(input.resources.providerOptions).length > 0) {
+            throw new Error("Tangle resource providerOptions are not supported");
+        }
+    }
+    if (input.secrets !== undefined && !Array.isArray(input.secrets)) {
+        throw new Error("Tangle secrets must be an array of names created with client.secrets.create(); inline secret values are not accepted");
+    }
+    if (input.secrets !== undefined) {
+        if (input.secrets.length > MAX_ARRAY_LENGTH) {
+            throw new Error("Tangle secret names exceed their bound");
+        }
+        for (const secret of input.secrets)
+            boundedIdentifier(secret, "Tangle secret name");
+    }
+}
+/** A custom mapper must not smuggle a value map into the Sandbox request. */
+export function assertMappedSecretNames(options) {
+    if (options.secrets !== undefined && !Array.isArray(options.secrets)) {
+        throw new Error("Tangle mapped secrets must be an array of stored secret names");
+    }
+    if (options.secrets !== undefined) {
+        if (options.secrets.length > MAX_ARRAY_LENGTH) {
+            throw new Error("Tangle mapped secrets exceed their bound");
+        }
+        for (const secret of options.secrets)
+            boundedIdentifier(secret, "Tangle mapped secret name");
+    }
+}
+export function assertCreateInputShape(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+        throw new Error("Tangle create input must be an object");
+    }
+    const keys = new Set(Object.keys(input));
+    for (const key of [
+        "profile",
+        "backend",
+        "workspace",
+        "resources",
+        "env",
+        "secrets",
+        "metadata",
+        "name",
+        "idempotencyKey",
+        "signal",
+        "providerOptions",
+    ])
+        keys.delete(key);
+    if (keys.size > 0)
+        throw new Error("Tangle create input contains unsupported fields");
+    if (typeof input.profile === "string") {
+        boundedIdentifier(input.profile, "Tangle profile reference");
+    }
+    else {
+        if (!input.profile || typeof input.profile !== "object" || Array.isArray(input.profile)) {
+            throw new Error("Tangle profile must be an object or bounded reference");
+        }
+        assertBoundedJson(input.profile);
+    }
+    if (input.workspace !== undefined) {
+        if (!input.workspace || typeof input.workspace !== "object" || Array.isArray(input.workspace)) {
+            throw new Error("Tangle workspace must be an object");
+        }
+        const workspaceKeys = new Set(Object.keys(input.workspace));
+        for (const key of ["environment", "image", "repoUrl", "gitRef", "cwd", "providerOptions"])
+            workspaceKeys.delete(key);
+        if (workspaceKeys.size > 0)
+            throw new Error("Tangle workspace contains unsupported fields");
+    }
+    if (input.resources !== undefined) {
+        if (!input.resources || typeof input.resources !== "object" || Array.isArray(input.resources)) {
+            throw new Error("Tangle resources must be an object");
+        }
+        const resourceKeys = new Set(Object.keys(input.resources));
+        for (const key of ["cpu", "memoryMb", "diskMb", "gpu", "providerOptions"])
+            resourceKeys.delete(key);
+        if (resourceKeys.size > 0)
+            throw new Error("Tangle resources contain unsupported fields");
+    }
+}
+export function assertMappedCreateOptions(options) {
+    if (!options || typeof options !== "object" || Array.isArray(options)) {
+        throw new Error("Tangle mapped create options must be an object");
+    }
+    assertBoundedJson(options);
+    if (Object.hasOwn(options, "providerOptions")) {
+        throw new Error("Tangle mapped create providerOptions are not supported");
+    }
+    if (options.name !== undefined) {
+        boundedString(options.name, "Tangle mapped environment name");
+        if (!options.name)
+            throw new Error("Tangle mapped environment name cannot be empty");
+    }
+    if (options.idempotencyKey !== undefined)
+        boundedIdentifier(options.idempotencyKey, "Tangle mapped idempotency key");
+    if (options.env !== undefined)
+        assertStringRecord(options.env, "Tangle mapped");
+    assertMappedSecretNames(options);
+}
+function inlineAgentProfile(profile) {
+    if (typeof profile === "string") {
+        throw new Error("Tangle provider requires an inline AgentProfile, not a profile reference");
+    }
+    if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+        throw new Error("Tangle inline AgentProfile must be an object");
+    }
+    assertBoundedJson(profile);
+    return profile;
+}
+function assertBoundedRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    assertBoundedJson(value);
+}
+function assertStringRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} environment must be a JSON object`);
+    }
+    if (Object.keys(value).length > MAX_MAP_ENTRIES) {
+        throw new Error(`${label} environment has too many variables`);
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        boundedIdentifier(key, `${label} environment variable name`);
+        boundedString(entry, `${label} environment variable value`);
+    }
+}

package/dist/tangle-environment-control.d.ts

@@ -0,0 +1,6 @@
+import type { AgentSessionRef, AgentTurnInput } from "@tangle-network/agent-interface/environment-provider";
+import type { SandboxInstanceLike, SandboxSessionLike } from "./tangle-types.js";
+export declare function sessionPromptRequestDigest(input: AgentTurnInput, provider: string, environmentId: string, sessionId: string, executionId: string): `sha256:${string}`;
+export declare function hasReplayPayload(input: AgentTurnInput): boolean;
+export declare function interruptAfterAbort(box: SandboxInstanceLike, reference: AgentSessionRef): Promise<void>;
+export declare function interruptExecutionAfterAbort(source: SandboxInstanceLike | SandboxSessionLike, sessionId: string, executionId: string): Promise<void>;

package/dist/tangle-environment-control.js

@@ -0,0 +1,50 @@
+import { canonicalCandidateDigest } from "@tangle-network/agent-interface";
+export function sessionPromptRequestDigest(input, provider, environmentId, sessionId, executionId) {
+    return canonicalCandidateDigest({
+        provider,
+        environmentId,
+        sessionId,
+        executionId,
+        ...(input.turnId === undefined ? {} : { turnId: input.turnId }),
+        ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+        ...(input.parts === undefined ? {} : { parts: input.parts }),
+        ...(input.model === undefined ? {} : { model: input.model }),
+        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+        ...(input.detach === undefined ? {} : { detach: input.detach }),
+        ...(input.context === undefined ? {} : { context: input.context }),
+    });
+}
+export function hasReplayPayload(input) {
+    return (input.prompt !== undefined ||
+        input.parts !== undefined ||
+        input.model !== undefined ||
+        input.timeoutMs !== undefined ||
+        input.turnId !== undefined ||
+        input.detach !== undefined ||
+        input.context !== undefined ||
+        input.providerOptions !== undefined);
+}
+export async function interruptAfterAbort(box, reference) {
+    const sessionId = reference.id;
+    const executionId = reference.controlRef?.executionId;
+    if (!box.session || executionId === undefined)
+        return;
+    try {
+        await box.session(sessionId)?.interrupt({ executionId });
+    }
+    catch {
+        // The original abort remains the caller-visible outcome; the provider has
+        // no stronger cleanup primitive when the late dispatch result is lost.
+    }
+}
+export async function interruptExecutionAfterAbort(source, sessionId, executionId) {
+    try {
+        const target = "interrupt" in source
+            ? source
+            : source.session?.(sessionId);
+        await target?.interrupt({ executionId });
+    }
+    catch {
+        // The operation's abort remains the caller-visible result; cleanup is best effort.
+    }
+}

package/dist/tangle-environment-dispatch.d.ts

@@ -0,0 +1,3 @@
+import type { AgentSessionRef, AgentTurnInput } from "@tangle-network/agent-interface/environment-provider";
+import type { SandboxInstanceLike } from "./tangle-types.js";
+export declare function dispatchEnvironmentRun(box: SandboxInstanceLike, provider: string, environmentId: string): (input: AgentTurnInput) => Promise<AgentSessionRef>;

package/dist/tangle-environment-dispatch.js

@@ -0,0 +1,60 @@
+import { AgentTurnInputSchema } from "@tangle-network/agent-interface";
+import { executionIdFromTurnInput, promptFromTurnInput, promptOptionsFromTurnInput, } from "./tangle-prompt.js";
+import { retainedSessionControlRef, sessionRefFromSandboxDispatch } from "./tangle-session-control.js";
+import { awaitWithSignal } from "./tangle-contract-safety.js";
+import { interruptAfterAbort, sessionPromptRequestDigest, } from "./tangle-environment-control.js";
+export function dispatchEnvironmentRun(box, provider, environmentId) {
+    return async (input) => {
+        AgentTurnInputSchema.parse(input);
+        input.signal?.throwIfAborted();
+        const expectedSessionId = input.sessionId ?? input.controlRef?.sessionId;
+        const promise = box.dispatchPrompt?.(promptFromTurnInput(input), promptOptionsFromTurnInput(input, { provider, environmentId }));
+        let dispatched;
+        try {
+            dispatched = await awaitWithSignal(promise, input.signal);
+        }
+        catch (error) {
+            if (input.signal?.aborted && promise) {
+                void promise
+                    .then((late) => {
+                    const lateRef = sessionRefFromSandboxDispatch(late, provider, environmentId, executionIdFromTurnInput(input));
+                    return interruptAfterAbort(box, lateRef);
+                })
+                    .catch(() => undefined);
+            }
+            throw error;
+        }
+        let reference;
+        try {
+            reference = sessionRefFromSandboxDispatch(dispatched, provider, environmentId, executionIdFromTurnInput(input), undefined, expectedSessionId);
+        }
+        catch (error) {
+            try {
+                const unexpected = sessionRefFromSandboxDispatch(dispatched, provider, environmentId, undefined);
+                if (unexpected.metadata?.dispatched === true &&
+                    unexpected.metadata.alreadyExisted !== true) {
+                    await interruptAfterAbort(box, unexpected);
+                }
+            }
+            catch {
+                // An invalid receipt cannot identify a safe execution to interrupt.
+            }
+            throw error;
+        }
+        const executionId = reference.controlRef?.executionId;
+        const requestDigest = executionId === undefined
+            ? undefined
+            : sessionPromptRequestDigest(input, provider, environmentId, reference.id, executionId);
+        const boundReference = executionId === undefined || requestDigest === undefined
+            ? reference
+            : {
+                ...reference,
+                controlRef: retainedSessionControlRef(reference.id, executionId, provider, environmentId, requestDigest),
+            };
+        if (input.signal?.aborted) {
+            await interruptAfterAbort(box, boundReference);
+            input.signal.throwIfAborted();
+        }
+        return boundReference;
+    };
+}

package/dist/tangle-environment-session.d.ts

@@ -0,0 +1,4 @@
+import type { AgentSession } from "@tangle-network/agent-interface/environment-provider";
+import type { AgentRunControlRef } from "@tangle-network/agent-interface";
+import type { SandboxSessionLike } from "./tangle-types.js";
+export declare function sandboxSessionAsAgentSession(session: SandboxSessionLike, controlRef: AgentRunControlRef | undefined, provider: string, environmentId: string): AgentSession;

package/dist/tangle-environment-session.js

@@ -0,0 +1,156 @@
+import { AgentTurnInputSchema } from "@tangle-network/agent-interface";
+import { environmentEventFromSandboxEvent } from "./tangle-events.js";
+import { agentTurnResultFromPromptRecord, promptFromTurnInput, promptOptionsFromTurnInput, validatedSandboxPromptResult, } from "./tangle-prompt.js";
+import { retainedSessionControlRef, resolveRetainedSessionControlRef, sameRunControlRef, sessionPromptExecutionId, } from "./tangle-session-control.js";
+import { sessionStatusFromUnknown } from "./tangle-environment-values.js";
+import { awaitWithSignal, boundedIdentifier, } from "./tangle-contract-safety.js";
+import { assertOptionKeys } from "./tangle-environment-validation.js";
+import { hasReplayPayload, interruptExecutionAfterAbort, sessionPromptRequestDigest, } from "./tangle-environment-control.js";
+export function sandboxSessionAsAgentSession(session, controlRef, provider, environmentId) {
+    let activeControlRef = controlRef;
+    return {
+        id: session.id,
+        get controlRef() {
+            return activeControlRef;
+        },
+        async status(options) {
+            assertOptionKeys(options, ["signal"], "Tangle session status");
+            const status = await awaitWithSignal(session.status(options), options?.signal);
+            options?.signal?.throwIfAborted();
+            if (!status)
+                return null;
+            return sessionStatusFromUnknown(status.status);
+        },
+        async *events(options) {
+            assertOptionKeys(options, ["since", "executionId", "signal"], "Tangle session events");
+            if (options?.since !== undefined)
+                boundedIdentifier(options.since, "Tangle event cursor");
+            if (options?.executionId !== undefined)
+                boundedIdentifier(options.executionId, "Tangle execution id");
+            if (options?.executionId !== undefined && activeControlRef?.executionId !== options.executionId) {
+                throw new Error("Tangle replay executionId conflicts with the control reference");
+            }
+            const executionId = activeControlRef?.executionId ?? options?.executionId;
+            if (options?.since !== undefined && executionId === undefined) {
+                throw new Error("Tangle cursor replay requires an exact executionId from its control reference");
+            }
+            options?.signal?.throwIfAborted();
+            const seenEventIds = new Set();
+            const iterator = session.events({
+                ...(options?.since !== undefined ? { since: options.since } : {}),
+                ...(executionId !== undefined ? { executionId } : {}),
+                ...(options?.signal ? { signal: options.signal } : {}),
+            })[Symbol.asyncIterator]();
+            let completed = false;
+            try {
+                while (true) {
+                    const next = await awaitWithSignal(iterator.next(), options?.signal);
+                    if (next.done) {
+                        completed = true;
+                        break;
+                    }
+                    options?.signal?.throwIfAborted();
+                    if (options?.since !== undefined && next.value.id === options.since)
+                        continue;
+                    const converted = environmentEventFromSandboxEvent(next.value, {
+                        executionId,
+                        sessionId: session.id,
+                    });
+                    if (converted.id === undefined)
+                        throw new Error("Tangle session event arrived without a stable id");
+                    if (seenEventIds.has(converted.id))
+                        throw new Error(`Tangle session replay repeated event id ${converted.id}`);
+                    seenEventIds.add(converted.id);
+                    options?.signal?.throwIfAborted();
+                    yield converted;
+                }
+            }
+            finally {
+                if (!completed) {
+                    void Promise.resolve(iterator.return?.()).catch(() => undefined);
+                }
+            }
+            options?.signal?.throwIfAborted();
+        },
+        async result(options) {
+            assertOptionKeys(options, ["signal"], "Tangle session result");
+            const expectedExecutionId = activeControlRef?.executionId;
+            if (expectedExecutionId === undefined)
+                throw new Error("Tangle session result requires an exact executionId from its control reference");
+            const result = await awaitWithSignal(session.result({ executionId: expectedExecutionId, signal: options?.signal }), options?.signal);
+            options?.signal?.throwIfAborted();
+            const resultRecord = validatedSandboxPromptResult(result);
+            if (resultRecord.executionId !== expectedExecutionId)
+                throw new Error("Tangle session result did not confirm its exact executionId");
+            return agentTurnResultFromPromptRecord(resultRecord, { sessionId: session.id });
+        },
+        async prompt(input) {
+            AgentTurnInputSchema.parse(input);
+            input.signal?.throwIfAborted();
+            if (input.sessionId !== undefined && input.sessionId !== session.id)
+                throw new Error("Tangle sessionId conflicts with this session");
+            const requestedControlRef = resolveRetainedSessionControlRef(input.controlRef, session.id, provider, environmentId);
+            if (activeControlRef && requestedControlRef && !sameRunControlRef(activeControlRef, requestedControlRef))
+                throw new Error("Tangle prompt control reference conflicts with this session");
+            const sourceControlRef = requestedControlRef ?? activeControlRef;
+            const replay = input.lastEventId !== undefined;
+            if (replay && sourceControlRef?.executionId !== undefined && input.executionId !== undefined && input.executionId !== sourceControlRef.executionId)
+                throw new Error("Tangle replay executionId conflicts with the control reference");
+            if (replay && sourceControlRef?.requestDigest === undefined) {
+                throw new Error("Tangle replay requires an exact request digest from its control reference");
+            }
+            const executionId = replay ? input.executionId ?? sourceControlRef?.executionId : input.executionId ?? sessionPromptExecutionId(provider, environmentId, session.id, input.turnId);
+            if (executionId === undefined)
+                throw new Error("Tangle session replay requires the exact executionId from its control reference");
+            const computedRequestDigest = sessionPromptRequestDigest(input, provider, environmentId, session.id, executionId);
+            const sameExecution = sourceControlRef?.executionId === executionId;
+            if (sourceControlRef?.requestDigest !== undefined &&
+                sameExecution &&
+                (!replay || hasReplayPayload(input)) &&
+                sourceControlRef.requestDigest !== computedRequestDigest) {
+                throw new Error("Tangle prompt request digest conflicts with the control reference");
+            }
+            const requestDigest = replay || sameExecution
+                ? sourceControlRef?.requestDigest
+                : computedRequestDigest;
+            if (requestDigest === undefined) {
+                throw new Error("Tangle prompt could not establish an exact request digest");
+            }
+            const promptInput = replay
+                ? { ...input, sessionId: session.id, executionId, controlRef: sourceControlRef }
+                : { ...input, sessionId: session.id, executionId, controlRef: undefined };
+            try {
+                const result = await awaitWithSignal(session.prompt(promptFromTurnInput(input), promptOptionsFromTurnInput(promptInput, { provider, environmentId, sessionId: session.id })), input.signal);
+                input.signal?.throwIfAborted();
+                const resultRecord = validatedSandboxPromptResult(result);
+                if (resultRecord.executionId !== executionId) {
+                    void interruptExecutionAfterAbort(session, session.id, executionId);
+                    throw new Error("Tangle session prompt did not confirm its exact executionId");
+                }
+                activeControlRef = retainedSessionControlRef(session.id, executionId, provider, environmentId, requestDigest);
+                return agentTurnResultFromPromptRecord(resultRecord, {
+                    sessionId: session.id,
+                    ...(input.contextTransfer ? { contextTransferRequest: input.contextTransfer } : {}),
+                    ...(input.contextTransfer ? { contextTransferRequested: true } : {}),
+                });
+            }
+            catch (error) {
+                if (input.signal?.aborted) {
+                    void interruptExecutionAfterAbort(session, session.id, executionId);
+                }
+                throw error;
+            }
+        },
+        async cancel(options) {
+            assertOptionKeys(options, ["signal"], "Tangle session cancel");
+            const executionId = activeControlRef?.executionId;
+            if (executionId === undefined)
+                throw new Error("Tangle session cancellation requires an exact executionId from its control reference");
+            options?.signal?.throwIfAborted();
+            const result = await awaitWithSignal(session.interrupt({ executionId, signal: options?.signal }), options?.signal);
+            options?.signal?.throwIfAborted();
+            if (result.cancelled !== true)
+                throw new Error("Tangle sandbox did not confirm cancellation");
+        },
+    };
+}

package/dist/tangle-environment-validation.d.ts

@@ -0,0 +1,11 @@
+import type { CheckpointRef, CheckpointRequest, ExecRequest, ForkRequest } from "@tangle-network/agent-interface/environment-provider";
+export declare function assertOptionKeys(value: object | undefined, allowed: readonly string[], label: string): void;
+export declare function assertRecord(value: unknown, label: string): asserts value is Record<string, unknown>;
+export declare function assertExecOptions(options: ExecRequest | undefined): void;
+export declare function assertCheckpointOptions(options: (CheckpointRequest & {
+    signal?: AbortSignal;
+}) | undefined): void;
+export declare function assertCheckpointRef(checkpoint: CheckpointRef): void;
+export declare function assertForkOptions(options: (ForkRequest & {
+    signal?: AbortSignal;
+}) | undefined): void;

package/dist/tangle-environment-validation.js

@@ -0,0 +1,63 @@
+import { assertBoundedJson, boundedIdentifier, boundedString, MAX_MAP_ENTRIES, } from "./tangle-contract-safety.js";
+export function assertOptionKeys(value, allowed, label) {
+    if (value === undefined)
+        return;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} options must be an object`);
+    }
+    const accepted = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!accepted.has(key))
+            throw new Error(`${label} options contain unsupported field ${key}`);
+    }
+}
+export function assertRecord(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be a JSON object`);
+    }
+    assertBoundedJson(value);
+    if (Object.keys(value).length > MAX_MAP_ENTRIES) {
+        throw new Error(`${label} has too many entries`);
+    }
+}
+export function assertExecOptions(options) {
+    assertOptionKeys(options, ["cwd", "env", "timeoutMs", "signal"], "Tangle exec");
+    if (options?.cwd !== undefined)
+        boundedString(options.cwd, "Tangle exec cwd");
+    if (options?.env !== undefined) {
+        assertRecord(options.env, "Tangle exec environment");
+        for (const [key, value] of Object.entries(options.env)) {
+            boundedIdentifier(key, "Tangle exec environment key");
+            boundedString(value, "Tangle exec environment value");
+        }
+    }
+    if (options?.timeoutMs !== undefined &&
+        (!Number.isSafeInteger(options.timeoutMs) || options.timeoutMs < 1)) {
+        throw new Error("Tangle exec timeoutMs must be a positive safe integer");
+    }
+}
+export function assertCheckpointOptions(options) {
+    assertOptionKeys(options, ["name", "metadata", "signal"], "Tangle checkpoint");
+    if (options?.name !== undefined)
+        boundedString(options.name, "Tangle checkpoint name");
+    if (options?.metadata !== undefined)
+        assertRecord(options.metadata, "Tangle checkpoint metadata");
+}
+export function assertCheckpointRef(checkpoint) {
+    if (!checkpoint || typeof checkpoint !== "object" || Array.isArray(checkpoint)) {
+        throw new Error("Tangle fork checkpoint must be an object");
+    }
+    assertOptionKeys(checkpoint, ["id", "provider", "metadata"], "Tangle fork checkpoint");
+    boundedIdentifier(checkpoint.id, "Tangle checkpoint id");
+    if (checkpoint.provider !== undefined)
+        boundedIdentifier(checkpoint.provider, "Tangle checkpoint provider");
+    if (checkpoint.metadata !== undefined)
+        assertRecord(checkpoint.metadata, "Tangle checkpoint metadata");
+}
+export function assertForkOptions(options) {
+    assertOptionKeys(options, ["name", "metadata", "signal"], "Tangle fork");
+    if (options?.name !== undefined)
+        boundedString(options.name, "Tangle fork name");
+    if (options?.metadata !== undefined)
+        assertRecord(options.metadata, "Tangle fork metadata");
+}

package/dist/tangle-environment-values.d.ts

@@ -0,0 +1,8 @@
+import type { AgentEnvironmentStatus, AgentSessionStatus, PlacementInfo } from "@tangle-network/agent-interface/environment-provider";
+import type { SandboxInstanceLike } from "./tangle-types.js";
+export declare function nonEmptyString(value: unknown): string | undefined;
+export declare function optionalNonEmptyString(value: unknown, label: string): string | undefined;
+export declare function checkpointIdFromResult(result: unknown): string;
+export declare function placementInfoFromLoopPlacement(placement: unknown, box: SandboxInstanceLike): PlacementInfo;
+export declare function statusFromUnknown(status: unknown): AgentEnvironmentStatus;
+export declare function sessionStatusFromUnknown(status: unknown): AgentSessionStatus;