@tangle-network/agent-provider-cli-bridge 0.6.4 → 0.7.1

package/README.md

@@ -49,6 +49,9 @@ Passing the same `sessionId` on later turns continues the same CLI conversation.
 `dispatch()` starts a bridge-owned durable run and returns after detaching its HTTP reader.
 The returned `AgentSession` exposes status, cursor-based event replay, the terminal result, continuation, and cancellation.
 Cancellation returns only after cli-bridge confirms the run is terminal.
+A direct stream treats a finish frame as provisional until cli-bridge returns the same run's aggregate result.
+A retained replay confirms its terminal state from the retained run endpoint.
+The provider rejects a terminal response when its run id or request digest does not match the accepted stream.
 Usage events and terminal result metadata include `modelRequests` only when the bridge measured an exact non-negative integer count.
 Missing, malformed, partial, or estimated request counts remain unknown.
 When `dispatch()` receives no `sessionId`, it creates one from that turn's stable run id and returns it.
@@ -58,3 +61,24 @@ Stopping a direct `environment.stream()` reader or destroying the environment ca
 
 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.
+
+## Environment observation
+
+`environment.observe()` returns the normalized `AgentEnvironmentObservation` when the provider document carries an `observation` block.
+Every surface keeps a freshness discriminator, so a value this bridge cannot report is visibly absent instead of arriving as a measured zero.
+
+| Surface | cli-bridge source | State when the source is missing |
+| --- | --- | --- |
+| `identity` | provider name and environment id | always known |
+| `lifecycle.status` | `running` until the environment is destroyed | always known |
+| `endpoint` | scheme, host, and explicit port of `baseUrl` | `unavailable` |
+| `placement.verified` | `defaultExecution.kind` as `sandbox` or `local` | always known |
+| `modelUsage` | the token usage and cost the newest execution measured | `unavailable` |
+
+cli-bridge forwards a turn and provisions no compute, so it states no requested or effective compute shape, no resource use, and no compute cost.
+It holds no account, so it states no plan, credit balance, quota, or billing period.
+Those five surfaces are never claimed in the capability document and always carry `unavailable` with the reason.
+
+The usage of one run is summed across its events and attributed to that run's execution id, which the observation carries as the provenance source.
+An environment rebuilt with `provider.get(id)` has measured nothing yet, so it reports the usage surface as unavailable until a turn completes through it.
+The endpoint holds only a scheme, a host, and an explicit port; userinfo, path, and query are dropped, and the bearer beside the base URL is never read.

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import type { AgentEnvironmentCapabilities, AgentEnvironmentProvider } from "@ta
 import { type HarnessType } from "@tangle-network/agent-interface";
 import { type CliBridgeProviderOptions } from "./provider-options.js";
 export type { CliBridgeProviderOptions } from "./provider-options.js";
