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

package/dist/capability-discovery.js

@@ -63,7 +63,14 @@ 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 sessions = {
         continue: adapter.sessions.continue && reported.sessions.continue,

package/dist/index.js

@@ -176,6 +176,7 @@ export function defaultCliBridgeCapabilities(harness) {
                 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-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "0.9.6",
+  "version": "0.10.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.5.0",
+    "@tangle-network/agent-interface": "^1.8.0",
     "undici": "7.29.0"
   },
   "devDependencies": {