@tangle-network/agent-provider-cli-bridge 0.2.33 → 0.3.1

package/README.md

@@ -8,9 +8,23 @@ import { createCliBridgeProvider } from '@tangle-network/agent-provider-cli-brid
 const provider = createCliBridgeProvider({
   baseUrl: 'http://127.0.0.1:8787',
   bearerToken: process.env.CLI_BRIDGE_TOKEN,
-  defaultModel: 'codex',
+})
+
+const environment = await provider.create({
+  profile: {
+    name: 'researcher',
+    harness: 'codex',
+    model: { default: 'gpt-5' },
+  },
 })
 ```
 
+The bridge model is selected from run data in this order: the turn, the provider default, or the profile's `harness` plus `model.default`.
+Execution fails before network use when none is present.
+
+Passing the same `sessionId` on later turns continues the same CLI conversation.
+`executionId` gives a turn stable bridge identity, and `lastEventId` reattaches after a reader failure.
+Stopping a reader or destroying the environment cancels every active bridge run and waits for terminal confirmation.
+
 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/index.d.ts

@@ -17,6 +17,8 @@ export interface CliBridgeProviderOptions {
     headersTimeoutMs?: number;
     /** Maximum idle time between response body chunks. Defaults to no timeout. */
     bodyTimeoutMs?: number;
+    /** Maximum wait for cli-bridge to confirm cancellation. Defaults to 30 seconds. */
+    cancelWaitMs?: number;
     fetch?: typeof fetch;
     name?: string;
     capabilities?: AgentEnvironmentCapabilities;

package/dist/index.js

@@ -1,78 +1,250 @@
+import { createHash } from "node:crypto";
 import { Agent, fetch as undiciFetch } from "undici";
 export function createCliBridgeProvider(options) {
     assertTimeout(options.headersTimeoutMs, "headersTimeoutMs");
     assertTimeout(options.bodyTimeoutMs, "bodyTimeoutMs");
+    assertTimeout(options.cancelWaitMs, "cancelWaitMs");
     const name = options.name ?? "cli-bridge";
     return {
         name,
         capabilities: () => options.capabilities ?? defaultCliBridgeCapabilities(),
         async create(input) {
             const transport = createTransport(options);
+            const environmentId = input.idempotencyKey ?? crypto.randomUUID();
+            const runs = new Map();
+            const readers = new Set();
             let destroyed = false;
             let closePromise;
-            return {
-                id: input.idempotencyKey ?? input.name ?? crypto.randomUUID(),
+            const stream = async function* (turn) {
+                if (destroyed)
+                    throw new Error("cli-bridge environment is destroyed");
+                yield* streamTrackedCliBridgeTurn(options, input, turn, transport, environmentId, runs, readers);
+            };
+            const environment = {
+                id: environmentId,
                 provider: name,
                 ...(input.name ? { name: input.name } : {}),
                 status: async () => (destroyed ? "stopped" : "running"),
-                stream: (turn) => {
-                    if (destroyed)
-                        throw new Error("cli-bridge environment is destroyed");
-                    return streamCliBridgeTurn(options, input, turn, transport);
-                },
+                stream,
                 placement: async () => ({
                     kind: options.defaultExecution?.kind === "sandbox" ? "sandbox" : "local",
                     providerMetadata: { baseUrl: options.baseUrl },
                 }),
-                destroy: () => {
+                async destroy() {
+                    if (closePromise)
+                        return closePromise;
                     destroyed = true;
-                    closePromise ??= transport.close();
-                    return closePromise;
+                    let cancellationsConfirmed = false;
+                    const attempt = (async () => {
+                        const cancellations = await Promise.allSettled(Array.from(runs.values()).map(async (run) => {
+                            const snapshot = await cancelCliBridgeRun(options, transport, run);
+                            if (runs.get(run.id) === run)
+                                runs.delete(run.id);
+                            return snapshot;
+                        }));
+                        const failures = cancellations.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+                        if (failures.length === 1)
+                            throw failures[0];
+                        if (failures.length > 1) {
+                            throw new AggregateError(failures, "cli-bridge environment cancellation failed");
+                        }
+                        cancellationsConfirmed = true;
+                        for (const reader of readers) {
+                            reader.abort(new DOMException("cli-bridge environment was destroyed", "AbortError"));
+                        }
+                        await transport.close();
+                    })();
+                    closePromise = attempt;
+                    try {
+                        await attempt;
+                    }
+                    catch (error) {
+                        closePromise = undefined;
+                        if (!cancellationsConfirmed)
+                            destroyed = false;
+                        throw error;
+                    }
                 },
             };
+            return environment;
         },
     };
 }
-async function* streamCliBridgeTurn(options, environmentInput, turn, transport) {
+async function* streamTrackedCliBridgeTurn(options, environmentInput, originalTurn, transport, environmentId, runs, readers) {
+    if (originalTurn.detach) {
+        throw new Error("cli-bridge provider does not support detached turns");
+    }
+    const sessionId = originalTurn.sessionId;
+    const turnId = originalTurn.turnId ?? crypto.randomUUID();
+    const runId = cliBridgeRunId(environmentId, originalTurn, turnId);
+    const controller = new AbortController();
+    const signals = [
+        originalTurn.signal,
+        environmentInput.signal,
+        controller.signal,
+    ].filter((signal) => signal !== undefined);
+    const turn = {
+        ...originalTurn,
+        turnId,
+        ...(signals.length > 0 ? { signal: AbortSignal.any(signals) } : {}),
+    };
+    const requestBody = JSON.stringify(toChatCompletionsBody(options, environmentInput, turn, runId));
+    const run = runs.get(runId) ?? {
+        id: runId,
+        readers: new Set(),
+    };
+    run.readers.add(controller);
+    readers.add(controller);
+    runs.set(runId, run);
+    let drained = false;
+    let threw = false;
+    try {
+        for await (const event of streamCliBridgeTurn(options, turn, requestBody, transport, runId, originalTurn.lastEventId, signals.length > 0 ? AbortSignal.any(signals) : undefined)) {
+            yield event;
+        }
+        drained = true;
+        if (runs.get(run.id) === run)
+            runs.delete(run.id);
+    }
+    catch (error) {
+        threw = true;
+        if (error instanceof CliBridgeRequestRejectedError) {
+            if (runs.get(run.id) === run)
+                runs.delete(run.id);
+            throw error;
+        }
+        let snapshot;
+        try {
+            snapshot = await getCliBridgeRun(options, transport, run.id);
+        }
+        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);
+    }
+}
+async function cancelCliBridgeRun(options, transport, run) {
+    if (run.cancellation)
+        return run.cancellation;
+    run.cancellation = (async () => {
+        const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(run.id)}/cancel`, {
+            method: "POST",
+            headers: requestHeaders(options),
+            body: "{}",
+        });
+        if (!response.ok) {
+            throw new Error(`cli-bridge cancel ${response.status}: ${await response.text()}`);
+        }
+        let snapshot = cancelSnapshot(await response.text());
+        const waitBudgetMs = options.cancelWaitMs ?? 30_000;
+        const deadline = Date.now() + waitBudgetMs;
+        while (!snapshot.terminal) {
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0)
+                break;
+            snapshot = await getCliBridgeRun(options, transport, run.id, Math.min(remainingMs, 30_000));
+            if (snapshot === null) {
+                throw new Error(`cli-bridge lost run "${run.id}" before confirming cancellation`);
+            }
+        }
+        if (!snapshot?.terminal) {
+            throw new Error(`cli-bridge run "${run.id}" did not confirm terminal cancellation`);
+        }
+        for (const reader of run.readers) {
+            reader.abort(new DOMException(`cli-bridge run ended ${snapshot.status}`, "AbortError"));
+        }
+        return snapshot;
+    })();
+    try {
+        return await run.cancellation;
+    }
+    finally {
+        run.cancellation = undefined;
+    }
+}
+async function getCliBridgeRun(options, transport, runId, waitMs) {
+    const query = waitMs === undefined ? "" : `?wait_ms=${waitMs}`;
+    const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/runs/${encodeURIComponent(runId)}${query}`, {
+        method: "GET",
+        headers: requestHeaders(options),
+    });
+    if (response.status === 404)
+        return null;
+    if (!response.ok) {
+        throw new Error(`cli-bridge run status ${response.status}: ${await response.text()}`);
+    }
+    return runSnapshot(await response.text());
+}
+async function* streamCliBridgeTurn(options, turn, requestBody, transport, runId, lastEventId, signal) {
     const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/chat/completions`, {
         method: "POST",
         headers: {
-            "content-type": "application/json",
+            ...requestHeaders(options),
             accept: "text/event-stream",
-            ...(options.bearerToken ? { authorization: `Bearer ${options.bearerToken}` } : {}),
             ...(turn.sessionId ? { "x-session-id": turn.sessionId } : {}),
+            ...(lastEventId ? { "last-event-id": lastEventId } : {}),
         },
-        body: JSON.stringify(toChatCompletionsBody(options, environmentInput, turn)),
-        signal: turn.signal ?? environmentInput.signal,
+        body: requestBody,
+        signal,
     });
     if (!response.ok) {
-        throw new Error(`cli-bridge ${response.status}: ${await response.text()}`);
+        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);
     }
     if (!response.body)
         throw new Error("cli-bridge response body is empty");
     let text = "";
