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

package/README.md

@@ -1,8 +1,11 @@
 # @tangle-network/agent-provider-tangle
 
 Wraps `@tangle-network/sandbox` as an `AgentEnvironmentProvider`.
-The peer range is `>=0.19.6 <1.0.0`; retained-run cancellation (`session.cancelRun`) first shipped in 0.19.6, and this package is developed and tested against 0.22.0.
-The floor stays at 0.19.6 although deployment capability discovery (`box.capabilities()`) needs 0.22.0: the adapter feature-detects that method, so a consumer on an older SDK keeps working and claims no retained control instead of failing to load.
+The peer range is `>=0.23.0 <1.0.0`, and this package is developed and tested against 0.23.0.
+The floor is 0.23.0 because the response path needs `session.respondToInteraction`, which first shipped there.
+The adapter feature-detects that method, so an older SDK claims no interactions rather than failing to load.
+The floor stands anyway: the earlier answer path resolves the session's first outstanding question rather than the one a response names, so a response meant for one ask resolves another and reports success.
+This adapter never falls back to it.
 
 ```ts
 import { Sandbox } from '@tangle-network/sandbox'
@@ -20,6 +23,8 @@ Sandbox metadata can include caller-authored values and does not authenticate it
 Reconstruct an exact session with `environment.session(reference.id, { controlRef: reference.controlRef })`; replay cursors are exclusive at both the agent interface and Sandbox session stream.
 Result, replay, and cancel operations select that exact execution instead of whichever execution most recently changed the shared session.
 Session status with an exact control reference reports a state only when the payload names that execution; a payload bound to a different or unnamed execution reports `unknown`.
+`AgentTurnInput.interactions` maps unchanged to `PromptOptions.backend.interactions` for the selected Sandbox turn.
+The requested posture is part of the retained request digest, so a retry with changed interaction behavior conflicts instead of reusing prior work.
 
 ## Two capability documents
 
@@ -47,12 +52,40 @@ Each deployment flag this adapter reads gates the claims it backs, and no flag i
 | `cancel.idempotent` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
 | `runs.eventReplay` | `streaming.replay`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
 | `runs.executionScopedStatus` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| `interactions.responseDedupe` | `interactions`, `environment.respondToInteraction`, `session.respondToInteraction` |
 
 Detached dispatch carries the caller's exact reference and refuses a receipt that does not name the execution back, so it needs both `dispatch` flags and a session handle to reach the run through.
 `sessions.continue`, `retainedControl`, and `session.cancelRun` need every flag in the table, because the capability schema refuses a partial retained-control block and each identity rests on its own flag.
 A claim takes its operation with it: `streaming.detach` gates `dispatch()`, and `session()` stands while any of `streaming.detach`, `streaming.replay`, or `sessions.continue` stands.
 A missing flag means unknown, and unknown is never a claim.
 
+Answering an ask rests on `interactions.responseDedupe` alone, and on nothing retained control needs.
+The adapter keeps no record of the responses it sent, so every replay answer comes from the deployment: repeating a command returns the recorded acknowledgement, and a different answer for a recorded ask is refused as `already_resolved_different`.
+A deployment that does not record what it acknowledges therefore claims no interactions, even where the local method exists, because an unrecorded response cannot be retried without risking a second answer to a running agent.
+The claim and the two methods stand or fall together.
+
+## Answering an interaction
+
+`respondToInteraction` takes the canonical `InteractionResponseCommand` and returns the canonical `InteractionAcknowledgement`.
+It is offered on the environment and on a session handle; the environment routes the command to the session its binding names.
+The command carries only the answer the caller supplied. No field is filled in on the caller's behalf, and an answer the outstanding ask's spec rejects is refused with the field named.
+
+| Result | Acknowledgement status |
+| --- | --- |
+| The deployment recorded and delivered the response | `accepted` |
+| The deployment already holds this exact response | `already_resolved_same` |
+| The deployment already holds a different response for the ask | `already_resolved_different`, message naming the recorded digest |
+| The command names another provider, environment, or session | `binding_mismatch` |
+| The deployment refuses the binding | `binding_mismatch` |
+| The ask is unknown to the deployment | `unknown_interaction` |
+| The session is unknown to the deployment | `unknown_run` |
+| The ask left the outstanding set on a deadline | `expired` |
+| The ask's spec rejects the answer | `invalid_response`, message naming each field |
+| The response is recorded and delivery is unconfirmed | `transport_failure`, `retryable: true` |
+| The request did not reach the route | `transport_failure`, `retryable: true` |
+
+A refusal is never reported as a success, and a recorded response whose delivery the deployment does not confirm is never reported as `accepted`.
+
 Four inputs claim nothing at all: a Sandbox SDK older than 0.22.0, a sandbox that is not running, a `null` document (a deployment predating capability discovery, or one serving a newer schema this SDK cannot read), and a capability read that fails.
 In each case the environment omits `dispatch` and `session`, so a caller never selects an action the deployment will reject.
 A document that leaves a flag unset is not one of them.
@@ -75,6 +108,62 @@ It also rejects `contextTransfer` and `nativeContinuation` inputs explicitly unt
 The adapter never advertises `branching.checkpoint` or `branching.fork`.
 Sandbox exposes `snapshot`, `listSnapshots`, `deleteSnapshot`, and `branch(count)` with different semantics; durable workspace branching stays unadvertised until the full `AgentWorkspaceBranching` contract — retry, lookup, conflict, and cleanup together — is implemented over that surface.
 
+## Environment observation
+
+`environment.observe()` returns the normalized `AgentEnvironmentObservation`.
+Every surface carries a freshness discriminator, so a value the Sandbox SDK does not report is visibly absent instead of arriving as a measured zero.
+The `observation` capability flag for a surface is true only when a source can put a value on it for that environment; the observation itself always carries the surface, with `unavailable` and its reason when there is nothing to report.
+
+| Surface | Sandbox source | State when the source is missing |
+| --- | --- | --- |
+| `identity` | provider name and `box.id` | always known |
+| `lifecycle.status` | `box.status` after a refresh | `stale` with the refresh failure |
+| `lifecycle.cleanup` | `box.expiresAt` as a scheduled retirement | omitted from the lifecycle value |
+| `endpoint` | scheme, host, and explicit port of `connection.runtimeUrl` | `unavailable` |
+| `placement.verified` | `client.describePlacement(box)` | `unavailable` |
+| `resources.requested` | the `create()` resource request | omitted on an environment rebuilt by id |
+| `resources.effective` | cgroup `memoryLimitMb` and the attached GPU lease | `unavailable` |
+| `resourceUse.current` / `peak` | cgroup `memoryCurrentMb` / `memoryPeakMb` | `unavailable` |
+| `modelUsage` | the newest execution this handle measured | `unavailable` |
+| `computeBilling` | the GPU lease's billed or estimated customer cost | `unavailable` |
+| `accountUsage` | `client.subscription()` and `client.usage()` | `unavailable` |
+
+Four quantities have no Sandbox source at all, and the adapter reports them as absent rather than deriving them.
+There is no effective CPU or disk figure anywhere in the SDK, so `resources.effective` carries memory and the accelerator only.
+The cgroup reports cumulative CPU microseconds, which is not a utilization figure, so `resourceUse` carries memory only rather than a rate computed from one sample.
+Sandbox prices an attached GPU lease and publishes no per-sandbox container compute cost, so `computeBilling` is unavailable on an environment with no lease.
+`lifecycle.continuity` and `lifecycle.persistence` have no readable source and are omitted.
+
+Two account values are reported as absent on purpose.
+A negative credit balance under an overage plan cannot be stated as non-negative remaining credit, and an account with no concurrent-sandbox ceiling has no quota to state; reporting either as zero would hide a debt or invent a limit.
+
+`resources.requested` is the request the adapter sends, not the request the caller typed.
+The contract states CPU, memory, and disk as `cpu`/`memoryMb`/`diskMb` while Sandbox reads `cpuCores`/`memoryMB`/`diskGB`, so the adapter translates them; a disk size that is not a whole number of gibibytes is refused rather than rounded.
+A `resources.gpu` class becomes one accelerator device, which is the Sandbox default device count for a request that names only its class.
+
+The observation makes two calls of its own — the account subscription and usage counters — plus the cgroup sample and a refresh.
+A hop that fails does not fail the observation: its surface carries the transport's own message as the reason, and a value the refresh could not renew is reported as `stale` rather than as current.
+
+Nothing in the observation can carry a credential.
+The endpoint holds only a scheme, a host, and an explicit port; userinfo, path, and query are dropped, and the bearer beside the runtime URL is never read.
+
+## Interactive terminal
+
+`environment.attachTerminal(request)` opens or reattaches one PTY over the sandbox terminal WebSocket, and `environment.terminal(id)` returns the live handle.
+The four `interactiveTerminal` flags rest on one fact — the sandbox serves the PTY socket and reports terminal metadata — because all four operations reach the caller through one socket from one linked SDK.
+
+Attach uses the request's `connectionId`, else its `terminalSessionId`, else a generated id; reusing an id reattaches the PTY and replays its retained screen, which the runtime reports as `reattached`.
+`mode: "logical"` is refused: Sandbox resumes a terminal only by attaching it, and serving an attach the caller did not ask for would start a PTY behind their back.
+
+`events()` replays retained frames from an EXCLUSIVE `since` cursor and then continues until the terminal exits.
+Only `output` frames carry a sequence; `ready`, `resize`, `error`, and `exit` keep their place in the same ordered log.
+A cursor the retained buffer no longer holds is refused, because resuming after the gap would drop output the consumer believes it received.
+
+Every reference states an expiry one detach window past the newest activity the adapter can prove, and `input` and `resize` refuse a reference that is expired or no longer running.
+`attachCount` counts the attaches this environment holds, not the runtime's own viewers.
+`close()` reports `closed` only when the socket delivered an exit; Sandbox exposes no terminal delete, so an unproven close reports `unknown` rather than claiming a termination that did not happen.
+An attach whose runtime metadata lacks a name, shell, working directory, geometry, timestamps, running state, or detach window fails closed with `unknown`, because a reference cannot state facts the runtime did not report.
+
 Pass `exactProcess: {}` only when the Sandbox deployment supports `agent: false` creates and reports `metadata.runtimeMode: "control"`.
 The optional capability creates an ephemeral sandbox with an authenticated control service but no managed agent workload or agent credentials, explicit resources, exact blocked/domain egress, bounded binary file reads, shell-free launch, and recoverable process output plus terminal reason.
 Set `teamId` inside `exactProcess` to scope create, lookup, and recovery to one team.

package/dist/index.d.ts

@@ -2,3 +2,4 @@ export type { TangleExactProcessOptions } from "./tangle-types.js";
 export * from "./tangle-types.js";
 export { createTangleProvider } from "./tangle-provider.js";
 export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";
+export { safeEndpointFromConnection } from "./tangle-observation.js";

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from "./tangle-types.js";
 export { createTangleProvider } from "./tangle-provider.js";
 export { defaultTangleSandboxCapabilities } from "./tangle-capabilities.js";
+export { safeEndpointFromConnection } from "./tangle-observation.js";

package/dist/tangle-capabilities.d.ts

@@ -1,6 +1,8 @@
 import type { AgentEnvironmentCapabilities, HarnessType } from "@tangle-network/agent-interface";
 import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
 import type { DeploymentCapabilitySupport } from "./tangle-deployment-capabilities.js";
+import type { ResourceProfile } from "@tangle-network/agent-interface";
+import { type ObservationSurfaceSupport } from "./tangle-observation.js";
 /**
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
@@ -29,8 +31,14 @@ export interface SandboxCapabilitySupport {
     placement: boolean;
     destroy: boolean;
     cancelRun: boolean;
+    /** The session handle exposes the digest-bound interaction command route. */
+    respondToInteraction: boolean;
+    /** Per-surface sources for the normalized observation. */
+    observation: ObservationSurfaceSupport;
+    /** The sandbox serves the PTY socket and reports terminal metadata. */
+    interactiveTerminal: boolean;
 }
-export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, client: SandboxClientLike): SandboxCapabilitySupport;
+export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, client: SandboxClientLike, requestedResources?: ResourceProfile): SandboxCapabilitySupport;
 /**
  * Establish client-stage facts before any sandbox exists. Two sources: the
  * client's own members (get, describePlacement) and, for an SDK-backed client,
@@ -53,6 +61,19 @@ export declare function clientCapabilitySupport(client: SandboxClientLike): Sand
  * can call is not a run the service retains.
  */
 export declare function tangleRetainedControlSupported(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): boolean;
+/**
+ * Decide whether answering an interaction may be claimed.
+ *
+ * Two independent fact sets must agree, as they do for retained control. The
+ * adapter surface must be able to send the command: a session handle exposing
+ * the digest-bound route. The deployment must record what it acknowledges,
+ * because this adapter keeps no resolution record of its own — every replay
+ * answer comes from the deployment. A deployment that leaves the flag unset
+ * refuses the claim even though the local method exists, since an
+ * unrecorded response cannot be retried without risking a second answer to a
+ * running agent.
+ */
+export declare function tangleInteractionResponsesSupported(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): boolean;
 /**
  * Narrow a declared capability document to established facts.
  *

package/dist/tangle-capabilities.js

@@ -1,6 +1,8 @@
 import { harnessSystemPromptIntents } from "@tangle-network/agent-interface";
 import { SandboxInstance } from "@tangle-network/sandbox";
 import { ADAPTER_CEILING_DEPLOYMENT, deploymentBacksRetainedControl, } from "./tangle-deployment-capabilities.js";
+import { clientObservationSurfaceSupport, observationSurfaceSupport, } from "./tangle-observation.js";
+import { sandboxBacksInteractiveTerminal } from "./tangle-terminal.js";
 /**
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
@@ -42,6 +44,26 @@ export function defaultTangleSandboxCapabilities(harness) {
         // together over one Sandbox surface, and the capability schema refuses
         // a partial block, so they stand or fall on the same fact set.
         sessions: { continue: true, list: false, messages: false },
+        // Answering an ask is declared as intent and stripped by narrowing unless
+        // the session exposes the command route and the deployment discloses its
+        // durable response record. Three claims are bounded by what the adapter
+        // can establish rather than by what the route carries:
+        //  - `secretAnswers` false, and no `secret` answer field: the deployment
+        //    discloses nothing about resolving a one-use secret handle, and an
+        //    undisclosed fact is not a claim.
+        //  - `responseScopes` names `interaction` alone, for the same reason: no
+        //    document states that a broader grant is honored on reuse.
+        //  - `concurrentRequests` true: the command names the ask it answers, so
+        //    several outstanding asks each take their own exact response.
+        interactions: {
+            kinds: ["question", "permission", "plan"],
+            answerFieldTypes: ["text", "number", "boolean", "select"],
+            responseScopes: ["interaction"],
+            secretAnswers: false,
+            concurrentRequests: true,
+            replay: true,
+            responseIdempotency: true,
+        },
         retainedControl: {
             exactRunIdentity: true,
             resultIdentity: true,
@@ -57,11 +79,32 @@ export function defaultTangleSandboxCapabilities(harness) {
         // Confidential execution needs verified attestation evidence, which this
         // adapter does not yet obtain, so it is never declared by default.
         confidential: false,
+        // Observation surfaces are declared as intent and narrowed per sandbox to
+        // the sources that can put a value on each one.
+        observation: {
+            identity: true,
+            lifecycle: true,
+            endpoint: true,
+            placement: true,
+            resources: true,
+            resourceUse: true,
+            modelUsage: true,
+            computeBilling: true,
+            accountUsage: true,
+        },
+        // The four terminal operations rest on one fact: the sandbox serves the
+        // PTY socket and reports terminal metadata. They stand or fall together.
+        interactiveTerminal: {
+            attach: true,
+            input: true,
+            resize: true,
+            reattach: true,
+        },
     };
 }
 // One reserved id names both probe handles; neither ever reaches the service.
 const CAPABILITY_PROBE_ID = "__tangle-capability-probe__";
-export function sandboxCapabilitySupport(box, client) {
+export function sandboxCapabilitySupport(box, client, requestedResources) {
     let session;
     if (typeof box.session === "function") {
         try {
@@ -83,6 +126,9 @@ export function sandboxCapabilitySupport(box, client) {
         placement: typeof client.describePlacement === "function",
         destroy: typeof box.delete === "function",
         cancelRun: typeof session?.cancelRun === "function",
+        respondToInteraction: typeof session?.respondToInteraction === "function",
+        observation: observationSurfaceSupport(box, client, requestedResources),
+        interactiveTerminal: sandboxBacksInteractiveTerminal(box),
     };
 }
 /**
@@ -121,9 +167,14 @@ function linkedSdkProbeInstance(client) {
  * re-measures them in `capabilitiesForSandbox`.
  */
 export function clientCapabilitySupport(client) {
+    const observation = clientObservationSurfaceSupport(client);
     const probe = linkedSdkProbeInstance(client);
-    if (probe)
-        return sandboxCapabilitySupport(probe, client);
+    if (probe) {
+        // The probe measures the linked SDK's method surface, so it decides the
+        // terminal transport. It carries no sandbox data, so the observation
+        // surfaces that rest on one environment's values stay at the ceiling.
+        return { ...sandboxCapabilitySupport(probe, client), observation };
+    }
     return {
         reconstruct: typeof client.get === "function",
         dispatchPrompt: true,
@@ -134,6 +185,9 @@ export function clientCapabilitySupport(client) {
         placement: typeof client.describePlacement === "function",
         destroy: true,
         cancelRun: false,
+        respondToInteraction: false,
+        observation,
+        interactiveTerminal: true,
     };
 }
 /**
@@ -158,6 +212,24 @@ export function tangleRetainedControlSupported(declared, support, deployment) {
         support.session &&
         support.cancelRun);
 }
+/**
+ * Decide whether answering an interaction may be claimed.
+ *
+ * Two independent fact sets must agree, as they do for retained control. The
+ * adapter surface must be able to send the command: a session handle exposing
+ * the digest-bound route. The deployment must record what it acknowledges,
+ * because this adapter keeps no resolution record of its own — every replay
+ * answer comes from the deployment. A deployment that leaves the flag unset
+ * refuses the claim even though the local method exists, since an
+ * unrecorded response cannot be retried without risking a second answer to a
+ * running agent.
+ */
+export function tangleInteractionResponsesSupported(declared, support, deployment) {
+    return (declared.interactions !== undefined &&
+        deployment.interactionResponses &&
+        support.session &&
+        support.respondToInteraction);
+}
 /**
  * Narrow a declared capability document to established facts.
  *
@@ -214,13 +286,57 @@ export function narrowedTangleCapabilities(declared, support, deployment) {
         },
         placement: support.placement ? declared.placement : false,
         usage: false,
+        ...(declared.observation === undefined
+            ? {}
+            : { observation: narrowedObservation(declared.observation, support.observation) }),
+        ...(declared.interactiveTerminal === undefined
+            ? {}
+            : {
+                interactiveTerminal: narrowedInteractiveTerminal(declared.interactiveTerminal, support.interactiveTerminal),
+            }),
     };
-    delete narrowed.interactions;
+    // A claimed block is passed through whole. Its sub-flags state what the
+    // route carries, not what one deployment reports, and the deployment's own
+    // fact has already decided whether the block survives at all.
+    if (!tangleInteractionResponsesSupported(declared, support, deployment)) {
+        delete narrowed.interactions;
+    }
     delete narrowed.nativeContinuation;
     if (!supportsRetainedControl)
         delete narrowed.retainedControl;
     return narrowed;
 }
+/**
+ * Clear every observation surface no source backs. The flag states whether a
+ * value can be produced; the observation itself always carries the surface
+ * with its freshness state, so a cleared flag never turns into a missing key.
+ */
+function narrowedObservation(declared, support) {
+    return {
+        identity: support.identity ? declared.identity : false,
+        lifecycle: support.lifecycle ? declared.lifecycle : false,
+        endpoint: support.endpoint ? declared.endpoint : false,
+        placement: support.placement ? declared.placement : false,
+        resources: support.resources ? declared.resources : false,
+        resourceUse: support.resourceUse ? declared.resourceUse : false,
+        modelUsage: support.modelUsage ? declared.modelUsage : false,
+        computeBilling: support.computeBilling ? declared.computeBilling : false,
+        accountUsage: support.accountUsage ? declared.accountUsage : false,
+    };
+}
+/**
+ * The four terminal operations reach the caller through one PTY socket from
+ * one linked SDK, so one fact decides them all: a sandbox that cannot serve
+ * the socket claims none of them.
+ */
+function narrowedInteractiveTerminal(declared, supported) {
+    return {
+        attach: supported ? declared.attach : false,
+        input: supported ? declared.input : false,
+        resize: supported ? declared.resize : false,
+        reattach: supported ? declared.reattach : false,
+    };
+}
 /**
  * Narrow provider-level claims to facts the client can prove before any
  * sandbox exists.

package/dist/tangle-create-options.js

@@ -1,4 +1,5 @@
 import { assertBoundedJson, boundedIdentifier, boundedString, MAX_ARRAY_LENGTH, MAX_MAP_ENTRIES, } from "./tangle-contract-safety.js";
+import { sandboxResourcesFromResourceRequest } from "./tangle-resources.js";
 export function sandboxOptionsFromCreateInput(input, defaultBackend) {
     assertCreateInputShape(input);
     assertNoInlineSecretValues(input);
@@ -40,8 +41,6 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend) {
     }
     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");
     }
@@ -51,13 +50,7 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend) {
         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`);
