@tangle-network/agent-provider-tangle 0.9.0 → 0.11.0

package/dist/tangle-environment.js

@@ -12,6 +12,10 @@ import { assertExecOptions, assertOptionKeys, } from "./tangle-environment-valid
 import { interruptExecutionAfterAbort, } from "./tangle-environment-control.js";
 import { dispatchEnvironmentRun } from "./tangle-environment-dispatch.js";
 import { sandboxSessionAsAgentSession } from "./tangle-environment-session.js";
+import { tangleInteractionResponder } from "./tangle-interaction-response.js";
+import { createExecutionUsageLog } from "./tangle-usage-log.js";
+import { observeTangleEnvironment } from "./tangle-observation.js";
+import { createTangleTerminalRegistry } from "./tangle-terminal.js";
 /**
  * Compose one concrete sandbox into an environment.
  *
@@ -28,8 +32,12 @@ import { sandboxSessionAsAgentSession } from "./tangle-environment-session.js";
  * nothing and keeps claiming nothing: the exposed operations and the document
  * are composed together and a caller may already hold either one. Compose the
  * environment again through `provider.get(id)` once the sandbox is running.
+ *
+ * @param request What the create call asked for. An environment rebuilt by id
+ * carries none of it, so its observation reports the requested compute shape
+ * as absent instead of restating a request it never saw.
  */
-export async function sandboxInstanceAsEnvironment(box, providerName, client, declaredCapabilities, operation) {
+export async function sandboxInstanceAsEnvironment(box, providerName, client, declaredCapabilities, operation, request) {
     const environmentId = boundedIdentifier(box.id, "Tangle environment id");
     boundedIdentifier(providerName, "Tangle provider name");
     if (box.metadata !== undefined) {
@@ -38,12 +46,19 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
         }
         assertBoundedJson(box.metadata);
     }
-    const support = sandboxCapabilitySupport(box, client);
+    const support = sandboxCapabilitySupport(box, client, request?.resources);
     const deployment = await readDeploymentCapabilitySupport(box, operation);
     const capabilities = frozenCapabilityDocument(AgentEnvironmentCapabilitiesSchema.parse(capabilitiesForSandbox(declaredCapabilities, support, deployment)));
     // The published document is the single source for what this environment
     // offers, so the session surface reads its grant from there.
     const retainedControl = capabilities.retainedControl !== undefined;
+    const interactionResponses = capabilities.interactions !== undefined;
+    // Usage is measured per execution, so the log collects what runs through
+    // this handle and the observation reports the newest record it holds.
+    const usageLog = createExecutionUsageLog();
+    const terminals = capabilities.interactiveTerminal?.attach === true
+        ? createTangleTerminalRegistry(box)
+        : undefined;
     const dispatch = capabilities.streaming.detach && box.dispatchPrompt
         ? dispatchEnvironmentRun(box, providerName, environmentId)
         : undefined;
@@ -92,6 +107,7 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
                             ? { streamBound: true }
                             : {}),
                     });
+                    usageLog.record(expectedExecutionId, converted.usage);
                     input.signal?.throwIfAborted();
                     yield converted;
                 }
@@ -128,7 +144,7 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
                     if (session.id !== id) {
                         throw new Error("sandbox session(id) returned an unrelated session");
                     }
-                    const agentSession = sandboxSessionAsAgentSession(session, resolveRetainedSessionControlRef(options?.controlRef, id, providerName, environmentId), providerName, environmentId, dispatch, exactExecutionEvents, retainedControl);
+                    const agentSession = sandboxSessionAsAgentSession(session, resolveRetainedSessionControlRef(options?.controlRef, id, providerName, environmentId), providerName, environmentId, dispatch, exactExecutionEvents, retainedControl, interactionResponses, usageLog);
                     // sessions.continue was granted from the probe session and the
                     // deployment document together; this backstop holds every
                     // concrete session to that grant, so a client whose sessions
@@ -142,6 +158,31 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
                 },
             }
             : {}),