-    const sessionId = turn.sessionId ?? environmentInput.idempotencyKey ?? environmentInput.name ?? "cli-bridge";
+    const sessionId = turn.sessionId ?? runId;
     const messageId = turn.turnId ?? `${sessionId}:assistant`;
     const emittedToolCalls = new Set();
     let completed = false;
-    for await (const event of parseSse(response.body)) {
-        if (event === "[DONE]")
+    let terminalCursor;
+    for await (const frame of parseSse(response.body)) {
+        if (frame.data === "[DONE]")
             continue;
-        const parsed = safeJson(event);
+        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";
-            yield { type: "status", data: { status: "failed", error: message } };
+            yield {
+                type: "status",
+                data: { status: "failed", error: message },
+                ...(frame.id ? { id: frame.id } : {}),
+            };
             throw new Error(`cli-bridge: ${message}`);
         }
         const choice = Array.isArray(parsed.choices) ? parsed.choices[0] : undefined;
         const delta = choice?.delta;
         const chunk = delta && typeof delta.content === "string" ? delta.content : "";
         const nextUsage = usageFromOpenAi(parsed.usage);
+        const frameEvents = [];
         if (nextUsage) {
-            yield { type: "usage", data: {}, usage: nextUsage };
+            frameEvents.push({ type: "usage", data: {}, usage: nextUsage });
         }
         if (chunk) {
             text += chunk;
@@ -88,11 +260,11 @@ async function* streamCliBridgeTurn(options, environmentInput, turn, transport)
                 part,
                 delta: chunk,
             };
-            yield {
+            frameEvents.push({
                 type: "message.part.updated",
                 data: { part, delta: chunk },
                 normalized,
-            };
+            });
         }
         for (const toolCall of toolCallsFromDelta(delta)) {
             const callId = toolCall.id ?? `${messageId}:tool:${toolCall.index}`;
@@ -112,33 +284,93 @@ async function* streamCliBridgeTurn(options, environmentInput, turn, transport)
                 type: "message.part.updated",
                 part,
             };
