@tangle-network/agent-provider-cli-bridge 0.8.1 → 0.9.0

package/dist/capability-discovery.js

@@ -1,5 +1,5 @@
 import { AgentEnvironmentCapabilitiesSchema, } from "@tangle-network/agent-interface/environment-provider";
-import { supportsCliBridgeNativeInteractions } from "./retained-native.js";
+import { supportsCliBridgeNativeContinuation, supportsCliBridgeNativeInteractions, } from "./retained-native.js";
 import { createCliBridgeTransport, requestHeaders, trimSlash, } from "./transport.js";
 /** Read the retained contract from the exact Bridge model route. */
 export async function discoverCliBridgeCapabilities(options, model) {
@@ -60,13 +60,21 @@ export function narrowCliBridgeCapabilities(adapter, reported, selectedBackend,
         detach: adapter.streaming.detach && reported.streaming.detach,
         turnIdempotency: adapter.streaming.turnIdempotency && reported.streaming.turnIdempotency,
     };
+    const nativeContinuation = supportsCliBridgeNativeContinuation(adapter) &&
+        supportsCliBridgeNativeContinuation(reported)
+        ? { atomicBoundary: true, requestIdempotency: true }
+        : undefined;
     const sessions = {
-        continue: adapter.sessions.continue && reported.sessions.continue,
+        continue: nativeContinuation !== undefined &&
+            adapter.sessions.continue &&
+            reported.sessions.continue,
         // The Bridge can list and inspect sessions, but this adapter exposes neither method.
         list: false,
         messages: false,
     };
-    const retainedControl = supportsRetainedControl(adapter) && supportsRetainedControl(reported)
+    const retainedControl = sessions.continue &&
+        supportsRetainedControl(adapter) &&
+        supportsRetainedControl(reported)
         ? {
             exactRunIdentity: true,
             resultIdentity: true,
@@ -111,6 +119,7 @@ export function narrowCliBridgeCapabilities(adapter, reported, selectedBackend,
         streaming,
         sessions,
         ...(retainedControl === undefined ? {} : { retainedControl }),
+        ...(nativeContinuation === undefined ? {} : { nativeContinuation }),
         ...(interactions === undefined ? {} : { interactions }),
         // Remote workspace support cannot create absent adapter methods.
         workspace: {

package/dist/index.js

@@ -148,13 +148,25 @@ export function defaultCliBridgeCapabilities(harness) {
             validation: false,
         },
         streaming: { live: true, replay: true, detach: true, turnIdempotency: true },
-        sessions: { continue: true, list: false, messages: false },
-        retainedControl: {
-            exactRunIdentity: true,
-            resultIdentity: true,
-            eventIdentity: true,
-            cancellationIdempotency: true,
+        sessions: {
+            continue: harness === "pi",
+            list: false,
+            messages: false,
         },
+        ...(harness === "pi"
+            ? {
+                retainedControl: {
+                    exactRunIdentity: true,
+                    resultIdentity: true,
+                    eventIdentity: true,
+                    cancellationIdempotency: true,
+                },
+                nativeContinuation: {
+                    atomicBoundary: true,
+                    requestIdempotency: true,
+                },
+            }
+            : {}),
         ...(harness === "pi"
             ? {
                 interactions: {

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, supportsCliBridgeNativeInteractions, } from "./retained-native.js";
+import { assertCliBridgeRequestedInteractions, assertCliBridgeNativeTurnModel, 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) {
@@ -253,6 +253,20 @@ function createCliBridgeSession(args) {
             const run = requireCurrentRun();
             return cancelExactCliBridgeRun(args.options, args.transport, run, request, cancelOptions?.signal);
         },
+        ...(supportsCliBridgeNativeContinuation(args.capabilities)
+            ? {
+                async contextBoundary(boundaryOptions) {
+                    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);
+                    if ("result" in result && result.result.usage !== undefined) {
+                        args.usageLog.record(result.controlRef.executionId, result.result.usage);
+                    }
+                    return result;
+                },
+            }
+            : {}),
         ...(respondToInteraction ? { respondToInteraction } : {}),
     };
 }

package/dist/retained-native.d.ts

@@ -1,5 +1,5 @@
 import type { AgentEnvironmentCapabilities, AgentTurnInput, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
-import { type Sha256Digest, type RequestedInteractions } from "@tangle-network/agent-interface";
+import { type AgentNativeContextContinuationOptions, type AgentNativeContextContinuationResult, type Sha256Digest, type NativeContextBoundaryProof, type NativeContextContinuationRequest, type RequestedInteractions } from "@tangle-network/agent-interface";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 import type { CliBridgeRun } from "./retained-run-state.js";
 import type { CliBridgeTransport } from "./transport.js";
@@ -12,10 +12,16 @@ export interface CliBridgeNativeSession {
 export type CliBridgeNativeSessionCache = Map<string, Promise<CliBridgeNativeSession>>;
 /** Interactions are valid only for the native retained Pi contract. */
 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;
 /** 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;
+/** 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>;
 /**
  * Create or reuse the server's retained native session for one external id.
  *

package/dist/retained-native.js

@@ -1,7 +1,9 @@
-import { AgentExactRunControlRefSchema, RequestedInteractionsSchema, canonicalCandidateDigest, } from "@tangle-network/agent-interface";
+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 { 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. */
 export function supportsCliBridgeNativeInteractions(capabilities, selectedBackend) {
     const interactions = capabilities.interactions;
@@ -18,6 +20,12 @@ export function supportsCliBridgeNativeInteractions(capabilities, selectedBacken
         retainedControl.eventIdentity &&
         retainedControl.cancellationIdempotency);
 }
+/** Native continuation is exposed only when the Bridge proves both guarantees. */
+export function supportsCliBridgeNativeContinuation(capabilities) {
+    return Boolean(capabilities.sessions.continue &&
+        capabilities.nativeContinuation?.atomicBoundary === true &&
+        capabilities.nativeContinuation.requestIdempotency === true);
+}
 /** Reject posture the selected environment did not advertise before transport use. */
 export function assertCliBridgeRequestedInteractions(capabilities, requested) {
     if (requested === undefined)
@@ -49,6 +57,194 @@ function piInteractionCapabilitiesMatch(interactions) {
         interactions.replay === true &&
         interactions.responseIdempotency === true);
 }
+/** Read the Bridge-owned exact boundary for the current retained run. */
+export async function readCliBridgeNativeContextBoundary(options, providerName, transport, run, signal) {
+    const controlRef = currentCliBridgeControlRef(run, providerName);
+    const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/sessions/${encodeURIComponent(controlRef.sessionId)}`, {
+        method: "GET",
+        headers: requestHeaders(options),
+        ...(signal ? { signal } : {}),
+    });
+    const responseText = await readBoundedResponseText(response, signal);
+    if (!response.ok) {
+        throw new CliBridgeRequestRejectedError(response.status, responseText);
+    }
+    const parsed = safeJson(responseText);
+    if (!parsed) {
+        throw new Error("cli-bridge native session boundary response is not a JSON object");
+    }
+    if (parsed.id !== undefined && parsed.id !== controlRef.sessionId) {
+        throw new Error("cli-bridge native session boundary response targets another session");
+    }
+    if (parsed.context_boundary === null)
+        return null;
+    const proof = NativeContextBoundaryProofSchema.safeParse(parsed.context_boundary);
+    if (!proof.success) {
+        throw new Error("cli-bridge native session returned an invalid context boundary", {
+            cause: proof.error,
+        });
+    }
+    assertBoundaryControlRef(proof.data, controlRef);
+    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) {
+    const exactRequest = NativeContextContinuationRequestSchema.parse(request);
+    const current = currentCliBridgeControlRef(run, providerName);
+    if (!sameControlRef(current, exactRequest.run)) {
+        throw new Error("cli-bridge native continuation targets another retained run");
+    }
+    if (nativeContextContinuationTurnDigest(continuationOptions.turn) !==
+        exactRequest.turnDigest) {
+        throw new Error("cli-bridge native continuation turn does not match its request digest");
+    }
+    const operation = continuationSignal(continuationOptions);
+    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 responseText = await readBoundedResponseText(response, operation.signal);
+        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);
+        }
+        return outcome;
+    }
+    finally {
+        operation.dispose();
+    }
+}
+function currentCliBridgeControlRef(run, providerName) {
+    if (run.controlRef !== undefined) {
+        const controlRef = AgentExactRunControlRefSchema.parse(run.controlRef);
+        if (!sameControlRef(controlRef, exactControlRefForRun(run, providerName))) {
+            throw new Error("cli-bridge retained run has a conflicting control reference");
+        }
+        return controlRef;
+    }
+    const controlRef = exactControlRefForRun(run, providerName);
+    run.controlRef = controlRef;
+    return controlRef;
+}
+function sameControlRef(left, right) {
+    return left.runId === right.runId &&
+        left.provider === right.provider &&
+        left.environmentId === right.environmentId &&
+        left.sessionId === right.sessionId &&
+        left.executionId === right.executionId &&
+        left.requestDigest === right.requestDigest;
+}
+function assertBoundaryControlRef(proof, controlRef) {
+    if (proof.runId !== controlRef.runId ||
+        proof.provider !== controlRef.provider ||
+        proof.environmentId !== controlRef.environmentId ||
+        proof.sessionId !== controlRef.sessionId ||
+        proof.executionId !== controlRef.executionId ||
+        proof.requestDigest !== controlRef.requestDigest) {
+        throw new Error("cli-bridge native session boundary does not bind to the retained run");
+    }
+}
+function parseNativeContinuationResult(value) {
+    const parsed = safeJson(value);
+    try {
+        return AgentNativeContextContinuationResultSchema.parse(parsed);
+    }
+    catch (error) {
+        throw new Error("cli-bridge native continuation returned an invalid result", {
+            cause: error,
+        });
+    }
+}
+function assertContinuationAcknowledgementBinding(request, outcome) {
+    const acknowledgement = outcome.acknowledgement;
+    if (acknowledgement.operationId !== request.operationId ||
+        acknowledgement.requestDigest !== request.requestDigest ||
+        acknowledgement.historyMessagesSent !== 0) {
+        throw new Error("cli-bridge native continuation acknowledgement is not bound to the request");
+    }
+    if (acknowledgement.actualBoundary !== undefined) {
+        assertBoundaryControlRef(acknowledgement.actualBoundary, request.run);
+    }
+}
+function continuationSignal(options) {
+    const timeoutMs = options.timeoutMs;
+    if (timeoutMs !== undefined &&
+        (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 2_147_483_647)) {
+        throw new Error("native continuation timeoutMs must be an integer from 0 through 2147483647");
+    }
+    if (timeoutMs === undefined) {
+        return { signal: options.signal, dispose: () => { } };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort(new DOMException("native continuation timed out", "TimeoutError"));
+    }, timeoutMs);
+    const signal = options.signal === undefined
+        ? controller.signal
+        : AbortSignal.any([options.signal, controller.signal]);
+    return {
+        signal,
+        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.
  *

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

@@ -2,11 +2,11 @@ import { type AgentExactRunControlRef, type AgentRunControlRef, type Sha256Diges
 import type { AgentTurnInput, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 export interface CliBridgeRun {
-    readonly id: string;
+    id: string;
     readonly environmentId: string;
     readonly sessionId?: string;
-    readonly executionId: string;
-    readonly turnId: string;
+    executionId: string;
+    turnId: string;
     readonly requestBody: string;
     readonly readers: Set<AbortController>;
     requestDigest?: Sha256Digest;
@@ -31,6 +31,8 @@ export declare function exactControlRefForRun(run: CliBridgeRun, providerName: s
 export declare function exactControlRefForSession(value: AgentRunControlRef, providerName: string, environmentId: string, sessionId: string): AgentExactRunControlRef;
 export declare function runFromControlRef(controlRef: AgentExactRunControlRef): CliBridgeRun;
 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 bindCliBridgeRun(prepared: CliBridgeRun, runs: Map<string, CliBridgeRun>): CliBridgeRun | undefined;
 export declare function restoreCliBridgeRun(run: CliBridgeRun, previous: CliBridgeRun | undefined, runs: Map<string, CliBridgeRun>): void;

package/dist/retained-run-state.js

@@ -45,6 +45,28 @@ export function assertRunMatchesControlRef(run, controlRef) {
     }
     run.controlRef = controlRef;
 }
+/** Advance one session object to the exact run returned by native continuation. */
+export function advanceCliBridgeRun(run, controlRef, providerName, runs) {
+    if (controlRef.provider !== providerName ||
+        controlRef.environmentId !== run.environmentId ||
+        controlRef.sessionId !== run.sessionId) {
+        throw new Error("cli-bridge native continuation returned a run for another session");
+    }
+    const existing = runs.get(controlRef.runId);
+    if (existing !== undefined && existing !== run) {
+        throw new Error("cli-bridge native continuation returned a run already owned by another session");
+    }
+    const previousId = run.id;
+    if (runs.get(previousId) === run && previousId !== controlRef.runId) {
+        runs.delete(previousId);
+    }
+    run.id = controlRef.runId;
+    run.executionId = controlRef.executionId;
+    run.turnId = controlRef.executionId;
+    run.requestDigest = controlRef.requestDigest;
+    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)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "AgentEnvironmentProvider adapter for cli-bridge retained sessions and one-shot turns",
   "type": "module",
   "license": "MIT",
@@ -59,7 +59,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "^1.0.1",
+    "@tangle-network/agent-interface": "^1.3.0",
     "undici": "7.29.0"
   },
   "devDependencies": {