@tangle-network/agent-provider-cli-bridge 0.9.1 → 0.9.2

package/README.md

@@ -40,6 +40,8 @@ Persist the returned `controlRef` before treating dispatch as accepted.
 It contains the exact provider, environment, session, execution, run, and request digest needed after a process restart.
 Reconstruct the environment with `provider.get(controlRef.environmentId)`, then call `environment.session(controlRef.sessionId, { controlRef })`.
 The provider rejects any coordinate or digest mismatch instead of attaching to a different run.
+If the caller crashes before saving `controlRef`, call `provider.lookupRun()` with the planned run coordinates.
+The lookup returns the server-issued digest only when all five planned coordinates match the retained run.
 
 The bridge model is selected from run data in this order: the turn, the provider default, or the profile's `harness` plus `model.default`.
 Execution fails before network use when none is present.
@@ -69,8 +71,11 @@ The provider stores the selected harness, exact model route, and canonical creat
 This identifier lets `provider.get()` reconstruct profile-selected routes after process death without a cache or repeated configuration.
 The create digest prevents an altered profile or workspace from reusing the previous retained identity.
 `provider.get()` accepts only identifiers created by this provider and rejects plain caller identifiers.
-The provider queries `/v1/capabilities` for the retained Pi route.
-The provider caches the valid response and enables native interactions only when the running Bridge proves the complete retained contract.
+The provider queries `/v1/capabilities` for each retained route restored through `provider.get()`.
+`provider.capabilities()` queries the configured default route before the Runtime selects retained execution.
+The provider shares concurrent discovery requests and refreshes every later query.
+It enables retained control only when the running Bridge proves the complete contract.
+It enables native interactions only when the running Bridge proves the Pi contract.
 Every native turn stays on the model route used for that discovery; another model requires another environment.
 An explicit capability document remains available for a caller that already performed the same discovery.
 That capability selects cli-bridge's native `/v1/sessions` and `/turns` transport; it never sends an interactive turn to `/v1/chat/completions`.

package/dist/capability-discovery.d.ts

@@ -2,7 +2,7 @@ import { type AgentEnvironmentCapabilities } from "@tangle-network/agent-interfa
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 /** Read the retained contract from the exact Bridge model route. */
 export declare function discoverCliBridgeCapabilities(options: CliBridgeProviderOptions, model: string): Promise<AgentEnvironmentCapabilities>;
-/** Share one readiness request between capability checks and environment creation. */
+/** Share concurrent readiness requests without retaining stale model truth. */
 export declare function cachedCliBridgeCapabilityDiscovery(options: CliBridgeProviderOptions): (model: string) => Promise<AgentEnvironmentCapabilities>;
 /**
  * Publish only operations implemented by this adapter and proved by Bridge.

package/dist/capability-discovery.js

@@ -1,6 +1,6 @@
 import { AgentEnvironmentCapabilitiesSchema, } from "@tangle-network/agent-interface/environment-provider";
 import { supportsCliBridgeNativeContinuation, supportsCliBridgeNativeInteractions, } from "./retained-native.js";
-import { createCliBridgeTransport, requestHeaders, trimSlash, } from "./transport.js";
+import { createCliBridgeTransport, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
 /** Read the retained contract from the exact Bridge model route. */
 export async function discoverCliBridgeCapabilities(options, model) {
     const transport = createCliBridgeTransport(options);
@@ -9,12 +9,13 @@ export async function discoverCliBridgeCapabilities(options, model) {
             method: "GET",
             headers: requestHeaders(options),
         });
+        const responseText = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES);
         if (!response.ok) {
-            throw new Error(`cli-bridge capability discovery returned HTTP ${response.status}: ${await response.text()}`);
+            throw new Error(`cli-bridge capability discovery returned HTTP ${response.status}: ${responseText}`);
         }
         let value;
         try {
-            value = JSON.parse(await response.text());
+            value = JSON.parse(responseText);
         }
         catch (error) {
             throw new Error("cli-bridge capability discovery returned invalid JSON", { cause: error });
@@ -31,7 +32,7 @@ export async function discoverCliBridgeCapabilities(options, model) {
         await transport.close();
     }
 }
-/** Share one readiness request between capability checks and environment creation. */
+/** Share concurrent readiness requests without retaining stale model truth. */
 export function cachedCliBridgeCapabilityDiscovery(options) {
     const cache = new Map();
     return (model) => {
@@ -40,10 +41,10 @@ export function cachedCliBridgeCapabilityDiscovery(options) {
             return existing;
         const pending = discoverCliBridgeCapabilities(options, model);
         cache.set(model, pending);
-        void pending.catch(() => {
+        void pending.finally(() => {
             if (cache.get(model) === pending)
                 cache.delete(model);
-        });
+        }).catch(() => { });
         return pending;
     };
 }

package/dist/index.d.ts

@@ -1,9 +1,15 @@
 import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider } from "@tangle-network/agent-interface/environment-provider";
-import { type HarnessType } from "@tangle-network/agent-interface";
+import { type AgentExactRunControlRef, type HarnessType } from "@tangle-network/agent-interface";
+import { type CliBridgeRunLookupInput } from "./retained-control.js";
 import { type CliBridgeProviderOptions } from "./provider-options.js";
 export type { CliBridgeProviderOptions } from "./provider-options.js";
+export type { CliBridgeRunLookupInput } from "./retained-control.js";
 export { safeEndpointFromBaseUrl } from "./observation.js";