-        }
-    }
+    const resources = sandboxResourcesFromResourceRequest(input.resources);
     if (workspace.environment !== undefined && workspace.image !== undefined) {
         throw new Error("Tangle workspace cannot specify both environment and image");
     }
@@ -77,7 +70,7 @@ export function sandboxOptionsFromCreateInput(input, defaultBackend) {
                 },
             }
             : {}),
-        ...(input.resources ? { resources: input.resources } : {}),
+        ...(resources ? { resources } : {}),
         ...(input.env ? { env: input.env } : {}),
         ...(Array.isArray(input.secrets) ? { secrets: input.secrets } : {}),
         ...(input.metadata ? { metadata: input.metadata } : {}),

package/dist/tangle-deployment-capabilities.d.ts

@@ -21,6 +21,13 @@ export interface DeploymentCapabilitySupport {
     readonly eventReplay: boolean;
     /** Status and results select one execution, not the session's latest. */
     readonly executionScopedStatus: boolean;
+    /**
+     * Interaction responses are recorded durably, so repeating one replays the
+     * recorded acknowledgement instead of delivering a second answer to a
+     * running agent. The adapter holds no record of its own, so this fact alone
+     * decides whether a response can be retried safely.
+     */
+    readonly interactionResponses: boolean;
 }
 /**
  * The deployment backs nothing.

package/dist/tangle-deployment-capabilities.js

@@ -13,6 +13,7 @@ export const UNPROVEN_DEPLOYMENT = {
     canonicalCancellation: false,
     eventReplay: false,
     executionScopedStatus: false,
+    interactionResponses: false,
 };
 /**
  * The client stage's deployment input: this adapter's ceiling, not a fact.
@@ -34,6 +35,7 @@ export const ADAPTER_CEILING_DEPLOYMENT = {
     canonicalCancellation: true,
     eventReplay: true,
     executionScopedStatus: true,
+    interactionResponses: true,
 };
 /**
  * Read the deployment facts out of a capability document. Every flag this
@@ -50,6 +52,7 @@ export function deploymentCapabilitySupport(document) {
             document.cancel?.idempotent === true,
         eventReplay: document.runs?.eventReplay === true,
         executionScopedStatus: document.runs?.executionScopedStatus === true,
+        interactionResponses: document.interactions?.responseDedupe === true,
     };
 }
 /**

package/dist/tangle-environment-control.js

@@ -15,6 +15,9 @@ export function sessionPromptRequestDigest(input, provider, environmentId, sessi
         ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
         ...(input.detach === undefined ? {} : { detach: input.detach }),
         ...(input.context === undefined ? {} : { context: input.context }),
+        ...(input.interactions === undefined
+            ? {}
+            : { interactions: input.interactions }),
     });
 }
 export function hasReplayPayload(input) {
@@ -25,6 +28,7 @@ export function hasReplayPayload(input) {
         input.turnId !== undefined ||
         input.detach !== undefined ||
         input.context !== undefined ||
+        input.interactions !== undefined ||
         input.providerOptions !== undefined);
 }
 export async function interruptAfterAbort(box, reference) {

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

@@ -2,6 +2,7 @@ import type { AgentSession, AgentSessionRef, AgentTurnInput } from "@tangle-netw
 import type { AgentExactRunControlRef, AgentRunControlRef } from "@tangle-network/agent-interface";
 import type { SandboxEvent } from "@tangle-network/sandbox";
 import type { SandboxSessionLike } from "./tangle-types.js";
+import type { ExecutionUsageLog } from "./tangle-usage-log.js";
 type ExactExecutionEventStream = (options: {
     sessionId: string;
     executionId: string;
@@ -14,6 +15,13 @@ type ExactExecutionEventStream = (options: {
  * document grants retained control. Canonical cancellation is offered only
  * under that grant: a `cancelRun` method the deployment does not honor is an
  * action the caller selects and finds rejected on the wire.
+ * @param interactionResponses Whether the environment's narrowed capability
+ * document claims interaction responses. The method is offered only under
+ * that claim, so a caller never selects an answer the deployment cannot
+ * record.
+ * @param usageLog Sink for the token usage each execution measured. The
+ * environment observation reads it, because Sandbox reports usage per
+ * execution result and never for the environment.
  */