+export { safeEndpointFromBaseUrl } from "./observation.js";
 export declare function createCliBridgeProvider(options: CliBridgeProviderOptions): AgentEnvironmentProvider;
 /**
  * Describe the bridge backend, not this adapter.

package/dist/index.js

@@ -1,12 +1,26 @@
 import { harnessSystemPromptIntents, snapshotAgentProfile, } from "@tangle-network/agent-interface";
 import { createCliBridgeEnvironment } from "./retained-environment.js";
 import { assertCliBridgeProviderOptions, } from "./provider-options.js";
+import { narrowedCliBridgeObservation } from "./observation.js";
+export { safeEndpointFromBaseUrl } from "./observation.js";
 export function createCliBridgeProvider(options) {
     assertCliBridgeProviderOptions(options);
     const name = options.name ?? "cli-bridge";
+    // 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
+            ? declared
+            : {
+                ...declared,
+                observation: narrowedCliBridgeObservation(declared.observation, options),
+            };
+    };
     return {
         name,
-        capabilities: () => options.capabilities ?? defaultCliBridgeCapabilities(),
+        capabilities: resolveCapabilities,
         async create(input) {
             if (typeof input.profile === "string") {
                 throw new Error(`createCliBridgeProvider requires an inline AgentProfile; named profile "${input.profile}" is unsupported`);
@@ -23,6 +37,7 @@ export function createCliBridgeProvider(options) {
                 environmentId,
                 allowDispatch: true,
                 cancelRunsOnDestroy: true,
+                capabilities: resolveCapabilities(),
             });
         },
         async get(id) {
@@ -36,6 +51,7 @@ export function createCliBridgeProvider(options) {
                 environmentId: id,
                 allowDispatch: false,
                 cancelRunsOnDestroy: false,
+                capabilities: resolveCapabilities(),
             });
         },
     };
@@ -88,5 +104,19 @@ export function defaultCliBridgeCapabilities(harness) {
         placement: true,
         usage: true,
         confidential: false,
+        // cli-bridge measures what a turn cost and where it forwarded that turn.
+        // It provisions no compute and holds no account, so the surfaces that
+        // describe provisioned resources and billing are never claimed.
+        observation: {
+            identity: true,
+            lifecycle: true,
+            endpoint: true,
+            placement: true,
+            resources: false,
+            resourceUse: false,
+            modelUsage: true,
+            computeBilling: false,
+            accountUsage: false,
+        },
     };
 }

package/dist/observation.d.ts

@@ -0,0 +1,49 @@
+import type { AgentEnvironmentCapabilities, AgentEnvironmentObservation, SafeEndpoint, TokenUsage } from "@tangle-network/agent-interface";
+import type { CliBridgeProviderOptions } from "./provider-options.js";
+/** One execution's accumulated token usage and cost. */
+interface ExecutionUsageRecord {
+    executionId: string;
+    usage: TokenUsage;
+    observedAt: string;
+}
+/**
+ * The newest per-execution usage this environment handle measured.
+ *
+ * cli-bridge reports usage on the events of one run, so the totals are summed
+ * per execution and the newest execution answers the environment-scoped
+ * observation. The record lives with the handle: an environment rebuilt by id
+ * starts with none, and the observation then reports the usage surface as
+ * unavailable rather than as a measured zero.
+ */
+export interface ExecutionUsageLog {
+    record(executionId: string | undefined, usage: TokenUsage | undefined): void;
+    latest(): ExecutionUsageRecord | undefined;
+}
+export declare function createExecutionUsageLog(): ExecutionUsageLog;
+/**
+ * Read the credential-free network location of the cli-bridge endpoint.
+ *
+ * Only the scheme, host, and explicit port are carried. Userinfo, path, and
+ * query are dropped, and the bearer beside the base URL is never read, so an
+ * endpoint payload cannot transport a credential.
+ */
+export declare function safeEndpointFromBaseUrl(baseUrl: string | undefined): SafeEndpoint | undefined;
+/**
+ * Clear every observation surface no source backs.
+ *
+ * cli-bridge forwards a turn to a remote bridge and reports what that turn
+ * cost. It never provisions compute, so it states no compute shape, no
+ * resource use, no compute cost, and no account plan. The endpoint rests on a
+ * base URL that parses.
+ */
+export declare function narrowedCliBridgeObservation(declared: NonNullable<AgentEnvironmentCapabilities["observation"]>, options: CliBridgeProviderOptions): NonNullable<AgentEnvironmentCapabilities["observation"]>;
+export interface CliBridgeObservationSources {
+    options: CliBridgeProviderOptions;
+    provider: string;
+    environmentId: string;
+    destroyed: boolean;
+    usageLog: ExecutionUsageLog;
+}
+/** Build the normalized, freshness-tagged observation of one environment. */
+export declare function observeCliBridgeEnvironment(sources: CliBridgeObservationSources): AgentEnvironmentObservation;
+export {};

package/dist/observation.js

