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

package/README.md

@@ -64,6 +64,42 @@ Replay and result reads fail loudly after cli-bridge's configured replay retenti
 Stopping a `session.events()` reader detaches only that replay observer.
 Stopping a direct `environment.stream()` reader or destroying the environment cancels its active bridge runs and waits for terminal confirmation.
 
+Pi retained sessions also expose typed permission interactions.
+The provider stores the selected harness, exact model route, and canonical create digest inside its opaque environment identifier.
+This identifier lets `provider.get()` reconstruct profile-selected routes after process death without a cache or repeated configuration.
+The create digest prevents an altered profile or workspace from reusing the previous retained identity.
+`provider.get()` accepts only identifiers created by this provider and rejects plain caller identifiers.
+The provider queries `/v1/capabilities` for the retained Pi route.
+The provider caches the valid response and enables native interactions only when the running Bridge proves the complete retained contract.
+Every native turn stays on the model route used for that discovery; another model requires another environment.
+An explicit capability document remains available for a caller that already performed the same discovery.
+That capability selects cli-bridge's native `/v1/sessions` and `/turns` transport; it never sends an interactive turn to `/v1/chat/completions`.
+The environment and session then expose `respondToInteraction()` for exact response commands.
+Each command carries its run, session, execution, request digest, and stable operation identifier.
+Native turns require caller-stable `turnId` and `executionId` values so an ambiguous admission cannot create another run.
+The bridge records repeated operations and rejects a different answer for an existing operation.
+The provider reports an unconfirmed network result as retryable and never reports it as accepted.
+Native replay reads `/v1/runs/:runId/events` and validates each canonical envelope through Agent Interface before exposing it.
+When a turn supplies `interactions`, the provider carries its exact map, including an explicit `{}`; an omitted map remains omitted.
+Every requested key must be advertised by the selected environment, including keys set to `false`; an unsupported key fails before transport use.
+One-shot requests keep this posture as a top-level `interactions` field rather than moving it into `metadata`.
+The cli-bridge turn schema must accept that top-level field and include it in its request digest.
+Other runners stay disabled until cli-bridge proves the same replay and response behavior for them.
+
+To run the real cross-repository contract, point the test at an installed cli-bridge source checkout:
+
+```sh
+CLI_BRIDGE_INTEGRATION_ROOT=/path/to/cli-bridge pnpm test -- tests/cli-bridge.integration.test.ts
+```
+
+Use `pnpm test:integration` for the fail-closed form of this command.
+It exits before Vitest when `CLI_BRIDGE_INTEGRATION_ROOT` is missing.
+The regular `pnpm test` command remains portable and skips this cross-repository test when no checkout is configured.
+
+The test launches the actual Bridge server and a jailed Pi RPC process.
+It proves dispatch, permission response, completion, reconnect, replay, and idempotent response retry.
+CI runs this test in a separate job against a pinned Bridge checkout, rebuilds its native SQLite binding, and fails if the checkout cannot build or the integration test is skipped.
+
 Response headers and streamed bodies have no transport timeout by default.
 For unattended runs, set `headersTimeoutMs`, `bodyTimeoutMs`, or an `AbortSignal` so an unresponsive bridge cannot wait forever.
 

package/dist/capability-discovery.d.ts

@@ -0,0 +1,15 @@
+import { type AgentEnvironmentCapabilities } from "@tangle-network/agent-interface/environment-provider";
+import type { CliBridgeProviderOptions } from "./provider-options.js";
+/** Read the retained contract from the exact Bridge model route. */
+export declare function discoverCliBridgeCapabilities(options: CliBridgeProviderOptions, model: string): Promise<AgentEnvironmentCapabilities>;
+/** Share one readiness request between capability checks and environment creation. */
+export declare function cachedCliBridgeCapabilityDiscovery(options: CliBridgeProviderOptions): (model: string) => Promise<AgentEnvironmentCapabilities>;
+/**
+ * Publish only operations implemented by this adapter and proved by Bridge.
+ *
+ * Bridge owns backend truth. This provider owns its HTTP adapter and local
+ * observation surfaces. A remote capability cannot create a provider method.
+ */
+export declare function narrowCliBridgeCapabilities(adapter: AgentEnvironmentCapabilities, reported: AgentEnvironmentCapabilities, selectedBackend?: string, options?: {
+    preserveAdapterObservation?: boolean;
+}): AgentEnvironmentCapabilities;