-export declare function sandboxSessionAsAgentSession(session: SandboxSessionLike, controlRef: AgentRunControlRef | undefined, provider: string, environmentId: string, dispatch: ((input: AgentTurnInput) => Promise<AgentSessionRef>) | undefined, exactExecutionEvents: ExactExecutionEventStream | undefined, retainedControl: boolean): AgentSession;
+export declare function sandboxSessionAsAgentSession(session: SandboxSessionLike, controlRef: AgentRunControlRef | undefined, provider: string, environmentId: string, dispatch: ((input: AgentTurnInput) => Promise<AgentSessionRef>) | undefined, exactExecutionEvents: ExactExecutionEventStream | undefined, retainedControl: boolean, interactionResponses: boolean, usageLog?: ExecutionUsageLog): AgentSession;
 export {};

package/dist/tangle-environment-session.js

@@ -1,24 +1,44 @@
 import { randomUUID } from "node:crypto";
 import { AgentTurnInputSchema } from "@tangle-network/agent-interface";
 import { AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, agentRunCancellationAcknowledgementMatchesRequest, } from "@tangle-network/agent-interface";
-import { environmentEventFromSandboxEvent, isSandboxConnectionMarker, sandboxEventIdentity, } from "./tangle-events.js";
+import { carriedSessionIds, environmentEventFromSandboxEvent, isSandboxConnectionMarker, sandboxEventIdentity, } from "./tangle-events.js";
 import { agentTurnResultFromPromptRecord, promptFromTurnInput, promptOptionsFromTurnInput, validatedSandboxPromptResult, } from "./tangle-prompt.js";
 import { retainedSessionControlRef, resolveRetainedSessionControlRef, sameRunControlRef, sessionPromptExecutionId, } from "./tangle-session-control.js";
 import { executionBoundSessionStatus, sessionStatusFromUnknown, } from "./tangle-environment-values.js";
 import { awaitWithSignal, boundedIdentifier, } from "./tangle-contract-safety.js";
 import { assertOptionKeys } from "./tangle-environment-validation.js";