@@ -0,0 +1,141 @@
+import { AgentEnvironmentObservationSchema } from "@tangle-network/agent-interface";
+export function createExecutionUsageLog() {
+    let latest;
+    return {
+        record(executionId, usage) {
+            // Usage without the execution it belongs to cannot be attributed, and an
+            // execution without usage measured nothing. Neither is recorded.
+            if (executionId === undefined || executionId.length === 0)
+                return;
+            if (usage === undefined)
+                return;
+            latest = {
+                executionId,
+                usage,
+                observedAt: new Date().toISOString(),
+            };
+        },
+        latest() {
+            return latest === undefined
+                ? undefined
+                : { ...latest, usage: { ...latest.usage } };
+        },
+    };
+}
+/**
+ * Read the credential-free network location of the cli-bridge endpoint.
+ *
+ * Only the scheme, host, and explicit port are carried. Userinfo, path, and
+ * query are dropped, and the bearer beside the base URL is never read, so an
+ * endpoint payload cannot transport a credential.
+ */
+export function safeEndpointFromBaseUrl(baseUrl) {
+    if (typeof baseUrl !== "string" || baseUrl.length === 0)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return undefined;
+    }
+    const scheme = parsed.protocol.replace(/:$/, "");
+    const host = parsed.hostname;
+    if (scheme.length === 0 || host.length === 0)
+        return undefined;
+    const port = parsed.port === "" ? undefined : Number.parseInt(parsed.port, 10);
+    if (port !== undefined && (!Number.isInteger(port) || port < 1 || port > 65_535)) {
+        return undefined;
+    }
+    return { scheme, host, ...(port === undefined ? {} : { port }) };
+}
+/**
+ * Clear every observation surface no source backs.
+ *
+ * cli-bridge forwards a turn to a remote bridge and reports what that turn
+ * cost. It never provisions compute, so it states no compute shape, no
+ * resource use, no compute cost, and no account plan. The endpoint rests on a
+ * base URL that parses.
+ */
+export function narrowedCliBridgeObservation(declared, options) {
+    const endpoint = safeEndpointFromBaseUrl(options.baseUrl) !== undefined;
+    return {
+        identity: declared.identity,
+        lifecycle: declared.lifecycle,
+        endpoint: endpoint ? declared.endpoint : false,
+        placement: declared.placement,
+        resources: false,
+        resourceUse: false,
+        modelUsage: declared.modelUsage,
+        computeBilling: false,
+        accountUsage: false,
+    };
+}
+/** Build the normalized, freshness-tagged observation of one environment. */
+export function observeCliBridgeEnvironment(sources) {
+    const capturedAt = new Date().toISOString();
+    const provenance = {
+        origin: "reported",
+        observedAt: capturedAt,
+        source: "cli-bridge",
+    };
+    const subject = {
+        provider: sources.provider,
+        environmentId: sources.environmentId,
+    };
+    const endpoint = safeEndpointFromBaseUrl(sources.options.baseUrl);
+    const latest = sources.usageLog.latest();
+    const absent = (reason) => ({
+        state: "unavailable",
+        reason,
+    });
+    const noCompute = "cli-bridge forwards a turn and provisions no compute";
+    const noAccount = "cli-bridge reports no account plan, credit, or quota";
+    const noProbe = "cli-bridge never probes the bridge, so its runtime state is unproven";
+    return AgentEnvironmentObservationSchema.parse({
+        subject,
+        capturedAt,
+        identity: { state: "known", value: subject, provenance },
+        // A destroyed handle stopped because this adapter stopped it, which is the
+        // only lifecycle fact cli-bridge establishes. A live handle holds a base
+        // URL and nothing else, and configuration is not a running runtime.
+        lifecycle: sources.destroyed
+            ? { state: "known", value: { status: "stopped" }, provenance }
+            : absent(noProbe),
+        endpoint: endpoint === undefined
+            ? absent("the cli-bridge base URL states no reachable host")
+            : { state: "known", value: endpoint, provenance },
+        // The configured execution kind is where the caller asked the turn to run,
+        // so it is carried as the request. cli-bridge runs no placement check, so
+        // nothing verifies it.
+        placement: {
+            requested: {
+                kind: sources.options.defaultExecution?.kind === "sandbox" ? "sandbox" : "local",
+            },
+            verified: absent(noProbe),
+        },
+        resources: { effective: absent(noCompute) },
+        resourceUse: { current: absent(noCompute), peak: absent(noCompute) },
+        modelUsage: latest === undefined
+            ? absent("no execution measured token usage through this environment handle")
+            : {
+                state: "known",
+                value: latest.usage,
+                // The provenance source names the execution the usage belongs to,
+                // because cli-bridge measures usage per run and never for the
+                // environment.
+                provenance: {
+                    origin: "reported",
+                    observedAt: latest.observedAt,
+                    source: latest.executionId,
+                },
+            },
+        computeBilling: absent(noCompute),
+        accountUsage: {
+            plan: absent(noAccount),
+            credits: absent(noAccount),
+            quota: absent(noAccount),
+            period: absent(noAccount),
+        },
+    });
+}

