@tangle-network/agent-provider-cli-bridge 0.10.0 → 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

@@ -72,6 +72,18 @@ export function narrowCliBridgeCapabilities(adapter, reported, selectedBackend,
                 : {}),
         }
         : 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,
         // The Bridge can list and inspect sessions, but this adapter exposes neither method.
@@ -125,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,6 +191,11 @@ export function defaultCliBridgeCapabilities(harness) {
             eventIdentity: true,
             cancellationIdempotency: true,
         },
+        contextTransfer: {
+            freshSession: true,
+            requestIdempotency: true,
+            lookup: true,
+        },
         ...(harness === "pi"
             ? {
                 nativeContinuation: {

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-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.10.0",
+  "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.8.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",