@tangle-network/agent-provider-cli-bridge 0.7.7 → 0.8.0

package/dist/retained-canonical-event.js

@@ -0,0 +1,135 @@
+import { RuntimeEventEnvelopeSchema, } from "@tangle-network/agent-interface";
+/** Decode one explicitly typed retained-run frame without guessing its wire format. */
+export function retainedCanonicalEvent(frame, context) {
+    if (frame.event === undefined)
+        return undefined;
+    if (frame.event === "error")
+        throw retainedCanonicalStreamError(frame.data);
+    const envelope = parseEnvelope(frame.data);
+    if (envelope.runId !== context.runId) {
+        throw new Error("cli-bridge canonical event belongs to another retained run");
+    }
+    if (frame.event !== envelope.event.type) {
+        throw new Error("cli-bridge SSE event type does not match its canonical envelope");
+    }
+    if (frame.id === undefined) {
+        throw new Error("cli-bridge canonical event has no replay cursor");
+    }
+    if (!isBaseTenInteger(frame.id) ||
+        envelope.sequence === 0 ||
+        Number(frame.id) !== envelope.sequence) {
+        throw new Error("cli-bridge canonical event cursor does not match its sequence");
+    }
+    const event = envelope.event;
+    const usage = usageFromCanonicalEvent(event);
+    return {
+        type: event.type,
+        // AgentSession.events({ since }) accepts a previously emitted event id.
+        // The bridge replays by its numeric SSE cursor, while eventId identifies
+        // the canonical envelope and is not a replay cursor.
+        id: frame.id,
+        data: {
+            ...eventPayload(event),
+            eventId: envelope.eventId,
+            sequence: envelope.sequence,
+            cursor: frame.id,
+            runId: context.runId,
+            sessionId: context.sessionId,
+            ...(context.executionId === undefined
+                ? {}
+                : { executionId: context.executionId }),
+            ...(envelope.occurredAt === undefined
+                ? {}
+                : { occurredAt: envelope.occurredAt }),
+            receivedAt: envelope.receivedAt,
+        },
+        normalized: event,
+        ...(usage === undefined ? {} : { usage }),
+        providerEvent: envelope,
+    };
+}
+export function isTerminalCanonicalEvent(event) {
+    return event.normalized?.type === "status" &&
+        ["completed", "failed", "cancelled"].includes(event.normalized.status);
+}
+function parseEnvelope(data) {
+    let value;
+    try {
+        value = JSON.parse(data);
+    }
+    catch (error) {
+        throw new Error("cli-bridge canonical event is not valid JSON", { cause: error });
+    }
+    const parsed = RuntimeEventEnvelopeSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new Error("cli-bridge emitted an invalid canonical event envelope", {
+            cause: parsed.error,
+        });
+    }
+    return parsed.data;
+}
+function eventPayload(event) {
+    const { type: _type, ...payload } = event;
+    return payload;
+}
+function usageFromCanonicalEvent(event) {
+    if (event.type !== "raw")
+        return undefined;
+    const providerEvent = recordValue(event.event);
+    if (providerEvent?.type !== "usage")
+        return undefined;
+    const data = recordValue(providerEvent.data);
+    const usage = recordValue(providerEvent.usage) ?? recordValue(data?.usage);
+    if (!usage)
+        return undefined;
+    const inputTokens = nonNegativeInteger(usage.inputTokens);
+    const outputTokens = nonNegativeInteger(usage.outputTokens);
+    if (inputTokens === undefined || outputTokens === undefined)
+        return undefined;
+    return {
+        inputTokens,
+        outputTokens,
+        ...optionalInteger(usage, "totalTokens"),
+        ...optionalInteger(usage, "cacheReadInputTokens"),
+        ...optionalInteger(usage, "cacheCreationInputTokens"),
+        ...optionalInteger(usage, "reasoningTokens"),
+        ...optionalNumber(usage, "cost"),
+    };
+}
+function optionalInteger(source, key) {
+    const value = nonNegativeInteger(source[key]);
+    return value === undefined ? {} : { [key]: value };
+}
+function optionalNumber(source, key) {
+    const value = source[key];
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? { [key]: value }
+        : {};
+}
+function nonNegativeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
+        ? value
+        : undefined;
+}
+function recordValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function isBaseTenInteger(value) {
+    return /^(0|[1-9][0-9]*)$/u.test(value) && Number.isSafeInteger(Number(value));
+}
+function retainedCanonicalStreamError(data) {
+    let message = "cli-bridge canonical event stream failed";
+    try {
+        const parsed = recordValue(JSON.parse(data));
+        const error = recordValue(parsed?.error);
+        if (typeof error?.message === "string" && error.message.length > 0) {
+            message = error.message;
+        }
+    }
+    catch {
+        // The typed error frame is authoritative even when its detail is malformed.
+    }
+    return new Error(`cli-bridge: ${message}`);
+}

package/dist/retained-control.js

@@ -57,7 +57,7 @@ async function performCliBridgeCancellation(options, transport, run) {
         throw new Error(`cli-bridge cancel ${response.status}: ${await response.text()}`);
     }
     let snapshot = cancelSnapshot(await response.text());
-    assertCliBridgeRunSnapshotIdentity(snapshot, run.id);
+    assertCliBridgeRunSnapshotIdentity(snapshot, run.id, run.requestDigest);
     const waitBudgetMs = options.cancelWaitMs ?? 30_000;
     const deadline = Date.now() + waitBudgetMs;
     while (!snapshot.terminal) {
@@ -166,5 +166,7 @@ export function agentSessionStatusFromRun(snapshot) {
         return "failed";
     if (snapshot.status === "cancelled")
         return "cancelled";
+    if (snapshot.status === "unknown")
+        return "unknown";
     return "running";
 }

package/dist/retained-environment.d.ts

@@ -13,5 +13,7 @@ export interface CreateCliBridgeEnvironmentArgs {
      * action the document did not carry.
      */
     readonly capabilities: AgentEnvironmentCapabilities;
+    readonly selectedBackend?: string;
+    readonly selectedModel?: string;
 }
 export declare function createCliBridgeEnvironment(args: CreateCliBridgeEnvironmentArgs): AgentEnvironment;

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>;