@tangle-network/agent-provider-cli-bridge 0.5.0 → 0.6.1

package/dist/retained-execution.js

@@ -0,0 +1,304 @@
+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 { requestHeaders, trimSlash } from "./transport.js";
+import { modelRequestCount } from "./wire.js";
+export async function* streamTrackedCliBridgeTurn(options, environmentInput, prepared, transport, runs, sessions, readers) {
+    const originalTurn = prepared.turn;
+    if (originalTurn.detach) {
+        throw new Error("cli-bridge provider does not support detached turns");
+    }
+    const controller = new AbortController();
+    const signals = [
+        originalTurn.signal,
+        environmentInput.signal,
+        controller.signal,
+    ].filter((signal) => signal !== undefined);
+    const signal = signals.length > 0 ? AbortSignal.any(signals) : undefined;
+    const turn = {
+        ...originalTurn,
+        ...(signal ? { signal } : {}),
+    };
+    const run = prepared.run;
+    const previousRun = bindCliBridgeRun(run, runs);
+    const previousSessionRun = bindCliBridgeSession(run, sessions);
+    run.readers.add(controller);
+    readers.add(controller);
+    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))) {
+            yield event;
+        }
+        drained = true;
+        if (runs.get(run.id) === run)
+            runs.delete(run.id);
+    }
+    catch (error) {
+        threw = true;
+        if (error instanceof CliBridgeRequestRejectedError) {
+            restoreCliBridgeRun(run, previousRun, runs);
+            restoreCliBridgeSession(run, previousSessionRun, sessions);
+            throw error;
+        }
+        let snapshot;
+        try {
+            snapshot = await getCliBridgeRun(options, transport, run);
+        }
+        catch {
+            snapshot = undefined;
+        }
+        if (snapshot?.terminal) {
+            if (runs.get(run.id) === run)
+                runs.delete(run.id);
+        }
+        else if (originalTurn.signal?.aborted || environmentInput.signal?.aborted) {
+            await cancelCliBridgeRun(options, transport, run);
+            if (runs.get(run.id) === run)
+                runs.delete(run.id);
+        }
+        throw error;
+    }
+    finally {
+        if (!drained && !threw && runs.get(run.id) === run) {
+            await cancelCliBridgeRun(options, transport, run);
+            runs.delete(run.id);
+        }
+        run.readers.delete(controller);
+        readers.delete(controller);
+    }
+}
+export async function dispatchCliBridgeTurn(options, environmentInput, prepared, transport, providerName, runs, sessions) {
+    const run = prepared.run;
+    const previousRun = bindCliBridgeRun(run, runs);
+    const previousSessionRun = bindCliBridgeSession(run, sessions);
+    const signals = [
+        prepared.turn.signal,
+        environmentInput.signal,
+    ].filter((signal) => signal !== undefined);
+    const signal = signals.length > 0 ? AbortSignal.any(signals) : undefined;
+    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.
+            }
+            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);
+        const controlRef = exactControlRefForRun(run, providerName);
+        run.controlRef = controlRef;
+        await detachCliBridgeReader(responseBody);
+        responseBody = undefined;
+        return {
+            id: run.sessionId,
+            provider: providerName,
+            controlRef,
+            metadata: {
+                runId: run.id,
+                requestDigest: run.requestDigest,
+            },
+        };
+    }
+    catch (error) {
+        let failure = error;
+        if (responseBody) {
+            try {
+                await detachCliBridgeReader(responseBody);
+            }
+            catch (detachError) {
+                failure = new AggregateError([failure, detachError], `cli-bridge dispatch "${run.id}" failed and its reader did not detach`);
+            }
+        }
+        if (failure instanceof CliBridgeRequestRejectedError) {
+            restoreCliBridgeRun(run, previousRun, runs);
+            restoreCliBridgeSession(run, previousSessionRun, sessions);
+            throw failure;
+        }
+        if (accepted || signal?.aborted) {
+            try {
+                await cancelCliBridgeRun(options, transport, run);
+                if (runs.get(run.id) === run)
+                    runs.delete(run.id);
+            }
+            catch (cancellationError) {
+                throw new AggregateError([failure, cancellationError], `cli-bridge dispatch "${run.id}" failed and cancellation was not confirmed`);
+            }
+        }
+        else {
+            restoreCliBridgeRun(run, previousRun, runs);
+        }
+        restoreCliBridgeSession(run, previousSessionRun, sessions);
+        throw failure;
+    }
+}
+export async function* streamCliBridgeSessionEvents(options, environmentInput, run, transport, runs, readers, eventOptions) {
+    if (eventOptions?.executionId !== undefined &&
+        eventOptions.executionId !== run.executionId) {
+        throw new Error("cli-bridge event request targets another retained execution");
+    }
+    const controller = new AbortController();
+    const signals = [
+        eventOptions?.signal,
+        environmentInput.signal,
+        controller.signal,
+    ].filter((signal) => signal !== undefined);
+    const signal = signals.length > 0 ? AbortSignal.any(signals) : undefined;
+    run.readers.add(controller);
+    readers.add(controller);
+    let drained = false;
+    try {
+        yield* streamCliBridgeTurn(options, {
+            ...(run.sessionId ? { sessionId: run.sessionId } : {}),
+            executionId: run.executionId,
+            turnId: run.turnId,
+        }, undefined, transport, run.id, eventOptions?.since ?? "0", signal, (response) => captureCliBridgeRunIdentity(response, run, false));
+        drained = true;
+        if (runs.get(run.id) === run)
+            runs.delete(run.id);
+    }
+    finally {
+        if (!drained) {
+            controller.abort(new DOMException("cli-bridge session event reader detached", "AbortError"));
+        }
+        run.readers.delete(controller);
+        readers.delete(controller);
+    }
+}
+export async function collectCliBridgeTurnResult(source, run, options, transport, signal) {
+    const events = [];
+    let text = "";
+    let usage;
+    let observedModelRequests = 0;
+    let modelRequestsKnown = false;
+    let terminalModelRequests;
+    let servedModel;
+    let systemFingerprint;
+    let streamError;
+    try {
+        for await (const event of source) {
+            events.push(event);
+            const finalText = event.data.finalText;
+            if (typeof finalText === "string") {
+                text = finalText;
+            }
+            else if (typeof event.data.delta === "string") {
+                text += event.data.delta;
+            }
+            usage = addTokenUsage(usage, event.usage);
+            const eventModel = event.data.model;
+            const eventFingerprint = event.data.system_fingerprint;
+            if (typeof eventModel === "string" && eventModel.length > 0)
+                servedModel = eventModel;
+            if (typeof eventFingerprint === "string" && eventFingerprint.length > 0) {
+                systemFingerprint = eventFingerprint;
+            }
+            const modelRequests = modelRequestCount(event.data.modelRequests);
+            if (modelRequests !== undefined) {
+                if (event.type === "result") {
+                    terminalModelRequests = modelRequests;
+                }
+                else if (event.type === "usage") {
+                    observedModelRequests += modelRequests;
+                    modelRequestsKnown = true;
+                }
+            }
+        }
+    }
+    catch (error) {
+        streamError = error;
+    }
+    const snapshot = await getCliBridgeRun(options, transport, run, undefined, signal);
+    if (!snapshot) {
+        if (streamError)
+            throw streamError;
+        throw new Error(`cli-bridge lost run "${run.id}" before reading its result`);
+    }
+    if (!snapshot.terminal) {
+        if (streamError)
+            throw streamError;
+        throw new Error(`cli-bridge run "${run.id}" has no terminal result`);
+    }
+    const success = snapshot.status === "done" && streamError === undefined;
+    return {
+        text,
+        success,
+        ...(!success
+            ? {
+                error: streamError instanceof Error
+                    ? streamError.message
+                    : `cli-bridge run ended ${snapshot.status}`,
+            }
+            : {}),
+        ...(run.sessionId ? { sessionId: run.sessionId } : {}),
+        ...(usage ? { usage } : {}),
+        metadata: {
+            runId: run.id,
+            executionId: run.executionId,
+            status: snapshot.status,
+            ...(run.requestDigest ? { requestDigest: run.requestDigest } : {}),
+            ...(terminalModelRequests !== undefined
+                ? { modelRequests: terminalModelRequests }
+                : modelRequestsKnown
+                    ? { modelRequests: observedModelRequests }
+                    : {}),
+            ...(servedModel === undefined ? {} : { model: servedModel }),
+            ...(systemFingerprint === undefined ? {} : { system_fingerprint: systemFingerprint }),
+        },
+        events,
+    };
+}
+function addTokenUsage(current, next) {
+    if (!next)
+        return current;
+    if (!current)
+        return { ...next };
+    return {
+        inputTokens: current.inputTokens + next.inputTokens,
+        outputTokens: current.outputTokens + next.outputTokens,
+        ...(current.totalTokens !== undefined || next.totalTokens !== undefined
+            ? { totalTokens: (current.totalTokens ?? 0) + (next.totalTokens ?? 0) }
+            : {}),
+        ...(current.cacheReadInputTokens !== undefined ||
+            next.cacheReadInputTokens !== undefined
+            ? {
+                cacheReadInputTokens: (current.cacheReadInputTokens ?? 0) +
+                    (next.cacheReadInputTokens ?? 0),
+            }
+            : {}),
+        ...(current.cacheCreationInputTokens !== undefined ||
+            next.cacheCreationInputTokens !== undefined
+            ? {
+                cacheCreationInputTokens: (current.cacheCreationInputTokens ?? 0) +
+                    (next.cacheCreationInputTokens ?? 0),
+            }
+            : {}),
+        ...(current.reasoningTokens !== undefined || next.reasoningTokens !== undefined
+            ? {
+                reasoningTokens: (current.reasoningTokens ?? 0) + (next.reasoningTokens ?? 0),
+            }
+            : {}),
+        ...(current.cost !== undefined || next.cost !== undefined
+            ? { cost: (current.cost ?? 0) + (next.cost ?? 0) }
+            : {}),
+    };
+}

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

