@2kw/ai 8.0.6 → 8.1.0-dev.12

package/dist/commands/agent-run.js

@@ -9,6 +9,7 @@ import { buildRunEnvelope, EXIT_CODES, MODE_OPTION_HELP, modeItem, parseModeOpti
 import { continueWithDecisions, decisionsFromAnswers, fetchPendingApprovals, parseToolAnswers, planContinuation, } from "../lib/agent-decide.js";
 import { PromptAbortedError, promptApprovals, readlineAsk } from "../lib/approval-prompt.js";
 import { withModelOverride } from "../lib/agent-models.js";
+import { postResponse } from "../lib/response-stream.js";
 import { readStdinInput } from "./ai.js";
 export function resolveRunInput(arg, inputFile, readStdin = readStdinInput) {
     const text = readRunInput(arg, inputFile, readStdin);
@@ -146,7 +147,7 @@ export function makeAgentRunCommand() {
             const body = {
                 model: `agent/${agentRef}`,
                 input: mode ? [...turn, modeItem(mode)] : text ?? [],
-                stream: false,
+                stream: true,
             };
             if (opts.conversation)
                 body.conversation = opts.conversation;
@@ -154,9 +155,17 @@ export function makeAgentRunCommand() {
                 body.previous_response_id = opts.continue;
             let data;
             try {
-                // The generated body type does not model a bare-string input, hence the cast.
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                ({ data } = await withSpinner("Running agent...", () => client.POST("/v1/responses", { body })));
+                data = await withSpinner("Running agent...", (spinner) => postResponse(client, body, (started) => {
+                    // Printed at once (#1729), so a run cut off later can still be found.
+                    if (!started.conversation?.id)
+                        return;
+                    // ora's render() writes a frame even off a TTY, where it never spins.
+                    if (spinner.isSpinning)
+                        spinner.clear();
+                    console.error(`Conversation: ${started.conversation.id}`);
+                    if (spinner.isSpinning)
+                        spinner.render();
+                }));
             }
             catch (err) {
                 throw await withAgentSuggestions(client, agentRef, err);

package/dist/commands/ai.js

@@ -5,6 +5,7 @@ import { chatUrlFor, isJsonOutput, resolveConfig } from "../lib/config.js";
 import { CliUsageError } from "../lib/errors.js";
 import { withModelOverride } from "../lib/agent-models.js";
 import { formatList, withSpinner } from "../lib/output.js";
+import { postResponse } from "../lib/response-stream.js";
 import { buildRunEnvelope, extractResponseText, printRunText, } from "../lib/agent-run.js";
 import chalk from "chalk";
 export { extractResponseText };
@@ -125,7 +126,19 @@ export function makeAiCommand() {
             if (opts.conversation)
                 body.conversation = opts.conversation;
             const client = getClient(command);
-            const { data } = await withSpinner("Generating response...", () => client.POST("/v1/responses", { body }));
+            // An agent turn is streamed (#1732): a proxy cuts a request that answers nothing for 100 s.
+            const data = await withSpinner("Generating response...", async (spinner) => opts.agent
+                ? postResponse(client, body, (started) => {
+                    // Printed at once, as `agents run` does, so a turn cut off later can still be found.
+                    if (!started.conversation?.id)
+                        return;
+                    if (spinner.isSpinning)
+                        spinner.clear();
+                    console.error(`Conversation: ${started.conversation.id}`);
+                    if (spinner.isSpinning)
+                        spinner.render();
+                })
+                : (await client.POST("/v1/responses", { body })).data);
             printResponseResult(data, command, opts.agent);
         });
     });

package/dist/commands/datasets.js

@@ -41,7 +41,7 @@ export function makeDatasetsCommand() {
         .description("Create a new dataset")
         .requiredOption("-n, --name <name>", "Dataset name")
         .option("-d, --description <text>", "Dataset description")
-        .option("-t, --type <type>", "Dataset type")
+        .option("-t, --type <type>", "Dataset type (default: text)")
         .option("--input-schema <json>", "Input JSON Schema")
         .option("--expected-output-schema <json>", "Expected output JSON Schema")
         .option("--metadata <json>", "Metadata (JSON)")

package/dist/commands/responses.js

@@ -7,7 +7,8 @@ export function makeResponsesCommand() {
     cmd
         .command("get")
         .description("Read a background response as it stands now: queued, in_progress, requires_action, completed, " +
-        "incomplete, failed or cancelled. Only background responses can be read by id.")
+        "incomplete, failed or cancelled. Only background responses can be read by id: the result of " +
+        "`agents run` is read with `conversations items list <conversationId>`.")
         .argument("<responseId>", "Response ID")
         .action(async (responseId, _opts, command) => {
         await runAction(command, async () => {

package/dist/lib/agent-decide.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { modeItem } from "./agent-run.js";
 import { CliUsageError } from "./errors.js";
 import { paginationParams } from "./pagination.js";
+import { postResponse } from "./response-stream.js";
 const defaultIo = {
     readFile: (path) => readFileSync(path, "utf-8"),
     // Not readStdinInput: that one trims, and a tool result is sent as read (P5).
@@ -215,12 +216,10 @@ export async function continueWithDecisions(client, agentId, responseId, decisio
     const body = {
         model: `agent/${agentId}${label ? `@${label}` : ""}${model ? `#${model}` : ""}`,
         previous_response_id: responseId,
-        stream: false,
+        stream: true,
         input: mode ? [...items, modeItem(mode)] : items,
     };
-    // The generated body type does not model backbone: extension items, hence the cast.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const { data } = await client.POST("/v1/responses", { body });
-    return data;
+    // Streamed for the reason a run is (#1729): the rest of the turn can outlast a proxy's timeout.
+    return postResponse(client, body);
 }
 //# sourceMappingURL=agent-decide.js.map

package/dist/lib/agent-run.js

@@ -189,6 +189,9 @@ const DECODED_ITEM_TYPES = new Set([
     "backbone:tool_image",
     // A table or chart a finished ShowTable or ShowChart call showed (#1419): it never holds a run either.
     "backbone:ui",
+    // A canvas a finished CanvasWrite or CanvasEdit call saved, and a member's selection (#1698): neither holds a run.
+    "backbone:canvas",
+    "backbone:canvas_selection",
     "mcp_approval_request",
     "mcp_call",
     "mcp_list_tools",

package/dist/lib/output.d.ts

@@ -1,3 +1,4 @@
+import { type Ora } from "ora";
 import type { Command } from "commander";
 type AnyRecord = Record<string, any>;
 /**
@@ -21,9 +22,11 @@ export declare function formatList(items: AnyRecord[] | undefined, command: Comm
  * Display a success message.
  */
 export declare function formatSuccess(message: string, command: Command): void;
+/** Stops the running spinner, if any, which shows the cursor again. Call it before `process.exit`. */
+export declare function stopSpinner(): void;
 /**
  * Run an async action with a spinner.
  */
-export declare function withSpinner<T>(text: string, action: () => Promise<T>): Promise<T>;
+export declare function withSpinner<T>(text: string, action: (spinner: Ora) => Promise<T>): Promise<T>;
 export {};
 //# sourceMappingURL=output.d.ts.map

package/dist/lib/output.js

@@ -82,13 +82,20 @@ export function formatSuccess(message, command) {
         console.log(chalk.green(message));
     }
 }
+/** The spinner `withSpinner` runs now, so an exit on Ctrl+C can stop it: ora hides the cursor while it spins (#1733). */
+let running;
+/** Stops the running spinner, if any, which shows the cursor again. Call it before `process.exit`. */
+export function stopSpinner() {
+    running?.stop();
+}
 /**
  * Run an async action with a spinner.
  */
 export async function withSpinner(text, action) {
     const spinner = ora(text).start();
+    running = spinner;
     try {
-        const result = await action();
+        const result = await action(spinner);
         spinner.succeed();
         return result;
     }
@@ -96,6 +103,10 @@ export async function withSpinner(text, action) {
         spinner.fail();
         throw err;
     }
+    finally {
+        if (running === spinner)
+            running = undefined;
+    }
 }
 function formatValue(value) {
     if (value === null || value === undefined)

package/dist/lib/response-stream.d.ts

@@ -0,0 +1,14 @@
+import type { ApiClient } from "./agent-lookup.js";
+import type { ResponsesResult } from "./agent-run.js";
+/**
+ * POSTs an agent turn to `/v1/responses` and returns its terminal response, as `stream: false` would (#1729).
+ * The turn is streamed: a proxy in front of the API cuts a request that answers nothing for 100 s (HTTP 524),
+ * and a stream's events and keepalives keep it open however long the run takes. A model that cannot stream
+ * is refused before any work (`stream_not_supported`), so that turn is sent again without a stream.
+ *
+ * `onStart` gets the response as `response.created` names it, before the run works. Once the conversation is
+ * known, a cut stream or Ctrl+C names it and the command that reads the run's result: a synchronous
+ * response cannot be read by id afterwards (`GET /v1/responses/{id}` reads background responses only).
+ */
+export declare function postResponse(client: ApiClient, body: Record<string, unknown>, onStart?: (started: ResponsesResult) => void): Promise<ResponsesResult>;
+//# sourceMappingURL=response-stream.d.ts.map

package/dist/lib/response-stream.js

@@ -0,0 +1,122 @@
+import { BackboneApiError } from "./errors.js";
+import { stopSpinner } from "./output.js";
+/**
+ * POSTs an agent turn to `/v1/responses` and returns its terminal response, as `stream: false` would (#1729).
+ * The turn is streamed: a proxy in front of the API cuts a request that answers nothing for 100 s (HTTP 524),
+ * and a stream's events and keepalives keep it open however long the run takes. A model that cannot stream
+ * is refused before any work (`stream_not_supported`), so that turn is sent again without a stream.
+ *
+ * `onStart` gets the response as `response.created` names it, before the run works. Once the conversation is
+ * known, a cut stream or Ctrl+C names it and the command that reads the run's result: a synchronous
+ * response cannot be read by id afterwards (`GET /v1/responses/{id}` reads background responses only).
+ */
+export async function postResponse(client, body, onStart) {
+    let response;
+    try {
+        // The generated body type does not model a bare-string input or backbone: items, hence the cast.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        ({ response } = await client.POST("/v1/responses", { body: { ...body, stream: true }, parseAs: "stream" }));
+    }
+    catch (err) {
+        if (!(err instanceof BackboneApiError && err.code === "stream_not_supported"))
+            throw err;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const { data } = await client.POST("/v1/responses", { body: { ...body, stream: false } });
+        return data;
+    }
+    if (!response.body || !response.headers.get("content-type")?.includes("text/event-stream")) {
+        return (await response.json());
+    }
+    return readResponseStream(response.body, onStart);
+}
+/** How to read a run whose stream was lost: the conversation keeps every item the run wrote. */
+function readHint(started) {
+    const conversation = started?.conversation?.id;
+    return conversation
+        ? ` The run goes on on the server; read its result with: 2kw conversations items list ${conversation}`
+        : "";
+}
+/** Reads Open Responses server-sent events up to the terminal one; comments (keepalives) are skipped. */
+async function readResponseStream(body, onStart) {
+    let started;
+    let error;
+    const failed = () => new BackboneApiError({
+        status: 500,
+        error: error?.code ?? "run_failed",
+        code: error?.code ?? undefined,
+        message: error?.message ?? "The response failed.",
+        timestamp: new Date().toISOString(),
+    });
+    const onInterrupt = () => {
+        stopSpinner(); // a spinning ora hides the cursor, and process.exit would leave it hidden (#1733)
+        console.error(`Interrupted.${readHint(started)}`);
+        process.exit(130);
+    };
+    const handle = (frame) => {
+        const data = frame
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith("data:"))
+            .map((line) => line.slice(5).trimStart())
+            .join("\n");
+        if (!data || data === "[DONE]")
+            return undefined;
+        let event;
+        try {
+            event = JSON.parse(data);
+        }
+        catch {
+            return undefined; // a garbled frame is skipped: the run goes on, and its terminal event still ends it
+        }
+        switch (event.type) {
+            case "response.created":
+                started = event.response;
+                if (started?.conversation?.id)
+                    process.once("SIGINT", onInterrupt);
+                onStart?.(event.response);
+                return undefined;
+            case "error":
+                error = event;
+                return undefined;
+            case "response.completed":
+            case "response.incomplete":
+                return event.response;
+            case "response.failed":
+                throw failed();
+            default:
+                return undefined;
+        }
+    };
+    const decoder = new TextDecoder();
+    let buffer = "";
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            let chunk;
+            try {
+                chunk = await reader.read();
+            }
+            catch (err) {
+                throw new Error(`The connection closed before the run finished (${err.message}).${readHint(started)}`);
+            }
+            if (chunk.done)
+                break;
+            buffer += decoder.decode(chunk.value, { stream: true });
+            let end;
+            while ((end = /\r?\n\r?\n/.exec(buffer))) {
+                const frame = buffer.slice(0, end.index);
+                buffer = buffer.slice(end.index + end[0].length);
+                const terminal = handle(frame);
+                if (terminal)
+                    return terminal;
+            }
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", onInterrupt);
+        await reader.cancel().catch(() => { });
+    }
+    if (error)
+        throw failed(); // an error event whose response.failed never arrived
+    throw new Error(`The response stream ended before the run finished.${readHint(started)}`);
+}
+//# sourceMappingURL=response-stream.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "8.0.6",
+  "version": "8.1.0-dev.12",
   "description": "CLI for 2kw.ai — schema-driven document extraction, an OpenAI-compatible EU LLM gateway, transcription, prompts, datasets, and experiments from your terminal or agentic workflows. Ships as 2kw, backbone, and bb.",
   "keywords": [
     "cli",