-export declare function createCliBridgeProvider(options: CliBridgeProviderOptions): AgentEnvironmentProvider;
+export interface CliBridgeProvider extends AgentEnvironmentProvider {
+    /** Recover the server-issued digest for one pre-dispatch retained admission. */
+    lookupRun(input: CliBridgeRunLookupInput): Promise<AgentExactRunControlRef | null>;
+}
+export declare function createCliBridgeProvider(options: CliBridgeProviderOptions): CliBridgeProvider;
 /**
  * Describe the bridge backend, not this adapter.
  *

package/dist/index.js

@@ -1,6 +1,7 @@
 import { agentEnvironmentCreateInputDigest, createAgentEnvironmentWithIdempotency, } from "@tangle-network/agent-interface/environment-provider";
 import { harnessTypeSchema, harnessSystemPromptIntents, snapshotAgentProfile, } from "@tangle-network/agent-interface";
 import { createCliBridgeEnvironment, } from "./retained-environment.js";
+import { lookupExactCliBridgeRun, } from "./retained-control.js";
 import { cachedCliBridgeCapabilityDiscovery, narrowCliBridgeCapabilities, } from "./capability-discovery.js";
 import { supportsCliBridgeNativeInteractions, } from "./retained-native.js";
 import { assertCliBridgeProviderOptions, } from "./provider-options.js";
@@ -14,6 +15,7 @@ export function createCliBridgeProvider(options) {
     const createRecords = new Map();
     const configuredBackend = selectedBackendFromRoute(options.defaultModel);
     const discoverCapabilities = cachedCliBridgeCapabilityDiscovery(options);
+    const remotelyVerifiedRoutes = new Set();
     // The observation surfaces are declared as intent and narrowed to the
     // sources this bridge can put a value on, so the environment offers the
     // operation exactly where the document claims it.
@@ -36,17 +38,19 @@ export function createCliBridgeProvider(options) {
         const { interactions: _interactions, ...withoutInteractions } = narrowed;
         return withoutInteractions;
     };
-    const resolveCapabilities = (selectedBackend, model, allowNativeInteractions = false) => {
+    const resolveCapabilities = (selectedBackend, model, allowNativeInteractions = false, discoverRemote = false) => {
         const local = localCapabilities(selectedBackend, allowNativeInteractions);
-        if (!allowNativeInteractions ||
-            options.capabilities !== undefined ||
-            selectedBackend !== "pi" ||
-            model === undefined) {
+        if (options.capabilities !== undefined)
             return local;
-        }
-        return discoverCapabilities(model).then((reported) => narrowCliBridgeCapabilities(local, reported, selectedBackend, {
-            preserveAdapterObservation: true,
-        }));
+        if (model === undefined)
+            return withoutRemoteRetainedCapabilities(local);
+        if (!discoverRemote)
+            return withoutRemoteRetainedCapabilities(local);
+        return discoverCapabilities(model).then((reported) => {
+            return narrowCliBridgeCapabilities(local, reported, selectedBackend, {
+                preserveAdapterObservation: true,
+            });
+        });
     };
     const createEnvironment = async (input) => {
         if (typeof input.profile === "string") {
@@ -72,14 +76,21 @@ export function createCliBridgeProvider(options) {
             environmentId,
             allowDispatch: true,
             cancelRunsOnDestroy: true,
-            capabilities: await resolveCapabilities(selectedBackend, model, true),
+            capabilities: await resolveCapabilities(selectedBackend, model, true, selectedBackend === "pi" ||
+                (model !== undefined && remotelyVerifiedRoutes.has(model))),
             selectedBackend,
             selectedModel: model,
         });
     };
     return {
         name,
-        capabilities: () => resolveCapabilities(configuredBackend, options.defaultModel, true),
+        lookupRun: (input) => lookupExactCliBridgeRun(options, name, input),
+        capabilities: () => {
+            if (options.defaultModel !== undefined) {
+                remotelyVerifiedRoutes.add(options.defaultModel);
+            }
+            return resolveCapabilities(configuredBackend, options.defaultModel, true, true);
+        },
         create(input) {
             return createAgentEnvironmentWithIdempotency(createRecords, input, () => createEnvironment(input));
         },
@@ -99,13 +110,17 @@ export function createCliBridgeProvider(options) {
                 environmentId: id,
                 allowDispatch: false,
                 cancelRunsOnDestroy: false,
-                capabilities: await resolveCapabilities(route.backend, route.model, true),
+                capabilities: await resolveCapabilities(route.backend, route.model, true, true),
                 selectedBackend: route.backend,
                 selectedModel: route.model,
             });
         },
     };
 }
+function withoutRemoteRetainedCapabilities(capabilities) {
+    const { retainedControl: _retainedControl, nativeContinuation: _nativeContinuation, interactions: _interactions, ...local } = capabilities;
+    return local;
+}
 function selectedBackendFromInput(input, configuredBackend) {
     if (input.backend !== undefined)
         return input.backend;

package/dist/interaction-response.js

@@ -1,5 +1,5 @@
 import { InteractionAcknowledgementSchema, InteractionResponseCommandSchema, } from "@tangle-network/agent-interface";
-import { requestHeaders, trimSlash, } from "./transport.js";
+import { MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
 function transportFailure(command, error, retryable = true) {
     return InteractionAcknowledgementSchema.parse({
         operationId: command.operationId,
@@ -89,7 +89,7 @@ export function cliBridgeInteractionResponder(options) {
         let acknowledgement;
         const retryableOnMalformed = response.status >= 500 || (response.status >= 200 && response.status < 300);
         try {
-            acknowledgement = InteractionAcknowledgementSchema.parse(JSON.parse(await response.text()));
+            acknowledgement = InteractionAcknowledgementSchema.parse(JSON.parse(await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, operation?.signal)));
         }
         catch (error) {
             return transportFailure(exact, error, retryableOnMalformed);

package/dist/provider-options.d.ts

@@ -1,4 +1,5 @@
 import type { AgentEnvironmentCapabilities } from "@tangle-network/agent-interface/environment-provider";
+export declare const MAX_CLI_BRIDGE_TIMEOUT_MS = 2147483647;
 export interface CliBridgeProviderOptions {
     baseUrl: string;
     bearerToken?: string;

package/dist/provider-options.js

@@ -1,3 +1,4 @@
+export const MAX_CLI_BRIDGE_TIMEOUT_MS = 2_147_483_647;
 export function assertCliBridgeProviderOptions(options) {
     assertTimeout(options.headersTimeoutMs, "headersTimeoutMs");
     assertTimeout(options.bodyTimeoutMs, "bodyTimeoutMs");
@@ -7,4 +8,7 @@ function assertTimeout(value, name) {
     if (value !== undefined && (!Number.isInteger(value) || value < 0)) {
         throw new Error(`createCliBridgeProvider ${name} must be a non-negative integer`);
     }
+    if (value !== undefined && value > MAX_CLI_BRIDGE_TIMEOUT_MS) {
+        throw new Error(`createCliBridgeProvider ${name} must be no greater than ${MAX_CLI_BRIDGE_TIMEOUT_MS}`);
+    }
 }

package/dist/retained-control.d.ts

@@ -1,11 +1,21 @@
-import { type AgentRunCancellationAcknowledgement, type AgentRunCancellationRequest } from "@tangle-network/agent-interface";
+import { type AgentExactRunControlRef, type AgentRunCancellationAcknowledgement, type AgentRunCancellationRequest } from "@tangle-network/agent-interface";
 import type { AgentSessionStatus } from "@tangle-network/agent-interface/environment-provider";
-import type { CliBridgeProviderOptions } from "./provider-options.js";
+import { type CliBridgeProviderOptions } from "./provider-options.js";
 import type { CliBridgeRun, CliBridgeRunSnapshot } from "./retained-run-state.js";
 import type { CliBridgeResponse, CliBridgeTransport } from "./transport.js";
+export declare function cliBridgeCancellationSignal(options: CliBridgeProviderOptions): AbortSignal;
 export declare function captureCliBridgeRunIdentity(response: CliBridgeResponse, run: CliBridgeRun, required: boolean): void;
 export declare function detachCliBridgeReader(body: AsyncIterable<Uint8Array>): Promise<void>;
 export declare function cancelCliBridgeRun(options: CliBridgeProviderOptions, transport: CliBridgeTransport, run: CliBridgeRun, signal?: AbortSignal): Promise<CliBridgeRunSnapshot>;
 export declare function cancelExactCliBridgeRun(options: CliBridgeProviderOptions, transport: CliBridgeTransport, run: CliBridgeRun, request: AgentRunCancellationRequest, signal?: AbortSignal): Promise<AgentRunCancellationAcknowledgement>;
 export declare function getCliBridgeRun(options: CliBridgeProviderOptions, transport: CliBridgeTransport, run: CliBridgeRun, waitMs?: number, signal?: AbortSignal): Promise<CliBridgeRunSnapshot | null>;
+export interface CliBridgeRunLookupInput {
+    readonly runId: string;
+    readonly environmentId: string;
+    readonly sessionId: string;
+    readonly executionId: string;
+    readonly signal?: AbortSignal;
+}
+/** Recover one exact Bridge run after dispatch succeeded but local admission did not. */
+export declare function lookupExactCliBridgeRun(options: CliBridgeProviderOptions, providerName: string, input: CliBridgeRunLookupInput): Promise<AgentExactRunControlRef | null>;
 export declare function agentSessionStatusFromRun(snapshot: CliBridgeRunSnapshot): AgentSessionStatus;

package/dist/retained-control.js