+import { tangleInteractionResponder } from "./tangle-interaction-response.js";
 import { hasReplayPayload, interruptExecutionAfterAbort, sessionPromptRequestDigest, } from "./tangle-environment-control.js";
 /**
  * @param retainedControl Whether the environment's narrowed capability
  * document grants retained control. Canonical cancellation is offered only
  * under that grant: a `cancelRun` method the deployment does not honor is an
  * action the caller selects and finds rejected on the wire.
+ * @param interactionResponses Whether the environment's narrowed capability
+ * document claims interaction responses. The method is offered only under
+ * that claim, so a caller never selects an answer the deployment cannot
+ * record.
+ * @param usageLog Sink for the token usage each execution measured. The
+ * environment observation reads it, because Sandbox reports usage per
+ * execution result and never for the environment.
  */
-export function sandboxSessionAsAgentSession(session, controlRef, provider, environmentId, dispatch, exactExecutionEvents, retainedControl) {
+export function sandboxSessionAsAgentSession(session, controlRef, provider, environmentId, dispatch, exactExecutionEvents, retainedControl, interactionResponses, usageLog) {
+    const measured = (executionId, result) => {
+        usageLog?.record(executionId, result.usage);
+        return result;
+    };
     let activeControlRef = controlRef
         ? resolveRetainedSessionControlRef(controlRef, session.id, provider, environmentId)
         : undefined;
     let promptInFlight = false;
+    const respondToInteraction = interactionResponses && typeof session.respondToInteraction === "function"
+        ? tangleInteractionResponder({
+            session,
+            sessionId: session.id,
+            provider,
+            environmentId,
+        })
+        : undefined;
     const cancelRunMethod = retainedControl ? session.cancelRun : undefined;
     const cancelRun = typeof cancelRunMethod === "function"
         ? async (request, options) => {
@@ -106,9 +126,13 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
                             markerIdentity.executionId !== executionId) {
                             throw new Error("Tangle exact session connection identified a different executionId");
                         }
-                        if (markerIdentity.sessionId !== undefined &&
-                            markerIdentity.sessionId !== session.id) {
-                            throw new Error("Tangle exact session connection identified a different sessionId");
+                        // Every position that names a session on the marker names the
+                        // session the stream was opened for. The marker carries no native
+                        // id, so no position is exempt.
+                        for (const carried of carriedSessionIds(markerIdentity)) {
+                            if (carried !== session.id) {
+                                throw new Error("Tangle exact session connection identified a different sessionId");
+                            }
                         }
                         continue;
                     }
@@ -143,10 +167,10 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
             const resultRecord = validatedSandboxPromptResult(result);
             if (resultRecord.executionId !== expectedExecutionId)
                 throw new Error("Tangle session result did not confirm its exact executionId");
-            return agentTurnResultFromPromptRecord(resultRecord, {
+            return measured(expectedExecutionId, agentTurnResultFromPromptRecord(resultRecord, {
                 sessionId: session.id,
                 controlRef: activeControlRef,
-            });
+            }));
         },
         async prompt(input) {
             AgentTurnInputSchema.parse(input);
@@ -199,10 +223,10 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
                     if (resultRecord.executionId !== nextControlRef.executionId) {
                         throw new Error("Tangle detached session prompt did not confirm its exact executionId");
                     }
-                    return agentTurnResultFromPromptRecord(resultRecord, {
+                    return measured(nextControlRef.executionId, agentTurnResultFromPromptRecord(resultRecord, {
                         sessionId: session.id,
                         controlRef: nextControlRef,
-                    });
+                    }));
                 }
                 const sourceControlRef = requestedControlRef ?? activeControlRef;
                 const replay = input.lastEventId !== undefined;
@@ -277,7 +301,7 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
                     }
                     const nextControlRef = targetControlRef;
                     activeControlRef = nextControlRef;