+        ...(interactionResponses && box.session
+            ? {
+                respondToInteraction(command, options) {
+                    assertOptionKeys(options, ["signal"], "Tangle interaction response");
+                    options?.signal?.throwIfAborted();
+                    // The command names its own session, so the environment answers an
+                    // ask on any session of this sandbox without the caller holding a
+                    // session object. The binding is checked against this handle, so a
+                    // command for another session is refused rather than delivered.
+                    const sessionId = boundedIdentifier(command?.binding?.sessionId, "Tangle interaction session id");
+                    const session = box.session?.(sessionId, options?.signal ? { signal: options.signal } : undefined);
+                    if (!session)
+                        throw new Error("sandbox session(id) returned undefined");
+                    if (session.id !== sessionId) {
+                        throw new Error("sandbox session(id) returned an unrelated session");
+                    }
+                    return tangleInteractionResponder({
+                        session,
+                        sessionId,
+                        provider: providerName,
+                        environmentId,
+                    })(command, options);
+                },
+            }
+            : {}),
         ...(capabilities.workspace.read && box.read
             ? {
                 async read(path, options) {
@@ -193,6 +234,36 @@ export async function sandboxInstanceAsEnvironment(box, providerName, client, de
                 },
             }
             : {}),
+        ...(capabilities.observation
+            ? {
+                async observe(options) {
+                    assertOptionKeys(options, ["signal"], "Tangle observe");
+                    return await observeTangleEnvironment({
+                        box,
+                        client,
+                        provider: providerName,
+                        environmentId,
+                        ...(request?.resources === undefined
+                            ? {}
+                            : { requestedResources: request.resources }),
+                        usageLog,
+                    }, options);
+                },
+            }
+            : {}),
+        ...(terminals
+            ? {
+                async attachTerminal(terminalRequest, options) {
+                    return await terminals.attach(terminalRequest, options);
+                },
+                terminal(terminalSessionId, options) {
+                    boundedIdentifier(terminalSessionId, "Tangle terminal session id");
+                    assertOptionKeys(options, ["signal"], "Tangle terminal");
+                    options?.signal?.throwIfAborted();
+                    return terminals.get(terminalSessionId);
+                },
+            }
+            : {}),
         async refresh(options) {
             assertOptionKeys(options, ["signal"], "Tangle refresh");
             options?.signal?.throwIfAborted();

package/dist/tangle-events.d.ts

@@ -2,11 +2,41 @@ import type { SandboxEvent } from "@tangle-network/sandbox";
 import type { AgentEnvironmentEvent } from "@tangle-network/agent-interface/environment-provider";
 /** The sidecar sends this envelope when an SSE connection is ready. */
 export declare function isSandboxConnectionMarker(event: SandboxEvent): boolean;
-/** Read identity from both run frames and /agents/events session envelopes. */
-export declare function sandboxEventIdentity(event: SandboxEvent): {
+/**
+ * The session ids a Sandbox event carries, kept separate by field position.
+ *
+ * `runFrameSessionId` is `data.sessionId`/`data.sessionID`. The run/stream lane
+ * copies that value straight from the backend adapter, so on `session.updated`
+ * it is the harness-native session id (Claude, Codex, OpenCode) rather than the
+ * runtime session id.
+ *
+ * `envelopeSessionId` is the `properties` and `properties.info` position of an
+ * /agents/events frame, plus `properties.part` on a frame type that publishes a
+ * part. The sidecar rewrites the backend's own ids to the runtime ids before it
+ * publishes there, so that position names the runtime session on every frame
+ * type it shapes.
+ *
+ * `sessionId` is the frame's own session id for a consumer that does not care
+ * which position carried it: the run-frame position when present, otherwise the
+ * envelope position. It repeats one of those two values and is never a third
+ * one, so a caller that must know the position reads the position.
+ */
+export type SandboxEventIdentity = {
     executionId?: string;
     sessionId?: string;
+    runFrameSessionId?: string;
+    envelopeSessionId?: string;
 };
+/**
+ * The session ids a frame carries, one per field position.
+ *
+ * Every position that names a session is an assertion the frame makes about
+ * itself, so each one is compared. Reducing them to a single precedence winner
+ * leaves the losing position unchecked.
+ */
+export declare function carriedSessionIds(identity: SandboxEventIdentity): readonly string[];
+/** Read identity from both run frames and /agents/events session envelopes. */
+export declare function sandboxEventIdentity(event: SandboxEvent): SandboxEventIdentity;
 export declare function environmentEventFromSandboxEvent(event: SandboxEvent, expected?: {
     executionId?: string;
     sessionId?: string;

package/dist/tangle-events.js

@@ -15,6 +15,69 @@ export function isSandboxConnectionMarker(event) {
         !Array.isArray(data) &&
         data.type === "connection.established");
 }
+/**
+ * The frame types whose `properties.part` the sidecar shapes.
+ *
+ * A `raw` frame carries a backend event the sidecar does not shape, so any
+ * `sessionID` inside it is the backend's own value and names no runtime
+ * session. The part position is therefore read only on a frame type that
+ * publishes a rewritten part. A type outside this set keeps its data opaque.
+ */
+const PART_BEARING_FRAME_TYPES = new Set([
+    "message.part.updated",
+]);
+/**
+ * The session ids a frame carries, one per field position.
+ *
+ * Every position that names a session is an assertion the frame makes about
+ * itself, so each one is compared. Reducing them to a single precedence winner
+ * leaves the losing position unchecked.
+ */
+export function carriedSessionIds(identity) {
+    return [identity.runFrameSessionId, identity.envelopeSessionId].filter((value) => value !== undefined);
+}
+/** Unwrap the nested identity carriers of a session-bus frame. */
+function sessionEnvelope(data, type) {
+    const record = (value) => value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+    const properties = record(data.properties);
+    // `data.part` is the run lane's raw backend part, whose ids are the backend's
+    // own. Only the part under `properties` has been rewritten to the runtime ids.
+    return {
+        properties,
+        info: record(properties?.info),
+        part: type !== undefined && PART_BEARING_FRAME_TYPES.has(type)
+            ? record(properties?.part)
+            : undefined,
+    };
+}
+/**
+ * The one value a set of alias fields carries.
+ *
+ * The aliases of an id within one frame are copies of a single value, so two
+ * different values across them is a frame claiming two identities. Such a frame
+ * is refused rather than resolved by field precedence, which would leave the
+ * losing alias unchecked.
+ */
+function agreedIdentifier(values, label) {
+    let agreed;
+    for (const raw of values) {
+        if (raw === undefined || raw === null)
+            continue;
+        const value = optionalNonEmptyString(raw, label);
+        if (value === undefined)
+            continue;
+        if (agreed === undefined) {
+            agreed = value;
+            continue;
+        }
+        if (agreed !== value) {
+            throw new Error(`${label} disagreed across the fields that carry it`);
+        }
+    }
+    return agreed;
+}
 /** Read identity from both run frames and /agents/events session envelopes. */
 export function sandboxEventIdentity(event) {
     const record = event;
@@ -23,24 +86,29 @@ export function sandboxEventIdentity(event) {
         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;
+    const { properties, info, part } = sessionEnvelope(dataRecord, typeof record.type === "string" ? record.type : undefined);
+    const runFrameSessionId = agreedIdentifier([dataRecord.sessionId, dataRecord.sessionID], "Tangle Sandbox event sessionId");
+    const envelopeSessionId = agreedIdentifier([
+        properties?.sessionId,
+        properties?.sessionID,
+        info?.sessionId,
+        info?.sessionID,
+        part?.sessionId,
+        part?.sessionID,
+    ], "Tangle Sandbox event sessionId");
     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"),
+        executionId: agreedIdentifier([dataRecord.executionId, properties?.executionId, info?.executionId], "Tangle Sandbox event executionId"),
+        sessionId: runFrameSessionId ?? envelopeSessionId,
+        runFrameSessionId,
+        envelopeSessionId,
+    };
+}
+/** Read the `title`/`time` content of a `session.updated` frame in either shape. */
+function sessionUpdateContent(data) {
+    const { info } = sessionEnvelope(data, "session.updated");
+    return {
+        title: data.title ?? info?.title,
+        time: data.time ?? info?.time,
     };
 }
 export function environmentEventFromSandboxEvent(event, expected = {}) {
@@ -72,27 +140,42 @@ export function environmentEventFromSandboxEvent(event, expected = {}) {
     if (Object.prototype.hasOwnProperty.call(data, "contextTransferReceipt")) {
         throw new Error("Tangle Sandbox emitted an unsolicited context transfer receipt");
     }
-    // An exact run stream is already selected by the runtime execution id.
-    // On that stream, session.updated carries the harness-native session id
-    // (for example an OpenCode session), not the runtime session id. Keep that
-    // value as event content while lifecycle frames remain identity-checked.
+    // A stream-bound iterator is the response body of the run this call started
+    // or the replay of one named execution, so the transport itself excludes
+    // another session's frames. On such a stream the run-frame position of
+    // `session.updated` carries the harness-native session id (for example an
+    // OpenCode session) rather than the runtime session id, so that one position
+    // on that one frame type is content. Every other position of that frame, and
+    // every position of every other frame type, names the runtime session and is
+    // compared to the expected id.
     const identity = sandboxEventIdentity(event);
-    const eventExecutionId = identity.executionId;
-    const eventSessionId = expected.streamBound === true && record.type === "session.updated"
-        ? undefined
-        : identity.sessionId;
-    if (expected.executionId !== undefined &&
-        ((eventExecutionId === undefined && expected.streamBound !== true) ||
-            (eventExecutionId !== undefined && eventExecutionId !== expected.executionId))) {
-        throw new Error("Tangle exact session event identified a different executionId");
+    const runFrameCarriesNativeSessionId = expected.streamBound === true && record.type === "session.updated";
+    const identityBearingSessionIds = carriedSessionIds(runFrameCarriesNativeSessionId
+        ? { envelopeSessionId: identity.envelopeSessionId }
+        : identity);
+    if (expected.executionId !== undefined) {
+        if (identity.executionId === undefined && expected.streamBound !== true) {
+            throw new Error("Tangle exact session event arrived without an executionId");
+        }
+        if (identity.executionId !== undefined &&
+            identity.executionId !== expected.executionId) {
+            throw new Error("Tangle exact session event identified a different executionId");
+        }
     }
-    if (expected.sessionId !== undefined &&
-        ((eventSessionId === undefined && expected.streamBound !== true) ||
-            (eventSessionId !== undefined && eventSessionId !== expected.sessionId))) {
-        throw new Error("Tangle exact session event identified a different sessionId");
+    if (expected.sessionId !== undefined) {
+        if (identityBearingSessionIds.length === 0 && expected.streamBound !== true) {
+            throw new Error("Tangle exact session event arrived without a sessionId");
+        }
+        for (const value of identityBearingSessionIds) {
+            if (value !== expected.sessionId) {
+                throw new Error("Tangle exact session event identified a different sessionId");
+            }
+        }
     }
     const usage = tokenUsageFromData(data);
-    const normalized = normalizeSandboxEvent(record.type, data);
+    // The session id reaches the normalized event whichever position carried it,
+    // including the native id an execution-bound stream just accepted as content.
+    const normalized = normalizeSandboxEvent(record.type, data, identity);
     return {
         type: record.type,
         data,
@@ -104,7 +187,8 @@ export function environmentEventFromSandboxEvent(event, expected = {}) {
         providerEvent: event,
     };
 }
-function normalizeSandboxEvent(type, data) {
+function normalizeSandboxEvent(type, data, identity) {
+    const sessionId = identity.sessionId;
     const supplied = data.normalized;
     if (supplied !== undefined) {
         const parsed = CanonicalStreamEventSchema.safeParse(supplied);
@@ -114,6 +198,17 @@ function normalizeSandboxEvent(type, data) {
         if (parsed.data.type !== type) {
             throw new Error(`Tangle Sandbox normalized event type "${parsed.data.type}" does not match transport type "${type}"`);
         }
+        // A supplied block is a field of the frame, so it repeats a session id one
+        // of the frame's own positions carries and introduces none of its own. Each
+        // position it can repeat is already bound: the check above compared every
+        // position that names the runtime session, and the run-frame position of a
+        // stream-bound `session.updated` holds the native id the computed block
+        // carries too. A frame that carries no session id can supply none either.
+        if (parsed.data.type === "session.updated") {
+            if (!carriedSessionIds(identity).includes(parsed.data.sessionId)) {
+                throw new Error("Tangle Sandbox normalized event named a session the frame does not carry");
+            }
+        }
         return parsed.data;
     }
     switch (type) {
@@ -164,13 +259,15 @@ function normalizeSandboxEvent(type, data) {
                 code: data.code,
                 message: data.message,
             });
-        case "session.updated":
+        case "session.updated": {
+            const content = sessionUpdateContent(data);
             return parseCanonical({
                 type,
-                sessionId: data.sessionId ?? data.sessionID,
-                ...(typeof data.title === "string" ? { title: data.title } : {}),
-                ...(data.time !== undefined ? { time: data.time } : {}),
+                sessionId,
+                ...(typeof content.title === "string" ? { title: content.title } : {}),
+                ...(content.time !== undefined ? { time: content.time } : {}),
             });
+        }
         case "interaction":
             return parseCanonical({ type, request: data.request });
         case "interaction.cancel":
@@ -209,8 +306,9 @@ function statusFromSandboxValue(value) {
             return "completed";
         case "failed":
         case "error":
-        case "cancelled":
             return "failed";
+        case "cancelled":
+            return "cancelled";
         default:
             return undefined;
     }

package/dist/tangle-failure-reason.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Bounded, credential-free summary of one Sandbox transport failure.
+ *
+ * A transport message carries the request URL, and that URL can carry userinfo
+ * or a query token, so no contract payload ever repeats the message. A summary
+ * is built from structured error members only: a status is re-emitted as an
+ * integer, and a code or an error name is emitted only when it matches a bare
+ * identifier, which cannot express a URL, a bearer, or whitespace.
+ */
+/** Which transport read one reason describes. */
+export type TransportRead = "environment refresh" | "placement lookup" | "resource usage read" | "subscription read" | "account usage read" | "terminal attach" | "terminal acknowledgement" | "terminal metadata read" | "terminal socket";
+/** Name the read that failed and the cause, with nothing copied from it. */
+export declare function transportFailureReason(read: TransportRead, error: unknown): string;

package/dist/tangle-failure-reason.js

@@ -0,0 +1,46 @@
+/**
+ * Bounded, credential-free summary of one Sandbox transport failure.
+ *
+ * A transport message carries the request URL, and that URL can carry userinfo
+ * or a query token, so no contract payload ever repeats the message. A summary
+ * is built from structured error members only: a status is re-emitted as an
+ * integer, and a code or an error name is emitted only when it matches a bare
+ * identifier, which cannot express a URL, a bearer, or whitespace.
+ */
+/** Codes and error names must match this to be carried into a reason. */
+const BARE_IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+/** Name the read that failed and the cause, with nothing copied from it. */
+export function transportFailureReason(read, error) {
+    return `the Sandbox ${read} failed (${failureCause(error)})`;
+}
+function failureCause(error) {
+    if (error === null || typeof error !== "object")
+        return "cause unreported";
+    const detail = error;
+    const name = bareIdentifier(detail.name);
+    if (name === "AbortError")
+        return "aborted";
+    if (name === "TimeoutError")
+        return "timed out";
+    const status = httpStatus(detail.status);
+    if (status !== undefined)
+        return `HTTP ${status}`;
+    const code = bareIdentifier(detail.code);
+    if (code !== undefined)
+        return `code ${code}`;
+    // A bare `Error` names no cause beyond the message, which is never carried.
+    if (name !== undefined && name !== "Error")
+        return name;
+    return "cause unreported";
+}
+function bareIdentifier(value) {
+    return typeof value === "string" && BARE_IDENTIFIER.test(value) ? value : undefined;
+}
+function httpStatus(value) {
+    return typeof value === "number" &&
+        Number.isSafeInteger(value) &&
+        value >= 100 &&
+        value <= 599
+        ? value
+        : undefined;
+}

package/dist/tangle-interaction-response.d.ts

@@ -0,0 +1,26 @@
+import type { InteractionAcknowledgement, InteractionResponseCommand } from "@tangle-network/agent-interface";
+import type { SandboxSessionLike } from "./tangle-types.js";
+export interface TangleInteractionResponderOptions {
+    session: SandboxSessionLike;
+    /** The session the bound ask must belong to. */
+    sessionId: string;
+    provider: string;
+    environmentId: string;
+}
+/**
+ * Answer one exact interaction through the Sandbox interaction command route.
+ *
+ * The route carries the canonical command whole and returns the deployment's
+ * own durable record, so this adapter keeps no resolution record of its own:
+ * the deployment decides `accepted`, `already_resolved_same`, and
+ * `already_resolved_different`, and its answer survives a restart of this
+ * process and a rebuilt environment object. The capability this responder is
+ * gated on is exactly that durable record.
+ *
+ * Two verdicts stay here, because the route cannot produce them as an
+ * acknowledgement: a command bound to another environment or session, and an
+ * answer the outstanding ask's spec rejects.
+ */
+export declare function tangleInteractionResponder(options: TangleInteractionResponderOptions): (command: InteractionResponseCommand, operation?: {
+    signal?: AbortSignal;
+}) => Promise<InteractionAcknowledgement>;