-            yield {
+            frameEvents.push({
                 type: "message.part.updated",
                 data: { part },
                 normalized,
-            };
+            });
         }
         if (choice?.finish_reason) {
             if (choice.finish_reason === "error") {
-                yield {
+                frameEvents.push({
                     type: "status",
                     data: { status: "failed", error: "cli-bridge returned finish_reason=error" },
-                };
+                });
+                yield* eventsWithCursor(frameEvents, frame.id);
                 throw new Error("cli-bridge returned finish_reason=error");
             }
             completed = true;
-            yield {
-                type: "result",
-                data: {
-                    finalText: text,
-                    finishReason: choice.finish_reason,
-                    status: "completed",
-                },
-            };
+            if (lastEventId) {
+                terminalCursor = frame.id;
+            }
+            else {
+                frameEvents.push({
+                    type: "result",
+                    data: {
+                        finalText: text,
+                        finishReason: choice.finish_reason,
+                        status: "completed",
+                    },
+                });
+            }
         }
+        yield* eventsWithCursor(frameEvents, choice?.finish_reason && lastEventId ? undefined : frame.id);
     }
-    if (!completed)
+    if (!completed && !lastEventId) {
         throw new Error("cli-bridge stream ended without a terminal result");
+    }
+    if (lastEventId) {
+        const result = await readFullCliBridgeResult(options, requestBody, transport, signal);
+        yield {
+            type: "result",
+            data: {
+                finalText: result.text,
+                finishReason: result.finishReason,
+                status: "completed",
+            },
+            id: terminalCursor ?? lastEventId,
+        };
+    }
+}
+class CliBridgeRequestRejectedError extends Error {
+    status;
+    constructor(status, detail) {
+        super(`cli-bridge ${status}: ${detail}`);
+        this.status = status;
+        this.name = "CliBridgeRequestRejectedError";
+    }
+}
+async function readFullCliBridgeResult(options, requestBody, transport, signal) {
+    const body = safeJson(requestBody);
+    if (!body)
+        throw new Error("cli-bridge replay request is not valid JSON");
+    const response = await transport.fetch(`${trimSlash(options.baseUrl)}/v1/chat/completions`, {
+        method: "POST",
+        headers: requestHeaders(options),
+        body: JSON.stringify({ ...body, stream: false }),
+        signal,
+    });
+    if (!response.ok) {
+        throw new Error(`cli-bridge replay result ${response.status}: ${await response.text()}`);
+    }
+    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 choice = Array.isArray(parsed?.choices) ? parsed.choices[0] : undefined;
+    const message = choice?.message && typeof choice.message === "object"
+        ? choice.message
+        : undefined;
+    if (typeof message?.content !== "string" ||
+        typeof choice?.finish_reason !== "string") {
+        throw new Error("cli-bridge replay result returned an invalid completion");
+    }
+    if (choice.finish_reason === "error" || choice.finish_reason === "timeout") {
+        throw new Error(`cli-bridge replay result ended ${choice.finish_reason}`);
+    }
+    return { text: message.content, finishReason: choice.finish_reason };
 }
 function createTransport(options) {
     if (options.fetch) {
@@ -167,13 +399,14 @@ function assertTimeout(value, name) {
         throw new Error(`createCliBridgeProvider ${name} must be a non-negative integer`);
     }
 }
-function toChatCompletionsBody(options, environmentInput, turn) {
+function toChatCompletionsBody(options, environmentInput, turn, runId) {
     const profile = inlineProfile(environmentInput.profile);
     return {
-        model: turn.model ?? environmentInput.backend ?? options.defaultModel ?? "opencode",
+        model: resolveBridgeModel(options, environmentInput, turn, profile),
         messages: messagesFromTurn(turn, profile),
         stream: true,
         ...(turn.sessionId ? { session_id: turn.sessionId } : {}),
+        run_id: runId,
         ...(options.defaultMode ? { mode: options.defaultMode } : {}),
         ...(profile ? { agent_profile: profile } : {}),
         ...(environmentInput.env ? { env: environmentInput.env } : {}),
@@ -186,6 +419,25 @@ function toChatCompletionsBody(options, environmentInput, turn) {
         },
     };
 }
+function resolveBridgeModel(options, environmentInput, turn, profile) {
+    const harness = environmentInput.backend ?? profile?.harness;
+    const model = turn.model ?? options.defaultModel ?? profile?.model?.default;
+    const provider = profile?.model?.provider;
+    if (!harness) {
+        if (model)
+            return model;
+        throw new Error("createCliBridgeProvider requires an explicit bridge model or a profile/backend harness");
+    }
+    if (!model || model === harness)
+        return harness;
+    if (model.startsWith(`${harness}/`))
+        return model;
+    if (model.includes("/"))
+        return `${harness}/${model}`;
+    if (provider)
+        return `${harness}/${provider}/${model}`;
+    return `${harness}/${model}`;
+}
 function messagesFromTurn(turn, profile) {
     const messages = [];
     const systemPrompt = profile?.prompt?.systemPrompt;
@@ -223,14 +475,14 @@ async function* parseSse(body) {
             const frame = buffer.slice(0, boundary.index);
             buffer = buffer.slice(boundary.index + boundary.length);
             const data = dataFromFrame(frame);
-            if (data !== undefined)
+            if (data)
                 yield data;
             boundary = findFrameBoundary(buffer);
         }
     }
     if (buffer) {
         const data = dataFromFrame(buffer);
-        if (data !== undefined)
+        if (data)
             yield data;
     }
 }
@@ -249,7 +501,16 @@ function dataFromFrame(frame) {
         .filter((line) => line.startsWith("data:"))
         .map((line) => line.slice("data:".length).trimStart())
         .join("\n");
-    return data || undefined;
+    if (!data)
+        return undefined;
+    const id = lines.find((line) => line.startsWith("id:"))?.slice("id:".length).trim();
+    return { data, ...(id ? { id } : {}) };
+}
+function* eventsWithCursor(events, cursor) {
+    for (let index = 0; index < events.length; index += 1) {
+        const event = events[index];
+        yield cursor && index === events.length - 1 ? { ...event, id: cursor } : event;
+    }
 }
 function toolCallsFromDelta(value) {
     if (!value || typeof value !== "object")
@@ -302,6 +563,52 @@ function usageFromOpenAi(value) {
         ...(cost !== undefined ? { cost } : {}),
     };
 }
+function requestHeaders(options) {
+    return {
+        "content-type": "application/json",
+        ...(options.bearerToken ? { authorization: `Bearer ${options.bearerToken}` } : {}),
+    };
+}
+function cliBridgeRunId(environmentId, turn, turnId) {
+    if (turn.executionId &&
+        turn.executionId.length <= 128 &&
+        /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u.test(turn.executionId)) {
+        return turn.executionId;
+    }
+    const digest = createHash("sha256")
+        .update(environmentId)
+        .update("\0")
+        .update(turn.sessionId ?? "")
+        .update("\0")
+        .update(turn.executionId ?? turnId)
+        .digest("hex");
+    return `agent-${digest}`;
+}
+function runSnapshot(value) {
+    const parsed = safeJson(value);
+    if (!parsed)
+        throw new Error("cli-bridge run status returned invalid JSON");
+    const id = parsed.id;
+    const status = parsed.status;
+    const terminal = parsed.terminal;
+    if (typeof id !== "string" ||
+        !["running", "done", "error", "cancelled"].includes(String(status)) ||
+        typeof terminal !== "boolean") {
+        throw new Error("cli-bridge run status returned an invalid snapshot");
+    }
+    return {
+        id,
+        status: status,
+        terminal,
+    };
+}
+function cancelSnapshot(value) {
+    const parsed = safeJson(value);
+    if (!parsed || !parsed.run || typeof parsed.run !== "object") {
+        throw new Error("cli-bridge cancel returned an invalid snapshot");
+    }
+    return runSnapshot(JSON.stringify(parsed.run));
+}
 function number(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
@@ -331,7 +638,7 @@ export function defaultCliBridgeCapabilities() {
             runtimeUpdate: false,
             validation: false,
         },
-        streaming: { live: true, replay: false, detach: false, turnIdempotency: true },
+        streaming: { live: true, replay: true, detach: false, turnIdempotency: true },
         sessions: { continue: true, list: false, messages: false },
         workspace: { read: false, write: false, exec: false, git: false, upload: false, download: false },
         branching: { checkpoint: false, fork: false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-provider-cli-bridge",
-  "version": "0.2.33",
+  "version": "0.3.1",
   "description": "AgentEnvironmentProvider adapter for cli-bridge /v1/chat/completions",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@tangle-network/agent-interface": "0.39.0",
+    "@tangle-network/agent-interface": "0.41.0",
     "undici": "7.28.0"
   },
   "devDependencies": {