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

package/README.md

@@ -51,6 +51,11 @@ The returned `AgentSession` exposes status, cursor-based event replay, the termi
 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.
+Retained native runs use canonical runtime envelopes and finish with a terminal status event.
+Pass any emitted event `id` back as `since` to resume after that event.
+The canonical envelope identity remains available as `event.data.eventId`.
+Legacy runs keep the OpenAI chunk format and its `[DONE]` marker.
+The provider uses the explicit SSE event field to select the format and rejects mixed streams.
 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.

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

@@ -0,0 +1,11 @@
+import type { AgentEnvironmentEvent } from "@tangle-network/agent-interface/environment-provider";
+import type { CliBridgeSseFrame } from "./wire.js";
+interface CanonicalEventContext {
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly executionId?: string;
+}
+/** 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 {};

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-stream.js

@@ -1,4 +1,5 @@
 import { retainedEventsWithIdentity, retainedReplayRequest, } from "./retained-event-cursor.js";
+import { isTerminalCanonicalEvent, retainedCanonicalEvent, } from "./retained-canonical-event.js";
 import { detachCliBridgeReader } from "./retained-control.js";
 import { requestHeaders, trimSlash } from "./transport.js";
 import { modelRequestsFromOpenAi, parseSse, responseIdentityFromOpenAi, safeJson, toolCallsFromDelta, usageFromOpenAi, } from "./wire.js";
@@ -72,14 +73,46 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
     let systemFingerprint;
     let textBoundaryPending = false;
     let sawProtocolEnd = false;
+    let protocol = "unknown";
+    let canonicalTerminalSeen = false;
     let terminalFrameSeen = false;
     let cancelledTerminalSeen = false;
     let terminalFrame;
     for await (const frame of parseSse(response.body)) {
         if (frame.data === "[DONE]") {
+            if (protocol === "canonical") {
+                throw new Error("cli-bridge mixed canonical and OpenAI stream formats");
+            }
+            protocol = "openai";
             sawProtocolEnd = true;
             continue;
         }
+        if (frame.event !== undefined) {
+            if (protocol === "openai") {
+                throw new Error("cli-bridge mixed canonical and OpenAI stream formats");
+            }
+            protocol = "canonical";
+            if (canonicalTerminalSeen) {
+                throw new Error("cli-bridge emitted an event after canonical terminal status");
+            }
+            const event = retainedCanonicalEvent(frame, {
+                runId,
+                sessionId,
+                ...(turn.executionId === undefined
+                    ? {}
+                    : { executionId: turn.executionId }),
+            });
+            if (!event) {
+                throw new Error("cli-bridge emitted an empty canonical event");
+            }
+            canonicalTerminalSeen = isTerminalCanonicalEvent(event);
+            yield event;
+            continue;
+        }
+        if (protocol === "canonical") {
+            throw new Error("cli-bridge mixed canonical and OpenAI stream formats");
+        }
+        protocol = "openai";
         if (terminalFrameSeen)
             continue;
         const parsed = safeJson(frame.data);
@@ -219,6 +252,12 @@ export async function* streamCliBridgeTurn(options, turn, requestBody, transport
         }
         yield* retainedEventsWithIdentity(frameEvents, frame.id, runId, sessionId, turn.executionId, replay.anchor);
     }
+    if (protocol === "canonical") {
+        if (!canonicalTerminalSeen) {
+            throw new Error("cli-bridge canonical stream ended without terminal status");
+        }
+        return;
+    }
     if (!sawProtocolEnd) {
         throw new Error("cli-bridge stream ended without the [DONE] protocol marker");
     }

package/dist/wire.d.ts

@@ -6,6 +6,7 @@ export declare function toChatCompletionsBody(options: CliBridgeProviderOptions,
 export interface CliBridgeSseFrame {
     readonly data: string;
     readonly id?: string;
+    readonly event?: string;
 }
 export declare function parseSse(body: AsyncIterable<Uint8Array>): AsyncIterable<CliBridgeSseFrame>;
 export declare function toolCallsFromDelta(value: unknown): Array<{

package/dist/wire.js

@@ -106,7 +106,11 @@ function dataFromFrame(frame) {
     if (!data)
         return undefined;
     const id = lines.find((line) => line.startsWith("id:"))?.slice("id:".length).trim();
-    return { data, ...(id ? { id } : {}) };
+    const event = lines
+        .find((line) => line.startsWith("event:"))
+        ?.slice("event:".length)
+        .trim();
+    return { data, ...(id ? { id } : {}), ...(event ? { event } : {}) };
 }
 export function toolCallsFromDelta(value) {
     if (!value || typeof value !== "object")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "AgentEnvironmentProvider adapter for cli-bridge /v1/chat/completions",
   "type": "module",
   "license": "MIT",
@@ -29,6 +29,8 @@
     "dist/observation.js",
     "dist/provider-options.d.ts",
     "dist/provider-options.js",
+    "dist/retained-canonical-event.d.ts",
+    "dist/retained-canonical-event.js",
     "dist/retained-control.d.ts",
     "dist/retained-control.js",
     "dist/retained-environment.d.ts",