@tangle-network/agent-provider-tangle 0.7.2 → 0.8.0

package/README.md

@@ -1,7 +1,8 @@
 # @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.21.1.
+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.
 
 ```ts
 import { Sandbox } from '@tangle-network/sandbox'
@@ -18,11 +19,49 @@ Reconstruct an exact session with `environment.session(reference.id, { controlRe
 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`.
 
-The provider claims `retainedControl` only from probed facts.
+## Two capability documents
+
+Capabilities are derived in two stages, and the two stages answer different questions.
+
+`provider.capabilities()` answers "what can this provider do against a deployment that backs it".
+It runs before any sandbox exists, so it measures the adapter surface alone and states the adapter's ceiling for everything a deployment decides.
 A lazy instance handle minted from the linked Sandbox SDK over the client's `fetch` transport must prove `dispatchPrompt`, `session`, and `cancelRun`, and the client must expose `get` for reconstruction; the probe sends no request and creates no resource.
-The probe measures the linked SDK's method surface, not the connected service; service-side truth needs the sidecar capability endpoint and is a follow-up.
-A client that cannot prove those facts gets no claim, so the runtime rejects retained dispatch before any sandbox is created.
-Each concrete sandbox narrows the declared document independently against its own measured method surface, so a capable sandbox keeps retained control even when the provider-level claim failed closed.
+That handle measures the linked SDK's method surface, never the connected service.
+A client that cannot prove those facts gets no retained-control claim, so the runtime rejects retained dispatch before any sandbox is created.
+
+`environment.capabilities` answers "what can this environment do", and it is the document to read before offering an operation.
+Composing an environment calls `box.capabilities()` once and derives every deployment-decided claim from that document.
+The operations an environment exposes match its own document exactly: a claim the document does not carry has no method behind it.
+One provider reaches deployments of different ages, which is why the environment carries its own document rather than inheriting the provider's.
+
+Each deployment flag this adapter reads gates the claims it backs, and no flag is read that gates nothing:
+
+| Deployment flag | Claims it gates |
+| --- | --- |
+| `dispatch.runControlRef` | `streaming.detach`, `streaming.turnIdempotency`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| `dispatch.executionIdOnAdmission` | `streaming.detach`, `streaming.turnIdempotency`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| `cancel.canonicalRunCancellation` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| `cancel.digestBound` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| `cancel.idempotent` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| `runs.eventReplay` | `streaming.replay`, `sessions.continue`, `retainedControl`, `session.cancelRun` |
+| `runs.executionScopedStatus` | `sessions.continue`, `retainedControl`, `session.cancelRun` |
+
+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.
+
+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.
+It drops the claims that flag gates and keeps every claim its remaining flags back.
+A document without `cancel.digestBound` still carries `streaming.detach` and `streaming.replay`, and its environment still exposes `dispatch` and `session`.
+A failed read claims nothing rather than failing `create()`: discovery runs against a sandbox a cold provision has already paid for, and a transport failure is not evidence about the deployment.
+The failure is reported on the warning channel.
+
+The document is measured once, when the environment is composed.
+A sandbox that is not yet running cannot answer, so an environment composed during provisioning claims 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.
 
 Pass the SDK client itself when retained control matters.
 An object-spread wrapper (`{ ...client }`) drops class prototype methods, including `fetch`, so the provider treats the wrapper as a non-SDK client and claims no retained control.

package/dist/tangle-capabilities.d.ts

@@ -1,19 +1,22 @@
 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";
 /**
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
  *
- * This is an upper bound, not a claim. `capabilitiesForClient()` and
- * `capabilitiesForSandbox()` narrow it to what the deployment actually
- * exposes, because a capability the client cannot back becomes an action the
- * caller selects and finds missing.
+ * This is an upper bound, not a claim. `capabilitiesForClient()` narrows it
+ * to the adapter surface, and `capabilitiesForSandbox()` narrows it again to
+ * what the deployment behind one sandbox reports, because a capability
+ * nothing backs becomes an action the caller selects and finds missing.
  */
 export declare function defaultTangleSandboxCapabilities(harness?: HarnessType): AgentEnvironmentCapabilities;
 /**
- * Deployment facts that gate declared capabilities. Every fact defaults to
- * false when it cannot be established; a false fact clears the matching
- * declared capability.
+ * Adapter-surface facts that gate declared capabilities: which methods this
+ * process can actually call. Every fact defaults to false when it cannot be
+ * established; a false fact clears the matching declared capability. These
+ * facts bound the claim from above — what the connected deployment honors is
+ * a separate fact, carried by `DeploymentCapabilitySupport`.
  */
 export interface SandboxCapabilitySupport {
     /** The provider can rebuild an environment by id (`client.get`). */
@@ -29,29 +32,64 @@ export interface SandboxCapabilitySupport {
 }
 export declare function sandboxCapabilitySupport(box: SandboxInstanceLike, client: SandboxClientLike): SandboxCapabilitySupport;
 /**
- * Establish client-stage facts before any sandbox exists. Two sources:
- * the client's own members (get, describePlacement) and, for an SDK-backed
- * client, the linked SDK surface via `linkedSdkProbeInstance`. Retained
- * control fails closed: without a probe handle nothing proves `cancelRun`,
- * so the provider must not claim it. Box-scoped workspace and streaming
- * facts stay at the declared upper bound when no handle can be minted —
- * each concrete sandbox re-narrows them in `capabilitiesForSandbox`.
+ * Establish client-stage facts before any sandbox exists. Two sources: the
+ * client's own members (get, describePlacement) and, for an SDK-backed client,
+ * the linked SDK surface via `linkedSdkProbeInstance`. These facts bound what
+ * the adapter can execute; the deployment that decides whether an execution is
+ * honored is unreachable at this stage. Box-scoped workspace facts stay at the
+ * declared upper bound when no handle can be minted, and each concrete sandbox
+ * re-measures them in `capabilitiesForSandbox`.
  */
 export declare function clientCapabilitySupport(client: SandboxClientLike): SandboxCapabilitySupport;
+/**
+ * Decide whether retained control may be claimed.
+ *
+ * Two independent fact sets must agree. The adapter surface must be able to
+ * execute it: exact dispatch, a session handle, canonical cancellation, and
+ * environment reconstruction by id. The connected deployment must honor it:
+ * exact dispatch, canonical cancellation, event replay, and execution-scoped
+ * status together. A deployment that leaves any of the four unreported refuses
+ * the claim even when every local method exists, because a method this process
+ * can call is not a run the service retains.
+ */
+export declare function tangleRetainedControlSupported(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): boolean;
 /**
  * Narrow a declared capability document to established facts.
  *
  * Braid derives product actions from these flags, so an over-claimed flag is
- * an offered action that throws at the moment the user selects it. Retained
- * control requires the complete fact set: exact dispatch, a session handle,
- * canonical cancellation, and environment reconstruction by id.
+ * an offered action that throws at the moment the user selects it. Each flag
+ * takes the narrowest fact set it rests on. Detached dispatch carries the
+ * caller's exact `runControlRef` and refuses a receipt that does not echo the
+ * execution back, and it is only reachable through a session handle, so
+ * `streaming.detach` needs exact dispatch from the deployment plus both local
+ * methods. Cursor replay needs the deployment's own event replay, and turn
+ * idempotency needs the deployment to honor the exact reference that
+ * identifies a repeated turn.
  */
-export declare function narrowedTangleCapabilities(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport): AgentEnvironmentCapabilities;
+export declare function narrowedTangleCapabilities(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): AgentEnvironmentCapabilities;
 /**
  * Narrow provider-level claims to facts the client can prove before any
- * sandbox exists. `clientCapabilitySupport` documents which facts stay at
- * the declared upper bound when the client offers no probe surface.
+ * sandbox exists.
+ *
+ * This document answers "what can this provider do against a deployment that
+ * backs it", which is the question a caller selects a provider on. No sandbox
+ * exists here, so the deployment input is the adapter's ceiling and this
+ * document is a bound, never a statement about one environment. Each concrete
+ * sandbox reads its own deployment in `capabilitiesForSandbox` and publishes
+ * the answer as `AgentEnvironment.capabilities`, which is the document a
+ * caller reads to decide which operation to offer against that environment.
  */
 export declare function capabilitiesForClient(declared: AgentEnvironmentCapabilities, client: SandboxClientLike): AgentEnvironmentCapabilities;
-/** Narrow a declared capability document to what this Sandbox instance backs. */
-export declare function capabilitiesForSandbox(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport): AgentEnvironmentCapabilities;
+/**
+ * Freeze a capability document before an environment publishes it.
+ *
+ * The document and the operations an environment exposes are decided together
+ * and must stay equal, so the copy a caller holds cannot be writable: a
+ * mutated flag would describe a surface this environment does not have.
+ */
+export declare function frozenCapabilityDocument<T>(document: T): T;
+/**
+ * Narrow a declared capability document to what this Sandbox instance backs
+ * and what the deployment behind it reports.
+ */
+export declare function capabilitiesForSandbox(declared: AgentEnvironmentCapabilities, support: SandboxCapabilitySupport, deployment: DeploymentCapabilitySupport): AgentEnvironmentCapabilities;

package/dist/tangle-capabilities.js

@@ -1,13 +1,14 @@
 import { harnessSystemPromptIntents } from "@tangle-network/agent-interface";
 import { SandboxInstance } from "@tangle-network/sandbox";
+import { ADAPTER_CEILING_DEPLOYMENT, deploymentBacksRetainedControl, } from "./tangle-deployment-capabilities.js";
 /**
  * The full capability document this adapter supports when the Sandbox client
  * implements every optional method.
  *
- * This is an upper bound, not a claim. `capabilitiesForClient()` and
- * `capabilitiesForSandbox()` narrow it to what the deployment actually
- * exposes, because a capability the client cannot back becomes an action the
- * caller selects and finds missing.
+ * This is an upper bound, not a claim. `capabilitiesForClient()` narrows it
+ * to the adapter surface, and `capabilitiesForSandbox()` narrows it again to
+ * what the deployment behind one sandbox reports, because a capability
+ * nothing backs becomes an action the caller selects and finds missing.
  */
 export function defaultTangleSandboxCapabilities(harness) {
     return {
@@ -35,10 +36,11 @@ export function defaultTangleSandboxCapabilities(harness) {
         streaming: { live: true, replay: true, detach: true, turnIdempotency: true },
         // Retained control is declared as intent here and stripped by narrowing
         // wherever the facts cannot prove dispatchPrompt, session, cancelRun,
-        // and environment reconstruction by id. The four sub-flags are
-        // all-or-nothing by design: this adapter implements the identities
+        // and environment reconstruction by id, or wherever the deployment does
+        // not report the run-control and cancellation flags. The four sub-flags
+        // are all-or-nothing by design: this adapter implements the identities
         // together over one Sandbox surface, and the capability schema refuses
-        // a partial block, so they stand or fall on the same probed fact set.
+        // a partial block, so they stand or fall on the same fact set.
         sessions: { continue: true, list: false, messages: false },
         retainedControl: {
             exactRunIdentity: true,
@@ -86,13 +88,14 @@ export function sandboxCapabilitySupport(box, client) {
 /**
  * Mint a lazy instance handle from the sandbox SDK linked into this process.
  * The handle measures the LINKED SDK's instance and session method surface —
- * an adapter-capability fact, not deployment truth. It is valid exactly when
- * the client is SDK-backed (carries the SDK `fetch` transport), because the
+ * an adapter-surface fact and therefore an upper bound, never a claim that
+ * the connected service honors those methods. It is valid exactly when the
+ * client is SDK-backed (carries the SDK `fetch` transport), because the
  * sandboxes such a client returns are instances of these same classes.
- * Deployment truth (what the connected service honors) needs the sidecar
- * capability endpoint and is a follow-up. The handle and its probe session
- * never leave the process: construction and `session(id)` are lazy in the
- * SDK, so no request is sent and no billable resource is created.
+ * Deployment truth arrives per-sandbox, from `box.capabilities()`, and can
+ * only narrow this bound. The handle and its probe session never leave the
+ * process: construction and `session(id)` are lazy in the SDK, so no request
+ * is sent and no billable resource is created.
  */
 function linkedSdkProbeInstance(client) {
     if (typeof client.fetch !== "function")
@@ -109,13 +112,13 @@ function linkedSdkProbeInstance(client) {
     }
 }
 /**
- * Establish client-stage facts before any sandbox exists. Two sources:
- * the client's own members (get, describePlacement) and, for an SDK-backed
- * client, the linked SDK surface via `linkedSdkProbeInstance`. Retained
- * control fails closed: without a probe handle nothing proves `cancelRun`,
- * so the provider must not claim it. Box-scoped workspace and streaming
- * facts stay at the declared upper bound when no handle can be minted —
- * each concrete sandbox re-narrows them in `capabilitiesForSandbox`.
+ * Establish client-stage facts before any sandbox exists. Two sources: the
+ * client's own members (get, describePlacement) and, for an SDK-backed client,
+ * the linked SDK surface via `linkedSdkProbeInstance`. These facts bound what
+ * the adapter can execute; the deployment that decides whether an execution is
+ * honored is unreachable at this stage. Box-scoped workspace facts stay at the
+ * declared upper bound when no handle can be minted, and each concrete sandbox
+ * re-measures them in `capabilitiesForSandbox`.
  */
 export function clientCapabilitySupport(client) {
     const probe = linkedSdkProbeInstance(client);
@@ -134,22 +137,43 @@ export function clientCapabilitySupport(client) {
     };
 }
 /**
- * Narrow a declared capability document to established facts.
+ * Decide whether retained control may be claimed.
  *
- * Braid derives product actions from these flags, so an over-claimed flag is
- * an offered action that throws at the moment the user selects it. Retained
- * control requires the complete fact set: exact dispatch, a session handle,
- * canonical cancellation, and environment reconstruction by id.
+ * Two independent fact sets must agree. The adapter surface must be able to
+ * execute it: exact dispatch, a session handle, canonical cancellation, and
+ * environment reconstruction by id. The connected deployment must honor it:
+ * exact dispatch, canonical cancellation, event replay, and execution-scoped
+ * status together. A deployment that leaves any of the four unreported refuses
+ * the claim even when every local method exists, because a method this process
+ * can call is not a run the service retains.
  */
-export function narrowedTangleCapabilities(declared, support) {
-    const supportsRetainedControl = declared.sessions.continue === true &&
+export function tangleRetainedControlSupported(declared, support, deployment) {
+    return (deploymentBacksRetainedControl(deployment) &&
+        declared.sessions.continue === true &&
         declared.streaming.detach === true &&
         declared.streaming.replay === true &&
         declared.streaming.turnIdempotency === true &&
         support.reconstruct &&
         support.dispatchPrompt &&
         support.session &&
-        support.cancelRun;
+        support.cancelRun);
+}
+/**
+ * Narrow a declared capability document to established facts.
+ *
+ * Braid derives product actions from these flags, so an over-claimed flag is
+ * an offered action that throws at the moment the user selects it. Each flag
+ * takes the narrowest fact set it rests on. Detached dispatch carries the
+ * caller's exact `runControlRef` and refuses a receipt that does not echo the
+ * execution back, and it is only reachable through a session handle, so
+ * `streaming.detach` needs exact dispatch from the deployment plus both local
+ * methods. Cursor replay needs the deployment's own event replay, and turn
+ * idempotency needs the deployment to honor the exact reference that
+ * identifies a repeated turn.
+ */
+export function narrowedTangleCapabilities(declared, support, deployment) {
+    const supportsRetainedControl = tangleRetainedControlSupported(declared, support, deployment);
+    const supportsDetach = support.dispatchPrompt && support.session && deployment.exactDispatch;
     // A cleared fact forces false; a held fact passes the declared value
     // through unchanged, so a malformed declaration still reaches the schema
     // at the provider boundary instead of being laundered into a boolean.
@@ -157,9 +181,11 @@ export function narrowedTangleCapabilities(declared, support) {
         ...declared,
         streaming: {
             ...declared.streaming,
-            detach: support.dispatchPrompt ? declared.streaming.detach : false,
-            replay: support.session ? declared.streaming.replay : false,
-            turnIdempotency: support.session
+            detach: supportsDetach ? declared.streaming.detach : false,
+            replay: support.session && deployment.eventReplay
+                ? declared.streaming.replay
+                : false,
+            turnIdempotency: deployment.exactDispatch
                 ? declared.streaming.turnIdempotency
                 : false,
         },
@@ -197,13 +223,37 @@ export function narrowedTangleCapabilities(declared, support) {
 }
 /**
  * Narrow provider-level claims to facts the client can prove before any
- * sandbox exists. `clientCapabilitySupport` documents which facts stay at
- * the declared upper bound when the client offers no probe surface.
+ * sandbox exists.
+ *
+ * This document answers "what can this provider do against a deployment that
+ * backs it", which is the question a caller selects a provider on. No sandbox
+ * exists here, so the deployment input is the adapter's ceiling and this
+ * document is a bound, never a statement about one environment. Each concrete
+ * sandbox reads its own deployment in `capabilitiesForSandbox` and publishes
+ * the answer as `AgentEnvironment.capabilities`, which is the document a
+ * caller reads to decide which operation to offer against that environment.
  */
 export function capabilitiesForClient(declared, client) {
-    return narrowedTangleCapabilities(declared, clientCapabilitySupport(client));
+    return narrowedTangleCapabilities(declared, clientCapabilitySupport(client), ADAPTER_CEILING_DEPLOYMENT);
+}
+/**
+ * Freeze a capability document before an environment publishes it.
+ *
+ * The document and the operations an environment exposes are decided together
+ * and must stay equal, so the copy a caller holds cannot be writable: a
+ * mutated flag would describe a surface this environment does not have.
+ */
+export function frozenCapabilityDocument(document) {
+    if (document === null || typeof document !== "object")
+        return document;
+    for (const value of Object.values(document))
+        frozenCapabilityDocument(value);
+    return Object.freeze(document);
 }
-/** Narrow a declared capability document to what this Sandbox instance backs. */
-export function capabilitiesForSandbox(declared, support) {
-    return narrowedTangleCapabilities(declared, support);
+/**
+ * Narrow a declared capability document to what this Sandbox instance backs
+ * and what the deployment behind it reports.
+ */
+export function capabilitiesForSandbox(declared, support, deployment) {
+    return narrowedTangleCapabilities(declared, support, deployment);
 }

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

@@ -0,0 +1,83 @@
+import type { SandboxInstanceLike, SandboxRuntimeCapabilityDocument } from "./tangle-types.js";
+/**
+ * What the connected deployment reports about the run operations this adapter
+ * builds on top of a sandbox.
+ *
+ * Each fact is the conjunction of every document flag its operation needs, so
+ * a document that reports part of an operation reports none of it. A flag the
+ * document leaves unset is unknown, and unknown is never a claim: an absent,
+ * unreadable, or partial document leaves every fact false.
+ */
+export interface DeploymentCapabilitySupport {
+    /**
+     * Run requests carry the caller's exact `runControlRef`, and admission
+     * echoes the executionId. Detached dispatch needs both: it sends the
+     * reference and refuses a receipt that does not name the execution back.
+     */
+    readonly exactDispatch: boolean;
+    /** Cancellation is canonical, digest-bound, and idempotent under replay. */
+    readonly canonicalCancellation: boolean;
+    /** Buffered run events replay by execution under stable event ids. */
+    readonly eventReplay: boolean;
+    /** Status and results select one execution, not the session's latest. */
+    readonly executionScopedStatus: boolean;
+}
+/**
+ * The deployment backs nothing.
+ *
+ * This is the client stage, where no sandbox exists to ask, and it is also
+ * every answer that fails to establish a fact: no capability method, a sandbox
+ * that cannot answer, a `null` document, a failed request, and a document that
+ * leaves a required flag unset.
+ */
+export declare const UNPROVEN_DEPLOYMENT: DeploymentCapabilitySupport;
+/**
+ * The client stage's deployment input: this adapter's ceiling, not a fact.
+ *
+ * No sandbox exists before create, so no deployment can be asked, and the
+ * provider document answers a different question from the environment's — it
+ * states what this adapter offers against a deployment that backs it, which is
+ * what a caller selects a provider on. `AgentEnvironment.capabilities` carries
+ * the measured answer for one sandbox, and every operation an environment
+ * exposes follows that document, never this ceiling.
+ *
+ * The ceiling stays wide deliberately. A provider document that claimed
+ * nothing before create would refuse retained runs against every deployment,
+ * including the ones that back them, because a caller must read the provider
+ * document to decide whether to start one at all.
+ */
+export declare const ADAPTER_CEILING_DEPLOYMENT: DeploymentCapabilitySupport;
+/**
+ * Read the deployment facts out of a capability document. Every flag this
+ * adapter acts on is read here; the shape carries no flag it does not act on.
+ */
+export declare function deploymentCapabilitySupport(document: SandboxRuntimeCapabilityDocument | null | undefined): DeploymentCapabilitySupport;
+/**
+ * Establish the deployment facts for one sandbox through capability
+ * discovery. Every outcome but the caller's own abort resolves to a fact set.
+ *
+ * Three inputs answer without a request: a Sandbox SDK older than 0.22.0,
+ * which carries no `capabilities` method; a sandbox that is not running, whose
+ * capability route can only answer with a state error; and a `null` document,
+ * which is a deployment predating capability discovery or one serving a schema
+ * this SDK cannot read.
+ *
+ * A failed request resolves the same way. Discovery runs against a sandbox
+ * that a cold provision has just paid for, and a transport failure or a
+ * defective document is not evidence about the run operations: failing here
+ * would trade an unknown for the certain loss of that sandbox. The failure
+ * reaches the warning channel, and the environment then offers no operation
+ * the document did not prove.
+ */
+export declare function readDeploymentCapabilitySupport(box: SandboxInstanceLike, options?: {
+    signal?: AbortSignal;
+}): Promise<DeploymentCapabilitySupport>;
+/**
+ * Whether the deployment backs the complete retained-control identity set.
+ * The capability schema refuses a partial retained-control block, and each
+ * identity rests on its own deployment fact, so they stand together: exact
+ * dispatch for run identity, execution-scoped status for result identity,
+ * event replay for event identity, and canonical cancellation for
+ * cancellation idempotency.
+ */
+export declare function deploymentBacksRetainedControl(deployment: DeploymentCapabilitySupport): boolean;

package/dist/tangle-deployment-capabilities.js

@@ -0,0 +1,103 @@
+import { statusFromUnknown } from "./tangle-environment-values.js";
+import { awaitWithSignal } from "./tangle-contract-safety.js";
+/**
+ * The deployment backs nothing.
+ *
+ * This is the client stage, where no sandbox exists to ask, and it is also
+ * every answer that fails to establish a fact: no capability method, a sandbox
+ * that cannot answer, a `null` document, a failed request, and a document that
+ * leaves a required flag unset.
+ */
+export const UNPROVEN_DEPLOYMENT = {
+    exactDispatch: false,
+    canonicalCancellation: false,
+    eventReplay: false,
+    executionScopedStatus: false,
+};
+/**
+ * The client stage's deployment input: this adapter's ceiling, not a fact.
+ *
+ * No sandbox exists before create, so no deployment can be asked, and the
+ * provider document answers a different question from the environment's — it
+ * states what this adapter offers against a deployment that backs it, which is
+ * what a caller selects a provider on. `AgentEnvironment.capabilities` carries
+ * the measured answer for one sandbox, and every operation an environment
+ * exposes follows that document, never this ceiling.
+ *
+ * The ceiling stays wide deliberately. A provider document that claimed
+ * nothing before create would refuse retained runs against every deployment,
+ * including the ones that back them, because a caller must read the provider
+ * document to decide whether to start one at all.
+ */
+export const ADAPTER_CEILING_DEPLOYMENT = {
+    exactDispatch: true,
+    canonicalCancellation: true,
+    eventReplay: true,
+    executionScopedStatus: true,
+};
+/**
+ * Read the deployment facts out of a capability document. Every flag this
+ * adapter acts on is read here; the shape carries no flag it does not act on.
+ */
+export function deploymentCapabilitySupport(document) {
+    if (!document || typeof document !== "object")
+        return UNPROVEN_DEPLOYMENT;
+    return {
+        exactDispatch: document.dispatch?.runControlRef === true &&
+            document.dispatch?.executionIdOnAdmission === true,
+        canonicalCancellation: document.cancel?.canonicalRunCancellation === true &&
+            document.cancel?.digestBound === true &&
+            document.cancel?.idempotent === true,
+        eventReplay: document.runs?.eventReplay === true,
+        executionScopedStatus: document.runs?.executionScopedStatus === true,
+    };
+}
+/**
+ * Establish the deployment facts for one sandbox through capability
+ * discovery. Every outcome but the caller's own abort resolves to a fact set.
+ *
+ * Three inputs answer without a request: a Sandbox SDK older than 0.22.0,
+ * which carries no `capabilities` method; a sandbox that is not running, whose
+ * capability route can only answer with a state error; and a `null` document,
+ * which is a deployment predating capability discovery or one serving a schema
+ * this SDK cannot read.
+ *
+ * A failed request resolves the same way. Discovery runs against a sandbox
+ * that a cold provision has just paid for, and a transport failure or a
+ * defective document is not evidence about the run operations: failing here
+ * would trade an unknown for the certain loss of that sandbox. The failure
+ * reaches the warning channel, and the environment then offers no operation
+ * the document did not prove.
+ */
+export async function readDeploymentCapabilitySupport(box, options) {
+    if (typeof box.capabilities !== "function")
+        return UNPROVEN_DEPLOYMENT;
+    if (statusFromUnknown(box.status) !== "running")
+        return UNPROVEN_DEPLOYMENT;
+    options?.signal?.throwIfAborted();
+    let document;
+    try {
+        document = await awaitWithSignal(box.capabilities(), options?.signal);
+    }
+    catch (error) {
+        options?.signal?.throwIfAborted();
+        console.warn(`Tangle capability discovery failed for sandbox ${box.id}: the deployment backs nothing`, error);
+        return UNPROVEN_DEPLOYMENT;
+    }
+    options?.signal?.throwIfAborted();
+    return deploymentCapabilitySupport(document);
+}
+/**
+ * Whether the deployment backs the complete retained-control identity set.
+ * The capability schema refuses a partial retained-control block, and each
+ * identity rests on its own deployment fact, so they stand together: exact
+ * dispatch for run identity, execution-scoped status for result identity,
+ * event replay for event identity, and canonical cancellation for
+ * cancellation idempotency.
+ */
+export function deploymentBacksRetainedControl(deployment) {
+    return (deployment.exactDispatch &&
+        deployment.canonicalCancellation &&
+        deployment.eventReplay &&
+        deployment.executionScopedStatus);
+}

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

@@ -9,5 +9,11 @@ type ExactExecutionEventStream = (options: {
     signal?: AbortSignal;
     controlRef?: AgentExactRunControlRef;
 }) => AsyncIterable<SandboxEvent>;
-export declare function sandboxSessionAsAgentSession(session: SandboxSessionLike, controlRef: AgentRunControlRef | undefined, provider: string, environmentId: string, dispatch?: (input: AgentTurnInput) => Promise<AgentSessionRef>, exactExecutionEvents?: ExactExecutionEventStream): AgentSession;
+/**
+ * @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.
+ */
+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 {};

package/dist/tangle-environment-session.js

@@ -8,12 +8,18 @@ import { executionBoundSessionStatus, sessionStatusFromUnknown, } from "./tangle
 import { awaitWithSignal, boundedIdentifier, } from "./tangle-contract-safety.js";
 import { assertOptionKeys } from "./tangle-environment-validation.js";
 import { hasReplayPayload, interruptExecutionAfterAbort, sessionPromptRequestDigest, } from "./tangle-environment-control.js";
-export function sandboxSessionAsAgentSession(session, controlRef, provider, environmentId, dispatch, exactExecutionEvents) {
+/**
+ * @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.
+ */
+export function sandboxSessionAsAgentSession(session, controlRef, provider, environmentId, dispatch, exactExecutionEvents, retainedControl) {
     let activeControlRef = controlRef
         ? resolveRetainedSessionControlRef(controlRef, session.id, provider, environmentId)
         : undefined;
     let promptInFlight = false;
-    const cancelRunMethod = session.cancelRun;
+    const cancelRunMethod = retainedControl ? session.cancelRun : undefined;
     const cancelRun = typeof cancelRunMethod === "function"
         ? async (request, options) => {
             assertOptionKeys(options, ["signal"], "Tangle exact session cancellation");

package/dist/tangle-environment.d.ts

@@ -1,3 +1,22 @@
 import type { AgentEnvironment, AgentEnvironmentCapabilities } from "@tangle-network/agent-interface/environment-provider";
 import type { SandboxClientLike, SandboxInstanceLike } from "./tangle-types.js";
-export declare function sandboxInstanceAsEnvironment(box: SandboxInstanceLike, providerName: string, client: SandboxClientLike, declaredCapabilities: AgentEnvironmentCapabilities): AgentEnvironment;
+/**
+ * Compose one concrete sandbox into an environment.
+ *
+ * This is the only stage that can read deployment truth, so it does: one
+ * `GET /capabilities` against the sandbox decides retained control, and the
+ * environment then exposes exactly the operations both the adapter surface
+ * and the deployment back. A deployment that cannot disclose a readable
+ * document yields no retained-control surface at all. The environment
+ * publishes the resulting document on `capabilities`, so a caller reads the
+ * answer for this sandbox rather than the provider's pre-sandbox claim.
+ *
+ * The document is measured once, here. A sandbox that is not yet running
+ * cannot answer, so an environment composed during provisioning claims
+ * 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.
+ */
+export declare function sandboxInstanceAsEnvironment(box: SandboxInstanceLike, providerName: string, client: SandboxClientLike, declaredCapabilities: AgentEnvironmentCapabilities, operation?: {
+    signal?: AbortSignal;
+}): Promise<AgentEnvironment>;

package/dist/tangle-environment.js

@@ -1,16 +1,35 @@
 import { AgentTurnInputSchema } from "@tangle-network/agent-interface";
+import { AgentEnvironmentCapabilitiesSchema } from "@tangle-network/agent-interface/environment-provider";
 import { environmentEventFromSandboxEvent } from "./tangle-events.js";
 import { executionIdFromTurnInput, promptFromTurnInput, promptOptionsFromTurnInput, } from "./tangle-prompt.js";
 import { resolveRetainedSessionControlRef } from "./tangle-session-control.js";
 import { placementInfoFromLoopPlacement, statusFromUnknown, } from "./tangle-environment-values.js";
 import { execResultFromSandboxExecResult } from "./tangle-result-values.js";
-import { capabilitiesForSandbox, sandboxCapabilitySupport } from "./tangle-capabilities.js";
+import { capabilitiesForSandbox, frozenCapabilityDocument, sandboxCapabilitySupport, } from "./tangle-capabilities.js";
+import { readDeploymentCapabilitySupport } from "./tangle-deployment-capabilities.js";
 import { awaitWithSignal, assertBoundedJson, boundedIdentifier, boundedString, } from "./tangle-contract-safety.js";
 import { assertExecOptions, assertOptionKeys, } from "./tangle-environment-validation.js";
 import { interruptExecutionAfterAbort, } from "./tangle-environment-control.js";
 import { dispatchEnvironmentRun } from "./tangle-environment-dispatch.js";
 import { sandboxSessionAsAgentSession } from "./tangle-environment-session.js";
-export function sandboxInstanceAsEnvironment(box, providerName, client, declaredCapabilities) {
+/**
+ * Compose one concrete sandbox into an environment.
+ *
+ * This is the only stage that can read deployment truth, so it does: one
+ * `GET /capabilities` against the sandbox decides retained control, and the
+ * environment then exposes exactly the operations both the adapter surface
+ * and the deployment back. A deployment that cannot disclose a readable
+ * document yields no retained-control surface at all. The environment
+ * publishes the resulting document on `capabilities`, so a caller reads the
+ * answer for this sandbox rather than the provider's pre-sandbox claim.
+ *
+ * The document is measured once, here. A sandbox that is not yet running
+ * cannot answer, so an environment composed during provisioning claims
+ * 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.
+ */
+export async function sandboxInstanceAsEnvironment(box, providerName, client, declaredCapabilities, operation) {
     const environmentId = boundedIdentifier(box.id, "Tangle environment id");
     boundedIdentifier(providerName, "Tangle provider name");
     if (box.metadata !== undefined) {
@@ -20,7 +39,11 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
         assertBoundedJson(box.metadata);
     }
     const support = sandboxCapabilitySupport(box, client);
-    const capabilities = capabilitiesForSandbox(declaredCapabilities, support);
+    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 dispatch = capabilities.streaming.detach && box.dispatchPrompt
         ? dispatchEnvironmentRun(box, providerName, environmentId)
         : undefined;
@@ -37,6 +60,7 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
         id: environmentId,
         provider: providerName,
         ...(box.name ? { name: boundedString(box.name, "Tangle environment name") } : {}),
+        capabilities,
         async status(options) {
             assertOptionKeys(options, ["signal"], "Tangle environment status");
             await awaitWithSignal(box.refresh?.(options), options?.signal);
@@ -103,11 +127,12 @@ export function sandboxInstanceAsEnvironment(box, providerName, client, declared
                     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);
-                    // sessions.continue was granted from a probe-session fact; this
-                    // backstop holds every concrete session to that fact, so a client
-                    // whose sessions diverge from its probe surface fails loud here
-                    // instead of failing at the first cancellation.
+                    const agentSession = sandboxSessionAsAgentSession(session, resolveRetainedSessionControlRef(options?.controlRef, id, providerName, environmentId), providerName, environmentId, dispatch, exactExecutionEvents, retainedControl);
+                    // 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
+                    // diverge from its probe surface fails loud here instead of
+                    // failing at the first cancellation.
                     if (capabilities.sessions.continue &&
                         typeof agentSession.cancelRun !== "function") {
                         throw new Error("Tangle retained session support requires SandboxSession.cancelRun");

package/dist/tangle-events.js

@@ -72,7 +72,15 @@ export function environmentEventFromSandboxEvent(event, expected = {}) {
     if (Object.prototype.hasOwnProperty.call(data, "contextTransferReceipt")) {
         throw new Error("Tangle Sandbox emitted an unsolicited context transfer receipt");
     }
-    const { executionId: eventExecutionId, sessionId: eventSessionId } = sandboxEventIdentity(event);
+    // 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.
+    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))) {

package/dist/tangle-prompt.js

@@ -58,15 +58,32 @@ export function promptOptionsFromTurnInput(input, target) {
         ...(input.detach !== undefined ? { detach: input.detach } : {}),
     };
 }
+const SANDBOX_OPTIONAL_RESULT_FIELDS = new Set([
+    "executionId",
+    "response",
+    "error",
+    "errorCode",
+    "toolInvocations",
+    "approval",
+    "question",
+    "plan",
+    "traceId",
+    "usage",
+    "costUsd",
+]);
 export function validatedSandboxPromptResult(result) {
     if (!result || typeof result !== "object" || Array.isArray(result)) {
         throw new Error("Tangle prompt returned no result object");
     }
-    const record = result;
-    if (Object.hasOwn(record, "contextTransferReceipt") &&
-        record.contextTransferReceipt === undefined) {
+    const source = result;
+    if (Object.hasOwn(source, "contextTransferReceipt") &&
+        source.contextTransferReceipt === undefined) {
         throw new Error("Tangle prompt result returned a context receipt for a turn that requested no transfer");
     }
+    // The Sandbox SDK materializes absent optional response fields as
+    // `undefined`. They were absent on the JSON wire and must stay absent in the
+    // provider-neutral result before the strict JSON check runs.
+    const record = Object.fromEntries(Object.entries(source).filter(([field, value]) => value !== undefined || !SANDBOX_OPTIONAL_RESULT_FIELDS.has(field)));
     assertBoundedJson(record);
     if (typeof record.success !== "boolean") {
         throw new Error("Tangle prompt result omitted its success status");

package/dist/tangle-provider.js

@@ -83,7 +83,7 @@ export function createTangleProvider(options) {
             }
             try {
                 input.signal?.throwIfAborted();
-                const environment = sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities);
+                const environment = await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, input.signal ? { signal: input.signal } : undefined);
                 input.signal?.throwIfAborted();
                 return environment;
             }
@@ -115,7 +115,7 @@ export function createTangleProvider(options) {
                     operation?.signal?.throwIfAborted();
                     if (!box || boundedIdentifier(box.id, "Tangle environment id") !== id)
                         return null;
-                    return sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities);
+                    return await sandboxInstanceAsEnvironment(box, providerName, options.client, declaredCapabilities, operation?.signal ? { signal: operation.signal } : undefined);
                 },
             }
             : {}),

package/dist/tangle-types.d.ts

@@ -31,6 +31,46 @@ export interface SandboxClientLike {
     }): Promise<SandboxInstanceLike[]>;
     describePlacement?(box: SandboxInstanceLike): unknown;
 }
+/**
+ * The `GET /capabilities` document as this adapter reads it: what the DEPLOYED
+ * sidecar image compiled in, not which methods the linked SDK class carries.
+ *
+ * Every capability flag this shape declares gates a claim the adapter makes,
+ * and the wire document's other flags are absent here because the adapter does
+ * not act on them yet. Every field is optional, and the document's own
+ * convention is that a missing flag means "unknown to that image", never
+ * false. The linked SDK parses a v1 wire body strictly, but this adapter reads
+ * any `SandboxInstanceLike`, so it never assumes a flag was validated: an
+ * absent field reaches the claim as unknown instead of being coerced. The
+ * SDK's `SandboxRuntimeCapabilities` is assignable to this shape;
+ * `deployment-capabilities.test.ts` pins that against the published type.
+ */
+export interface SandboxRuntimeCapabilityDocument {
+    schema?: number;
+    agentInterface?: string;
+    sidecarVersion?: string;
+    image?: string;
+    dispatch?: {
+        /** Run requests accept a caller-supplied exact `runControlRef`. */
+        runControlRef?: boolean;
+        /** Admission echoes the executionId the request named. */
+        executionIdOnAdmission?: boolean;
+    };
+    cancel?: {
+        /** Cancellation accepts the canonical digest-bound request. */
+        canonicalRunCancellation?: boolean;
+        /** Cancellation binds to the run's request digest. */
+        digestBound?: boolean;
+        /** Replaying an operation id returns the stored acknowledgement. */
+        idempotent?: boolean;
+    };
+    runs?: {
+        /** Status and results select one execution of a session. */
+        executionScopedStatus?: boolean;
+        /** Buffered run events replay by execution. */
+        eventReplay?: boolean;
+    };
+}
 export interface SandboxProcessStatusLike {
     pid: number;
     running: boolean;
@@ -106,6 +146,15 @@ export interface SandboxInstanceLike {
         }): Promise<unknown>;
     };
     process?: SandboxProcessManagerLike;
+    /**
+     * Capability discovery against the deployment behind this sandbox. Absent
+     * on a Sandbox SDK older than 0.22.0, which is why every call site feature-
+     * detects it: an older SDK cannot read deployment truth, so the adapter
+     * claims no retained control rather than trusting its own method surface.
+     * Resolves to null when the deployment cannot disclose a document this SDK
+     * reads; a malformed document throws.
+     */
+    capabilities?(): Promise<SandboxRuntimeCapabilityDocument | null>;
     refresh?(options?: {
         signal?: AbortSignal;
     }): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-tangle",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "AgentEnvironmentProvider adapter for Tangle sandboxes",
   "type": "module",
   "license": "MIT",
@@ -37,6 +37,8 @@
     "dist/tangle-exact-process-validation.js",
     "dist/tangle-capabilities.d.ts",
     "dist/tangle-capabilities.js",
+    "dist/tangle-deployment-capabilities.d.ts",
+    "dist/tangle-deployment-capabilities.js",
     "dist/tangle-create-options.d.ts",
     "dist/tangle-create-options.js",
     "dist/tangle-environment-values.d.ts",
@@ -67,7 +69,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.49.0"
+    "@tangle-network/agent-interface": "0.50.0"
   },
   "peerDependencies": {
     "@tangle-network/sandbox": ">=0.19.6 <1.0.0"
@@ -80,11 +82,11 @@
   "devDependencies": {
     "@tangle-network/agent-eval": "0.145.3",
     "@tangle-network/agent-runtime": "0.132.13",
-    "@tangle-network/sandbox": "0.21.1",
+    "@tangle-network/sandbox": "0.22.0",
     "@types/node": "25.6.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5",
-    "@tangle-network/agent-provider-testkit": "0.6.4"
+    "@tangle-network/agent-provider-testkit": "0.7.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",