package/dist/retained-environment.d.ts

@@ -1,4 +1,4 @@
-import type { AgentEnvironment, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import type { AgentEnvironment, AgentEnvironmentCapabilities, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
 export interface CreateCliBridgeEnvironmentArgs {
     readonly options: CliBridgeProviderOptions;
@@ -7,5 +7,11 @@ export interface CreateCliBridgeEnvironmentArgs {
     readonly environmentId: string;
     readonly allowDispatch: boolean;
     readonly cancelRunsOnDestroy: boolean;
+    /**
+     * The document this provider publishes. The environment offers an optional
+     * operation only where the document claims it, so a caller never selects an
+     * action the document did not carry.
+     */
+    readonly capabilities: AgentEnvironmentCapabilities;
 }
 export declare function createCliBridgeEnvironment(args: CreateCliBridgeEnvironmentArgs): AgentEnvironment;

package/dist/retained-environment.js

@@ -1,5 +1,6 @@
 import { agentSessionStatusFromRun, cancelCliBridgeRun, cancelExactCliBridgeRun, getCliBridgeRun, } from "./retained-control.js";
-import { collectCliBridgeTurnResult, dispatchCliBridgeTurn, streamCliBridgeSessionEvents, streamTrackedCliBridgeTurn, } from "./retained-execution.js";
+import { addTokenUsage, collectCliBridgeTurnResult, dispatchCliBridgeTurn, streamCliBridgeSessionEvents, streamTrackedCliBridgeTurn, } from "./retained-execution.js";
+import { createExecutionUsageLog, observeCliBridgeEnvironment, } from "./observation.js";
 import { assertRunMatchesControlRef, exactControlRefForSession, prepareCliBridgeRun, runFromControlRef, } from "./retained-run-state.js";
 import { createCliBridgeTransport } from "./transport.js";
 export function createCliBridgeEnvironment(args) {
@@ -8,6 +9,7 @@ export function createCliBridgeEnvironment(args) {
     const runs = new Map();
     const sessions = new Map();
     const readers = new Set();
+    const usageLog = createExecutionUsageLog();
     let destroyed = false;
     let closePromise;
     const stream = async function* (turn) {
@@ -17,7 +19,14 @@ export function createCliBridgeEnvironment(args) {
             throw new Error("a reconstructed cli-bridge environment can only control an existing run");
         }
         const prepared = prepareCliBridgeRun(options, environmentInput, turn, environmentId, false);
-        yield* streamTrackedCliBridgeTurn(options, environmentInput, prepared, transport, runs, sessions, readers);
+        // 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)) {
+            streamedUsage = addTokenUsage(streamedUsage, event.usage);
+            usageLog.record(prepared.run.executionId, streamedUsage);
+            yield event;
+        }
     };
     return {
         id: environmentId,
@@ -52,8 +61,23 @@ export function createCliBridgeEnvironment(args) {
                 allowPrompt: args.allowDispatch,
                 requestedControlRef: sessionOptions?.controlRef,
                 isDestroyed: () => destroyed,
+                usageLog,
             });
         },
+        ...(args.capabilities.observation
+            ? {
+                async observe(observeOptions) {
+                    observeOptions?.signal?.throwIfAborted();
+                    return observeCliBridgeEnvironment({
+                        options,
+                        provider: providerName,
+                        environmentId,
+                        destroyed,
+                        usageLog,
+                    });
+                },
+            }
+            : {}),
         placement: async (placementOptions) => {
             placementOptions?.signal?.throwIfAborted();
             return {
@@ -161,7 +185,9 @@ function createCliBridgeSession(args) {
         },
         async result(resultOptions) {
             const run = requireCurrentRun();
-            return 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, 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;
         },
         async prompt(input) {
             if (!args.allowPrompt) {
@@ -175,6 +201,7 @@ function createCliBridgeSession(args) {
                 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.usageLog.record(prepared.run.executionId, result.usage);
             return { ...result, sessionId: args.id };
         },
         async cancel(cancelOptions) {

package/dist/retained-execution.d.ts

@@ -1,3 +1,4 @@
+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";
@@ -10,3 +11,5 @@ export declare function streamCliBridgeSessionEvents(options: CliBridgeProviderO
     signal?: AbortSignal;
 }): AsyncIterable<AgentEnvironmentEvent>;
 export declare function collectCliBridgeTurnResult(source: AsyncIterable<AgentEnvironmentEvent>, run: CliBridgeRun, options: CliBridgeProviderOptions, transport: CliBridgeTransport, signal?: AbortSignal): Promise<AgentTurnResult>;
+/** Sum the usage a run reported across its events into one total. */
+export declare function addTokenUsage(current: TokenUsage | undefined, next: TokenUsage | undefined): TokenUsage | undefined;

package/dist/retained-execution.js

@@ -27,7 +27,7 @@ export async function* streamTrackedCliBridgeTurn(options, environmentInput, pre
     let drained = false;
     let threw = false;
     try {
-        for await (const event of streamCliBridgeTurn(options, turn, run.requestBody, transport, run.id, originalTurn.lastEventId, signal, (response) => captureCliBridgeRunIdentity(response, run, false))) {
+        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;
         }
         drained = true;
@@ -171,7 +171,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));
+        }, undefined, transport, run.id, eventOptions?.since ?? "0", signal, (response) => captureCliBridgeRunIdentity(response, run, false), () => getCliBridgeRun(options, transport, run, 30_000, signal));
         drained = true;
         if (runs.get(run.id) === run)
             runs.delete(run.id);
@@ -267,7 +267,8 @@ export async function collectCliBridgeTurnResult(source, run, options, transport
         events,
     };
 }
-function addTokenUsage(current, next) {
+/** Sum the usage a run reported across its events into one total. */
+export function addTokenUsage(current, next) {
     if (!next)
         return current;
     if (!current)

package/dist/retained-stream.d.ts

@@ -1,8 +1,9 @@
 import type { AgentEnvironmentEvent, AgentTurnInput } from "@tangle-network/agent-interface/environment-provider";
 import type { CliBridgeProviderOptions } from "./provider-options.js";
+import type { CliBridgeRunSnapshot } from "./retained-run-state.js";
 import type { CliBridgeResponse, CliBridgeTransport } from "./transport.js";
 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, onAccepted?: (response: CliBridgeResponse) => void): 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>): AsyncIterable<AgentEnvironmentEvent>;

package/dist/retained-stream.js

@@ -1,4 +1,5 @@
 import { retainedEventsWithIdentity, retainedReplayRequest, } from "./retained-event-cursor.js";
+import { detachCliBridgeReader } from "./retained-control.js";
 import { requestHeaders, trimSlash } from "./transport.js";
 import { modelRequestsFromOpenAi, parseSse, responseIdentityFromOpenAi, safeJson, toolCallsFromDelta, usageFromOpenAi, } from "./wire.js";
 export class CliBridgeRequestRejectedError extends Error {
@@ -9,7 +10,15 @@ export class CliBridgeRequestRejectedError extends Error {
         this.name = "CliBridgeRequestRejectedError";
     }
 }
-export async function* streamCliBridgeTurn(options, turn, requestBody, transport, runId, lastEventId, signal, onAccepted) {
+class CliBridgeRunCancelledError extends Error {
+    detail;
+    constructor(detail) {
+        super(`cli-bridge run cancelled: ${detail}`);
+        this.detail = detail;
+        this.name = "CliBridgeRunCancelledError";
+    }
+}
+export async function* streamCliBridgeTurn(options, turn, requestBody, transport, runId, lastEventId, signal, onResponse, readAuthoritativeRun) {
     const reconnect = requestBody === undefined;
     const replay = retainedReplayRequest(lastEventId);
     const response = await transport.fetch(reconnect
@@ -37,9 +46,20 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
         }
         throw new CliBridgeRequestRejectedError(response.status, detail);
     }
-    onAccepted?.(response);
     if (!response.body)
         throw new Error("cli-bridge response body is empty");
+    try {
+        onResponse?.(response);
+    }
+    catch (error) {
+        try {
+            await detachCliBridgeReader(response.body);
+        }
+        catch (detachError) {
+            throw new AggregateError([error, detachError], `cli-bridge rejected response identity for run "${runId}" and could not detach its reader`);
+        }
+        throw error;
+    }
     let text = "";
     const sessionId = turn.sessionId ?? runId;
     const messageId = turn.turnId ?? `${sessionId}:assistant`;
@@ -51,25 +71,39 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
     let servedModel;
     let systemFingerprint;
     let textBoundaryPending = false;
-    let terminalCursor;
     let sawProtocolEnd = false;
+    let terminalFrameSeen = false;
+    let cancelledTerminalSeen = false;
+    let terminalFrame;
     for await (const frame of parseSse(response.body)) {
         if (frame.data === "[DONE]") {
             sawProtocolEnd = true;
             continue;
         }
+        if (terminalFrameSeen)
+            continue;
         const parsed = safeJson(frame.data);
         if (!parsed)
             continue;
         if (parsed.error && typeof parsed.error === "object") {
             const error = parsed.error;
             const message = typeof error.message === "string" ? error.message : "cli-bridge error";
+            const cancelled = error.type === "run_cancelled";
             yield* retainedEventsWithIdentity([{
                     type: "status",
-                    data: { status: "failed", error: message },
-                    normalized: { type: "status", status: "failed", detail: message },
+                    data: { status: cancelled ? "cancelled" : "failed", error: message },
+                    normalized: {
+                        type: "status",
+                        status: cancelled ? "cancelled" : "failed",
+                        detail: message,
+                    },
                 }], frame.id, runId, sessionId, turn.executionId, replay.anchor);
-            throw new Error(`cli-bridge: ${message}`);
+            terminalFrameSeen = true;
+            completed = cancelled;
+            cancelledTerminalSeen = cancelled;
+            if (!cancelled)
+                throw new Error(`cli-bridge: ${message}`);
+            continue;
         }
         const choice = Array.isArray(parsed.choices) ? parsed.choices[0] : undefined;
         const delta = choice?.delta;
@@ -161,6 +195,7 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
         if (toolCallDeltas.length > 0)
             textBoundaryPending = true;
         if (choice?.finish_reason) {
+            terminalFrameSeen = true;
             if (choice.finish_reason === "error") {
                 frameEvents.push({
                     type: "status",
@@ -175,61 +210,160 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
                 throw new Error("cli-bridge returned finish_reason=error");
             }
             completed = true;
-            if (lastEventId && requestBody !== undefined) {
-                terminalCursor = frame.id === undefined
-                    ? undefined
-                    : `${frame.id}:${frameEvents.length}`;
-            }
-            else {
-                frameEvents.push({
-                    type: "result",
-                    data: {
-                        finalText: text,
-                        finishReason: choice.finish_reason,
-                        status: "completed",
-                        ...identityData,
-                        ...(modelRequestsKnown ? { modelRequests: observedModelRequests } : {}),
-                    },
-                });
-            }
+            terminalFrame = {
+                ...(frame.id === undefined ? {} : { id: frame.id }),
+                events: frameEvents,
+                finishReason: choice.finish_reason,
+            };
+            continue;
         }
         yield* retainedEventsWithIdentity(frameEvents, frame.id, runId, sessionId, turn.executionId, replay.anchor);
     }
     if (!sawProtocolEnd) {
         throw new Error("cli-bridge stream ended without the [DONE] protocol marker");
     }
+    if (cancelledTerminalSeen)
+        return;
     if (!completed && lastEventId === undefined) {
+        let snapshot;
+        try {
+            snapshot = await terminalRunSnapshot(runId, readAuthoritativeRun);
+        }
+        catch (error) {
+            throw new Error("cli-bridge stream ended without a terminal result", {
+                cause: error,
+            });
+        }
+        if (snapshot.status === "cancelled") {
+            const event = cancelledEvent(`cli-bridge run "${runId}" was cancelled`);
+            yield {
+                ...event,
+                data: {
+                    ...event.data,
+                    runId,
+                    sessionId,
+                    ...(turn.executionId === undefined
+                        ? {}
+                        : { executionId: turn.executionId }),
+                },
+            };
+            return;
+        }
         throw new Error("cli-bridge stream ended without a terminal result");
     }
-    if (lastEventId && requestBody !== undefined) {
-        const result = await readFullCliBridgeResult(options, requestBody, transport, signal, onAccepted);
-        const finalModelRequests = result.modelRequests ??
-            (modelRequestsKnown ? observedModelRequests : undefined);
-        const finalCursor = terminalCursor ?? lastEventId;
-        yield {
-            type: "result",
-            data: {
-                finalText: result.text,
-                finishReason: result.finishReason,
-                status: "completed",
-                ...(result.model === undefined ? {} : { model: result.model }),
-                ...(result.system_fingerprint === undefined
-                    ? {}
-                    : { system_fingerprint: result.system_fingerprint }),
-                runId,
-                sessionId,
-                ...(turn.executionId === undefined ? {} : { executionId: turn.executionId }),
-                ...(finalCursor === undefined ? {} : { cursor: finalCursor }),
-                ...(finalModelRequests === undefined
-                    ? {}
-                    : { modelRequests: finalModelRequests }),
-            },
-            ...(result.usage && !sawUsage ? { usage: result.usage } : {}),
-            ...(finalCursor === undefined ? {} : { id: finalCursor }),
-        };
+    if (!terminalFrame) {
+        if (requestBody !== undefined && lastEventId !== undefined) {
+            try {
+                await readFullCliBridgeResult(options, requestBody, transport, signal, onResponse);
+            }
+            catch (error) {
+                if (error instanceof CliBridgeRunCancelledError)
+                    return;
+                throw error;
+            }
+        }
+        else if (requestBody === undefined) {
+            await terminalRunSnapshot(runId, readAuthoritativeRun);
+        }
+        return;
     }
+    let terminalEvent;
+    let terminalFailure;
+    if (requestBody !== undefined) {
+        let result;
+        try {
+            result = await readFullCliBridgeResult(options, requestBody, transport, signal, onResponse);
+        }
+        catch (error) {
+            if (error instanceof CliBridgeRunCancelledError) {
+                terminalEvent = cancelledEvent(error.detail);
+            }
+            else {
+                throw error;
+            }
+        }
+        if (result !== undefined) {
+            const finalModelRequests = result.modelRequests ??
+                (modelRequestsKnown ? observedModelRequests : undefined);
+            terminalEvent = {
+                type: "result",
+                data: {
+                    finalText: lastEventId === undefined ? text : result.text,
+                    finishReason: lastEventId === undefined ? terminalFrame.finishReason : result.finishReason,
+                    status: "completed",
+                    ...(result.model === undefined ? {} : { model: result.model }),
+                    ...(result.system_fingerprint === undefined
+                        ? {}
+                        : { system_fingerprint: result.system_fingerprint }),
+                    ...(finalModelRequests === undefined
+                        ? {}
+                        : { modelRequests: finalModelRequests }),
+                },
+                ...(result.usage && !sawUsage ? { usage: result.usage } : {}),
+            };
+        }
+    }
+    else {
+        const snapshot = await terminalRunSnapshot(runId, readAuthoritativeRun);
+        if (snapshot.status === "cancelled") {
+            terminalEvent = cancelledEvent(`cli-bridge run "${runId}" was cancelled`);
+        }
+        else if (snapshot.status === "error") {
+            const detail = `cli-bridge run "${runId}" ended with an error`;
+            terminalEvent = failedEvent(detail);
+            terminalFailure = new Error(detail);
+        }
+        else {
+            terminalEvent = {
+                type: "result",
+                data: {
+                    finalText: text,
+                    finishReason: terminalFrame.finishReason,
+                    status: "completed",
+                    ...(servedModel === undefined ? {} : { model: servedModel }),
+                    ...(systemFingerprint === undefined
+                        ? {}
+                        : { system_fingerprint: systemFingerprint }),
+                    ...(modelRequestsKnown ? { modelRequests: observedModelRequests } : {}),
+                },
+            };
+        }
+    }
+    if (!terminalEvent) {
+        throw new Error("cli-bridge terminal state did not produce a terminal event");
+    }
+    terminalFrame.events.push(terminalEvent);
+    yield* retainedEventsWithIdentity(terminalFrame.events, terminalFrame.id, runId, sessionId, turn.executionId, replay.anchor);
+    if (terminalFailure)
+        throw terminalFailure;
+}
+async function terminalRunSnapshot(runId, readAuthoritativeRun) {
+    if (!readAuthoritativeRun) {
+        throw new Error("cli-bridge retained stream omitted authoritative run status");
+    }
+    const snapshot = await readAuthoritativeRun();
+    if (!snapshot)
+        throw new Error(`cli-bridge lost run "${runId}" before terminal replay`);
+    if (!snapshot.terminal || snapshot.status === "running") {
+        throw new Error(`cli-bridge run "${runId}" remained active after its stream ended`);
+    }
+    return snapshot;
+}
+function cancelledEvent(detail) {
+    return {
+        type: "status",
+        data: { status: "cancelled", error: detail },
+        normalized: { type: "status", status: "cancelled", detail },
+    };
 }
-async function readFullCliBridgeResult(options, requestBody, transport, signal, onAccepted) {
+function failedEvent(detail) {
+    return {
+        type: "status",
+        data: { status: "failed", error: detail },
+        normalized: { type: "status", status: "failed", detail },
+    };
+}
+async function readFullCliBridgeResult(options, requestBody, transport, signal, onResponse) {
     const body = safeJson(requestBody);
     if (!body)
         throw new Error("cli-bridge replay request is not valid JSON");
@@ -239,15 +373,22 @@ async function readFullCliBridgeResult(options, requestBody, transport, signal,
         body: JSON.stringify({ ...body, stream: false }),
         ...(signal ? { signal } : {}),
     });
+    const responseText = await response.text();
+    onResponse?.(response);
     if (!response.ok) {
-        throw new Error(`cli-bridge replay result ${response.status}: ${await response.text()}`);
+        const error = cliBridgeError(safeJson(responseText));
+        if (error?.type === "run_cancelled") {
+            throw new CliBridgeRunCancelledError(cliBridgeErrorMessage(error));
+        }
+        throw new Error(`cli-bridge replay result ${response.status}: ${responseText}`);
     }
-    onAccepted?.(response);
-    const parsed = safeJson(await response.text());
-    if (parsed?.error && typeof parsed.error === "object") {
-        const error = parsed.error;
-        const message = typeof error.message === "string" ? error.message : "cli-bridge replay failed";
-        throw new Error(`cli-bridge replay result failed: ${message}`);
+    const parsed = safeJson(responseText);
+    const error = cliBridgeError(parsed);
+    if (error) {
+        if (error.type === "run_cancelled") {
+            throw new CliBridgeRunCancelledError(cliBridgeErrorMessage(error));
+        }
+        throw new Error(`cli-bridge replay result failed: ${cliBridgeErrorMessage(error)}`);
     }
     const choice = Array.isArray(parsed?.choices) ? parsed.choices[0] : undefined;
     const message = choice?.message && typeof choice.message === "object"
@@ -274,3 +415,12 @@ async function readFullCliBridgeResult(options, requestBody, transport, signal,
             : { system_fingerprint: responseIdentity.system_fingerprint }),
     };
 }
+function cliBridgeError(parsed) {
+    const error = parsed?.error;
+    return error && typeof error === "object" && !Array.isArray(error)
+        ? error
+        : undefined;
+}
+function cliBridgeErrorMessage(error) {
+    return typeof error.message === "string" ? error.message : "cli-bridge replay failed";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "0.6.4",
+  "version": "0.7.1",
   "description": "AgentEnvironmentProvider adapter for cli-bridge /v1/chat/completions",
   "type": "module",
   "license": "MIT",
@@ -25,6 +25,8 @@
   "files": [
     "dist/index.d.ts",
     "dist/index.js",
+    "dist/observation.d.ts",
+    "dist/observation.js",
     "dist/provider-options.d.ts",
     "dist/provider-options.js",
     "dist/retained-control.d.ts",
@@ -47,7 +49,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.51.0",
+    "@tangle-network/agent-interface": "0.52.0",
     "undici": "7.29.0"
   },
   "devDependencies": {