@tangle-network/agent-provider-cli-bridge 1.1.2 → 2.0.0

package/README.md

@@ -49,7 +49,7 @@ The lookup returns the server-issued digest only when all five planned coordinat
 
 ## Which call adds a turn
 
-Continuation has two tiers, and the tier depends on whether the environment object came from `create()` or from `get()`.
+Creation, ordinary reconstruction and accepted transfer attachment have different admission authority.
 
 In the process that created the environment, `environment.dispatch()`, `environment.stream()`, and `session.prompt()` all add a turn.
 Passing the same `sessionId` continues the same CLI conversation.
@@ -58,10 +58,11 @@ After `provider.get(environmentId)` reconstructs the environment, only `session.
 It requires the `nativeContinuation` capability, which the provider publishes only for the Pi harness today, and only when the running Bridge proves the same contract.
 The reconstructed environment deliberately refuses every other way to start work: `environment.stream()` and `environment.dispatch()` throw "a reconstructed cli-bridge environment can only control an existing run", and `session.prompt()` throws "a reconstructed cli-bridge session cannot start another turn".
 A reconstructed environment for any other harness therefore controls its existing runs (status, cursor replay, result, cancellation, and interaction responses) but adds no turn.
-Restart-safe continuation for those harnesses needs native sessions in the Bridge server itself, which the Bridge does not have yet; it is tracked in the `drewstone/cli-bridge` repository and cannot be reached from this adapter.
+
+When the exact deployed route confirms `contextTransfer.attach`, `provider.get(environmentId, { contextTransfer: request })` instead attaches the accepted transfer's first turn. The request must carry its exact profile. The adapter looks up the canonical operation, requires an available matching receipt for that environment, and returns it as `environment.contextTransferReceipt`. The resulting `dispatch`, `stream` and `session.prompt` accept only that request and its destination identities. They do not allocate another environment or replace a missing one. Changed context or profile fails before dispatch; a missing or uncertain receipt refuses attachment. Destroying this reconstructed handle closes its readers without canceling the accepted destination's runs.
 
 The capability document keeps `sessions.continue: true` on a reconstructed environment because the Agent Interface couples that flag to `retainedControl`: a document that reports `sessions.continue: false` while keeping retained run control fails `AgentEnvironmentCapabilitiesSchema` with "retained control requires exact run, result, event, cancellation, replay, detach, turn, and session identity together".
-`nativeContinuation` is the flag that states whether a reconstructed environment can add a turn: present means `continueNative` works, absent means no call on that environment starts one.
+`nativeContinuation` states whether an ordinary reconstructed environment supports `continueNative`. It does not authorize the first turn of a separate transfer.
 
 A runtime caller continues a retained run with `RetainedRunHandle.continueNative`, not with `startRetainedRunInEnvironment`.
 `startRetainedRunInEnvironment` requires `provider.list` for its ownership proof, and this provider exposes no `list`; it then calls `environment.dispatch()`, which a reconstructed environment refuses.

package/dist/capability-discovery.js

@@ -82,6 +82,8 @@ export function narrowCliBridgeCapabilities(adapter, reported, selectedBackend,
             freshSession: true,
             requestIdempotency: true,
             lookup: true,
+            ...(adapter.contextTransfer.attach === true && reported.contextTransfer.attach === true
+                ? { attach: true } : {}),
         }
         : undefined;
     const sessions = {

package/dist/context-transfer.js

@@ -9,6 +9,9 @@ export function createCliBridgeContextTransfer(options) {
 }
 export async function transferCliBridgeContext(options, request, signal) {
     const exact = ContextTransferRequestSchema.parse(request);
+    if (exact.workspace?.snapshot !== undefined) {
+        throw new Error("CLI Bridge provider does not support portable workspace snapshots");
+    }
     const transport = createCliBridgeTransport(options);
     try {
         const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/context-transfers`, {

package/dist/index.js

@@ -1,10 +1,10 @@
-import { agentEnvironmentCreateInputDigest, createAgentEnvironmentWithIdempotency, } from "@tangle-network/agent-interface/environment-provider";
-import { harnessTypeSchema, harnessSystemPromptIntents, snapshotAgentProfile, WorkspaceRequestSchema, workspaceCwdPathForBase, } from "@tangle-network/agent-interface";
+import { agentEnvironmentCreateInputDigest, createAgentEnvironmentWithIdempotency, AgentEnvironmentGetOptionsSchema, } from "@tangle-network/agent-interface/environment-provider";
+import { harnessTypeSchema, harnessSystemPromptIntents, snapshotAgentProfile, deepFreeze, ContextTransferReceiptSchema, WorkspaceRequestSchema, workspaceCwdPathForBase, } 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 { createCliBridgeContextTransfer, lookupCliBridgeContextByEnvironment, } from "./context-transfer.js";
+import { createCliBridgeContextTransfer, lookupCliBridgeContextByEnvironment, lookupCliBridgeContext, } from "./context-transfer.js";
 import { assertCliBridgeProviderOptions, } from "./provider-options.js";
 import { narrowedCliBridgeObservation } from "./observation.js";
 import { cliBridgeEnvironmentId, optionalCliBridgeEnvironmentRoute, } from "./environment-identity.js";
@@ -13,6 +13,9 @@ export { safeEndpointFromBaseUrl } from "./observation.js";
 export { closeExactCliBridgeSession } from "./retained-control.js";
 export function createCliBridgeProvider(options) {
     assertCliBridgeProviderOptions(options);
+    if (options.capabilities?.create?.workspaceSnapshot === true) {
+        throw new Error("CLI Bridge provider does not support portable workspace snapshots");
+    }
     const name = options.name ?? "cli-bridge";
     const createRecords = new Map();
     const configuredBackend = selectedBackendFromRoute(options.defaultModel);
@@ -55,6 +58,9 @@ export function createCliBridgeProvider(options) {
         });
     };
     const createEnvironment = async (input) => {
+        if (input.workspace?.snapshot !== undefined) {
+            throw new Error("CLI Bridge provider does not support portable workspace snapshots");
+        }
         if (input.runtimeAttachments !== undefined) {
             throw new Error("CLI Bridge provider does not support runtime MCP attachments");
         }
@@ -111,9 +117,44 @@ export function createCliBridgeProvider(options) {
             if (id.length === 0 || id.trim() !== id) {
                 throw new Error("cli-bridge environment id must be non-empty and have no outer whitespace");
             }
+            const operation = AgentEnvironmentGetOptionsSchema.parse(getOptions ?? {});
+            operation.signal?.throwIfAborted();
+            const accepted = operation.contextTransfer;
+            if (accepted !== undefined) {
+                if (accepted.profile === undefined)
+                    throw new Error("CLI Bridge attachment requires the accepted exact profile");
+                if (accepted.workspace?.snapshot !== undefined)
+                    throw new Error("CLI Bridge provider does not support portable workspace snapshots");
+                const destination = accepted.plan.destination;
+                if (destination.provider !== name || (destination.environmentId !== undefined && destination.environmentId !== id)) {
+                    throw new Error("CLI Bridge attachment targets another provider or environment");
+                }
+                const backend = destination.runner;
+                const environmentInput = { profile: snapshotAgentProfile(accepted.profile), backend,
+                    ...(accepted.workspace === undefined ? {} : { workspace: accepted.workspace }),
+                    ...(accepted.resources === undefined ? {} : { resources: accepted.resources }),
+                    idempotencyKey: accepted.operationId };
+                const model = resolveBridgeModel({ ...options, defaultModel: undefined }, environmentInput, { model: destination.model ?? accepted.profile.model?.default ?? backend }, accepted.profile);
+                const attachedOptions = { ...options, defaultModel: model };
+                const capabilities = await resolveCapabilities(backend, model, true, true);
+                if (capabilities.contextTransfer?.attach !== true)
+                    throw new Error("CLI Bridge context transfer attachment is unsupported by the selected deployment");
+                const transfer = await lookupCliBridgeContext(options, accepted, operation.signal);
+                if (transfer === undefined || (transfer.status !== "accepted" && transfer.status !== "replayed") || transfer.environmentId !== id) {
+                    throw new Error("CLI Bridge attachment requires an available exact transfer receipt");
+                }
+                operation.signal?.throwIfAborted();
+                return createCliBridgeEnvironment({
+                    options: attachedOptions, providerName: name, environmentId: id, environmentInput,
+                    allowDispatch: true, cancelRunsOnDestroy: false, capabilities,
+                    selectedBackend: backend, selectedModel: model,
+                    acceptedContextTransfer: accepted,
+                    contextTransferReceipt: deepFreeze(ContextTransferReceiptSchema.parse(transfer)),
+                });
+            }
             const ownedRoute = optionalCliBridgeEnvironmentRoute(id);
             const transfer = ownedRoute === undefined
-                ? await lookupCliBridgeContextByEnvironment(options, id, getOptions?.signal)
+                ? await lookupCliBridgeContextByEnvironment(options, id, operation.signal)
                 : undefined;
             const backend = ownedRoute?.backend ?? transfer?.destination.runner;
             const destinationModel = transfer?.destination.model;
@@ -204,6 +245,7 @@ export function defaultCliBridgeCapabilities(harness) {
             freshSession: true,
             requestIdempotency: true,
             lookup: true,
+            attach: true,
         },
         ...(harness === "pi"
             ? {

package/dist/retained-environment.d.ts

@@ -1,6 +1,9 @@
 import type { AgentEnvironment, AgentEnvironmentCapabilities, AgentEnvironmentCreation, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import type { ContextTransferRequest, ContextTransferReceipt } from "@tangle-network/agent-interface";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 export interface CreateCliBridgeEnvironmentArgs {
+    readonly acceptedContextTransfer?: ContextTransferRequest;
+    readonly contextTransferReceipt?: ContextTransferReceipt;
     readonly options: CliBridgeProviderOptions;
     readonly providerName: string;
     readonly environmentInput: CreateAgentEnvironmentInput;

package/dist/retained-environment.js

@@ -41,11 +41,11 @@ export function createCliBridgeEnvironment(args) {
             throw new Error("cli-bridge environment is destroyed");
         assertCliBridgeTurnAllowed(args.allowDispatch, "environment.stream()");
         if (args.selectedModel !== undefined &&
-            args.capabilities.retainedControl !== undefined) {
+            (args.capabilities.retainedControl !== undefined || args.acceptedContextTransfer !== undefined)) {
             assertCliBridgeTurnModel(options, environmentInput, turn, args.selectedModel);
         }
         assertCliBridgeRequestedInteractions(args.capabilities, turn.interactions);
-        const prepared = prepareCliBridgeRun(options, environmentInput, turn, providerName, environmentId, useNativeInteractions);
+        const prepared = prepareCliBridgeRun(options, environmentInput, turn, providerName, environmentId, useNativeInteractions, args.acceptedContextTransfer);
         // A streamed run reports usage across its events, so the totals are summed
         // here and recorded as one execution's measurement.
         let streamedUsage;
@@ -60,6 +60,7 @@ export function createCliBridgeEnvironment(args) {
         provider: providerName,
         ...(args.creation === undefined ? {} : { creation: args.creation }),
         capabilities: args.capabilities,
+        ...(args.contextTransferReceipt === undefined ? {} : { contextTransferReceipt: args.contextTransferReceipt }),
         ...(environmentInput.name ? { name: environmentInput.name } : {}),
         status: async (statusOptions) => {
             statusOptions?.signal?.throwIfAborted();
@@ -71,11 +72,11 @@ export function createCliBridgeEnvironment(args) {
                 throw new Error("cli-bridge environment is destroyed");
             assertCliBridgeTurnAllowed(args.allowDispatch, "environment.dispatch()");
             if (args.selectedModel !== undefined &&
-                args.capabilities.retainedControl !== undefined) {
+                (args.capabilities.retainedControl !== undefined || args.acceptedContextTransfer !== undefined)) {
                 assertCliBridgeTurnModel(options, environmentInput, turn, args.selectedModel);
             }
             assertCliBridgeRequestedInteractions(args.capabilities, turn.interactions);
-            const prepared = prepareCliBridgeRun(options, environmentInput, turn, providerName, environmentId, useNativeInteractions);
+            const prepared = prepareCliBridgeRun(options, environmentInput, turn, providerName, environmentId, useNativeInteractions, args.acceptedContextTransfer);
             return dispatchCliBridgeTurn(options, environmentInput, prepared, transport, providerName, runs, sessions, nativeSessions, useNativeInteractions);
         },
         session(id, sessionOptions) {
@@ -99,6 +100,7 @@ export function createCliBridgeEnvironment(args) {
                 interactionsEnabled: respondToInteraction !== undefined,
                 useNativeInteractions,
                 selectedModel: args.selectedModel,
+                acceptedContextTransfer: args.acceptedContextTransfer,
             });
         },
         ...(respondToInteraction ? { respondToInteraction } : {}),
@@ -243,14 +245,14 @@ function createCliBridgeSession(args) {
                 throw new Error(`cli-bridge session "${args.id}" cannot prompt session "${input.sessionId}"`);
             }
             if (args.selectedModel !== undefined &&
-                args.capabilities.retainedControl !== undefined) {
+                (args.capabilities.retainedControl !== undefined || args.acceptedContextTransfer !== 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.providerName, args.environmentId, args.useNativeInteractions);
+            }, args.providerName, args.environmentId, args.useNativeInteractions, args.acceptedContextTransfer);
             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

@@ -33,6 +33,7 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pro
     let admitted = false;
     let admissionValidated = false;
     try {
+        await confirmCliBridgeContextTransfer(options, originalTurn, run, signal);
         if (useNativeInteractions) {
             await beginCliBridgeNativeTurn(options, providerName, environmentInput, turn, run, transport, nativeSessions, signal, () => {
                 admitted = true;
@@ -51,7 +52,6 @@ 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);
@@ -112,6 +112,7 @@ export async function dispatchCliBridgeTurn(options, environmentInput, prepared,
     let accepted = false;
     let responseBody;
     try {
+        await confirmCliBridgeContextTransfer(options, prepared.turn, run, signal);
         if (useNativeInteractions) {
             await beginCliBridgeNativeTurn(options, providerName, environmentInput, prepared.turn, run, transport, nativeSessions, signal, () => {
                 accepted = true;
@@ -146,7 +147,6 @@ 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;
@@ -202,7 +202,11 @@ async function confirmCliBridgeContextTransfer(options, turn, run, signal) {
     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");
+        throw new CliBridgeRequestRejectedError(409, "cli-bridge did not confirm admitted portable context");
+    }
+    if (transfer.environmentId !== run.environmentId || transfer.sessionId !== run.sessionId ||
+        transfer.runId !== run.id || transfer.executionId !== run.executionId) {
+        throw new CliBridgeRequestRejectedError(409, "cli-bridge portable context belongs to another environment or run");
     }
     run.contextTransferReceipt = transfer;
 }

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

@@ -1,4 +1,4 @@
-import { type AgentExactRunControlRef, type AgentRunControlRef, type Sha256Digest } from "@tangle-network/agent-interface";
+import { type ContextTransferRequest, 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";
@@ -37,7 +37,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, providerName: string, environmentId: string, requireStableIdentity?: boolean): PreparedCliBridgeRun;
+export declare function prepareCliBridgeRun(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, originalTurn: AgentTurnInput, providerName: string, environmentId: string, requireStableIdentity?: boolean, acceptedContextTransfer?: ContextTransferRequest): 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,4 +1,4 @@
-import { AgentExactRunControlRefSchema, AgentTurnInputSchema, } from "@tangle-network/agent-interface";
+import { AgentExactRunControlRefSchema, AgentTurnInputSchema, canonicalAgentProfileDigest, } from "@tangle-network/agent-interface";
 import { assertCliBridgeRunId, cliBridgeRunId, toChatCompletionsBody, } from "./wire.js";
 export function exactControlRefForRun(run, providerName) {
     if (!run.sessionId || !run.requestDigest) {
@@ -70,8 +70,12 @@ 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, providerName, environmentId, requireStableIdentity = false) {
+export function prepareCliBridgeRun(options, environmentInput, originalTurn, providerName, environmentId, requireStableIdentity = false, acceptedContextTransfer) {
     const validatedTurn = AgentTurnInputSchema.parse(originalTurn);
+    if (acceptedContextTransfer !== undefined && (validatedTurn.contextTransfer?.requestDigest !== acceptedContextTransfer.requestDigest ||
+        (validatedTurn.profile !== undefined && canonicalAgentProfileDigest(validatedTurn.profile) !== acceptedContextTransfer.plan.destination.profileDigest))) {
+        throw new Error("CLI Bridge turn conflicts with its accepted context transfer");
+    }
     if (requireStableIdentity &&
         (validatedTurn.turnId === undefined || validatedTurn.executionId === undefined)) {
         throw new Error("native cli-bridge turns require stable turnId and executionId");
@@ -83,7 +87,7 @@ export function prepareCliBridgeRun(options, environmentInput, originalTurn, pro
     const executionId = validatedTurn.executionId ?? destination?.executionId ?? runId;
     if (destination !== undefined &&
         (destination.provider !== providerName ||
-            destination.environmentId !== environmentId ||
+            (destination.environmentId !== undefined && destination.environmentId !== environmentId) ||
             destination.sessionId !== sessionId ||
             destination.executionId !== executionId)) {
         throw new Error("cli-bridge context transfer targets another destination");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "1.1.2",
+  "version": "2.0.0",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -64,10 +64,11 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^3.0.0",
+    "@tangle-network/agent-interface": "^5.0.0",
     "undici": "8.11.2"
   },
   "devDependencies": {
+    "@tangle-network/agent-provider-testkit": "0.12.0",
     "@types/node": "26.6.3",
     "typescript": "7.0.2",
     "vitest": "5.0.2"