@tangle-network/agent-provider-tangle 0.6.2 → 0.7.0

package/dist/tangle-events.js

@@ -1,6 +1,48 @@
+import { CanonicalStreamEventSchema, } from "@tangle-network/agent-interface";
 import { assertBoundedJson } from "./tangle-contract-safety.js";
 import { optionalNonEmptyString } from "./tangle-environment-values.js";
 import { tokenUsageFromData } from "./tangle-result-values.js";
+/** The sidecar sends this envelope when an SSE connection is ready. */
+export function isSandboxConnectionMarker(event) {
+    if (!event || typeof event !== "object")
+        return false;
+    const record = event;
+    if (record.type === "connection.established")
+        return true;
+    const data = record.data;
+    return (data !== null &&
+        typeof data === "object" &&
+        !Array.isArray(data) &&
+        data.type === "connection.established");
+}
+/** Read identity from both run frames and /agents/events session envelopes. */
+export function sandboxEventIdentity(event) {
+    const record = event;
+    const data = record.data;
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        return {};
+    }
+    const dataRecord = data;
+    const properties = dataRecord.properties &&
+        typeof dataRecord.properties === "object" &&
+        !Array.isArray(dataRecord.properties)
+        ? dataRecord.properties
+        : undefined;
+    const info = properties?.info &&
+        typeof properties.info === "object" &&
+        !Array.isArray(properties.info)
+        ? properties.info
+        : undefined;
+    return {
+        executionId: optionalNonEmptyString(dataRecord.executionId ?? properties?.executionId ?? info?.executionId, "Tangle Sandbox event executionId"),
+        sessionId: optionalNonEmptyString(dataRecord.sessionId ??
+            dataRecord.sessionID ??
+            properties?.sessionId ??
+            properties?.sessionID ??
+            info?.sessionId ??
+            info?.sessionID, "Tangle Sandbox event sessionId"),
+    };
+}
 export function environmentEventFromSandboxEvent(event, expected = {}) {
     if (!event || typeof event !== "object") {
         throw new Error("Tangle Sandbox emitted a non-object event");
@@ -30,27 +72,145 @@ export function environmentEventFromSandboxEvent(event, expected = {}) {
     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");
+    const { executionId: eventExecutionId, sessionId: eventSessionId } = sandboxEventIdentity(event);
     if (expected.executionId !== undefined &&
-        (eventExecutionId === undefined || eventExecutionId !== expected.executionId)) {
+        ((eventExecutionId === undefined && expected.streamBound !== true) ||
+            (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)) {
+        ((eventSessionId === undefined && expected.streamBound !== true) ||
+            (eventSessionId !== undefined && eventSessionId !== expected.sessionId))) {
         throw new Error("Tangle exact session event identified a different sessionId");
     }
     const usage = tokenUsageFromData(data);
+    const normalized = normalizeSandboxEvent(record.type, data);
     return {
         type: record.type,
         data,
         ...(typeof record.id === "string" ? { id: record.id } : {}),
+        ...(normalized ? { normalized } : {}),
         // 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 normalizeSandboxEvent(type, data) {
+    const supplied = data.normalized;
+    if (supplied !== undefined) {
+        const parsed = CanonicalStreamEventSchema.safeParse(supplied);
+        if (!parsed.success) {
+            throw new Error("Tangle Sandbox emitted an invalid normalized event");
+        }
+        if (parsed.data.type !== type) {
+            throw new Error(`Tangle Sandbox normalized event type "${parsed.data.type}" does not match transport type "${type}"`);
+        }
+        return parsed.data;
+    }
+    switch (type) {
+        case "status": {
+            const status = statusFromSandboxValue(data.status);
+            if (!status)
+                return undefined;
+            return {
+                type: "status",
+                status,
+                ...detailFromSandboxData(data),
+            };
+        }
+        case "message.part.updated": {
+            const candidate = {
+                type,
+                ...(data.part !== undefined ? { part: data.part } : {}),
+                ...(typeof data.delta === "string" ? { delta: data.delta } : {}),
+            };
+            const parsed = CanonicalStreamEventSchema.safeParse(candidate);
+            return parsed.success ? parsed.data : undefined;
+        }
+        case "tool-heartbeat":
+            return parseCanonical({
+                type,
+                toolName: data.toolName,
+                partId: data.partId,
+                elapsedMs: data.elapsedMs,
+            });
+        case "tool-slow":
+            return parseCanonical({
+                type,
+                toolName: data.toolName,
+                partId: data.partId,
+                elapsedMs: data.elapsedMs,
+                thresholdMs: data.thresholdMs,
+            });
+        case "model-processing":
+            return parseCanonical({
+                type,
+                phase: data.phase,
+                ...(typeof data.toolName === "string" ? { toolName: data.toolName } : {}),
+                ...(typeof data.elapsedMs === "number" ? { elapsedMs: data.elapsedMs } : {}),
+            });
+        case "warning":
+            return parseCanonical({
+                type,
+                code: data.code,
+                message: data.message,
+            });
+        case "session.updated":
+            return parseCanonical({
+                type,
+                sessionId: data.sessionId ?? data.sessionID,
+                ...(typeof data.title === "string" ? { title: data.title } : {}),
+                ...(data.time !== undefined ? { time: data.time } : {}),
+            });
+        case "interaction":
+            return parseCanonical({ type, request: data.request });
+        case "interaction.cancel":
+            return parseCanonical({
+                type,
+                id: data.id,
+                ...(typeof data.reason === "string" ? { reason: data.reason } : {}),
+            });
+        case "plan.submitted":
+            return parseCanonical({ type, plan: data.plan });
+        case "result":
+        case "done":
+        default:
+            // These transport frames carry terminal/result data, but they are not
+            // members of the provider-neutral canonical event union. The exact
+            // result endpoint remains the authoritative result surface.
+            return undefined;
+    }
+}
+function parseCanonical(value) {
+    const parsed = CanonicalStreamEventSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+function statusFromSandboxValue(value) {
+    if (typeof value !== "string")
+        return undefined;
+    switch (value) {
+        case "started":
+        case "queued":
+            return "started";
+        case "processing":
+        case "running":
+            return "processing";
+        case "completed":
+        case "success":
+            return "completed";
+        case "failed":
+        case "error":
+        case "cancelled":
+            return "failed";
+        default:
+            return undefined;
+    }
+}
+function detailFromSandboxData(data) {
+    const detail = [data.detail, data.error, data.message].find((value) => typeof value === "string" && value.length > 0);
+    return detail === undefined ? {} : { detail };
+}
 function assertBoundedRecord(value) {
     if (Object.keys(value).length > 256) {
         throw new Error("Tangle Sandbox event data has too many fields");

package/dist/tangle-prompt.d.ts

@@ -1,6 +1,6 @@
 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";
+import type { AgentExactRunControlRef, 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: {
@@ -20,5 +20,6 @@ export declare function agentTurnResultFromPromptRecord(record: ValidatedSandbox
     contextTransferRequested?: boolean;
     contextTransferRequest?: import("@tangle-network/agent-interface").ContextTransferRequest;
     sessionId?: string;
+    controlRef?: AgentExactRunControlRef;
 }): AgentTurnResult;
 export {};

package/dist/tangle-prompt.js

@@ -31,9 +31,6 @@ export function promptOptionsFromTurnInput(input, 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");
@@ -55,6 +52,7 @@ export function promptOptionsFromTurnInput(input, target) {
         ...(input.context ? { context: input.context } : {}),
         ...(input.signal ? { signal: input.signal } : {}),
         ...(executionId ? { executionId } : {}),
+        ...(controlRef ? { runControlRef: controlRef } : {}),
         ...(input.lastEventId ? { lastEventId: input.lastEventId } : {}),
         ...(input.turnId ? { turnId: input.turnId } : {}),
         ...(input.detach !== undefined ? { detach: input.detach } : {}),
@@ -118,6 +116,18 @@ const AWAITING_STATUSES = new Set([
     "awaiting_plan_decision",
 ]);
 export function agentTurnResultFromPromptRecord(record, options = {}) {
+    const controlRef = options.controlRef
+        ? AgentExactRunControlRefSchema.parse(options.controlRef)
+        : undefined;
+    if (controlRef !== undefined &&
+        options.sessionId !== undefined &&
+        controlRef.sessionId !== options.sessionId) {
+        throw new Error("Tangle prompt result sessionId conflicts with its control reference");
+    }
+    if (controlRef !== undefined &&
+        record.executionId !== controlRef.executionId) {
+        throw new Error("Tangle prompt result did not confirm its exact executionId");
+    }
     const text = typeof record.response === "string"
         ? record.response
         : typeof record.text === "string"
@@ -155,6 +165,13 @@ export function agentTurnResultFromPromptRecord(record, options = {}) {
         // "the agent is asking you something" indistinguishable from "the turn
         // failed", while the sandbox stayed alive waiting for an answer.
         metadata: {
+            ...(controlRef
+                ? {
+                    runId: controlRef.runId,
+                    executionId: controlRef.executionId,
+                    requestDigest: controlRef.requestDigest,
+                }
+                : {}),
             status: record.status,
             awaitingInteraction: awaiting,
             terminal: !awaiting,

package/dist/tangle-provider.js

@@ -15,7 +15,7 @@ export function createTangleProvider(options) {
             providerName,
         })
         : undefined;
-    const resolveCapabilities = async () => {
+    const resolveDeclaredCapabilities = async () => {
         const configured = options.capabilities
             ? typeof options.capabilities === "function"
                 ? await options.capabilities()
@@ -24,14 +24,17 @@ export function createTangleProvider(options) {
         if (!exactProcess && configured.exactProcess) {
             throw new Error("Tangle capabilities cannot advertise exactProcess without exactProcess configuration");
         }
-        const withExactProcess = exactProcess
+        return exactProcess
             ? {
                 ...configured,
                 exactProcess: { egress: ["blocked", "strict"] },
             }
             : configured;
-        return AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForClient(withExactProcess, options.client));
     };
+    // Provider-boundary document: client-stage facts only. It also validates
+    // the configured document, so create() and get() call it before any effect.
+    const narrowedProviderCapabilities = (declared) => AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForClient(declared, options.client));
+    const resolveCapabilities = async () => narrowedProviderCapabilities(await resolveDeclaredCapabilities());
     return {
         name: providerName,
         ...(exactProcess ? { exactProcess } : {}),
@@ -44,7 +47,11 @@ export function createTangleProvider(options) {
             if (input.providerOptions && Object.keys(input.providerOptions).length > 0) {
                 throw new Error("Tangle create providerOptions are not supported");
             }
-            const capabilities = await resolveCapabilities();
+            // The sandbox stage narrows from the declared document, not the
+            // provider-boundary one: the client stage cannot observe box-scoped
+            // facts, so measured instance facts must decide them per sandbox.
+            const declaredCapabilities = await resolveDeclaredCapabilities();
+            narrowedProviderCapabilities(declaredCapabilities);
             const createOptions = options.mapCreateInput?.(input) ??
                 sandboxOptionsFromCreateInput(input, options.defaultBackend ?? "opencode");
             assertMappedCreateOptions(createOptions);
@@ -76,7 +83,7 @@ export function createTangleProvider(options) {
             }
             try {
                 input.signal?.throwIfAborted();
-                const environment = sandboxInstanceAsEnvironment(box, providerName, options.client, capabilities);
+                const environment = sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities);
                 input.signal?.throwIfAborted();
                 return environment;
             }
@@ -101,14 +108,14 @@ export function createTangleProvider(options) {
                 async get(id, operation) {
                     assertProviderOperationOptions(operation, "Tangle get");
                     boundedIdentifier(id, "Tangle environment id");
+                    const declaredCapabilities = await resolveDeclaredCapabilities();
+                    narrowedProviderCapabilities(declaredCapabilities);
                     operation?.signal?.throwIfAborted();
                     const box = await awaitWithSignal(options.client.get?.(id, operation), operation?.signal);
                     operation?.signal?.throwIfAborted();
                     if (!box || boundedIdentifier(box.id, "Tangle environment id") !== id)
                         return null;
-                    return box
-                        ? sandboxInstanceAsEnvironment(box, providerName, options.client, await resolveCapabilities())
-                        : null;
+                    return sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities);
                 },
             }
             : {}),

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

@@ -1,7 +1,8 @@
-import type { AgentRunControlRef } from "@tangle-network/agent-interface";
+import type { AgentExactRunControlRef, AgentRunControlRef } from "@tangle-network/agent-interface";
 import type { AgentSessionRef } from "@tangle-network/agent-interface/environment-provider";
-export declare function sessionRefFromSandboxDispatch(dispatched: unknown, providerName: string, environmentId: string, expectedExecutionId: string | undefined, requestDigest?: `sha256:${string}` | undefined, expectedSessionId?: string | undefined): AgentSessionRef;
-export declare function retainedSessionControlRef(sessionId: string, executionId: string, provider: string, environmentId: string, requestDigest?: `sha256:${string}`): AgentRunControlRef;
-export declare function sessionPromptExecutionId(provider: string, environmentId: string, sessionId: string, turnId: string | undefined): string;
+export declare function sessionRefFromSandboxDispatch(dispatched: unknown, providerName: string, environmentId: string, expectedExecutionId: string | undefined, requestDigest?: `sha256:${string}` | undefined, expectedSessionId?: string | undefined, callerControlRef?: AgentExactRunControlRef | undefined): AgentSessionRef;
+export declare function retainedSessionControlRef(sessionId: string, executionId: string, provider: string, environmentId: string, requestDigest?: `sha256:${string}`, runId?: string): AgentExactRunControlRef;
+export declare function sessionPromptExecutionId(requestDigest: `sha256:${string}`): string;
+export declare function sessionPromptSessionId(provider: string, environmentId: string, turnId: string | undefined): string | undefined;
 export declare function sameRunControlRef(left: AgentRunControlRef, right: AgentRunControlRef): boolean;
-export declare function resolveRetainedSessionControlRef(candidate: AgentRunControlRef | undefined, sessionId: string, provider: string, environmentId: string): AgentRunControlRef | undefined;
+export declare function resolveRetainedSessionControlRef(candidate: AgentRunControlRef | undefined, sessionId: string, provider: string, environmentId: string): AgentExactRunControlRef | undefined;

package/dist/tangle-session-control.js

@@ -1,8 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
+import { createHash } from "node:crypto";
 import { AgentExactRunControlRefSchema, canonicalCandidateDigest, } from "@tangle-network/agent-interface";
 import { nonEmptyString } from "./tangle-environment-values.js";
 import { assertBoundedJson, boundedIdentifier, } from "./tangle-contract-safety.js";
-export function sessionRefFromSandboxDispatch(dispatched, providerName, environmentId, expectedExecutionId, requestDigest = undefined, expectedSessionId = undefined) {
+export function sessionRefFromSandboxDispatch(dispatched, providerName, environmentId, expectedExecutionId, requestDigest = undefined, expectedSessionId = undefined, callerControlRef = undefined) {
     const record = dispatched && typeof dispatched === "object" && !Array.isArray(dispatched)
         ? dispatched
         : undefined;
@@ -34,11 +34,26 @@ export function sessionRefFromSandboxDispatch(dispatched, providerName, environm
     if (record.dispatched !== undefined && typeof record.dispatched !== "boolean") {
         throw new Error("sandbox dispatch returned an invalid dispatched flag");
     }
+    const accepted = record.runControlRef === undefined
+        ? callerControlRef === undefined
+            ? undefined
+            : AgentExactRunControlRefSchema.safeParse(callerControlRef)
+        : AgentExactRunControlRefSchema.safeParse(record.runControlRef);
+    if (accepted === undefined || !accepted.success) {
+        throw new Error("sandbox dispatch did not return the exact run control reference");
+    }
+    if (accepted.data.provider !== providerName ||
+        accepted.data.environmentId !== environmentId ||
+        accepted.data.sessionId !== id ||
+        accepted.data.executionId !== executionId ||
+        (requestDigest !== undefined && accepted.data.requestDigest !== requestDigest)) {
+        throw new Error("sandbox dispatch returned an exact control reference for another run");
+    }
+    const controlRef = Object.freeze(accepted.data);
     return {
         id,
         provider: providerName,
-        controlRef: retainedSessionControlRef(id, executionId, providerName, environmentId, requestDigest ??
-            canonicalCandidateDigest({ provider: providerName, environmentId, id, executionId })),
+        controlRef,
         metadata: {
             ...(record.status ? { status: record.status } : {}),
             ...(record.alreadyExisted !== undefined ? { alreadyExisted: record.alreadyExisted } : {}),
@@ -46,24 +61,27 @@ export function sessionRefFromSandboxDispatch(dispatched, providerName, environm
         },
     };
 }
-export function retainedSessionControlRef(sessionId, executionId, provider, environmentId, requestDigest) {
-    return AgentExactRunControlRefSchema.parse({
-        runId: executionId,
+export function retainedSessionControlRef(sessionId, executionId, provider, environmentId, requestDigest, runId = executionId) {
+    return Object.freeze(AgentExactRunControlRefSchema.parse({
+        runId,
         provider,
         environmentId,
         sessionId,
         executionId,
         requestDigest: requestDigest ??
             canonicalCandidateDigest({ provider, environmentId, sessionId, executionId }),
-    });
+    }));
+}
+export function sessionPromptExecutionId(requestDigest) {
+    return `session-turn-${requestDigest.slice("sha256:".length)}`;
 }
-export function sessionPromptExecutionId(provider, environmentId, sessionId, turnId) {
+export function sessionPromptSessionId(provider, environmentId, turnId) {
     if (turnId === undefined)
-        return randomUUID();
+        return undefined;
     const digest = createHash("sha256")
-        .update(`${provider}\0${environmentId}\0${sessionId}\0${turnId}`)
+        .update(`${provider}\0${environmentId}\0${turnId}`)
         .digest("hex");
-    return `session-turn-${digest}`;
+    return `session-${digest}`;
 }
 export function sameRunControlRef(left, right) {
     return (left.runId === right.runId &&
@@ -82,8 +100,5 @@ export function resolveRetainedSessionControlRef(candidate, sessionId, provider,
         controlRef.sessionId !== sessionId) {
         throw new Error("Tangle control reference does not match this session");
     }
-    if (controlRef.runId !== controlRef.executionId) {
-        throw new Error("Tangle session control reference requires runId to equal executionId");
-    }
-    return controlRef;
+    return retainedSessionControlRef(sessionId, controlRef.executionId, provider, environmentId, controlRef.requestDigest, controlRef.runId);
 }

package/dist/tangle-types.d.ts

@@ -1,5 +1,5 @@
 import type { BackendType, CreateSandboxOptions, ExecResult as SandboxExecResult, PromptOptions, PromptResult, SandboxEvent } from "@tangle-network/sandbox";
-import type { InputPart } from "@tangle-network/agent-interface";
+import type { AgentRunCancellationAcknowledgement, AgentRunCancellationRequest, InputPart } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 export interface TangleExactProcessOptions {
     teamId?: string;
@@ -9,6 +9,17 @@ export interface SandboxClientLike {
         signal?: AbortSignal;
         timeoutMs?: number;
     }): Promise<SandboxInstanceLike>;
+    /**
+     * SDK HttpClient transport, present on `Sandbox` and `TangleSandboxClient`.
+     * Retained control requires it: the provider mints a lazy probe instance
+     * over this surface to read the linked SDK's method surface before any
+     * sandbox exists. An object-spread wrapper (`{ ...client }`) drops class
+     * prototype methods including this one, so such a wrapper never claims
+     * retained control; pass the SDK client itself or delegate its methods.
+     */
+    fetch?(path: string, options?: RequestInit, fetchOptions?: {
+        timeoutMs?: number;
+    }): Promise<Response>;
     get?(id: string, requestOptions?: {
         signal?: AbortSignal;
     }): Promise<SandboxInstanceLike | null>;
@@ -95,12 +106,6 @@ export interface SandboxInstanceLike {
         }): Promise<unknown>;
     };
     process?: SandboxProcessManagerLike;
-    checkpoint?(options?: {
-        signal?: AbortSignal;
-    } & Record<string, unknown>): Promise<unknown>;
-    fork?(checkpointId: string, options?: {
-        signal?: AbortSignal;
-    } & Record<string, unknown>): Promise<SandboxInstanceLike>;
     refresh?(options?: {
         signal?: AbortSignal;
     }): Promise<void>;
@@ -129,6 +134,9 @@ export interface SandboxSessionLike {
     }): Promise<{
         cancelled: boolean;
     }>;
+    cancelRun?(request: AgentRunCancellationRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<AgentRunCancellationAcknowledgement>;
 }
 export interface TangleProviderOptions {
     client: SandboxClientLike;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -70,7 +70,7 @@
     "@tangle-network/agent-interface": "0.47.0"
   },
   "peerDependencies": {
-    "@tangle-network/sandbox": ">=0.17.0 <1.0.0"
+    "@tangle-network/sandbox": ">=0.19.6 <1.0.0"
   },
   "peerDependenciesMeta": {
     "@tangle-network/sandbox": {
@@ -78,7 +78,9 @@
     }
   },
   "devDependencies": {
-    "@tangle-network/sandbox": "0.17.0",
+    "@tangle-network/agent-eval": "0.145.3",
+    "@tangle-network/agent-runtime": "0.132.13",
+    "@tangle-network/sandbox": "0.21.1",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",