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

package/dist/retained-environment.js

@@ -1,6 +1,8 @@
 import { agentSessionStatusFromRun, cancelCliBridgeRun, cancelExactCliBridgeRun, getCliBridgeRun, } from "./retained-control.js";
 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 { assertRunMatchesControlRef, exactControlRefForSession, prepareCliBridgeRun, runFromControlRef, } from "./retained-run-state.js";
 import { createCliBridgeTransport } from "./transport.js";
 export function createCliBridgeEnvironment(args) {
@@ -8,8 +10,18 @@ export function createCliBridgeEnvironment(args) {
     const transport = createCliBridgeTransport(options);
     const runs = new Map();
     const sessions = new Map();
+    const nativeSessions = new Map();
     const readers = new Set();
     const usageLog = createExecutionUsageLog();
+    const useNativeInteractions = supportsCliBridgeNativeInteractions(args.capabilities, args.selectedBackend);
+    const respondToInteraction = useNativeInteractions
+        ? cliBridgeInteractionResponder({
+            options,
+            transport,
+            providerName,
+            environmentId,
+        })
+        : undefined;
     let destroyed = false;
     let closePromise;
     const stream = async function* (turn) {
@@ -18,11 +30,15 @@ export function createCliBridgeEnvironment(args) {
         if (!args.allowDispatch) {
             throw new Error("a reconstructed cli-bridge environment can only control an existing run");
         }
-        const prepared = prepareCliBridgeRun(options, environmentInput, turn, environmentId, false);
+        if (useNativeInteractions) {
+            assertCliBridgeNativeTurnModel(options, environmentInput, turn, args.selectedModel);
+        }
+        assertCliBridgeRequestedInteractions(args.capabilities, turn.interactions);
+        const prepared = prepareCliBridgeRun(options, environmentInput, turn, environmentId, useNativeInteractions);
         // A streamed run reports usage across its events, so the totals are summed
         // here and recorded as one execution's measurement.
         let streamedUsage;
-        for await (const event of streamTrackedCliBridgeTurn(options, environmentInput, prepared, transport, runs, sessions, readers)) {
+        for await (const event of streamTrackedCliBridgeTurn(options, environmentInput, providerName, prepared, transport, runs, sessions, readers, nativeSessions, useNativeInteractions)) {
             streamedUsage = addTokenUsage(streamedUsage, event.usage);
             usageLog.record(prepared.run.executionId, streamedUsage);
             yield event;
@@ -31,6 +47,7 @@ export function createCliBridgeEnvironment(args) {
     return {
         id: environmentId,
         provider: providerName,
+        capabilities: args.capabilities,
         ...(environmentInput.name ? { name: environmentInput.name } : {}),
         status: async (statusOptions) => {
             statusOptions?.signal?.throwIfAborted();
@@ -43,8 +60,12 @@ export function createCliBridgeEnvironment(args) {
             if (!args.allowDispatch) {
                 throw new Error("a reconstructed cli-bridge environment cannot dispatch new work");
             }
+            if (useNativeInteractions) {
+                assertCliBridgeNativeTurnModel(options, environmentInput, turn, args.selectedModel);
+            }
+            assertCliBridgeRequestedInteractions(args.capabilities, turn.interactions);
             const prepared = prepareCliBridgeRun(options, environmentInput, turn, environmentId, true);
-            return dispatchCliBridgeTurn(options, environmentInput, prepared, transport, providerName, runs, sessions);
+            return dispatchCliBridgeTurn(options, environmentInput, prepared, transport, providerName, runs, sessions, nativeSessions, useNativeInteractions);
         },
         session(id, sessionOptions) {
             sessionOptions?.signal?.throwIfAborted();
@@ -58,12 +79,18 @@ export function createCliBridgeEnvironment(args) {
                 runs,
                 sessions,
                 readers,
+                nativeSessions,
                 allowPrompt: args.allowDispatch,
                 requestedControlRef: sessionOptions?.controlRef,
                 isDestroyed: () => destroyed,
                 usageLog,
+                capabilities: args.capabilities,
+                interactionsEnabled: respondToInteraction !== undefined,
+                useNativeInteractions,
+                selectedModel: args.selectedModel,
             });
         },
+        ...(respondToInteraction ? { respondToInteraction } : {}),
         ...(args.capabilities.observation
             ? {
                 async observe(observeOptions) {
@@ -112,6 +139,7 @@ export function createCliBridgeEnvironment(args) {
                 }
                 await transport.close();
                 sessions.clear();
+                nativeSessions.clear();
                 runs.clear();
             })();
             closePromise = attempt;
@@ -165,6 +193,15 @@ function createCliBridgeSession(args) {
             throw new Error(`cli-bridge session "${args.id}" has no run`);
         return run;
     };
+    const respondToInteraction = args.interactionsEnabled
+        ? cliBridgeInteractionResponder({
+            sessionId: args.id,
+            options: args.options,
+            transport: args.transport,
+            providerName: args.providerName,
+            environmentId: args.environmentId,
+        })
+        : undefined;
     return {
         id: args.id,
         get controlRef() {
@@ -181,11 +218,11 @@ function createCliBridgeSession(args) {
         },
         async *events(eventOptions) {
             const run = requireCurrentRun();
-            yield* streamCliBridgeSessionEvents(args.options, args.environmentInput, run, args.transport, args.runs, args.readers, eventOptions);
+            yield* streamCliBridgeSessionEvents(args.options, args.environmentInput, args.providerName, run, args.transport, args.runs, args.readers, eventOptions);
         },
         async result(resultOptions) {
             const run = requireCurrentRun();
-            const result = await collectCliBridgeTurnResult(streamCliBridgeSessionEvents(args.options, args.environmentInput, run, args.transport, args.runs, args.readers, { since: "0", signal: resultOptions?.signal }), run, args.options, args.transport, resultOptions?.signal);
+            const result = await collectCliBridgeTurnResult(streamCliBridgeSessionEvents(args.options, args.environmentInput, args.providerName, run, args.transport, args.runs, args.readers, { since: "0", signal: resultOptions?.signal }), run, args.options, args.transport, resultOptions?.signal);
             args.usageLog.record(run.executionId, result.usage);
             return result;
         },
@@ -196,11 +233,15 @@ function createCliBridgeSession(args) {
             if (input.sessionId && input.sessionId !== args.id) {
                 throw new Error(`cli-bridge session "${args.id}" cannot prompt session "${input.sessionId}"`);
             }
+            if (args.useNativeInteractions) {
+                assertCliBridgeNativeTurnModel(args.options, args.environmentInput, input, args.selectedModel);
+            }
+            assertCliBridgeRequestedInteractions(args.capabilities, input.interactions);
             const prepared = prepareCliBridgeRun(args.options, args.environmentInput, {
                 ...input,
                 sessionId: args.id,
-            }, args.environmentId, false);
-            const result = await collectCliBridgeTurnResult(streamTrackedCliBridgeTurn(args.options, args.environmentInput, prepared, args.transport, args.runs, args.sessions, args.readers), prepared.run, args.options, args.transport, input.signal);
+            }, args.environmentId, args.useNativeInteractions);
+            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 };
         },
@@ -212,5 +253,6 @@ function createCliBridgeSession(args) {
             const run = requireCurrentRun();
             return cancelExactCliBridgeRun(args.options, args.transport, run, request, cancelOptions?.signal);
         },
+        ...(respondToInteraction ? { respondToInteraction } : {}),
     };
 }

package/dist/retained-execution.d.ts

@@ -2,10 +2,11 @@ import type { TokenUsage } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentEvent, AgentSessionRef, AgentTurnResult, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 import { type CliBridgeRun, type CliBridgeSessionState, type PreparedCliBridgeRun } from "./retained-run-state.js";
+import { type CliBridgeNativeSessionCache } from "./retained-native.js";
 import type { CliBridgeTransport } from "./transport.js";
-export declare function streamTrackedCliBridgeTurn(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, prepared: PreparedCliBridgeRun, transport: CliBridgeTransport, runs: Map<string, CliBridgeRun>, sessions: Map<string, CliBridgeSessionState>, readers: Set<AbortController>): AsyncIterable<AgentEnvironmentEvent>;
-export declare function dispatchCliBridgeTurn(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, prepared: PreparedCliBridgeRun, transport: CliBridgeTransport, providerName: string, runs: Map<string, CliBridgeRun>, sessions: Map<string, CliBridgeSessionState>): Promise<AgentSessionRef>;
-export declare function streamCliBridgeSessionEvents(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, run: CliBridgeRun, transport: CliBridgeTransport, runs: Map<string, CliBridgeRun>, readers: Set<AbortController>, eventOptions?: {
+export declare function streamTrackedCliBridgeTurn(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, providerName: string, prepared: PreparedCliBridgeRun, transport: CliBridgeTransport, runs: Map<string, CliBridgeRun>, sessions: Map<string, CliBridgeSessionState>, readers: Set<AbortController>, nativeSessions: CliBridgeNativeSessionCache, useNativeInteractions: boolean): AsyncIterable<AgentEnvironmentEvent>;
+export declare function dispatchCliBridgeTurn(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, prepared: PreparedCliBridgeRun, transport: CliBridgeTransport, providerName: string, runs: Map<string, CliBridgeRun>, sessions: Map<string, CliBridgeSessionState>, nativeSessions: CliBridgeNativeSessionCache, useNativeInteractions: boolean): Promise<AgentSessionRef>;
+export declare function streamCliBridgeSessionEvents(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, providerName: string, run: CliBridgeRun, transport: CliBridgeTransport, runs: Map<string, CliBridgeRun>, readers: Set<AbortController>, eventOptions?: {
     since?: string;
     executionId?: string;
     signal?: AbortSignal;

package/dist/retained-execution.js

@@ -1,9 +1,10 @@
 import { cancelCliBridgeRun, captureCliBridgeRunIdentity, detachCliBridgeReader, getCliBridgeRun, } from "./retained-control.js";
 import { bindCliBridgeRun, bindCliBridgeSession, exactControlRefForRun, restoreCliBridgeRun, restoreCliBridgeSession, } from "./retained-run-state.js";
 import { CliBridgeRequestRejectedError, streamCliBridgeTurn, } from "./retained-stream.js";
+import { beginCliBridgeNativeTurn, } from "./retained-native.js";
 import { requestHeaders, trimSlash } from "./transport.js";
 import { modelRequestCount } from "./wire.js";
-export async function* streamTrackedCliBridgeTurn(options, environmentInput, prepared, transport, runs, sessions, readers) {
+export async function* streamTrackedCliBridgeTurn(options, environmentInput, providerName, prepared, transport, runs, sessions, readers, nativeSessions, useNativeInteractions) {
     const originalTurn = prepared.turn;
     if (originalTurn.detach) {
         throw new Error("cli-bridge provider does not support detached turns");
@@ -26,9 +27,26 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pre
     readers.add(controller);
     let drained = false;
     let threw = false;
+    let admitted = false;
+    let admissionValidated = false;
     try {
-        for await (const event of streamCliBridgeTurn(options, turn, run.requestBody, transport, run.id, originalTurn.lastEventId, signal, (response) => captureCliBridgeRunIdentity(response, run, true), () => getCliBridgeRun(options, transport, run, 30_000, signal))) {
-            yield event;
+        if (useNativeInteractions) {
+            await beginCliBridgeNativeTurn(options, providerName, environmentInput, turn, run, transport, nativeSessions, signal, () => {
+                admitted = true;
+            });
+            admissionValidated = true;
+            for await (const event of streamCliBridgeTurn(options, turn, undefined, transport, run.id, originalTurn.lastEventId, signal, (response) => captureCliBridgeRunIdentity(response, run, false), () => getCliBridgeRun(options, transport, run, 30_000, signal), (event) => assertCanonicalEventBinding(event.normalized, run, providerName))) {
+                yield event;
+            }
+        }
+        else {
+            for await (const event of streamCliBridgeTurn(options, turn, run.requestBody, transport, run.id, originalTurn.lastEventId, signal, (response) => {
+                admitted = true;
+                captureCliBridgeRunIdentity(response, run, true);
+                admissionValidated = true;
+            }, () => getCliBridgeRun(options, transport, run, 30_000, signal))) {
+                yield event;
+            }
         }
         drained = true;
         if (runs.get(run.id) === run)
@@ -36,7 +54,7 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pre
     }
     catch (error) {
         threw = true;
-        if (error instanceof CliBridgeRequestRejectedError) {
+        if (error instanceof CliBridgeRequestRejectedError && !admitted) {
             restoreCliBridgeRun(run, previousRun, runs);
             restoreCliBridgeSession(run, previousSessionRun, sessions);
             throw error;
@@ -52,8 +70,13 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pre
             if (runs.get(run.id) === run)
                 runs.delete(run.id);
         }
-        else if (originalTurn.signal?.aborted || environmentInput.signal?.aborted) {
-            await cancelCliBridgeRun(options, transport, run);
+        else if ((admitted && !admissionValidated) ||
+            originalTurn.signal?.aborted ||
+            environmentInput.signal?.aborted) {
+            const cancellation = await cancelCliBridgeRun(options, transport, run);
+            if (cancellation.requestDigest !== undefined) {
+                run.requestDigest = cancellation.requestDigest;
+            }
             if (runs.get(run.id) === run)
                 runs.delete(run.id);
         }
@@ -68,7 +91,7 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pre
         readers.delete(controller);
     }
 }
-export async function dispatchCliBridgeTurn(options, environmentInput, prepared, transport, providerName, runs, sessions) {
+export async function dispatchCliBridgeTurn(options, environmentInput, prepared, transport, providerName, runs, sessions, nativeSessions, useNativeInteractions) {
     const run = prepared.run;
     const previousRun = bindCliBridgeRun(run, runs);
     const previousSessionRun = bindCliBridgeSession(run, sessions);
@@ -80,35 +103,44 @@ export async function dispatchCliBridgeTurn(options, environmentInput, prepared,
     let accepted = false;
     let responseBody;
     try {
-        const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/chat/completions`, {
-            method: "POST",
-            headers: {
-                ...requestHeaders(options),
-                accept: "text/event-stream",
-                ...(run.sessionId ? { "x-session-id": run.sessionId } : {}),
-            },
-            body: run.requestBody,
-            ...(signal ? { signal } : {}),
-        });
-        if (!response.ok) {
-            let detail = "request rejected";
-            try {
-                detail = await response.text();
-            }
-            catch {
-                // The HTTP status already proves this request was rejected.
+        if (useNativeInteractions) {
+            await beginCliBridgeNativeTurn(options, providerName, environmentInput, prepared.turn, run, transport, nativeSessions, signal, () => {
+                accepted = true;
+            });
+        }
+        else {
+            const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/chat/completions`, {
+                method: "POST",
+                headers: {
+                    ...requestHeaders(options),
+                    accept: "text/event-stream",
+                    ...(run.sessionId ? { "x-session-id": run.sessionId } : {}),
+                },
+                body: run.requestBody,
+                ...(signal ? { signal } : {}),
+            });
+            if (!response.ok) {
+                let detail = "request rejected";
+                try {
+                    detail = await response.text();
+                }
+                catch {
+                    // The HTTP status already proves this request was rejected.
+                }
+                throw new CliBridgeRequestRejectedError(response.status, detail);
             }
-            throw new CliBridgeRequestRejectedError(response.status, detail);
+            accepted = true;
+            if (!response.body)
+                throw new Error("cli-bridge response body is empty");
+            responseBody = response.body;
+            captureCliBridgeRunIdentity(response, run, true);
         }
-        accepted = true;
-        if (!response.body)
-            throw new Error("cli-bridge response body is empty");
-        responseBody = response.body;
-        captureCliBridgeRunIdentity(response, run, true);
         const controlRef = exactControlRefForRun(run, providerName);
         run.controlRef = controlRef;
-        await detachCliBridgeReader(responseBody);
-        responseBody = undefined;
+        if (responseBody) {
+            await detachCliBridgeReader(responseBody);
+            responseBody = undefined;
+        }
         return {
             id: run.sessionId,
             provider: providerName,
@@ -151,7 +183,7 @@ export async function dispatchCliBridgeTurn(options, environmentInput, prepared,
         throw failure;
     }
 }
-export async function* streamCliBridgeSessionEvents(options, environmentInput, run, transport, runs, readers, eventOptions) {
+export async function* streamCliBridgeSessionEvents(options, environmentInput, providerName, run, transport, runs, readers, eventOptions) {
     if (eventOptions?.executionId !== undefined &&
         eventOptions.executionId !== run.executionId) {
         throw new Error("cli-bridge event request targets another retained execution");
@@ -171,7 +203,7 @@ export async function* streamCliBridgeSessionEvents(options, environmentInput, r
             ...(run.sessionId ? { sessionId: run.sessionId } : {}),
             executionId: run.executionId,
             turnId: run.turnId,
-        }, undefined, transport, run.id, eventOptions?.since ?? "0", signal, (response) => captureCliBridgeRunIdentity(response, run, false), () => getCliBridgeRun(options, transport, run, 30_000, signal));
+        }, undefined, transport, run.id, eventOptions?.since ?? "0", signal, (response) => captureCliBridgeRunIdentity(response, run, false), () => getCliBridgeRun(options, transport, run, 30_000, signal), (event) => assertCanonicalEventBinding(event.normalized, run, providerName));
         drained = true;
         if (runs.get(run.id) === run)
             runs.delete(run.id);
@@ -184,6 +216,19 @@ export async function* streamCliBridgeSessionEvents(options, environmentInput, r
         readers.delete(controller);
     }
 }
+function assertCanonicalEventBinding(event, run, providerName) {
+    if (event?.type !== "interaction")
+        return;
+    const binding = event.request.binding;
+    if (binding.runId !== run.id ||
+        binding.provider !== providerName ||
+        binding.environmentId !== run.environmentId ||
+        binding.sessionId !== run.sessionId ||
+        binding.executionId !== run.executionId ||
+        binding.interactionId !== event.request.id) {
+        throw new Error("cli-bridge interaction event does not bind to the retained run");
+    }
+}
 export async function collectCliBridgeTurnResult(source, run, options, transport, signal) {
     const events = [];
     let text = "";

package/dist/retained-native.d.ts

@@ -0,0 +1,27 @@
+import type { AgentEnvironmentCapabilities, AgentTurnInput, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import { type Sha256Digest, 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";
+/** The server-owned native session identity cached by one provider handle. */
+export interface CliBridgeNativeSession {
+    readonly id: string;
+    readonly model: string;
+    readonly createRequestDigest: Sha256Digest;
+}
+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;
+/** 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;
+/**
+ * Create or reuse the server's retained native session for one external id.
+ *
+ * The cache stores the promise so concurrent first turns cannot create two
+ * native sessions for the same id.
+ */
+export declare function ensureCliBridgeNativeSession(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, turn: AgentTurnInput, sessionId: string, transport: CliBridgeTransport, sessions: CliBridgeNativeSessionCache, signal?: AbortSignal): Promise<CliBridgeNativeSession>;
+/** Admit one native retained turn and bind its server digest to the run. */
+export declare function beginCliBridgeNativeTurn(options: CliBridgeProviderOptions, providerName: string, environmentInput: CreateAgentEnvironmentInput, turn: AgentTurnInput, run: CliBridgeRun, transport: CliBridgeTransport, sessions: CliBridgeNativeSessionCache, signal?: AbortSignal, onAdmission?: () => void): Promise<void>;

package/dist/retained-native.js

@@ -0,0 +1,204 @@
+import { AgentExactRunControlRefSchema, RequestedInteractionsSchema, canonicalCandidateDigest, } from "@tangle-network/agent-interface";
+import { CliBridgeRequestRejectedError } from "./retained-stream.js";
+import { requestHeaders, trimSlash, } from "./transport.js";
+import { inlineProfile, safeJson, resolveBridgeModel, toRetainedSessionBody, toRetainedTurnBody, } from "./wire.js";
+/** Interactions are valid only for the native retained Pi contract. */
+export function supportsCliBridgeNativeInteractions(capabilities, selectedBackend) {
+    const interactions = capabilities.interactions;
+    const retainedControl = capabilities.retainedControl;
+    return Boolean(selectedBackend === "pi" &&
+        piInteractionCapabilitiesMatch(interactions) &&
+        capabilities.streaming.live &&
+        capabilities.streaming.replay &&
+        capabilities.streaming.detach &&
+        capabilities.streaming.turnIdempotency &&
+        capabilities.sessions.continue &&
+        retainedControl?.exactRunIdentity &&
+        retainedControl.resultIdentity &&
+        retainedControl.eventIdentity &&
+        retainedControl.cancellationIdempotency);
+}
+/** Reject posture the selected environment did not advertise before transport use. */
+export function assertCliBridgeRequestedInteractions(capabilities, requested) {
+    if (requested === undefined)
+        return;
+    const parsed = RequestedInteractionsSchema.parse(requested);
+    const advertised = new Set(capabilities.interactions?.kinds ?? []);
+    const unsupported = Object.keys(parsed).filter((kind) => !advertised.has(kind));
+    if (unsupported.length > 0) {
+        throw new Error(`cli-bridge environment does not advertise requested interaction kind(s): ${unsupported.join(", ")}`);
+    }
+}
+/** Keep capability discovery and every native turn on one exact model route. */
+export function assertCliBridgeNativeTurnModel(options, environmentInput, turn, selectedModel) {
+    if (selectedModel === undefined) {
+        throw new Error("cli-bridge native interactions require an environment model");
+    }
+    const requestedModel = resolveBridgeModel(options, environmentInput, turn, inlineProfile(environmentInput.profile));
+    if (requestedModel !== selectedModel) {
+        throw new Error(`cli-bridge native environment model is ${JSON.stringify(selectedModel)}; create another environment for ${JSON.stringify(requestedModel)}`);
+    }
+}
+function piInteractionCapabilitiesMatch(interactions) {
+    return Boolean(interactions &&
+        interactions.kinds.includes("permission") &&
+        interactions.answerFieldTypes.includes("select") &&
+        interactions.responseScopes.includes("interaction") &&
+        interactions.secretAnswers === false &&
+        interactions.concurrentRequests === false &&
+        interactions.replay === true &&
+        interactions.responseIdempotency === true);
+}
+/**
+ * Create or reuse the server's retained native session for one external id.
+ *
+ * The cache stores the promise so concurrent first turns cannot create two
+ * native sessions for the same id.
+ */
+export async function ensureCliBridgeNativeSession(options, environmentInput, turn, sessionId, transport, sessions, signal) {
+    const profile = inlineProfile(environmentInput.profile);
+    const model = resolveBridgeModel(options, environmentInput, turn, profile);
+    const existing = sessions.get(sessionId);
+    if (existing) {
+        const session = await existing;
+        assertNativeSessionModel(session, model);
+        return session;
+    }
+    const pending = createCliBridgeNativeSession(options, environmentInput, profile, sessionId, model, transport, signal);
+    sessions.set(sessionId, pending);
+    try {
+        const session = await pending;
+        assertNativeSessionModel(session, model);
+        return session;
+    }
+    catch (error) {
+        if (sessions.get(sessionId) === pending)
+            sessions.delete(sessionId);
+        throw error;
+    }
+}
+async function createCliBridgeNativeSession(options, environmentInput, profile, sessionId, model, transport, signal) {
+    const body = toRetainedSessionBody(options, environmentInput, profile, sessionId, model);
+    const createRequestDigest = canonicalCandidateDigest(body);
+    const url = `${trimSlash(options.baseUrl)}/v1/sessions`;
+    const init = {
+        method: "POST",
+        headers: requestHeaders(options),
+        body: JSON.stringify(body),
+        ...(signal ? { signal } : {}),
+    };
+    const response = await transport.fetch(url, init);
+    if (response.status === 409) {
+        return recoverConflictingNativeSession(options, sessionId, model, createRequestDigest, transport, signal, response);
+    }
+    if (!response.ok) {
+        throw new CliBridgeRequestRejectedError(response.status, await response.text());
+    }
+    return parseNativeSessionView(await response.text(), sessionId, model, createRequestDigest);
+}
+async function recoverConflictingNativeSession(options, sessionId, model, createRequestDigest, transport, signal, conflictResponse) {
+    await conflictResponse.text();
+    const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/sessions/${encodeURIComponent(sessionId)}`, {
+        method: "GET",
+        headers: requestHeaders(options),
+        ...(signal ? { signal } : {}),
+    });
+    if (!response.ok) {
+        throw new CliBridgeRequestRejectedError(response.status, `session ${JSON.stringify(sessionId)} could not be recovered: ${await response.text()}`);
+    }
+    return parseNativeSessionView(await response.text(), sessionId, model, createRequestDigest);
+}
+function parseNativeSessionView(value, expectedId, expectedModel, expectedCreateRequestDigest) {
+    const parsed = safeJson(value);
+    const id = parsed?.id;
+    const model = parsed?.model;
+    const digest = parsed?.create_request_digest;
+    const parsedDigest = AgentExactRunControlRefSchema.shape.requestDigest.safeParse(digest);
+    if (typeof id !== "string" ||
+        typeof model !== "string" ||
+        !parsedDigest.success) {
+        throw new Error("cli-bridge retained session returned an invalid session view");
+    }
+    if (id !== expectedId) {
+        throw new Error(`cli-bridge returned session ${JSON.stringify(id)} for requested session ${JSON.stringify(expectedId)}`);
+    }
+    if (model !== expectedModel) {
+        throw new Error(`cli-bridge retained session ${JSON.stringify(expectedId)} is bound to model ${JSON.stringify(model)}`);
+    }
+    if (parsedDigest.data !== expectedCreateRequestDigest) {
+        throw new Error(`cli-bridge retained session ${JSON.stringify(expectedId)} has a different creation request digest`);
+    }
+    return {
+        id,
+        model,
+        createRequestDigest: parsedDigest.data,
+    };
+}
+function assertNativeSessionModel(session, expectedModel) {
+    if (session.model !== expectedModel) {
+        throw new Error(`cli-bridge retained session ${JSON.stringify(session.id)} cannot change model from ${JSON.stringify(session.model)} to ${JSON.stringify(expectedModel)}`);
+    }
+}
+/** Admit one native retained turn and bind its server digest to the run. */
+export async function beginCliBridgeNativeTurn(options, providerName, environmentInput, turn, run, transport, sessions, signal, onAdmission) {
+    if (!run.sessionId) {
+        throw new Error("cli-bridge native retained turns require a session id");
+    }
+    const body = toRetainedTurnBody(turn, run, providerName);
+    const nativeSession = await ensureCliBridgeNativeSession(options, environmentInput, turn, run.sessionId, transport, sessions, signal);
+    const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/sessions/${encodeURIComponent(run.sessionId)}/turns`, {
+        method: "POST",
+        headers: requestHeaders(options),
+        body: JSON.stringify(body),
+        ...(signal ? { signal } : {}),
+    });
+    if (!response.ok) {
+        throw new CliBridgeRequestRejectedError(response.status, await response.text());
+    }
+    onAdmission?.();
+    const parsed = safeJson(await response.text());
+    const responseSession = parsed?.session;
+    const responseRun = parsed?.run;
+    const responseSessionId = responseSession && typeof responseSession === "object"
+        ? responseSession.id
+        : undefined;
+    const responseSessionModel = responseSession && typeof responseSession === "object"
+        ? responseSession.model
+        : undefined;
+    const responseSessionDigest = responseSession && typeof responseSession === "object"
+        ? responseSession.create_request_digest
+        : undefined;
+    const parsedSessionDigest = AgentExactRunControlRefSchema.shape.requestDigest.safeParse(responseSessionDigest);
+    const runId = responseRun && typeof responseRun === "object"
+        ? responseRun.id
+        : undefined;
+    const responseSessionIdFromRun = responseRun && typeof responseRun === "object"
+        ? responseRun.sessionId
+        : undefined;
+    const executionId = responseRun && typeof responseRun === "object"
+        ? responseRun.executionId
+        : undefined;
+    const requestDigestValue = responseRun && typeof responseRun === "object"
+        ? responseRun.requestDigest
+        : undefined;
+    const requestDigest = AgentExactRunControlRefSchema.shape.requestDigest.safeParse(requestDigestValue);
+    if (!parsed ||
+        typeof responseSessionId !== "string" ||
+        responseSessionId !== run.sessionId ||
+        responseSessionModel !== nativeSession.model ||
+        !parsedSessionDigest.success ||
+        parsedSessionDigest.data !== nativeSession.createRequestDigest ||
+        typeof runId !== "string" ||
+        runId !== run.id ||
+        typeof responseSessionIdFromRun !== "string" ||
+        responseSessionIdFromRun !== run.sessionId ||
+        typeof executionId !== "string" ||
+        executionId !== run.executionId ||
+        !requestDigest.success) {
+        throw new Error("cli-bridge retained turn returned mismatched run coordinates");
+    }
+    if (run.requestDigest !== undefined && run.requestDigest !== requestDigest.data) {
+        throw new Error("cli-bridge retained turn changed the admitted request digest");
+    }
+    run.requestDigest = requestDigest.data;
+}

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

@@ -20,7 +20,7 @@ export interface CliBridgeSessionState {
 export interface CliBridgeRunSnapshot {
     readonly id: string;
     readonly requestDigest?: Sha256Digest;
-    readonly status: "running" | "done" | "error" | "cancelled";
+    readonly status: "running" | "done" | "error" | "cancelled" | "unknown";
     readonly terminal: boolean;
 }
 export interface PreparedCliBridgeRun {

package/dist/retained-run-state.js

@@ -46,6 +46,10 @@ export function assertRunMatchesControlRef(run, controlRef) {
     run.controlRef = controlRef;
 }
 export function prepareCliBridgeRun(options, environmentInput, originalTurn, environmentId, requireSession) {
+    if (requireSession &&
+        (originalTurn.turnId === undefined || originalTurn.executionId === undefined)) {
+        throw new Error("cli-bridge native retained turns require stable turnId and executionId values");
+    }
     const turnId = originalTurn.turnId ?? crypto.randomUUID();
     const runId = cliBridgeRunId(environmentId, originalTurn, turnId);
     const sessionId = originalTurn.sessionId ?? (requireSession ? runId : undefined);

package/dist/retained-stream.d.ts

@@ -6,4 +6,4 @@ export declare class CliBridgeRequestRejectedError extends Error {
     readonly status: number;
     constructor(status: number, detail: string);
 }
-export declare function streamCliBridgeTurn(options: CliBridgeProviderOptions, turn: AgentTurnInput, requestBody: string | undefined, transport: CliBridgeTransport, runId: string, lastEventId?: string, signal?: AbortSignal, onResponse?: (response: CliBridgeResponse) => void, readAuthoritativeRun?: () => Promise<CliBridgeRunSnapshot | null>): AsyncIterable<AgentEnvironmentEvent>;
+export declare function streamCliBridgeTurn(options: CliBridgeProviderOptions, turn: AgentTurnInput, requestBody: string | undefined, transport: CliBridgeTransport, runId: string, lastEventId?: string, signal?: AbortSignal, onResponse?: (response: CliBridgeResponse) => void, readAuthoritativeRun?: () => Promise<CliBridgeRunSnapshot | null>, validateCanonicalEvent?: (event: AgentEnvironmentEvent) => void): AsyncIterable<AgentEnvironmentEvent>;