@@ -1,6 +1,12 @@
-import { AgentExactRunControlRefSchema, AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, agentRunCancellationAcknowledgementMatchesRequest, } from "@tangle-network/agent-interface";
-import { requestHeaders, trimSlash } from "./transport.js";
-import { cancelSnapshot, runSnapshot } from "./wire.js";
+import { AgentExactRunControlRefSchema, AgentRunCancellationAcknowledgementSchema, AgentRunCancellationRequestSchema, agentRunCancellationRequestDigest, agentRunCancellationAcknowledgementMatchesRequest, } from "@tangle-network/agent-interface";
+import { assertCliBridgeProviderOptions, } from "./provider-options.js";
+import { createCliBridgeTransport, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
+import { assertCliBridgeRunId, runSnapshot } from "./wire.js";
+const DEFAULT_CANCELLATION_WAIT_MS = 30_000;
+export function cliBridgeCancellationSignal(options) {
+    assertCliBridgeProviderOptions(options);
+    return AbortSignal.timeout(options.cancelWaitMs ?? DEFAULT_CANCELLATION_WAIT_MS);
+}
 export function captureCliBridgeRunIdentity(response, run, required) {
     const responseRunId = response.headers.get("x-run-id");
     const requestDigestHeader = response.headers.get("x-run-request-digest");
@@ -24,8 +30,34 @@ export function captureCliBridgeRunIdentity(response, run, required) {
     if (run.requestDigest !== undefined && requestDigest === null) {
         throw new Error(`cli-bridge replay response omitted X-Run-Request-Digest for run "${run.id}"`);
     }
-    if (requestDigest !== null)
+    const responseProvider = response.headers.get("x-run-provider");
+    const responseEnvironmentId = response.headers.get("x-run-environment-id");
+    const responseSessionId = response.headers.get("x-run-session-id");
+    const responseExecutionId = response.headers.get("x-run-execution-id");
+    const completeCoordinates = [
+        responseRunId,
+        requestDigest,
+        responseProvider,
+        responseEnvironmentId,
+        responseSessionId,
+        responseExecutionId,
+    ].every((value) => value !== null);
+    if ((required || run.controlRef !== undefined) && !completeCoordinates) {
+        throw new Error("cli-bridge response omitted exact run coordinates");
+    }
+    if (completeCoordinates) {
+        bindExactControlRef(run, AgentExactRunControlRefSchema.parse({
+            runId: responseRunId,
+            requestDigest,
+            provider: responseProvider,
+            environmentId: responseEnvironmentId,
+            sessionId: responseSessionId,
+            executionId: responseExecutionId,
+        }));
+    }
+    else if (requestDigest !== null) {
         run.requestDigest = requestDigest;
+    }
 }
 export async function detachCliBridgeReader(body) {
     const cancellable = body;
@@ -48,23 +80,43 @@ export async function cancelCliBridgeRun(options, transport, run, signal) {
     return waitForOperation(run.cancellation, signal);
 }
 async function performCliBridgeCancellation(options, transport, run) {
-    const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(run.id)}/cancel`, {
+    const waitBudgetMs = options.cancelWaitMs ?? DEFAULT_CANCELLATION_WAIT_MS;
+    const deadline = Date.now() + waitBudgetMs;
+    const signal = cliBridgeCancellationSignal(options);
+    let snapshot = null;
+    if (run.controlRef === undefined) {
+        snapshot = await getCliBridgeRun(options, transport, run, undefined, signal);
+        if (snapshot === null) {
+            throw new Error(`cli-bridge cannot safely cancel unknown run "${run.id}"`);
+        }
+        if (snapshot.terminal)
+            return snapshot;
+    }
+    const exactRequest = automaticCancellationRequest(run);
+    const response = await waitForOperation(transport.fetch(`${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(run.id)}/cancel`, {
         method: "POST",
         headers: requestHeaders(options),
-        body: "{}",
-    });
-    if (!response.ok) {
-        throw new Error(`cli-bridge cancel ${response.status}: ${await response.text()}`);
+        body: JSON.stringify(exactRequest),
+        signal,
+    }), signal);
+    const responseText = await waitForOperation(readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal), signal);
+    const acknowledgement = parseExactCancellationAcknowledgement(exactRequest, response.status, responseText);
+    if (acknowledgement.status === "conflict" ||
+        acknowledgement.status === "unknown" ||
+        acknowledgement.effect === "unknown") {
+        throw new Error(`cli-bridge did not prove cancellation for run "${run.id}": ${acknowledgement.status}`);
     }
-    let snapshot = cancelSnapshot(await response.text());
-    assertCliBridgeRunSnapshotIdentity(snapshot, run.id, run.requestDigest);
-    const waitBudgetMs = options.cancelWaitMs ?? 30_000;
-    const deadline = Date.now() + waitBudgetMs;
-    while (!snapshot.terminal) {
+    if (acknowledgement.effect === "cancelled") {
+        snapshot = exactTerminalCancellationSnapshot(run, "cancelled");
+    }
+    else if (acknowledgement.effect === "not_live") {
+        snapshot = exactTerminalCancellationSnapshot(run, "unknown");
+    }
+    while (snapshot === null || !snapshot.terminal) {
         const remainingMs = deadline - Date.now();
         if (remainingMs <= 0)
             break;
-        snapshot = await getCliBridgeRun(options, transport, run, Math.min(remainingMs, 30_000));
+        snapshot = await getCliBridgeRun(options, transport, run, Math.min(remainingMs, 30_000), signal);
         if (snapshot === null) {
             throw new Error(`cli-bridge lost run "${run.id}" before confirming cancellation`);
         }
@@ -77,6 +129,32 @@ async function performCliBridgeCancellation(options, transport, run) {
     }
     return snapshot;
 }
+function exactTerminalCancellationSnapshot(run, status) {
+    if (run.controlRef === undefined) {
+        throw new Error("cli-bridge exact cancellation lost its bound run identity");
+    }
+    return {
+        id: run.id,
+        requestDigest: run.controlRef.requestDigest,
+        controlRef: run.controlRef,
+        status,
+        terminal: true,
+    };
+}
+function automaticCancellationRequest(run) {
+    if (run.controlRef === undefined) {
+        throw new Error(`cli-bridge cannot safely cancel run "${run.id}" without complete exact coordinates`);
+    }
+    const material = {
+        operationId: `cancel-${run.controlRef.requestDigest.slice("sha256:".length)}`,
+        run: run.controlRef,
+        reason: "provider cleanup",
+    };
+    return AgentRunCancellationRequestSchema.parse({
+        ...material,
+        requestDigest: agentRunCancellationRequestDigest(material),
+    });
+}
 function clearCancellation(run, cancellation) {
     if (run.cancellation === cancellation)
         run.cancellation = undefined;
@@ -84,7 +162,10 @@ function clearCancellation(run, cancellation) {
 function waitForOperation(operation, signal) {
     if (!signal)
         return operation;
-    signal.throwIfAborted();
+    if (signal.aborted) {
+        void operation.catch(() => { });
+        return Promise.reject(signal.reason);
+    }
     return new Promise((resolve, reject) => {
         const abort = () => reject(signal.reason);
         signal.addEventListener("abort", abort, { once: true });
@@ -102,15 +183,22 @@ export async function cancelExactCliBridgeRun(options, transport, run, request,
     if (!run.controlRef || !sameControlRef(run.controlRef, exactRequest.run)) {
         throw new Error("cli-bridge cancellation targets another retained run");
     }
-    const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(run.id)}/cancel`, {
+    const timeoutSignal = cliBridgeCancellationSignal(options);
+    const operationSignal = signal === undefined
+        ? timeoutSignal
+        : AbortSignal.any([signal, timeoutSignal]);
+    const response = await waitForOperation(transport.fetch(`${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(run.id)}/cancel`, {
         method: "POST",
         headers: requestHeaders(options),
         body: JSON.stringify(exactRequest),
-        ...(signal ? { signal } : {}),
-    });
-    const responseText = await response.text();
-    if (!response.ok && response.status !== 409) {
-        throw new Error(`cli-bridge cancel ${response.status}: ${responseText}`);
+        signal: operationSignal,
+    }), operationSignal);
+    const responseText = await waitForOperation(readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, operationSignal), operationSignal);
+    return parseExactCancellationAcknowledgement(exactRequest, response.status, responseText);
+}
+function parseExactCancellationAcknowledgement(request, status, responseText) {
+    if ((status < 200 || status >= 300) && status !== 409) {
+        throw new Error(`cli-bridge cancel ${status}: ${responseText}`);
     }
     let acknowledgement;
     try {
@@ -121,7 +209,7 @@ export async function cancelExactCliBridgeRun(options, transport, run, request,
             cause: error,
         });
     }
-    if (!agentRunCancellationAcknowledgementMatchesRequest(exactRequest, acknowledgement)) {
+    if (!agentRunCancellationAcknowledgementMatchesRequest(request, acknowledgement)) {
         throw new Error("cli-bridge returned a cancellation acknowledgement for another request");
     }
     return acknowledgement;
@@ -136,27 +224,62 @@ function sameControlRef(left, right) {
 }
 export async function getCliBridgeRun(options, transport, run, waitMs, signal) {
     const query = waitMs === undefined ? "" : `?wait_ms=${waitMs}`;
-    const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(run.id)}${query}`, {
+    const response = await waitForOperation(transport.fetch(`${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(run.id)}${query}`, {
         method: "GET",
         headers: requestHeaders(options),
         ...(signal ? { signal } : {}),
-    });
+    }), signal);
+    const responseText = await waitForOperation(readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal), signal);
     if (response.status === 404)
         return null;
     if (!response.ok) {
-        throw new Error(`cli-bridge run status ${response.status}: ${await response.text()}`);
+        throw new Error(`cli-bridge run status ${response.status}: ${responseText}`);
     }
-    const snapshot = runSnapshot(await response.text());
-    assertCliBridgeRunSnapshotIdentity(snapshot, run.id, run.requestDigest);
+    const snapshot = runSnapshot(responseText);
+    bindCliBridgeRunSnapshot(run, snapshot);
     return snapshot;
 }
-function assertCliBridgeRunSnapshotIdentity(snapshot, expectedRunId, expectedRequestDigest) {
-    if (snapshot.id !== expectedRunId) {
-        throw new Error(`cli-bridge returned run "${snapshot.id}" for requested run "${expectedRunId}"`);
+function bindCliBridgeRunSnapshot(run, snapshot) {
+    if (snapshot.controlRef === undefined) {
+        throw new Error("cli-bridge run status omitted exact run coordinates");
+    }
+    bindExactControlRef(run, snapshot.controlRef);
+}
+function bindExactControlRef(run, controlRef) {
+    if (controlRef.runId !== run.id ||
+        controlRef.provider !== run.provider ||
+        controlRef.environmentId !== run.environmentId ||
+        controlRef.sessionId !== run.sessionId ||
+        controlRef.executionId !== run.executionId ||
+        (run.requestDigest !== undefined && controlRef.requestDigest !== run.requestDigest)) {
+        throw new Error("cli-bridge returned another retained run identity");
+    }
+    run.requestDigest = controlRef.requestDigest;
+    run.controlRef = Object.freeze(controlRef);
+}
+/** Recover one exact Bridge run after dispatch succeeded but local admission did not. */
+export async function lookupExactCliBridgeRun(options, providerName, input) {
+    const runId = assertCliBridgeRunId(AgentExactRunControlRefSchema.shape.runId.parse(input.runId));
+    const environmentId = AgentExactRunControlRefSchema.shape.environmentId.parse(input.environmentId);
+    const sessionId = AgentExactRunControlRefSchema.shape.sessionId.parse(input.sessionId);
+    const executionId = AgentExactRunControlRefSchema.shape.executionId.parse(input.executionId);
+    const transport = createCliBridgeTransport(options);
+    const run = {
+        id: runId,
+        provider: providerName,
+        environmentId,
+        sessionId,
+        executionId,
+        turnId: executionId,
+        requestBody: "",
+        readers: new Set(),
+    };
+    try {
+        const snapshot = await getCliBridgeRun(options, transport, run, undefined, input.signal);
+        return snapshot?.controlRef ?? null;
     }
-    if (expectedRequestDigest !== undefined &&
-        snapshot.requestDigest !== expectedRequestDigest) {
-        throw new Error(`cli-bridge returned request digest "${snapshot.requestDigest}" for run "${expectedRunId}"`);
+    finally {
+        await transport.close();
     }
 }
 export function agentSessionStatusFromRun(snapshot) {

package/dist/retained-environment.js

@@ -2,7 +2,7 @@ import { agentSessionStatusFromRun, cancelCliBridgeRun, cancelExactCliBridgeRun,
 import { addTokenUsage, collectCliBridgeTurnResult, dispatchCliBridgeTurn, streamCliBridgeSessionEvents, streamTrackedCliBridgeTurn, } from "./retained-execution.js";
 import { createExecutionUsageLog, observeCliBridgeEnvironment, } from "./observation.js";
 import { cliBridgeInteractionResponder } from "./interaction-response.js";
-import { assertCliBridgeRequestedInteractions, assertCliBridgeNativeTurnModel, continueCliBridgeNative, readCliBridgeNativeContextBoundary, supportsCliBridgeNativeContinuation, supportsCliBridgeNativeInteractions, } from "./retained-native.js";
+import { assertCliBridgeRequestedInteractions, assertCliBridgeTurnModel, continueCliBridgeNative, readCliBridgeNativeContextBoundary, supportsCliBridgeNativeContinuation, supportsCliBridgeNativeInteractions, } from "./retained-native.js";
 import { assertRunMatchesControlRef, exactControlRefForSession, prepareCliBridgeRun, runFromControlRef, } from "./retained-run-state.js";
 import { createCliBridgeTransport } from "./transport.js";
 export function createCliBridgeEnvironment(args) {
@@ -30,11 +30,12 @@ export function createCliBridgeEnvironment(args) {
         if (!args.allowDispatch) {
             throw new Error("a reconstructed cli-bridge environment can only control an existing run");
         }
-        if (useNativeInteractions) {
-            assertCliBridgeNativeTurnModel(options, environmentInput, turn, args.selectedModel);
+        if (args.selectedModel !== undefined &&
+            args.capabilities.retainedControl !== undefined) {
+            assertCliBridgeTurnModel(options, environmentInput, turn, args.selectedModel);
         }
         assertCliBridgeRequestedInteractions(args.capabilities, turn.interactions);
-        const prepared = prepareCliBridgeRun(options, environmentInput, turn, environmentId, useNativeInteractions);
+        const prepared = prepareCliBridgeRun(options, environmentInput, turn, providerName, environmentId, useNativeInteractions);
         // A streamed run reports usage across its events, so the totals are summed
         // here and recorded as one execution's measurement.
         let streamedUsage;
@@ -60,11 +61,12 @@ export function createCliBridgeEnvironment(args) {
             if (!args.allowDispatch) {
                 throw new Error("a reconstructed cli-bridge environment cannot dispatch new work");
             }
-            if (useNativeInteractions) {
-                assertCliBridgeNativeTurnModel(options, environmentInput, turn, args.selectedModel);
+            if (args.selectedModel !== undefined &&
+                args.capabilities.retainedControl !== undefined) {
+                assertCliBridgeTurnModel(options, environmentInput, turn, args.selectedModel);
             }
             assertCliBridgeRequestedInteractions(args.capabilities, turn.interactions);
-            const prepared = prepareCliBridgeRun(options, environmentInput, turn, environmentId, true);
+            const prepared = prepareCliBridgeRun(options, environmentInput, turn, providerName, environmentId, useNativeInteractions);
             return dispatchCliBridgeTurn(options, environmentInput, prepared, transport, providerName, runs, sessions, nativeSessions, useNativeInteractions);
         },
         session(id, sessionOptions) {
@@ -233,14 +235,15 @@ function createCliBridgeSession(args) {
             if (input.sessionId && input.sessionId !== args.id) {
                 throw new Error(`cli-bridge session "${args.id}" cannot prompt session "${input.sessionId}"`);
             }
-            if (args.useNativeInteractions) {
-                assertCliBridgeNativeTurnModel(args.options, args.environmentInput, input, args.selectedModel);
+            if (args.selectedModel !== undefined &&
+                args.capabilities.retainedControl !== undefined) {
+                assertCliBridgeTurnModel(args.options, args.environmentInput, input, args.selectedModel);
             }
             assertCliBridgeRequestedInteractions(args.capabilities, input.interactions);
             const prepared = prepareCliBridgeRun(args.options, args.environmentInput, {
                 ...input,
                 sessionId: args.id,
-            }, args.environmentId, args.useNativeInteractions);
+            }, args.providerName, args.environmentId, args.useNativeInteractions);
             const result = await collectCliBridgeTurnResult(streamTrackedCliBridgeTurn(args.options, args.environmentInput, args.providerName, prepared, args.transport, args.runs, args.sessions, args.readers, args.nativeSessions, args.useNativeInteractions), prepared.run, args.options, args.transport, input.signal);
             args.usageLog.record(prepared.run.executionId, result.usage);
             return { ...result, sessionId: args.id };

package/dist/retained-execution.js

@@ -1,8 +1,8 @@
-import { cancelCliBridgeRun, captureCliBridgeRunIdentity, detachCliBridgeReader, getCliBridgeRun, } from "./retained-control.js";
+import { cancelCliBridgeRun, captureCliBridgeRunIdentity, cliBridgeCancellationSignal, detachCliBridgeReader, getCliBridgeRun, } from "./retained-control.js";
 import { bindCliBridgeRun, bindCliBridgeSession, exactControlRefForRun, restoreCliBridgeRun, restoreCliBridgeSession, } from "./retained-run-state.js";
 import { CliBridgeRequestRejectedError, streamCliBridgeTurn, } from "./retained-stream.js";
 import { beginCliBridgeNativeTurn, } from "./retained-native.js";
-import { requestHeaders, trimSlash } from "./transport.js";
+import { MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
 import { modelRequestCount } from "./wire.js";
 export async function* streamTrackedCliBridgeTurn(options, environmentInput, providerName, prepared, transport, runs, sessions, readers, nativeSessions, useNativeInteractions) {
     const originalTurn = prepared.turn;
@@ -43,7 +43,7 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pro
             for await (const event of streamCliBridgeTurn(options, turn, run.requestBody, transport, run.id, originalTurn.lastEventId, signal, (response) => {
                 admitted = true;
                 captureCliBridgeRunIdentity(response, run, true);
-                admissionValidated = true;
+                admissionValidated = response.body !== null;
             }, () => getCliBridgeRun(options, transport, run, 30_000, signal))) {
                 yield event;
             }
@@ -61,7 +61,7 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pro
         }
         let snapshot;
         try {
-            snapshot = await getCliBridgeRun(options, transport, run);
+            snapshot = await getCliBridgeRun(options, transport, run, undefined, cliBridgeCancellationSignal(options));
         }
         catch {
             snapshot = undefined;
@@ -73,12 +73,17 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pro
         else if ((admitted && !admissionValidated) ||
             originalTurn.signal?.aborted ||
             environmentInput.signal?.aborted) {
-            const cancellation = await cancelCliBridgeRun(options, transport, run);
-            if (cancellation.requestDigest !== undefined) {
-                run.requestDigest = cancellation.requestDigest;
+            try {
+                const cancellation = await cancelCliBridgeRun(options, transport, run);
+                if (cancellation.requestDigest !== undefined) {
+                    run.requestDigest = cancellation.requestDigest;
+                }
+                if (runs.get(run.id) === run)
+                    runs.delete(run.id);
+            }
+            catch (cleanupError) {
+                throw new AggregateError([error, cleanupError], `cli-bridge stream "${run.id}" failed and exact cancellation was not confirmed`);
             }
-            if (runs.get(run.id) === run)
-                runs.delete(run.id);
         }
         throw error;
     }
@@ -122,7 +127,7 @@ export async function dispatchCliBridgeTurn(options, environmentInput, prepared,
             if (!response.ok) {
                 let detail = "request rejected";
                 try {
-                    detail = await response.text();
+                    detail = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
                 }
                 catch {
                     // The HTTP status already proves this request was rejected.

package/dist/retained-native.d.ts

@@ -17,7 +17,7 @@ export declare function supportsCliBridgeNativeContinuation(capabilities: AgentE
 /** Reject posture the selected environment did not advertise before transport use. */
 export declare function assertCliBridgeRequestedInteractions(capabilities: AgentEnvironmentCapabilities, requested: RequestedInteractions | undefined): void;
 /** Keep capability discovery and every native turn on one exact model route. */
-export declare function assertCliBridgeNativeTurnModel(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, turn: AgentTurnInput, selectedModel: string | undefined): void;
+export declare function assertCliBridgeTurnModel(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, turn: AgentTurnInput, selectedModel: string | undefined): void;
 /** Read the Bridge-owned exact boundary for the current retained run. */
 export declare function readCliBridgeNativeContextBoundary(options: CliBridgeProviderOptions, providerName: string, transport: CliBridgeTransport, run: CliBridgeRun, signal?: AbortSignal): Promise<NativeContextBoundaryProof | null>;
 /** Send one canonical same-session continuation and advance the live run identity. */

package/dist/retained-native.js

@@ -1,7 +1,7 @@
 import { AgentNativeContextContinuationResultSchema, AgentExactRunControlRefSchema, NativeContextBoundaryProofSchema, NativeContextContinuationRequestSchema, RequestedInteractionsSchema, agentNativeContextContinuationResultMatchesRequest, canonicalCandidateDigest, nativeContextContinuationTurnDigest, } from "@tangle-network/agent-interface";
 import { CliBridgeRequestRejectedError } from "./retained-stream.js";
 import { advanceCliBridgeRun, exactControlRefForRun, } from "./retained-run-state.js";
-import { requestHeaders, trimSlash, } from "./transport.js";
+import { MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
 import { inlineProfile, safeJson, resolveBridgeModel, toRetainedSessionBody, toRetainedTurnBody, } from "./wire.js";
 const MAX_NATIVE_CONTINUATION_RESPONSE_BYTES = 1_048_576;
 /** Interactions are valid only for the native retained Pi contract. */
@@ -38,13 +38,13 @@ export function assertCliBridgeRequestedInteractions(capabilities, requested) {
     }
 }
 /** Keep capability discovery and every native turn on one exact model route. */
-export function assertCliBridgeNativeTurnModel(options, environmentInput, turn, selectedModel) {
+export function assertCliBridgeTurnModel(options, environmentInput, turn, selectedModel) {
     if (selectedModel === undefined) {
-        throw new Error("cli-bridge native interactions require an environment model");
+        throw new Error("cli-bridge retained execution requires an environment model");
     }
     const requestedModel = resolveBridgeModel(options, environmentInput, turn, inlineProfile(environmentInput.profile));
     if (requestedModel !== selectedModel) {
-        throw new Error(`cli-bridge native environment model is ${JSON.stringify(selectedModel)}; create another environment for ${JSON.stringify(requestedModel)}`);
+        throw new Error(`cli-bridge environment model is ${JSON.stringify(selectedModel)}; create another environment for ${JSON.stringify(requestedModel)}`);
     }
 }
 function piInteractionCapabilitiesMatch(interactions) {
@@ -65,7 +65,7 @@ export async function readCliBridgeNativeContextBoundary(options, providerName,
         headers: requestHeaders(options),
         ...(signal ? { signal } : {}),
     });
-    const responseText = await readBoundedResponseText(response, signal);
+    const responseText = await readBoundedCliBridgeResponse(response, MAX_NATIVE_CONTINUATION_RESPONSE_BYTES, signal);
     if (!response.ok) {
         throw new CliBridgeRequestRejectedError(response.status, responseText);
     }
@@ -107,7 +107,7 @@ export async function continueCliBridgeNative(options, providerName, transport,
             body: JSON.stringify({ request: exactRequest, turn: continuationOptions.turn }),
             ...(operation.signal ? { signal: operation.signal } : {}),
         });
-        const responseText = await readBoundedResponseText(response, operation.signal);
+        const responseText = await readBoundedCliBridgeResponse(response, MAX_NATIVE_CONTINUATION_RESPONSE_BYTES, operation.signal);
         const outcome = parseNativeContinuationResult(responseText);
         assertContinuationAcknowledgementBinding(exactRequest, outcome);
         if (outcome.acknowledgement.status === "accepted" ||
@@ -202,49 +202,6 @@ function continuationSignal(options) {
         dispose: () => clearTimeout(timer),
     };
 }
-async function readBoundedResponseText(response, signal) {
-    const contentLength = response.headers.get("content-length");
-    if (contentLength !== null) {
-        const parsedLength = Number(contentLength);
-        if (Number.isSafeInteger(parsedLength) &&
-            parsedLength > MAX_NATIVE_CONTINUATION_RESPONSE_BYTES) {
-            throw new Error("cli-bridge native continuation response exceeds its byte limit");
-        }
-    }
-    if (response.body === null) {
-        signal?.throwIfAborted();
-        const text = await response.text();
-        if (new TextEncoder().encode(text).byteLength > MAX_NATIVE_CONTINUATION_RESPONSE_BYTES) {
-            throw new Error("cli-bridge native continuation response exceeds its byte limit");
-        }
-        return text;
-    }
-    const iterator = response.body[Symbol.asyncIterator]();
-    const decoder = new TextDecoder();
-    let bytes = 0;
-    let text = "";
-    let complete = false;
-    try {
-        while (true) {
-            signal?.throwIfAborted();
-            const next = await iterator.next();
-            if (next.done)
-                break;
-            bytes += next.value.byteLength;
-            if (bytes > MAX_NATIVE_CONTINUATION_RESPONSE_BYTES) {
-                throw new Error("cli-bridge native continuation response exceeds its byte limit");
-            }
-            text += decoder.decode(next.value, { stream: true });
-        }
-        complete = true;
-        return text + decoder.decode();
-    }
-    finally {
-        if (!complete) {
-            await iterator.return?.();
-        }
-    }
-}
 /**
  * Create or reuse the server's retained native session for one external id.
  *
@@ -288,21 +245,21 @@ async function createCliBridgeNativeSession(options, environmentInput, profile,
         return recoverConflictingNativeSession(options, sessionId, model, createRequestDigest, transport, signal, response);
     }
     if (!response.ok) {
-        throw new CliBridgeRequestRejectedError(response.status, await response.text());
+        throw new CliBridgeRequestRejectedError(response.status, await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal));
     }
-    return parseNativeSessionView(await response.text(), sessionId, model, createRequestDigest);
+    return parseNativeSessionView(await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal), sessionId, model, createRequestDigest);
 }
 async function recoverConflictingNativeSession(options, sessionId, model, createRequestDigest, transport, signal, conflictResponse) {
-    await conflictResponse.text();
+    await readBoundedCliBridgeResponse(conflictResponse, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
     const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/sessions/${encodeURIComponent(sessionId)}`, {
         method: "GET",
         headers: requestHeaders(options),
         ...(signal ? { signal } : {}),
     });
     if (!response.ok) {
-        throw new CliBridgeRequestRejectedError(response.status, `session ${JSON.stringify(sessionId)} could not be recovered: ${await response.text()}`);
+        throw new CliBridgeRequestRejectedError(response.status, `session ${JSON.stringify(sessionId)} could not be recovered: ${await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal)}`);
     }
-    return parseNativeSessionView(await response.text(), sessionId, model, createRequestDigest);
+    return parseNativeSessionView(await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal), sessionId, model, createRequestDigest);
 }
 function parseNativeSessionView(value, expectedId, expectedModel, expectedCreateRequestDigest) {
     const parsed = safeJson(value);
@@ -349,10 +306,10 @@ export async function beginCliBridgeNativeTurn(options, providerName, environmen
         ...(signal ? { signal } : {}),
     });
     if (!response.ok) {
-        throw new CliBridgeRequestRejectedError(response.status, await response.text());
+        throw new CliBridgeRequestRejectedError(response.status, await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal));
     }
     onAdmission?.();
