@tangle-network/agent-provider-cli-bridge 0.9.6 → 0.11.0

package/README.md

@@ -102,7 +102,9 @@ Pi retained sessions also expose typed permission interactions and native contin
 The provider stores the selected harness, exact model route, and canonical create digest inside its opaque environment identifier.
 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.
+An accepted portable-context destination can supply its exact environment identifier through `requestedId`.
+The provider recovers that caller-owned route from cli-bridge's durable transfer receipt.
+An unknown caller-owned identifier returns `null`.
 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.

package/dist/capability-discovery.js

@@ -63,7 +63,26 @@ export function narrowCliBridgeCapabilities(adapter, reported, selectedBackend,
     };
     const nativeContinuation = supportsCliBridgeNativeContinuation(adapter) &&
         supportsCliBridgeNativeContinuation(reported)
-        ? { atomicBoundary: true, requestIdempotency: true }
+        ? {
+            atomicBoundary: true,
+            requestIdempotency: true,
+            ...(adapter.nativeContinuation?.admissionControl === true &&
+                reported.nativeContinuation?.admissionControl === true
+                ? { admissionControl: true }
+                : {}),
+        }
+        : undefined;
+    const contextTransfer = adapter.contextTransfer?.freshSession === true &&
+        adapter.contextTransfer.requestIdempotency === true &&
+        adapter.contextTransfer.lookup === true &&
+        reported.contextTransfer?.freshSession === true &&
+        reported.contextTransfer.requestIdempotency === true &&
+        reported.contextTransfer.lookup === true
+        ? {
+            freshSession: true,
+            requestIdempotency: true,
+            lookup: true,
+        }
         : undefined;
     const sessions = {
         continue: adapter.sessions.continue && reported.sessions.continue,
@@ -118,6 +137,7 @@ export function narrowCliBridgeCapabilities(adapter, reported, selectedBackend,
         sessions,
         ...(retainedControl === undefined ? {} : { retainedControl }),
         ...(nativeContinuation === undefined ? {} : { nativeContinuation }),
+        ...(contextTransfer === undefined ? {} : { contextTransfer }),
         ...(interactions === undefined ? {} : { interactions }),
         // Remote workspace support cannot create absent adapter methods.
         workspace: {

package/dist/context-transfer.d.ts

@@ -0,0 +1,8 @@
+import { type AgentContextTransferProvider, type ContextTransferRequest, type ContextTransferResult, type ContextTransferReceipt } from "@tangle-network/agent-interface";
+import type { CliBridgeProviderOptions } from "./provider-options.js";
+/** Bind the shared portable-context contract to CLI Bridge's durable endpoint. */
+export declare function createCliBridgeContextTransfer(options: CliBridgeProviderOptions): AgentContextTransferProvider;
+export declare function transferCliBridgeContext(options: CliBridgeProviderOptions, request: ContextTransferRequest, signal?: AbortSignal): Promise<ContextTransferResult>;
+export declare function lookupCliBridgeContext(options: CliBridgeProviderOptions, request: ContextTransferRequest, signal?: AbortSignal): Promise<ContextTransferResult | undefined>;
+/** Recover the accepted destination route for one caller-owned environment id. */
+export declare function lookupCliBridgeContextByEnvironment(options: CliBridgeProviderOptions, environmentId: string, signal?: AbortSignal): Promise<ContextTransferReceipt | undefined>;

package/dist/context-transfer.js

@@ -0,0 +1,117 @@
+import { ContextTransferRequestSchema, ContextTransferResultSchema, contextTransferResultMatchesRequest, } from "@tangle-network/agent-interface";
+import { createCliBridgeTransport, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
+/** Bind the shared portable-context contract to CLI Bridge's durable endpoint. */
+export function createCliBridgeContextTransfer(options) {
+    return {
+        transfer: (request, transferOptions) => transferCliBridgeContext(options, request, transferOptions?.signal),
+        lookup: (request, lookupOptions) => lookupCliBridgeContext(options, request, lookupOptions?.signal),
+    };
+}
+export async function transferCliBridgeContext(options, request, signal) {
+    const exact = ContextTransferRequestSchema.parse(request);
+    const transport = createCliBridgeTransport(options);
+    try {
+        const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/context-transfers`, {
+            method: "POST",
+            headers: requestHeaders(options),
+            body: JSON.stringify(exact),
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const body = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
+        return parseContextTransferResponse(exact, response.status, body);
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        return transportFailure(exact, error);
+    }
+    finally {
+        await transport.close();
+    }
+}
+export async function lookupCliBridgeContext(options, request, signal) {
+    const exact = ContextTransferRequestSchema.parse(request);
+    const transport = createCliBridgeTransport(options);
+    try {
+        const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/context-transfers/${encodeURIComponent(exact.operationId)}?request_digest=${encodeURIComponent(exact.requestDigest)}`, {
+            method: "GET",
+            headers: requestHeaders(options),
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const body = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
+        if (response.status === 404)
+            return undefined;
+        return parseContextTransferResponse(exact, response.status, body);
+    }
+    catch (error) {
+        signal?.throwIfAborted();
+        return transportFailure(exact, error);
+    }
+    finally {
+        await transport.close();
+    }
+}
+/** Recover the accepted destination route for one caller-owned environment id. */
+export async function lookupCliBridgeContextByEnvironment(options, environmentId, signal) {
+    const transport = createCliBridgeTransport(options);
+    try {
+        const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/context-transfer-environments/${encodeURIComponent(environmentId)}`, {
+            method: "GET",
+            headers: requestHeaders(options),
+            ...(signal === undefined ? {} : { signal }),
+        });
+        const body = await readBoundedCliBridgeResponse(response, MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, signal);
+        if (response.status === 404)
+            return undefined;
+        const parsed = parseContextTransferResult(body, response.status);
+        if ((parsed.status !== "accepted" && parsed.status !== "replayed") ||
+            parsed.environmentId !== environmentId) {
+            throw new Error("CLI Bridge returned a context transfer for another environment");
+        }
+        return parsed;
+    }
+    finally {
+        await transport.close();
+    }
+}
+function parseContextTransferResponse(request, status, body) {
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch (error) {
+        return transportFailure(request, new Error(`CLI Bridge context transfer returned HTTP ${status} with invalid JSON`, {
+            cause: error,
+        }));
+    }
+    const parsed = ContextTransferResultSchema.safeParse(value);
+    if (!parsed.success || !contextTransferResultMatchesRequest(request, parsed.data)) {
+        return transportFailure(request, new Error(`CLI Bridge context transfer returned HTTP ${status} with an invalid result`));
+    }
+    return parsed.data;
+}
+function parseContextTransferResult(body, status) {
+    let value;
+    try {
+        value = JSON.parse(body);
+    }
+    catch (error) {
+        throw new Error(`CLI Bridge context transfer returned HTTP ${status} with invalid JSON`, {
+            cause: error,
+        });
+    }
+    const parsed = ContextTransferResultSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new Error(`CLI Bridge context transfer returned HTTP ${status} with an invalid result`);
+    }
+    return parsed.data;
+}
+function transportFailure(request, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return ContextTransferResultSchema.parse({
+        status: "transport_failure",
+        operationId: request.operationId,
+        requestDigest: request.requestDigest,
+        message: message.slice(0, 4_096) || "CLI Bridge context transfer failed",
+        retryable: true,
+    });
+}

package/dist/environment-identity.d.ts

@@ -11,3 +11,5 @@ export interface CliBridgeEnvironmentRoute {
 export declare function cliBridgeEnvironmentId(route: Omit<CliBridgeEnvironmentRoute, "createDigest">, createDigest: Sha256Digest, idempotencyKey?: string): string;
 /** Recover the exact route from a provider-owned retained identifier. */
 export declare function cliBridgeEnvironmentRoute(id: string): CliBridgeEnvironmentRoute;
+/** Parse a provider-owned route, or identify a caller-owned destination id. */
+export declare function optionalCliBridgeEnvironmentRoute(id: string): CliBridgeEnvironmentRoute | undefined;

package/dist/environment-identity.js

@@ -60,6 +60,12 @@ export function cliBridgeEnvironmentRoute(id) {
         createDigest,
     };
 }
+/** Parse a provider-owned route, or identify a caller-owned destination id. */
+export function optionalCliBridgeEnvironmentRoute(id) {
+    if (!id.startsWith(CLI_BRIDGE_ENVIRONMENT_ID_PREFIX))
+        return undefined;
+    return cliBridgeEnvironmentRoute(id);
+}
 function optionalRouteValue(value) {
     return value === null || routeValue(value);
 }

package/dist/index.js

@@ -4,9 +4,10 @@ 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 { createCliBridgeContextTransfer, lookupCliBridgeContextByEnvironment, } from "./context-transfer.js";
 import { assertCliBridgeProviderOptions, } from "./provider-options.js";
 import { narrowedCliBridgeObservation } from "./observation.js";
-import { cliBridgeEnvironmentId, cliBridgeEnvironmentRoute, } from "./environment-identity.js";
+import { cliBridgeEnvironmentId, optionalCliBridgeEnvironmentRoute, } from "./environment-identity.js";
 import { resolveBridgeModel } from "./wire.js";
 export { safeEndpointFromBaseUrl } from "./observation.js";
 export function createCliBridgeProvider(options) {
@@ -68,7 +69,8 @@ export function createCliBridgeProvider(options) {
         const model = hasEnvironmentModel
             ? resolveBridgeModel(options, environmentInput, {}, profile)
             : undefined;
-        const environmentId = cliBridgeEnvironmentId({ backend: selectedBackend, model }, agentEnvironmentCreateInputDigest(environmentInput), input.idempotencyKey);
+        const environmentId = input.requestedId ?? cliBridgeEnvironmentId({ backend: selectedBackend, model }, agentEnvironmentCreateInputDigest(environmentInput), input.idempotencyKey);
+        assertRequestedEnvironmentId(environmentId);
         return createCliBridgeEnvironment({
             options,
             providerName: name,
@@ -85,6 +87,7 @@ export function createCliBridgeProvider(options) {
     };
     return {
         name,
+        contextTransfer: createCliBridgeContextTransfer(options),
         lookupRun: (input) => lookupExactCliBridgeRun(options, name, input),
         capabilities: () => {
             if (options.defaultModel !== undefined) {
@@ -95,31 +98,41 @@ export function createCliBridgeProvider(options) {
         create(input) {
             return createAgentEnvironmentWithIdempotency(createRecords, input, () => createEnvironment(input));
         },
-        async get(id) {
+        async get(id, getOptions) {
             if (id.length === 0 || id.trim() !== id) {
                 throw new Error("cli-bridge environment id must be non-empty and have no outer whitespace");
             }
-            const route = cliBridgeEnvironmentRoute(id);
+            const ownedRoute = optionalCliBridgeEnvironmentRoute(id);
+            const transfer = ownedRoute === undefined
+                ? await lookupCliBridgeContextByEnvironment(options, id, getOptions?.signal)
+                : undefined;
+            const backend = ownedRoute?.backend ?? transfer?.destination.runner;
+            const destinationModel = transfer?.destination.model;
+            const model = ownedRoute?.model ?? (destinationModel === undefined || destinationModel === backend || destinationModel.startsWith(`${backend}/`)
+                ? destinationModel ?? backend
+                : `${backend}/${destinationModel}`);
+            if (ownedRoute === undefined && transfer === undefined)
+                return null;
             return createCliBridgeEnvironment({
                 options,
                 providerName: name,
                 environmentInput: {
                     profile: { name: "reconnected" },
-                    ...(route.backend === undefined ? {} : { backend: route.backend }),
+                    ...(backend === undefined ? {} : { backend }),
                     idempotencyKey: id,
                 },
                 environmentId: id,
                 allowDispatch: false,
                 cancelRunsOnDestroy: false,
-                capabilities: await resolveCapabilities(route.backend, route.model, true, true),
-                selectedBackend: route.backend,
-                selectedModel: route.model,
+                capabilities: await resolveCapabilities(backend, model, true, true),
+                selectedBackend: backend,
+                selectedModel: model,
             });
         },
     };
 }
 function withoutRemoteRetainedCapabilities(capabilities) {
-    const { retainedControl: _retainedControl, nativeContinuation: _nativeContinuation, interactions: _interactions, ...local } = capabilities;
+    const { retainedControl: _retainedControl, nativeContinuation: _nativeContinuation, contextTransfer: _contextTransfer, interactions: _interactions, ...local } = capabilities;
     return local;
 }
 function selectedBackendFromInput(input, configuredBackend) {
@@ -135,6 +148,13 @@ function selectedBackendFromRoute(route) {
     const parsed = harnessTypeSchema.safeParse(candidate);
     return parsed.success ? parsed.data : undefined;
 }
+function assertRequestedEnvironmentId(value) {
+    if (value.length === 0 ||
+        value.length > 256 ||
+        !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(value)) {
+        throw new Error("cli-bridge requested environment id must be 1-256 URL-safe characters");
+    }
+}
 /**
  * Describe the bridge backend, not this adapter.
  *
@@ -171,11 +191,17 @@ export function defaultCliBridgeCapabilities(harness) {
             eventIdentity: true,
             cancellationIdempotency: true,
         },
+        contextTransfer: {
+            freshSession: true,
+            requestIdempotency: true,
+            lookup: true,
+        },
         ...(harness === "pi"
             ? {
                 nativeContinuation: {
                     atomicBoundary: true,
                     requestIdempotency: true,
+                    admissionControl: true,
                 },
             }
             : {}),

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, assertCliBridgeTurnModel, continueCliBridgeNative, readCliBridgeNativeContextBoundary, supportsCliBridgeNativeContinuation, supportsCliBridgeNativeInteractions, } from "./retained-native.js";
+import { assertCliBridgeRequestedInteractions, assertCliBridgeTurnModel, continueCliBridgeNative, readCliBridgeNativeContextBoundary, supportsCliBridgeNativeContinuation, supportsCliBridgeNativeAdmissionControl, supportsCliBridgeNativeInteractions, } from "./retained-native.js";
 import { assertRunMatchesControlRef, exactControlRefForSession, prepareCliBridgeRun, runFromControlRef, } from "./retained-run-state.js";
 import { createCliBridgeTransport } from "./transport.js";
 /**
@@ -269,7 +269,7 @@ function createCliBridgeSession(args) {
                     return readCliBridgeNativeContextBoundary(args.options, args.providerName, args.transport, requireCurrentRun(), boundaryOptions?.signal);
                 },
                 async continueNative(request, continuationOptions) {
-                    const result = await continueCliBridgeNative(args.options, args.providerName, args.transport, requireCurrentRun(), request, continuationOptions, args.runs);
+                    const result = await continueCliBridgeNative(args.options, args.providerName, args.transport, requireCurrentRun(), request, continuationOptions, args.runs, supportsCliBridgeNativeAdmissionControl(args.capabilities));
                     if ("result" in result && result.result.usage !== undefined) {
                         args.usageLog.record(result.controlRef.executionId, result.result.usage);
                     }

package/dist/retained-execution.js

@@ -4,6 +4,7 @@ import { CliBridgeRequestRejectedError, streamCliBridgeTurn, } from "./retained-
 import { beginCliBridgeNativeTurn, } from "./retained-native.js";
 import { MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
 import { modelRequestCount } from "./wire.js";
+import { lookupCliBridgeContext } from "./context-transfer.js";
 export async function* streamTrackedCliBridgeTurn(options, environmentInput, providerName, prepared, transport, runs, sessions, readers, nativeSessions, useNativeInteractions) {
     const originalTurn = prepared.turn;
     if (originalTurn.detach) {
@@ -48,6 +49,7 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pro
                 yield event;
             }
         }
+        await confirmCliBridgeContextTransfer(options, originalTurn, run, signal);
         drained = true;
         if (runs.get(run.id) === run)
             runs.delete(run.id);
@@ -142,6 +144,7 @@ export async function dispatchCliBridgeTurn(options, environmentInput, prepared,
         }
         const controlRef = exactControlRefForRun(run, providerName);
         run.controlRef = controlRef;
+        await confirmCliBridgeContextTransfer(options, prepared.turn, run, signal);
         if (responseBody) {
             await detachCliBridgeReader(responseBody);
             responseBody = undefined;
@@ -150,6 +153,9 @@ export async function dispatchCliBridgeTurn(options, environmentInput, prepared,
             id: run.sessionId,
             provider: providerName,
             controlRef,
+            ...(run.contextTransferReceipt === undefined
+                ? {}
+                : { contextTransferReceipt: run.contextTransferReceipt }),
             metadata: {
                 runId: run.id,
                 requestDigest: run.requestDigest,
@@ -188,6 +194,16 @@ export async function dispatchCliBridgeTurn(options, environmentInput, prepared,
         throw failure;
     }
 }
+async function confirmCliBridgeContextTransfer(options, turn, run, signal) {
+    if (turn.contextTransfer === undefined)
+        return;
+    const transfer = await lookupCliBridgeContext(options, turn.contextTransfer, signal);
+    if (transfer === undefined ||
+        (transfer.status !== "accepted" && transfer.status !== "replayed")) {
+        throw new Error("cli-bridge did not confirm admitted portable context");
+    }
+    run.contextTransferReceipt = transfer;
+}
 export async function* streamCliBridgeSessionEvents(options, environmentInput, providerName, run, transport, runs, readers, eventOptions) {
     if (eventOptions?.executionId !== undefined &&
         eventOptions.executionId !== run.executionId) {
@@ -302,6 +318,9 @@ export async function collectCliBridgeTurnResult(source, run, options, transport
             }
             : {}),
         ...(run.sessionId ? { sessionId: run.sessionId } : {}),
+        ...(run.contextTransferReceipt === undefined
+            ? {}
+            : { contextTransferReceipt: run.contextTransferReceipt }),
         ...(usage ? { usage } : {}),
         metadata: {
             runId: run.id,

package/dist/retained-native.d.ts

@@ -14,6 +14,8 @@ export type CliBridgeNativeSessionCache = Map<string, Promise<CliBridgeNativeSes
 export declare function supportsCliBridgeNativeInteractions(capabilities: AgentEnvironmentCapabilities, selectedBackend?: string): boolean;
 /** Native continuation is exposed only when the Bridge proves both guarantees. */
 export declare function supportsCliBridgeNativeContinuation(capabilities: AgentEnvironmentCapabilities): boolean;
+/** Early continuation control is valid only with the complete retained-run contract. */
+export declare function supportsCliBridgeNativeAdmissionControl(capabilities: AgentEnvironmentCapabilities): boolean;
 /** 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. */
@@ -21,7 +23,7 @@ export declare function assertCliBridgeTurnModel(options: CliBridgeProviderOptio
 /** 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. */
-export declare function continueCliBridgeNative(options: CliBridgeProviderOptions, providerName: string, transport: CliBridgeTransport, run: CliBridgeRun, request: NativeContextContinuationRequest, continuationOptions: AgentNativeContextContinuationOptions, runs: Map<string, CliBridgeRun>): Promise<AgentNativeContextContinuationResult>;
+export declare function continueCliBridgeNative(options: CliBridgeProviderOptions, providerName: string, transport: CliBridgeTransport, run: CliBridgeRun, request: NativeContextContinuationRequest, continuationOptions: AgentNativeContextContinuationOptions, runs: Map<string, CliBridgeRun>, admissionControl: boolean): Promise<AgentNativeContextContinuationResult>;
 /**
  * Create or reuse the server's retained native session for one external id.
  *

package/dist/retained-native.js

@@ -1,4 +1,4 @@
-import { AgentNativeContextContinuationResultSchema, AgentExactRunControlRefSchema, NativeContextBoundaryProofSchema, NativeContextContinuationRequestSchema, RequestedInteractionsSchema, agentNativeContextContinuationResultMatchesRequest, canonicalCandidateDigest, nativeContextContinuationTurnDigest, sameAgentRunControlRef, } from "@tangle-network/agent-interface";
+import { AgentNativeContextContinuationResultSchema, AgentNativeContextContinuationAdmissionSchema, AgentExactRunControlRefSchema, NativeContextBoundaryProofSchema, NativeContextContinuationRequestSchema, RequestedInteractionsSchema, agentNativeContextContinuationResultMatchesRequest, agentNativeContextContinuationAdmissionMatchesRequest, canonicalCandidateDigest, nativeContextContinuationTurnDigest, sameAgentRunControlRef, } from "@tangle-network/agent-interface";
 import { CliBridgeRequestRejectedError } from "./retained-stream.js";
 import { advanceCliBridgeRun, exactControlRefForRun, } from "./retained-run-state.js";
 import { MAX_CLI_BRIDGE_CONTROL_RESPONSE_BYTES, readBoundedCliBridgeResponse, requestHeaders, trimSlash, } from "./transport.js";
@@ -26,6 +26,16 @@ export function supportsCliBridgeNativeContinuation(capabilities) {
         capabilities.nativeContinuation?.atomicBoundary === true &&
         capabilities.nativeContinuation.requestIdempotency === true);
 }
+/** Early continuation control is valid only with the complete retained-run contract. */
+export function supportsCliBridgeNativeAdmissionControl(capabilities) {
+    const retained = capabilities.retainedControl;
+    return Boolean(supportsCliBridgeNativeContinuation(capabilities) &&
+        capabilities.nativeContinuation?.admissionControl === true &&
+        retained?.exactRunIdentity === true &&
+        retained.resultIdentity === true &&
+        retained.eventIdentity === true &&
+        retained.cancellationIdempotency === true);
+}
 /** Reject posture the selected environment did not advertise before transport use. */
 export function assertCliBridgeRequestedInteractions(capabilities, requested) {
     if (requested === undefined)
@@ -88,7 +98,7 @@ export async function readCliBridgeNativeContextBoundary(options, providerName,
     return proof.data;
 }
 /** Send one canonical same-session continuation and advance the live run identity. */
-export async function continueCliBridgeNative(options, providerName, transport, run, request, continuationOptions, runs) {
+export async function continueCliBridgeNative(options, providerName, transport, run, request, continuationOptions, runs, admissionControl) {
     const exactRequest = NativeContextContinuationRequestSchema.parse(request);
     const current = currentCliBridgeControlRef(run, providerName);
     if (!sameAgentRunControlRef(current, exactRequest.run)) {
@@ -98,37 +108,99 @@ export async function continueCliBridgeNative(options, providerName, transport,
         exactRequest.turnDigest) {
         throw new Error("cli-bridge native continuation turn does not match its request digest");
     }
+    if (continuationOptions.onAdmission !== undefined && !admissionControl) {
+        throw new Error("cli-bridge native continuation does not advertise early admission control");
+    }
     const operation = continuationSignal(continuationOptions);
+    const endpoint = `${trimSlash(options.baseUrl)}/v1/sessions/${encodeURIComponent(exactRequest.run.sessionId)}/continue`;
+    const body = JSON.stringify({ request: exactRequest, turn: continuationOptions.turn });
+    const requestInit = {
+        method: "POST",
+        headers: requestHeaders(options),
+        body,
+        ...(operation.signal ? { signal: operation.signal } : {}),
+    };
     try {
         operation.signal?.throwIfAborted();
-        const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/sessions/${encodeURIComponent(exactRequest.run.sessionId)}/continue`, {
-            method: "POST",
-            headers: requestHeaders(options),
-            body: JSON.stringify({ request: exactRequest, turn: continuationOptions.turn }),
-            ...(operation.signal ? { signal: operation.signal } : {}),
-        });
+        const response = await transport.fetch(continuationOptions.onAdmission === undefined
+            ? endpoint
+            : `${endpoint}?return=admission`, requestInit);
         const responseText = await readBoundedCliBridgeResponse(response, MAX_NATIVE_CONTINUATION_RESPONSE_BYTES, operation.signal);
+        if (continuationOptions.onAdmission !== undefined && response.status === 202) {
+            const admission = parseNativeContinuationAdmission(responseText);
+            assertContinuationAdmissionBinding(exactRequest, admission);
+            assertContinuationAdmissionHeaders(response, admission.controlRef);
+            advanceCliBridgeRun(run, admission.controlRef, providerName, runs);
+            continuationOptions.onAdmission(admission.controlRef);
+            operation.signal?.throwIfAborted();
+            const terminalResponse = await transport.fetch(endpoint, requestInit);
+            const terminalText = await readBoundedCliBridgeResponse(terminalResponse, MAX_NATIVE_CONTINUATION_RESPONSE_BYTES, operation.signal);
+            return acceptNativeContinuationResult(terminalResponse, terminalText, exactRequest, run, providerName, runs);
+        }
         const outcome = parseNativeContinuationResult(responseText);
-        assertContinuationAcknowledgementBinding(exactRequest, outcome);
-        if (outcome.acknowledgement.status === "accepted" ||
-            outcome.acknowledgement.status === "replayed") {
-            if (!agentNativeContextContinuationResultMatchesRequest(exactRequest, outcome)) {
-                throw new Error("cli-bridge native continuation returned an acknowledgement for another request");
-            }
-            if (!response.ok) {
-                throw new Error(`cli-bridge native continuation returned HTTP ${response.status} for an accepted result`);
-            }
-            if (!("controlRef" in outcome)) {
-                throw new Error("cli-bridge native continuation omitted its current control reference");
-            }
-            advanceCliBridgeRun(run, outcome.controlRef, providerName, runs);
+        if (continuationOptions.onAdmission !== undefined &&
+            (outcome.acknowledgement.status === "accepted" ||
+                outcome.acknowledgement.status === "replayed")) {
+            throw new Error("cli-bridge native continuation omitted its advertised early admission");
         }
-        return outcome;
+        return acceptParsedNativeContinuationResult(response, outcome, exactRequest, run, providerName, runs);
     }
     finally {
         operation.dispose();
     }
 }
+function acceptNativeContinuationResult(response, responseText, request, run, providerName, runs) {
+    return acceptParsedNativeContinuationResult(response, parseNativeContinuationResult(responseText), request, run, providerName, runs);
+}
+function acceptParsedNativeContinuationResult(response, outcome, exactRequest, run, providerName, runs) {
+    assertContinuationAcknowledgementBinding(exactRequest, outcome);
+    if (outcome.acknowledgement.status === "accepted" ||
+        outcome.acknowledgement.status === "replayed") {
+        if (!agentNativeContextContinuationResultMatchesRequest(exactRequest, outcome)) {
+            throw new Error("cli-bridge native continuation returned an acknowledgement for another request");
+        }
+        if (!response.ok) {
+            throw new Error(`cli-bridge native continuation returned HTTP ${response.status} for an accepted result`);
+        }
+        if (!("controlRef" in outcome)) {
+            throw new Error("cli-bridge native continuation omitted its current control reference");
+        }
+        advanceCliBridgeRun(run, outcome.controlRef, providerName, runs);
+    }
+    return outcome;
+}
+function parseNativeContinuationAdmission(value) {
+    const parsed = safeJson(value);
+    try {
+        return AgentNativeContextContinuationAdmissionSchema.parse(parsed);
+    }
+    catch (error) {
+        throw new Error("cli-bridge native continuation returned an invalid admission", {
+            cause: error,
+        });
+    }
+}
+function assertContinuationAdmissionBinding(request, admission) {
+    if (!agentNativeContextContinuationAdmissionMatchesRequest(request, admission)) {
+        throw new Error("cli-bridge native continuation admission is not bound to the request");
+    }
+}
+function assertContinuationAdmissionHeaders(response, controlRef) {
+    const expected = new Map([
+        ["x-run-id", controlRef.runId],
+        ["x-run-request-digest", controlRef.requestDigest],
+        ["x-run-provider", controlRef.provider],
+        ["x-run-environment-id", controlRef.environmentId],
+        ["x-run-session-id", controlRef.sessionId],
+        ["x-run-execution-id", controlRef.executionId],
+        ["location", `/v1/runs/${encodeURIComponent(controlRef.runId)}`],
+    ]);
+    for (const [name, value] of expected) {
+        if (response.headers.get(name) !== value) {
+            throw new Error(`cli-bridge native continuation admission has invalid ${name}`);
+        }
+    }
+}
 function currentCliBridgeControlRef(run, providerName) {
     if (run.controlRef !== undefined) {
         const controlRef = AgentExactRunControlRefSchema.parse(run.controlRef);

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

@@ -1,5 +1,6 @@
 import { type AgentExactRunControlRef, type AgentRunControlRef, type Sha256Digest } from "@tangle-network/agent-interface";
 import type { AgentTurnInput, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import type { ContextTransferReceipt } from "@tangle-network/agent-interface";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 export interface CliBridgeRun {
     id: string;
@@ -13,6 +14,7 @@ export interface CliBridgeRun {
     requestDigest?: Sha256Digest;
     controlRef?: AgentExactRunControlRef;
     cancellation?: Promise<CliBridgeRunSnapshot>;
+    contextTransferReceipt?: ContextTransferReceipt;
 }
 export interface CliBridgeSessionState {
     readonly id: string;

package/dist/retained-run-state.js

@@ -77,9 +77,17 @@ export function prepareCliBridgeRun(options, environmentInput, originalTurn, pro
         throw new Error("native cli-bridge turns require stable turnId and executionId");
     }
     const turnId = validatedTurn.turnId ?? crypto.randomUUID();
-    const runId = cliBridgeRunId(environmentId, validatedTurn, turnId);
-    const sessionId = validatedTurn.sessionId ?? runId;
-    const executionId = validatedTurn.executionId ?? runId;
+    const destination = validatedTurn.contextTransfer?.plan.destination;
+    const runId = destination?.runId ?? cliBridgeRunId(environmentId, validatedTurn, turnId);
+    const sessionId = validatedTurn.sessionId ?? destination?.sessionId ?? runId;
+    const executionId = validatedTurn.executionId ?? destination?.executionId ?? runId;
+    if (destination !== undefined &&
+        (destination.provider !== providerName ||
+            destination.environmentId !== environmentId ||
+            destination.sessionId !== sessionId ||
+            destination.executionId !== executionId)) {
+        throw new Error("cli-bridge context transfer targets another destination");
+    }
     const turn = {
         ...validatedTurn,
         turnId,

package/dist/wire.js

@@ -24,6 +24,9 @@ export function toChatCompletionsBody(options, environmentInput, turn, coordinat
         ...(environmentInput.workspace?.cwd ? { cwd: environmentInput.workspace.cwd } : {}),
         ...(execution ? { execution } : {}),
         ...(interactions === undefined ? {} : { interactions }),
+        ...(turn.contextTransfer === undefined
+            ? {}
+            : { context_transfer: turn.contextTransfer }),
         metadata: {
             ...(environmentInput.metadata ?? {}),
             ...(turn.context ?? {}),
@@ -99,6 +102,9 @@ export function toRetainedTurnBody(turn, run, providerName) {
         provider: providerName,
         environment_id: run.environmentId,
         ...(turn.interactions === undefined ? {} : { interactions }),
+        ...(turn.contextTransfer === undefined
+            ? {}
+            : { context_transfer: turn.contextTransfer }),
         ...(turn.context !== undefined ? { context: turn.context } : {}),
         ...(turn.providerOptions !== undefined
             ? { provider_options: turn.providerOptions }
@@ -111,8 +117,6 @@ function assertRetainedTurnInputSupported(turn) {
         unsupported.push("timeoutMs");
     if (turn.controlRef !== undefined)
         unsupported.push("controlRef");
-    if (turn.contextTransfer !== undefined)
-        unsupported.push("contextTransfer");
     if (turn.nativeContinuation !== undefined)
         unsupported.push("nativeContinuation");
     // `detach` controls the provider's response reader. The bridge request stays unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "0.9.6",
+  "version": "0.11.0",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,8 @@
     "dist/environment-identity.js",
     "dist/capability-discovery.d.ts",
     "dist/capability-discovery.js",
+    "dist/context-transfer.d.ts",
+    "dist/context-transfer.js",
     "dist/interaction-response.d.ts",
     "dist/interaction-response.js",
     "dist/observation.d.ts",
@@ -59,13 +61,13 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^1.5.0",
+    "@tangle-network/agent-interface": "^1.9.0",
     "undici": "7.29.0"
   },
   "devDependencies": {
-    "@types/node": "25.6.0",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "@types/node": "26.4.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
   },
   "scripts": {
     "build": "pnpm run clean && tsc -p tsconfig.build.json",