@@ -0,0 +1,38 @@
+import { type AgentExactRunControlRef, type AgentRunControlRef, type Sha256Digest } from "@tangle-network/agent-interface";
+import type { AgentTurnInput, CreateAgentEnvironmentInput } from "@tangle-network/agent-interface/environment-provider";
+import type { CliBridgeProviderOptions } from "./provider-options.js";
+export interface CliBridgeRun {
+    readonly id: string;
+    readonly environmentId: string;
+    readonly sessionId?: string;
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly requestBody: string;
+    readonly readers: Set<AbortController>;
+    requestDigest?: Sha256Digest;
+    controlRef?: AgentExactRunControlRef;
+    cancellation?: Promise<CliBridgeRunSnapshot>;
+}
+export interface CliBridgeSessionState {
+    readonly id: string;
+    current: CliBridgeRun;
+}
+export interface CliBridgeRunSnapshot {
+    readonly id: string;
+    readonly requestDigest?: Sha256Digest;
+    readonly status: "running" | "done" | "error" | "cancelled";
+    readonly terminal: boolean;
+}
+export interface PreparedCliBridgeRun {
+    readonly run: CliBridgeRun;
+    readonly turn: AgentTurnInput;
+}
+export declare function exactControlRefForRun(run: CliBridgeRun, providerName: string): AgentExactRunControlRef;
+export declare function exactControlRefForSession(value: AgentRunControlRef, providerName: string, environmentId: string, sessionId: string): AgentExactRunControlRef;
+export declare function runFromControlRef(controlRef: AgentExactRunControlRef): CliBridgeRun;
+export declare function assertRunMatchesControlRef(run: CliBridgeRun, controlRef: AgentExactRunControlRef): void;
+export declare function prepareCliBridgeRun(options: CliBridgeProviderOptions, environmentInput: CreateAgentEnvironmentInput, originalTurn: AgentTurnInput, environmentId: string, requireSession: boolean): PreparedCliBridgeRun;
+export declare function bindCliBridgeRun(prepared: CliBridgeRun, runs: Map<string, CliBridgeRun>): CliBridgeRun | undefined;
+export declare function restoreCliBridgeRun(run: CliBridgeRun, previous: CliBridgeRun | undefined, runs: Map<string, CliBridgeRun>): void;
+export declare function bindCliBridgeSession(run: CliBridgeRun, sessions: Map<string, CliBridgeSessionState>): CliBridgeRun | undefined;
+export declare function restoreCliBridgeSession(run: CliBridgeRun, previous: CliBridgeRun | undefined, sessions: Map<string, CliBridgeSessionState>): void;