-    const parsed = safeJson(await response.text());
+    const parsed = safeJson(await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal));
     const responseSession = parsed?.session;
     const responseRun = parsed?.run;
     const responseSessionId = responseSession && typeof responseSession === "object"
@@ -374,6 +331,12 @@ export async function beginCliBridgeNativeTurn(options, providerName, environmen
     const executionId = responseRun && typeof responseRun === "object"
         ? responseRun.executionId
         : undefined;
+    const responseProvider = responseRun && typeof responseRun === "object"
+        ? responseRun.provider
+        : undefined;
+    const responseEnvironmentId = responseRun && typeof responseRun === "object"
+        ? responseRun.environmentId
+        : undefined;
     const requestDigestValue = responseRun && typeof responseRun === "object"
         ? responseRun.requestDigest
         : undefined;
@@ -390,6 +353,8 @@ export async function beginCliBridgeNativeTurn(options, providerName, environmen
         responseSessionIdFromRun !== run.sessionId ||
         typeof executionId !== "string" ||
         executionId !== run.executionId ||
+        responseProvider !== providerName ||
+        responseEnvironmentId !== run.environmentId ||
         !requestDigest.success) {
         throw new Error("cli-bridge retained turn returned mismatched run coordinates");
     }
@@ -397,4 +362,5 @@ export async function beginCliBridgeNativeTurn(options, providerName, environmen
         throw new Error("cli-bridge retained turn changed the admitted request digest");
     }
     run.requestDigest = requestDigest.data;
+    run.controlRef = exactControlRefForRun(run, providerName);
 }