-                    return agentTurnResultFromPromptRecord(resultRecord, {
+                    return measured(executionId, agentTurnResultFromPromptRecord(resultRecord, {
                         sessionId: session.id,
                         controlRef: nextControlRef,
                         ...(input.contextTransfer
@@ -286,7 +310,7 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
                         ...(input.contextTransfer
                             ? { contextTransferRequested: true }
                             : {}),
-                    });
+                    }));
                 }
                 catch (error) {
                     if (input.signal?.aborted && input.detach !== true) {
@@ -311,5 +335,6 @@ export function sandboxSessionAsAgentSession(session, controlRef, provider, envi
                 throw new Error("Tangle sandbox did not confirm cancellation");
         },
         ...(cancelRun ? { cancelRun } : {}),
+        ...(respondToInteraction ? { respondToInteraction } : {}),
     };
 }

package/dist/tangle-environment.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEnvironment, AgentEnvironmentCapabilities } from "@tangle-network/agent-interface/environment-provider";
+import type { AgentEnvironment, AgentEnvironmentCapabilities, ResourceProfile } from "@tangle-network/agent-interface/environment-provider";
 import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
 /**
  * Compose one concrete sandbox into an environment.
@@ -16,7 +16,13 @@ import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.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 declare function sandboxInstanceAsEnvironment(box: SandboxInstanceLike, providerName: string, client: SandboxClientLike, declaredCapabilities: AgentEnvironmentCapabilities, operation?: {
     signal?: AbortSignal;
+}, request?: {
+    resources?: ResourceProfile;
 }): Promise<AgentEnvironment>;