package/dist/retained-run-state.js

@@ -0,0 +1,97 @@
+import { AgentExactRunControlRefSchema, } from "@tangle-network/agent-interface";
+import { cliBridgeRunId, toChatCompletionsBody } from "./wire.js";
+export function exactControlRefForRun(run, providerName) {
+    if (!run.sessionId || !run.requestDigest) {
+        throw new Error("cli-bridge did not return complete retained run coordinates");
+    }
+    return Object.freeze(AgentExactRunControlRefSchema.parse({
+        runId: run.id,
+        provider: providerName,
+        environmentId: run.environmentId,
+        sessionId: run.sessionId,
+        executionId: run.executionId,
+        requestDigest: run.requestDigest,
+    }));
+}
+export function exactControlRefForSession(value, providerName, environmentId, sessionId) {
+    const controlRef = Object.freeze(AgentExactRunControlRefSchema.parse(value));
+    if (controlRef.provider !== providerName ||
+        controlRef.environmentId !== environmentId ||
+        controlRef.sessionId !== sessionId) {
+        throw new Error("cli-bridge control reference does not bind to this session");
+    }
+    return controlRef;
+}
+export function runFromControlRef(controlRef) {
+    return {
+        id: controlRef.runId,
+        environmentId: controlRef.environmentId,
+        sessionId: controlRef.sessionId,
+        executionId: controlRef.executionId,
+        turnId: controlRef.executionId,
+        requestBody: "",
+        readers: new Set(),
+        requestDigest: controlRef.requestDigest,
+        controlRef,
+    };
+}
+export function assertRunMatchesControlRef(run, controlRef) {
+    if (run.id !== controlRef.runId ||
+        run.environmentId !== controlRef.environmentId ||
+        run.sessionId !== controlRef.sessionId ||
+        run.executionId !== controlRef.executionId ||
+        run.requestDigest !== controlRef.requestDigest) {
+        throw new Error("cli-bridge control reference conflicts with the retained run");
+    }
+    run.controlRef = controlRef;
+}
+export function prepareCliBridgeRun(options, environmentInput, originalTurn, environmentId, requireSession) {
+    const turnId = originalTurn.turnId ?? crypto.randomUUID();
+    const runId = cliBridgeRunId(environmentId, originalTurn, turnId);
+    const sessionId = originalTurn.sessionId ?? (requireSession ? runId : undefined);
+    const turn = {
+        ...originalTurn,
+        turnId,
+        ...(sessionId ? { sessionId } : {}),
+    };
+    return {
+        turn,
+        run: {
+            id: runId,
+            environmentId,
+            ...(sessionId ? { sessionId } : {}),
+            executionId: originalTurn.executionId ?? runId,
+            turnId,
+            requestBody: JSON.stringify(toChatCompletionsBody(options, environmentInput, turn, runId)),
+            readers: new Set(),
+        },
+    };
+}
+export function bindCliBridgeRun(prepared, runs) {
+    const previous = runs.get(prepared.id);
+    runs.set(prepared.id, prepared);
+    return previous;
+}
+export function restoreCliBridgeRun(run, previous, runs) {
+    if (runs.get(run.id) !== run)
+        return;
+    if (previous)
+        runs.set(run.id, previous);
+    else
+        runs.delete(run.id);
+}
+export function bindCliBridgeSession(run, sessions) {
+    if (!run.sessionId)
+        return undefined;
+    const previous = sessions.get(run.sessionId)?.current;
+    sessions.set(run.sessionId, { id: run.sessionId, current: run });
+    return previous;
+}
+export function restoreCliBridgeSession(run, previous, sessions) {
+    if (!run.sessionId || sessions.get(run.sessionId)?.current !== run)
+        return;
+    if (previous)
+        sessions.set(run.sessionId, { id: run.sessionId, current: previous });
+    else
+        sessions.delete(run.sessionId);
+}

package/dist/retained-stream.d.ts

@@ -0,0 +1,8 @@
+import type { AgentEnvironmentEvent, AgentTurnInput } from "@tangle-network/agent-interface/environment-provider";
+import type { CliBridgeProviderOptions } from "./provider-options.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>;