package/dist/retained-run-state.d.ts

@@ -3,6 +3,7 @@ import type { AgentTurnInput, CreateAgentEnvironmentInput } from "@tangle-networ
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 export interface CliBridgeRun {
     id: string;
+    readonly provider: string;
     readonly environmentId: string;
     readonly sessionId?: string;
     executionId: string;
@@ -20,6 +21,7 @@ export interface CliBridgeSessionState {
 export interface CliBridgeRunSnapshot {
     readonly id: string;
     readonly requestDigest?: Sha256Digest;
+    readonly controlRef?: AgentExactRunControlRef;
     readonly status: "running" | "done" | "error" | "cancelled" | "unknown";
     readonly terminal: boolean;
 }
@@ -33,7 +35,7 @@ export declare function runFromControlRef(controlRef: AgentExactRunControlRef):
 export declare function assertRunMatchesControlRef(run: CliBridgeRun, controlRef: AgentExactRunControlRef): void;
 /** Advance one session object to the exact run returned by native continuation. */
 export declare function advanceCliBridgeRun(run: CliBridgeRun, controlRef: AgentExactRunControlRef, providerName: string, runs: Map<string, CliBridgeRun>): void;
-export declare function prepareCliBridgeRun(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, originalTurn: AgentTurnInput, environmentId: string, requireSession: boolean): PreparedCliBridgeRun;
+export declare function prepareCliBridgeRun(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, originalTurn: AgentTurnInput, providerName: string, environmentId: string, requireStableIdentity?: boolean): PreparedCliBridgeRun;
 export declare function bindCliBridgeRun(prepared: CliBridgeRun, runs: Map<string, CliBridgeRun>): CliBridgeRun | undefined;
 export declare function restoreCliBridgeRun(run: CliBridgeRun, previous: CliBridgeRun | undefined, runs: Map<string, CliBridgeRun>): void;
 export declare function bindCliBridgeSession(run: CliBridgeRun, sessions: Map<string, CliBridgeSessionState>): CliBridgeRun | undefined;

package/dist/retained-run-state.js

@@ -1,5 +1,5 @@
-import { AgentExactRunControlRefSchema, } from "@tangle-network/agent-interface";
-import { cliBridgeRunId, toChatCompletionsBody } from "./wire.js";
+import { AgentExactRunControlRefSchema, AgentTurnInputSchema, } from "@tangle-network/agent-interface";
+import { assertCliBridgeRunId, cliBridgeRunId, toChatCompletionsBody, } from "./wire.js";
 export function exactControlRefForRun(run, providerName) {
     if (!run.sessionId || !run.requestDigest) {
         throw new Error("cli-bridge did not return complete retained run coordinates");
@@ -15,6 +15,7 @@ export function exactControlRefForRun(run, providerName) {
 }
 export function exactControlRefForSession(value, providerName, environmentId, sessionId) {
     const controlRef = Object.freeze(AgentExactRunControlRefSchema.parse(value));
+    assertCliBridgeRunId(controlRef.runId);
     if (controlRef.provider !== providerName ||
         controlRef.environmentId !== environmentId ||
         controlRef.sessionId !== sessionId) {
@@ -25,6 +26,7 @@ export function exactControlRefForSession(value, providerName, environmentId, se
 export function runFromControlRef(controlRef) {
     return {
         id: controlRef.runId,
+        provider: controlRef.provider,
         environmentId: controlRef.environmentId,
         sessionId: controlRef.sessionId,
         executionId: controlRef.executionId,
@@ -37,6 +39,7 @@ export function runFromControlRef(controlRef) {
 }
 export function assertRunMatchesControlRef(run, controlRef) {
     if (run.id !== controlRef.runId ||
+        run.provider !== controlRef.provider ||
         run.environmentId !== controlRef.environmentId ||
         run.sessionId !== controlRef.sessionId ||
         run.executionId !== controlRef.executionId ||
@@ -67,28 +70,38 @@ export function advanceCliBridgeRun(run, controlRef, providerName, runs) {
     run.controlRef = Object.freeze(AgentExactRunControlRefSchema.parse(controlRef));
     runs.set(run.id, run);
 }
-export function prepareCliBridgeRun(options, environmentInput, originalTurn, environmentId, requireSession) {
-    if (requireSession &&
-        (originalTurn.turnId === undefined || originalTurn.executionId === undefined)) {
-        throw new Error("cli-bridge native retained turns require stable turnId and executionId values");
+export function prepareCliBridgeRun(options, environmentInput, originalTurn, providerName, environmentId, requireStableIdentity = false) {
+    const validatedTurn = AgentTurnInputSchema.parse(originalTurn);
+    if (requireStableIdentity &&
+        (validatedTurn.turnId === undefined || validatedTurn.executionId === undefined)) {
+        throw new Error("native cli-bridge turns require stable turnId and executionId");
     }
-    const turnId = originalTurn.turnId ?? crypto.randomUUID();
-    const runId = cliBridgeRunId(environmentId, originalTurn, turnId);
-    const sessionId = originalTurn.sessionId ?? (requireSession ? runId : undefined);
+    const turnId = validatedTurn.turnId ?? crypto.randomUUID();
+    const runId = cliBridgeRunId(environmentId, validatedTurn, turnId);
+    const sessionId = validatedTurn.sessionId ?? runId;
+    const executionId = validatedTurn.executionId ?? runId;
     const turn = {
-        ...originalTurn,
+        ...validatedTurn,
         turnId,
-        ...(sessionId ? { sessionId } : {}),
+        sessionId,
+        executionId,
     };
     return {
         turn,
         run: {
             id: runId,
+            provider: providerName,
             environmentId,
-            ...(sessionId ? { sessionId } : {}),
-            executionId: originalTurn.executionId ?? runId,
+            sessionId,
+            executionId,
             turnId,
-            requestBody: JSON.stringify(toChatCompletionsBody(options, environmentInput, turn, runId)),
+            requestBody: JSON.stringify(toChatCompletionsBody(options, environmentInput, turn, {
+                runId,
+                provider: providerName,
+                environmentId,
+                sessionId,
+                executionId,
+            })),
             readers: new Set(),
         },
     };

package/dist/retained-stream.js

@@ -1,7 +1,7 @@
 import { retainedEventsWithIdentity, retainedReplayRequest, } from "./retained-event-cursor.js";
 import { isTerminalCanonicalEvent, retainedCanonicalEvent, } from "./retained-canonical-event.js";
 import { detachCliBridgeReader } from "./retained-control.js";
-import { requestHeaders, trimSlash } from "./transport.js";
+import { MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, MAX_CLI_BRIDGE_RESULT_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
 import { modelRequestsFromOpenAi, parseSse, responseIdentityFromOpenAi, safeJson, toolCallsFromDelta, usageFromOpenAi, } from "./wire.js";
 export class CliBridgeRequestRejectedError extends Error {
     status;
@@ -40,27 +40,29 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
     if (!response.ok) {
         let detail = "request rejected";
         try {
-            detail = await response.text();
+            detail = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
         }
         catch {
             // The HTTP status already proves this request was rejected.
         }
         throw new CliBridgeRequestRejectedError(response.status, detail);
     }
-    if (!response.body)
-        throw new Error("cli-bridge response body is empty");
     try {
         onResponse?.(response);
     }
     catch (error) {
-        try {
-            await detachCliBridgeReader(response.body);
-        }
-        catch (detachError) {
-            throw new AggregateError([error, detachError], `cli-bridge rejected response identity for run "${runId}" and could not detach its reader`);
+        if (response.body) {
+            try {
+                await detachCliBridgeReader(response.body);
+            }
+            catch (detachError) {
+                throw new AggregateError([error, detachError], `cli-bridge rejected response identity for run "${runId}" and could not detach its reader`);
+            }
         }
         throw error;
     }
+    if (!response.body)
+        throw new Error("cli-bridge response body is empty");
     let text = "";
     const sessionId = turn.sessionId ?? runId;
     const messageId = turn.turnId ?? `${sessionId}:assistant`;
@@ -439,7 +441,7 @@ async function readFullCliBridgeResult(options, requestBody, transport, signal,
         body: JSON.stringify({ ...body, stream: false }),
         ...(signal ? { signal } : {}),
     });
-    const responseText = await response.text();
+    const responseText = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_RESULT_RESPONSE_BYTES, signal);
     onResponse?.(response);
     if (!response.ok) {
         const error = cliBridgeError(safeJson(responseText));

package/dist/transport.d.ts

@@ -1,4 +1,6 @@
 import type { CliBridgeProviderOptions } from "./provider-options.js";
+export declare const MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES: number;
+export declare const MAX_CLI_BRIDGE_RESULT_RESPONSE_BYTES: number;
 export interface CliBridgeTransport {
     fetch(input: string, init: CliBridgeRequest): Promise<CliBridgeResponse>;
     close(): Promise<void>;
@@ -21,3 +23,4 @@ export interface CliBridgeResponse {
 export declare function createCliBridgeTransport(options: CliBridgeProviderOptions): CliBridgeTransport;
 export declare function requestHeaders(options: CliBridgeProviderOptions): Record<string, string>;
 export declare function trimSlash(value: string): string;
+export declare function readBoundedCliBridgeResponse(response: CliBridgeResponse, maxBytes: number, signal?: AbortSignal): Promise<string>;

package/dist/transport.js

@@ -1,4 +1,6 @@
 import { Agent, fetch as undiciFetch } from "undici";
+export const MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES = 64 * 1024;
+export const MAX_CLI_BRIDGE_RESULT_RESPONSE_BYTES = 16 * 1024 * 1024;
 export function createCliBridgeTransport(options) {
     if (options.fetch) {
         const fetch = options.fetch;
@@ -30,3 +32,81 @@ export function requestHeaders(options) {
 export function trimSlash(value) {
     return value.replace(/\/+$/, "");
 }
+export async function readBoundedCliBridgeResponse(response, maxBytes, signal) {
+    signal?.throwIfAborted();
+    if (response.body === null)
+        return "";
+    const iterator = response.body[Symbol.asyncIterator]();
+    const decoder = new TextDecoder();
+    const chunks = [];
+    let bytes = 0;
+    let closePromise;
+    const close = () => {
+        if (closePromise === undefined) {
+            closePromise = (async () => {
+                await iterator.return?.();
+            })();
+        }
+        return closePromise;
+    };
+    try {
+        while (true) {
+            const next = await nextCliBridgeResponseChunk(iterator, signal, close);
+            if (next.done)
+                break;
+            bytes += next.value.byteLength;
+            if (bytes > maxBytes) {
+                throw new Error(`cli-bridge response exceeded ${maxBytes} bytes`);
+            }
+            chunks.push(decoder.decode(next.value, { stream: true }));
+        }
+        chunks.push(decoder.decode());
+        return chunks.join("");
+    }
+    finally {
+        if (signal?.aborted) {
+            void close().catch(() => { });
+        }
+        else {
+            await close();
+        }
+    }
+}
+function nextCliBridgeResponseChunk(iterator, signal, close) {
+    if (signal === undefined)
+        return iterator.next();
+    if (signal.aborted) {
+        void close().catch(() => { });
+        return Promise.reject(signal.reason);
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbort);
+            callback();
+        };
+        const onAbort = () => {
+            finish(() => reject(signal.reason));
+            void close().catch(() => { });
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        let next;
+        try {
+            next = Promise.resolve(iterator.next());
+        }
+        catch (error) {
+            finish(() => reject(error));
+            return;
+        }
+        if (settled)
+            return;
+        void next.then((result) => finish(() => resolve(result)), (error) => finish(() => reject(error)));
+    });
+}

package/dist/wire.d.ts

@@ -2,7 +2,13 @@ import type { AgentProfile, AgentProfileRef, TokenUsage } from "@tangle-network/
 import type { AgentTurnInput, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 import type { CliBridgeRun, CliBridgeRunSnapshot } from "./retained-run-state.js";
-export declare function toChatCompletionsBody(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, turn: AgentTurnInput, runId: string): Record<string, unknown>;
+export declare function toChatCompletionsBody(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, turn: AgentTurnInput, coordinates: {
+    readonly runId: string;
+    readonly provider: string;
+    readonly environmentId: string;
+    readonly sessionId: string;
+    readonly executionId: string;
+}): Record<string, unknown>;
 export declare function resolveBridgeModel(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, turn: AgentTurnInput, profile: AgentProfile | undefined): string;
 export declare function toRetainedSessionBody(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, profile: AgentProfile | undefined, sessionId: string, model: string): Record<string, unknown>;
 /** Encode the exact retained turn contract without moving posture into metadata. */
@@ -29,5 +35,6 @@ export declare function responseIdentityFromOpenAi(value: unknown): {
 } | undefined;
 export declare function modelRequestCount(value: unknown): number | undefined;
 export declare function cliBridgeRunId(environmentId: string, turn: AgentTurnInput, turnId: string): string;
+export declare function assertCliBridgeRunId(value: string): string;
 export declare function runSnapshot(value: string): CliBridgeRunSnapshot;
 export declare function cancelSnapshot(value: string): CliBridgeRunSnapshot;

package/dist/wire.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { AgentExactRunControlRefSchema, RequestedInteractionsSchema, } from "@tangle-network/agent-interface";
-export function toChatCompletionsBody(options, environmentInput, turn, runId) {
+export function toChatCompletionsBody(options, environmentInput, turn, coordinates) {
     const profile = inlineProfile(environmentInput.profile);
     const execution = executionFromInput(options, environmentInput);
     const interactions = turn.interactions === undefined
@@ -10,8 +10,11 @@ export function toChatCompletionsBody(options, environmentInput, turn, runId) {
         model: resolveBridgeModel(options, environmentInput, turn, profile),
         messages: messagesFromTurn(turn),
         stream: true,
-        ...(turn.sessionId ? { session_id: turn.sessionId } : {}),
-        run_id: runId,
+        session_id: coordinates.sessionId,
+        run_id: coordinates.runId,
+        provider: coordinates.provider,
+        environment_id: coordinates.environmentId,
+        execution_id: coordinates.executionId,
         ...(options.defaultMode ? { mode: options.defaultMode } : {}),
         ...(profile ? { agent_profile: profile } : {}),
         ...(profile?.model?.reasoningEffort
@@ -304,20 +307,34 @@ function nonEmptyString(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 export function cliBridgeRunId(environmentId, turn, turnId) {
-    if (turn.executionId &&
-        turn.executionId.length <= 128 &&
-        /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(turn.executionId)) {
+    if (turnId.length === 0) {
+        throw new Error("cli-bridge turn id must be non-empty");
+    }
+    if (turn.executionId !== undefined && turn.executionId.length === 0) {
+        throw new Error("cli-bridge execution id must be non-empty");
+    }
+    if (turn.executionId !== undefined && isCliBridgeRunId(turn.executionId)) {
         return turn.executionId;
     }
+    const executionId = turn.executionId ?? turnId;
     const digest = createHash("sha256")
         .update(environmentId)
         .update("\0")
         .update(turn.sessionId ?? "")
         .update("\0")
-        .update(turn.executionId ?? turnId)
+        .update(executionId)
         .digest("hex");
     return `agent-${digest}`;
 }
+export function assertCliBridgeRunId(value) {
+    if (!isCliBridgeRunId(value)) {
+        throw new Error("cli-bridge run id must be 1-128 URL-safe characters");
+    }
+    return value;
+}
+function isCliBridgeRunId(value) {
+    return value.length <= 128 && /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(value);
+}
 export function runSnapshot(value) {
     const parsed = safeJson(value);
     if (!parsed)
@@ -328,15 +345,25 @@ export function runSnapshot(value) {
         : AgentExactRunControlRefSchema.shape.requestDigest.safeParse(parsed.requestDigest);
     const status = parsed.status;
     const terminal = parsed.terminal;
+    const controlRef = AgentExactRunControlRefSchema.safeParse({
+        runId: id,
+        provider: parsed.provider,
+        environmentId: parsed.environmentId,
+        sessionId: parsed.sessionId,
+        executionId: parsed.executionId,
+        requestDigest: requestDigest?.success ? requestDigest.data : undefined,
+    });
     if (typeof id !== "string" ||
         (requestDigest !== undefined && !requestDigest.success) ||
         !["running", "done", "error", "cancelled", "unknown"].includes(String(status)) ||
-        typeof terminal !== "boolean") {
+        typeof terminal !== "boolean" ||
+        (status === "running" && terminal)) {
         throw new Error("cli-bridge run status returned an invalid snapshot");
     }
     return {
         id,
         ...(requestDigest?.success ? { requestDigest: requestDigest.data } : {}),
+        ...(controlRef.success ? { controlRef: controlRef.data } : {}),
         status: status,
         terminal,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",