package/dist/capability-discovery.js

@@ -0,0 +1,164 @@
+import { AgentEnvironmentCapabilitiesSchema, } from "@tangle-network/agent-interface/environment-provider";
+import { 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) {
+    const transport = createCliBridgeTransport(options);
+    try {
+        const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/capabilities?model=${encodeURIComponent(model)}`, {
+            method: "GET",
+            headers: requestHeaders(options),
+        });
+        if (!response.ok) {
+            throw new Error(`cli-bridge capability discovery returned HTTP ${response.status}: ${await response.text()}`);
+        }
+        let value;
+        try {
+            value = JSON.parse(await response.text());
+        }
+        catch (error) {
+            throw new Error("cli-bridge capability discovery returned invalid JSON", { cause: error });
+        }
+        const parsed = AgentEnvironmentCapabilitiesSchema.safeParse(value);
+        if (!parsed.success) {
+            throw new Error("cli-bridge capability discovery returned an invalid capability document", {
+                cause: parsed.error,
+            });
+        }
+        return parsed.data;
+    }
+    finally {
+        await transport.close();
+    }
+}
+/** Share one readiness request between capability checks and environment creation. */
+export function cachedCliBridgeCapabilityDiscovery(options) {
+    const cache = new Map();
+    return (model) => {
+        const existing = cache.get(model);
+        if (existing)
+            return existing;
+        const pending = discoverCliBridgeCapabilities(options, model);
+        cache.set(model, pending);
+        void pending.catch(() => {
+            if (cache.get(model) === pending)
+                cache.delete(model);
+        });
+        return pending;
+    };
+}
+/**
+ * Publish only operations implemented by this adapter and proved by Bridge.
+ *
+ * Bridge owns backend truth. This provider owns its HTTP adapter and local
+ * observation surfaces. A remote capability cannot create a provider method.
+ */
+export function narrowCliBridgeCapabilities(adapter, reported, selectedBackend, options = {}) {
+    const streaming = {
+        live: adapter.streaming.live && reported.streaming.live,
+        replay: adapter.streaming.replay && reported.streaming.replay,
+        detach: adapter.streaming.detach && reported.streaming.detach,
+        turnIdempotency: adapter.streaming.turnIdempotency && reported.streaming.turnIdempotency,
+    };
+    const sessions = {
+        continue: 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)
+        ? {
+            exactRunIdentity: true,
+            resultIdentity: true,
+            eventIdentity: true,
+            cancellationIdempotency: true,
+        }
+        : undefined;
+    const interactions = supportsCliBridgeNativeInteractions(adapter, selectedBackend) &&
+        supportsCliBridgeNativeInteractions(reported, selectedBackend)
+        ? adapter.interactions
+        : undefined;
+    const observation = options.preserveAdapterObservation
+        ? adapter.observation
+        : intersectObservation(adapter.observation, reported.observation);
+    const candidate = {
+        profile: {
+            namedProfiles: adapter.profile.namedProfiles && reported.profile.namedProfiles,
+            systemPrompt: {
+                replace: adapter.profile.systemPrompt.replace && reported.profile.systemPrompt.replace,
+                append: adapter.profile.systemPrompt.append && reported.profile.systemPrompt.append,
+            },
+            instructions: adapter.profile.instructions && reported.profile.instructions,
+            tools: adapter.profile.tools && reported.profile.tools,
+            permissions: adapter.profile.permissions && reported.profile.permissions,
+            mcp: adapter.profile.mcp && reported.profile.mcp,
+            subagents: adapter.profile.subagents && reported.profile.subagents,
+            resources: {
+                files: adapter.profile.resources.files && reported.profile.resources.files,
+                instructions: adapter.profile.resources.instructions && reported.profile.resources.instructions,
+                tools: adapter.profile.resources.tools === true && reported.profile.resources.tools === true,
+                skills: adapter.profile.resources.skills === true && reported.profile.resources.skills === true,
+                agents: adapter.profile.resources.agents === true && reported.profile.resources.agents === true,
+                commands: adapter.profile.resources.commands === true && reported.profile.resources.commands === true,
+            },
+            hooks: adapter.profile.hooks === true && reported.profile.hooks === true,
+            modes: adapter.profile.modes === true && reported.profile.modes === true,
+            runtimeUpdate: adapter.profile.runtimeUpdate && reported.profile.runtimeUpdate,
+            // AgentEnvironmentProvider has no profile validator, even when Bridge does.
+            validation: false,
+            ...intersectExtensions(adapter.profile.extensions, reported.profile.extensions),
+        },
+        streaming,
+        sessions,
+        ...(retainedControl === undefined ? {} : { retainedControl }),
+        ...(interactions === undefined ? {} : { interactions }),
+        // Remote workspace support cannot create absent adapter methods.
+        workspace: {
+            read: false,
+            write: false,
+            exec: false,
+            git: false,
+            upload: false,
+            download: false,
+        },
+        branching: { checkpoint: false, fork: false },
+        placement: adapter.placement && reported.placement,
+        usage: adapter.usage && reported.usage,
+        confidential: adapter.confidential && reported.confidential,
+        // Observation is measured by this adapter, not by the remote backend document.
+        ...(observation === undefined ? {} : { observation }),
+    };
+    return AgentEnvironmentCapabilitiesSchema.parse(candidate);
+}
+function intersectObservation(adapter, reported) {
+    if (adapter === undefined || reported === undefined)
+        return undefined;
+    return {
+        identity: adapter.identity && reported.identity,
+        lifecycle: adapter.lifecycle && reported.lifecycle,
+        endpoint: adapter.endpoint && reported.endpoint,
+        placement: adapter.placement && reported.placement,
+        resources: adapter.resources && reported.resources,
+        resourceUse: adapter.resourceUse && reported.resourceUse,
+        modelUsage: adapter.modelUsage && reported.modelUsage,
+        computeBilling: adapter.computeBilling && reported.computeBilling,
+        accountUsage: adapter.accountUsage && reported.accountUsage,
+    };
+}
+function supportsRetainedControl(capabilities) {
+    const retained = capabilities.retainedControl;
+    return Boolean(retained?.exactRunIdentity &&
+        retained.resultIdentity &&
+        retained.eventIdentity &&
+        retained.cancellationIdempotency &&
+        capabilities.streaming.replay &&
+        capabilities.streaming.detach &&
+        capabilities.streaming.turnIdempotency &&
+        capabilities.sessions.continue);
+}
+function intersectExtensions(adapter, reported) {
+    if (adapter === undefined || reported === undefined)
+        return {};
+    const allowed = new Set(reported);
+    return { extensions: adapter.filter((extension) => allowed.has(extension)) };
+}

package/dist/environment-identity.d.ts

@@ -0,0 +1,13 @@
+import type { Sha256Digest } from "@tangle-network/agent-interface";
+export interface CliBridgeEnvironmentRoute {
+    readonly backend?: string;
+    readonly model?: string;
+    readonly createDigest: Sha256Digest;
+}
+/**
+ * Keep the exact route and create digest inside the provider-owned id.
+ * The nonce hides a caller idempotency key while repeated creates stay stable.
+ */
+export declare function cliBridgeEnvironmentId(route: Omit<CliBridgeEnvironmentRoute, "createDigest">, createDigest: Sha256Digest, idempotencyKey?: string): string;
+/** Recover the exact route from a provider-owned retained identifier. */
+export declare function cliBridgeEnvironmentRoute(id: string): CliBridgeEnvironmentRoute;

package/dist/environment-identity.js

@@ -0,0 +1,87 @@
+import { createHash, randomUUID } from "node:crypto";
+const CLI_BRIDGE_ENVIRONMENT_ID_PREFIX = "cb1.";
+const MAX_ENVIRONMENT_ID_LENGTH = 512;
+/**
+ * Keep the exact route and create digest inside the provider-owned id.
+ * The nonce hides a caller idempotency key while repeated creates stay stable.
+ */
+export function cliBridgeEnvironmentId(route, createDigest, idempotencyKey) {
+    assertEnvironmentRoute(route.backend, route.model, createDigest);
+    const nonce = idempotencyKey === undefined
+        ? randomUUID()
+        : createHash("sha256").update(idempotencyKey).digest("base64url");
+    const payload = JSON.stringify([
+        route.backend ?? null,
+        route.model ?? null,
+        createDigest,
+        nonce,
+    ]);
+    const id = `${CLI_BRIDGE_ENVIRONMENT_ID_PREFIX}${Buffer.from(payload).toString("base64url")}`;
+    if (id.length > MAX_ENVIRONMENT_ID_LENGTH) {
+        throw new Error("cli-bridge route is too long to retain in an environment id");
+    }
+    return id;
+}
+/** Recover the exact route from a provider-owned retained identifier. */
+export function cliBridgeEnvironmentRoute(id) {
+    if (!id.startsWith(CLI_BRIDGE_ENVIRONMENT_ID_PREFIX)) {
+        throw new Error("cli-bridge environment id is not a provider-owned retained identity");
+    }
+    if (id.length > MAX_ENVIRONMENT_ID_LENGTH) {
+        throw new Error("cli-bridge environment id has invalid retained route data");
+    }
+    const encoded = id.slice(CLI_BRIDGE_ENVIRONMENT_ID_PREFIX.length);
+    let payload;
+    try {
+        const decoded = Buffer.from(encoded, "base64url");
+        if (decoded.toString("base64url") !== encoded)
+            throw new Error("non-canonical encoding");
+        payload = JSON.parse(decoded.toString("utf8"));
+    }
+    catch {
+        throw new Error("cli-bridge environment id has invalid retained route data");
+    }
+    if (!Array.isArray(payload) || payload.length !== 4) {
+        throw new Error("cli-bridge environment id has invalid retained route data");
+    }
+    const [backend, model, createDigest, nonce] = payload;
+    if (!optionalRouteValue(backend) ||
+        !optionalRouteValue(model) ||
+        !sha256Digest(createDigest) ||
+        !modelMatchesBackend(backend, model) ||
+        typeof nonce !== "string" ||
+        nonce.length === 0 ||
+        nonce.length > 64) {
+        throw new Error("cli-bridge environment id has invalid retained route data");
+    }
+    return {
+        ...(backend === null ? {} : { backend }),
+        ...(model === null ? {} : { model }),
+        createDigest,
+    };
+}
+function optionalRouteValue(value) {
+    return value === null || routeValue(value);
+}
+function routeValue(value) {
+    return (typeof value === "string" &&
+        value.length > 0 &&
+        value.length <= MAX_ENVIRONMENT_ID_LENGTH &&
+        value.trim() === value);
+}
+function sha256Digest(value) {
+    return typeof value === "string" && /^sha256:[0-9a-f]{64}$/u.test(value);
+}
+function modelMatchesBackend(backend, model) {
+    if (model === null)
+        return backend === null;
+    return backend === null || model === backend || model.startsWith(`${backend}/`);
+}
+function assertEnvironmentRoute(backend, model, createDigest) {
+    if (!optionalRouteValue(backend ?? null) ||
+        !optionalRouteValue(model ?? null) ||
+        !sha256Digest(createDigest) ||
+        !modelMatchesBackend(backend ?? null, model ?? null)) {
+        throw new Error("cli-bridge environment route is invalid");
+    }
+}

package/dist/index.js

@@ -1,34 +1,70 @@
-import { createAgentEnvironmentWithIdempotency } from "@tangle-network/agent-interface/environment-provider";
-import { harnessSystemPromptIntents, snapshotAgentProfile, } from "@tangle-network/agent-interface";
-import { createCliBridgeEnvironment } from "./retained-environment.js";
+import { agentEnvironmentCreateInputDigest, createAgentEnvironmentWithIdempotency, } from "@tangle-network/agent-interface/environment-provider";
+import { harnessTypeSchema, harnessSystemPromptIntents, snapshotAgentProfile, } from "@tangle-network/agent-interface";
+import { createCliBridgeEnvironment, } from "./retained-environment.js";
+import { cachedCliBridgeCapabilityDiscovery, narrowCliBridgeCapabilities, } from "./capability-discovery.js";
+import { supportsCliBridgeNativeInteractions, } from "./retained-native.js";
 import { assertCliBridgeProviderOptions, } from "./provider-options.js";
 import { narrowedCliBridgeObservation } from "./observation.js";
+import { cliBridgeEnvironmentId, cliBridgeEnvironmentRoute, } from "./environment-identity.js";
+import { resolveBridgeModel } from "./wire.js";
 export { safeEndpointFromBaseUrl } from "./observation.js";
 export function createCliBridgeProvider(options) {
     assertCliBridgeProviderOptions(options);
     const name = options.name ?? "cli-bridge";
     const createRecords = new Map();
+    const configuredBackend = selectedBackendFromRoute(options.defaultModel);
+    const discoverCapabilities = cachedCliBridgeCapabilityDiscovery(options);
     // The observation surfaces are declared as intent and narrowed to the
     // sources this bridge can put a value on, so the environment offers the
     // operation exactly where the document claims it.
-    const resolveCapabilities = () => {
-        const declared = options.capabilities ?? defaultCliBridgeCapabilities();
-        return declared.observation === undefined
+    const localCapabilities = (selectedBackend, allowNativeInteractions = false) => {
+        const parsedHarness = harnessTypeSchema.safeParse(selectedBackend);
+        const adapter = defaultCliBridgeCapabilities(parsedHarness.success ? parsedHarness.data : undefined);
+        const declared = options.capabilities === undefined
+            ? adapter
+            : narrowCliBridgeCapabilities(adapter, options.capabilities, selectedBackend);
+        const narrowed = declared.observation === undefined
             ? declared
             : {
                 ...declared,
                 observation: narrowedCliBridgeObservation(declared.observation, options),
             };
+        if (allowNativeInteractions &&
+            supportsCliBridgeNativeInteractions(narrowed, selectedBackend)) {
+            return narrowed;
+        }
+        const { interactions: _interactions, ...withoutInteractions } = narrowed;
+        return withoutInteractions;
+    };
+    const resolveCapabilities = (selectedBackend, model, allowNativeInteractions = false) => {
+        const local = localCapabilities(selectedBackend, allowNativeInteractions);
+        if (!allowNativeInteractions ||
+            options.capabilities !== undefined ||
+            selectedBackend !== "pi" ||
+            model === undefined) {
+            return local;
+        }
+        return discoverCapabilities(model).then((reported) => narrowCliBridgeCapabilities(local, reported, selectedBackend, {
+            preserveAdapterObservation: true,
+        }));
     };
     const createEnvironment = async (input) => {
         if (typeof input.profile === "string") {
             throw new Error(`createCliBridgeProvider requires an inline AgentProfile; named profile "${input.profile}" is unsupported`);
         }
+        const profile = snapshotAgentProfile(input.profile);
         const environmentInput = {
             ...input,
-            profile: snapshotAgentProfile(input.profile),
+            profile,
         };
-        const environmentId = input.idempotencyKey ?? crypto.randomUUID();
+        const selectedBackend = selectedBackendFromInput(environmentInput, configuredBackend);
+        const hasEnvironmentModel = selectedBackend !== undefined ||
+            options.defaultModel !== undefined ||
+            profile.model?.default !== undefined;
+        const model = hasEnvironmentModel
+            ? resolveBridgeModel(options, environmentInput, {}, profile)
+            : undefined;
+        const environmentId = cliBridgeEnvironmentId({ backend: selectedBackend, model }, agentEnvironmentCreateInputDigest(environmentInput), input.idempotencyKey);
         return createCliBridgeEnvironment({
             options,
             providerName: name,
@@ -36,12 +72,14 @@ export function createCliBridgeProvider(options) {
             environmentId,
             allowDispatch: true,
             cancelRunsOnDestroy: true,
-            capabilities: resolveCapabilities(),
+            capabilities: await resolveCapabilities(selectedBackend, model, true),
+            selectedBackend,
+            selectedModel: model,
         });
     };
     return {
         name,
-        capabilities: resolveCapabilities,
+        capabilities: () => resolveCapabilities(configuredBackend, options.defaultModel, true),
         create(input) {
             return createAgentEnvironmentWithIdempotency(createRecords, input, () => createEnvironment(input));
         },
@@ -49,18 +87,38 @@ export function createCliBridgeProvider(options) {
             if (id.length === 0 || id.trim() !== id) {
                 throw new Error("cli-bridge environment id must be non-empty and have no outer whitespace");
             }
+            const route = cliBridgeEnvironmentRoute(id);
             return createCliBridgeEnvironment({
                 options,
                 providerName: name,
-                environmentInput: { profile: { name: "reconnected" }, idempotencyKey: id },
+                environmentInput: {
+                    profile: { name: "reconnected" },
+                    ...(route.backend === undefined ? {} : { backend: route.backend }),
+                    idempotencyKey: id,
+                },
                 environmentId: id,
                 allowDispatch: false,
                 cancelRunsOnDestroy: false,
-                capabilities: resolveCapabilities(),
+                capabilities: await resolveCapabilities(route.backend, route.model, true),
+                selectedBackend: route.backend,
+                selectedModel: route.model,
             });
         },
     };
 }
+function selectedBackendFromInput(input, configuredBackend) {
+    if (input.backend !== undefined)
+        return input.backend;
+    if (typeof input.profile !== "string" && input.profile.harness !== undefined) {
+        return input.profile.harness;
+    }
+    return configuredBackend;
+}
+function selectedBackendFromRoute(route) {
+    const candidate = route?.split("/", 1)[0];
+    const parsed = harnessTypeSchema.safeParse(candidate);
+    return parsed.success ? parsed.data : undefined;
+}
 /**
  * Describe the bridge backend, not this adapter.
  *
@@ -97,6 +155,19 @@ export function defaultCliBridgeCapabilities(harness) {
             eventIdentity: true,
             cancellationIdempotency: true,
         },
+        ...(harness === "pi"
+            ? {
+                interactions: {
+                    kinds: ["permission"],
+                    answerFieldTypes: ["select"],
+                    responseScopes: ["interaction"],
+                    secretAnswers: false,
+                    concurrentRequests: false,
+                    replay: true,
+                    responseIdempotency: true,
+                },
+            }
+            : {}),
         workspace: {
             read: false,
             write: false,

package/dist/interaction-response.d.ts

@@ -0,0 +1,15 @@
+import type { InteractionAcknowledgement, InteractionResponseCommand } from "@tangle-network/agent-interface";
+import type { CliBridgeProviderOptions } from "./provider-options.js";
+import { type CliBridgeTransport } from "./transport.js";
+interface CliBridgeInteractionResponderOptions {
+    readonly sessionId?: string;
+    readonly providerName: string;
+    readonly environmentId: string;
+    readonly options: CliBridgeProviderOptions;
+    readonly transport: CliBridgeTransport;
+}
+/** Send one retry-safe response command to its exact retained CLI run. */
+export declare function cliBridgeInteractionResponder(options: CliBridgeInteractionResponderOptions): (command: InteractionResponseCommand, operation?: {
+    signal?: AbortSignal;
+}) => Promise<InteractionAcknowledgement>;
+export {};

package/dist/interaction-response.js

@@ -0,0 +1,100 @@
+import { InteractionAcknowledgementSchema, InteractionResponseCommandSchema, } from "@tangle-network/agent-interface";
+import { requestHeaders, trimSlash, } from "./transport.js";
+function transportFailure(command, error, retryable = true) {
+    return InteractionAcknowledgementSchema.parse({
+        operationId: command.operationId,
+        binding: command.binding,
+        commandDigest: command.commandDigest,
+        status: "transport_failure",
+        message: `cli-bridge did not confirm the interaction response: ${error instanceof Error ? error.message : String(error)}`,
+        retryable,
+    });
+}
+function expectedHttpStatus(status) {
+    if (status === "accepted" || status === "already_resolved_same")
+        return 200;
+    if (status === "invalid_response")
+        return 400;
+    if (status === "unknown_run" || status === "unknown_interaction")
+        return 404;
+    if (status === "already_resolved_different" ||
+        status === "expired" ||
+        status === "cancelled" ||
+        status === "binding_mismatch")
+        return 409;
+    return 502;
+}
+function matchesHttpStatus(acknowledgement, status) {
+    if (status === expectedHttpStatus(acknowledgement.status))
+        return true;
+    // Bridge uses 429 only for a retryable rejection before the response can take effect.
+    return (status === 429 &&
+        acknowledgement.status === "transport_failure" &&
+        acknowledgement.retryable === true);
+}
+function classifyAcknowledgement(acknowledgement, status) {
+    if (!matchesHttpStatus(acknowledgement, status)) {
+        throw new Error(`cli-bridge interaction acknowledgement status ${JSON.stringify(acknowledgement.status)} contradicts HTTP ${status}`);
+    }
+    if (status >= 400 && status < 500 && acknowledgement.retryable === undefined) {
+        return { ...acknowledgement, retryable: false };
+    }
+    return acknowledgement;
+}
+function assertAcknowledgesCommand(acknowledgement, command) {
+    const actual = acknowledgement.binding;
+    const expected = command.binding;
+    if (acknowledgement.operationId !== command.operationId ||
+        acknowledgement.commandDigest !== command.commandDigest ||
+        actual.runId !== expected.runId ||
+        actual.provider !== expected.provider ||
+        actual.environmentId !== expected.environmentId ||
+        actual.sessionId !== expected.sessionId ||
+        actual.executionId !== expected.executionId ||
+        actual.interactionId !== expected.interactionId ||
+        actual.requestDigest !== expected.requestDigest) {
+        throw new Error("cli-bridge returned an interaction acknowledgement for another operation");
+    }
+}
+/** Send one retry-safe response command to its exact retained CLI run. */
+export function cliBridgeInteractionResponder(options) {
+    return async (command, operation) => {
+        const exact = InteractionResponseCommandSchema.parse(command);
+        operation?.signal?.throwIfAborted();
+        if (exact.binding.provider !== options.providerName ||
+            exact.binding.environmentId !== options.environmentId ||
+            (options.sessionId !== undefined && exact.binding.sessionId !== options.sessionId)) {
+            return InteractionAcknowledgementSchema.parse({
+                operationId: exact.operationId,
+                binding: exact.binding,
+                commandDigest: exact.commandDigest,
+                status: "binding_mismatch",
+                message: "interaction response does not use this cli-bridge environment binding",
+            });
+        }
+        let response;
+        try {
+            response = await options.transport.fetch(`${trimSlash(options.options.baseUrl)}/v1/runs/${encodeURIComponent(exact.binding.runId)}/interactions/${encodeURIComponent(exact.binding.interactionId)}/respond`, {
+                method: "POST",
+                headers: requestHeaders(options.options),
+                body: JSON.stringify(exact),
+                ...(operation?.signal ? { signal: operation.signal } : {}),
+            });
+        }
+        catch (error) {
+            operation?.signal?.throwIfAborted();
+            return transportFailure(exact, error);
+        }
+        operation?.signal?.throwIfAborted();
+        let acknowledgement;
+        const retryableOnMalformed = response.status >= 500 || (response.status >= 200 && response.status < 300);
+        try {
+            acknowledgement = InteractionAcknowledgementSchema.parse(JSON.parse(await response.text()));
+        }
+        catch (error) {
+            return transportFailure(exact, error, retryableOnMalformed);
+        }
+        assertAcknowledgesCommand(acknowledgement, exact);
+        return classifyAcknowledgement(acknowledgement, response.status);
+    };
+}

package/dist/retained-canonical-event.d.ts

@@ -1,3 +1,4 @@
+import { type StreamEvent } from "@tangle-network/agent-interface";
 import type { AgentEnvironmentEvent } from "@tangle-network/agent-interface/environment-provider";
 import type { CliBridgeSseFrame } from "./wire.js";
 interface CanonicalEventContext {
@@ -7,5 +8,11 @@ interface CanonicalEventContext {
 }
 /** Decode one explicitly typed retained-run frame without guessing its wire format. */
 export declare function retainedCanonicalEvent(frame: CliBridgeSseFrame, context: CanonicalEventContext): AgentEnvironmentEvent | undefined;
-export declare function isTerminalCanonicalEvent(event: AgentEnvironmentEvent): boolean;
+export declare function isTerminalCanonicalEvent(event: AgentEnvironmentEvent): event is AgentEnvironmentEvent & {
+    normalized: Extract<StreamEvent, {
+        type: "status";
+    }> & {
+        status: "completed" | "failed" | "cancelled";
+    };
+};
 export {};

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;