@2kw/ai 6.3.0-dev.75 → 6.3.0-dev.84

package/dist/commands/agent-run.d.ts

@@ -1,5 +1,10 @@
 import { Command } from "commander";
 export declare function resolveRunInput(arg: string | undefined, inputFile: string | undefined, readStdin?: () => string | undefined): string;
+/**
+ * The task text from the argument, then the file, then stdin; `undefined` when none is given. A
+ * `--continue` run may have none: a connect pause is continued with an empty input (#807).
+ */
+export declare function readRunInput(arg: string | undefined, inputFile: string | undefined, readStdin?: () => string | undefined): string | undefined;
 export declare function makeAgentRunCommand(): Command;
 export declare function makeAgentDecideCommand(): Command;
 //# sourceMappingURL=agent-run.d.ts.map

package/dist/commands/agent-run.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { getClient, runAction } from "../lib/client.js";
-import { isJsonOutput } from "../lib/config.js";
+import { chatUrlFor, isJsonOutput, resolveConfig } from "../lib/config.js";
 import { BackboneApiError, CliUsageError } from "../lib/errors.js";
 import { withSpinner } from "../lib/output.js";
 import { resolveAgent, splitAgentRef, suggestAgents } from "../lib/agent-lookup.js";
@@ -11,6 +11,17 @@ import { PromptAbortedError, promptApprovals, readlineAsk } from "../lib/approva
 import { withModelOverride } from "../lib/agent-models.js";
 import { readStdinInput } from "./ai.js";
 export function resolveRunInput(arg, inputFile, readStdin = readStdinInput) {
+    const text = readRunInput(arg, inputFile, readStdin);
+    if (text === undefined) {
+        throw new CliUsageError("Input is required: pass it as an argument, with --input-file, or via stdin.");
+    }
+    return text;
+}
+/**
+ * The task text from the argument, then the file, then stdin; `undefined` when none is given. A
+ * `--continue` run may have none: a connect pause is continued with an empty input (#807).
+ */
+export function readRunInput(arg, inputFile, readStdin = readStdinInput) {
     if (arg)
         return arg;
     if (inputFile) {
@@ -29,10 +40,7 @@ export function resolveRunInput(arg, inputFile, readStdin = readStdinInput) {
             throw new CliUsageError(`Input file ${inputFile} is empty.`);
         return text;
     }
-    const piped = readStdin();
-    if (piped)
-        return piped;
-    throw new CliUsageError("Input is required: pass it as an argument, with --input-file, or via stdin.");
+    return readStdin() || undefined;
 }
 async function withAgentSuggestions(client, agentRef, err) {
     if (!(err instanceof BackboneApiError) || err.status !== 404 || !err.message.startsWith("Agent not found")) {
@@ -56,8 +64,9 @@ async function withAgentSuggestions(client, agentRef, err) {
  */
 async function finishRun(command, client, target, first, opts) {
     const agentRef = `${target.name}${target.label ? `@${target.label}` : ""}${target.model ? `#${target.model}` : ""}`;
+    const chatUrl = chatUrlFor(resolveConfig(command).baseUrl);
     let result = first;
-    let env = buildRunEnvelope(result, agentRef);
+    let env = buildRunEnvelope(result, agentRef, chatUrl);
     if (opts.interactive && env.status === "requires_approval") {
         try {
             const agent = await resolveAgent(client, target.name);
@@ -91,7 +100,7 @@ async function finishRun(command, client, target, first, opts) {
                 }
                 const decisions = decisionsFromAnswers(rows, answers);
                 result = await withSpinner("Continuing...", () => continueWithDecisions(client, String(agent.id), responseId, decisions, target.label, target.model, target.mode));
-                env = buildRunEnvelope(result, agentRef);
+                env = buildRunEnvelope(result, agentRef, chatUrl);
             }
         }
         catch (err) {
@@ -115,12 +124,12 @@ async function finishRun(command, client, target, first, opts) {
 }
 export function makeAgentRunCommand() {
     return new Command("run")
-        .description("Run an agent on a task (exit 3 = paused for approval, 4 = needs client tool output, 5 = incomplete)")
+        .description("Run an agent on a task (exit 3 = paused for approval, 4 = needs client tool output or a connector connected in chat, 5 = incomplete)")
         .argument("<agent>", "Agent name or id, optionally with @label and #model")
-        .argument("[input]", "Task text (or use --input-file, or pipe it on stdin)")
+        .argument("[input]", "Task text (or use --input-file, or pipe it on stdin); optional with --continue")
         .option("--input-file <path>", "Read the task text from a file")
         .option("--conversation <id>", "Continue a conversation")
-        .option("--continue <responseId>", "Continue from a previous response")
+        .option("--continue <responseId>", "Continue from a previous response, with or without new input")
         .option("--model <model>", "Run this request on another model from the agent's list (sends <agent>#<model>)")
         .option("--mode <mode>", MODE_OPTION_HELP)
         .option("--no-input", "Never prompt for approvals, even on a terminal")
@@ -129,12 +138,14 @@ export function makeAgentRunCommand() {
         await runAction(command, async () => {
             const agentRef = withModelOverride(agentArg, opts.model);
             const mode = parseModeOption(opts.mode);
-            const text = resolveRunInput(input, opts.inputFile);
+            // A continuation may send no new turn (#807): the connect pause's `next` is exactly that command.
+            const text = opts.continue ? readRunInput(input, opts.inputFile) : resolveRunInput(input, opts.inputFile);
             const client = getClient(command);
-            // Without --mode the body stays exactly as before #656 (D2): input is the bare string.
+            const turn = text === undefined ? [] : [{ type: "message", role: "user", content: text }];
+            // Without --mode the body stays exactly as before #656 (D2): input is the bare string, or [] without one.
             const body = {
                 model: `agent/${agentRef}`,
-                input: mode ? [{ type: "message", role: "user", content: text }, modeItem(mode)] : text,
+                input: mode ? [...turn, modeItem(mode)] : text ?? [],
                 stream: false,
             };
             if (opts.conversation)

package/dist/commands/ai.js

@@ -1,7 +1,7 @@
 import { Command } from "commander";
 import { readFileSync } from "node:fs";
 import { getClient, runAction } from "../lib/client.js";
-import { isJsonOutput } from "../lib/config.js";
+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";
@@ -46,7 +46,7 @@ function printResponseResult(result, command, agentRef) {
         console.log(JSON.stringify(result, null, 2));
         return;
     }
-    printRunText(buildRunEnvelope(result, agentRef));
+    printRunText(buildRunEnvelope(result, agentRef, chatUrlFor(resolveConfig(command).baseUrl)));
     if (result?.usage) {
         const usage = result.usage;
         console.log(chalk.dim(`[${result.model} | ${usage.input_tokens} in / ${usage.output_tokens} out / ${usage.total_tokens} total tokens]`));

package/dist/lib/agent-run.d.ts

@@ -25,6 +25,19 @@ export interface PendingToolCall {
     callId: string;
     arguments: unknown;
 }
+/**
+ * A connector the run waits for the user to connect, allow or reconnect in chat.2kw.ai: an open
+ * `backbone:connector_auth_request` (#807 R12). The caller never answers the connect call; the
+ * continuation re-checks access itself.
+ */
+export interface PendingConnection {
+    serverLabel: string;
+    host: string;
+    /** `connect`, `allow` or `reconnect`. */
+    reason: string;
+    /** The egress difference an allow is re-asked for; absent otherwise. */
+    destinations?: string[];
+}
 /** The end user's conversation mode (epic &59); the server matches these three values exactly. */
 export type ConversationMode = "plan" | "ask" | "auto";
 export declare const CONVERSATION_MODES: readonly ConversationMode[];
@@ -57,6 +70,7 @@ export interface RunEnvelope {
     toolCalls: ToolCallSummary[];
     pendingApprovals: PendingApproval[];
     pendingToolCalls: PendingToolCall[];
+    pendingConnections: PendingConnection[];
     incompleteReason: string | null;
     usage: {
         inputTokens: number;
@@ -102,7 +116,13 @@ export declare function parseAgentModel(model?: string): {
  */
 export declare function stripControl(s: string): string;
 export declare function shellQuote(value: string): string;
-export declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string): RunEnvelope;
+/** "Connect a (h), allow the agent to use b (h) and reconnect c (h)". */
+export declare function connectionsSentence(connections: PendingConnection[]): string;
+/**
+ * @param chatUrl the chat web host of the API the run went to ({@link chatUrlFor}); a connect pause's
+ *   `next` sends the user to its Connectors page.
+ */
+export declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string, chatUrl?: string): RunEnvelope;
 /** Human-readable rendering of an envelope on stdout. Every value printed is passed through {@link stripControl}. */
 export declare function printRunText(env: RunEnvelope): void;
 export {};

package/dist/lib/agent-run.js

@@ -1,4 +1,5 @@
 import chalk from "chalk";
+import { DEFAULT_CHAT_URL } from "./config.js";
 import { CliUsageError } from "./errors.js";
 export const CONVERSATION_MODES = ["plan", "ask", "auto"];
 /** `--mode` help text, in the words of the embedded chat's mode chip (#655). */
@@ -91,7 +92,78 @@ export function shellQuote(value) {
         return value;
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-export function buildRunEnvelope(result, agentRef) {
+/** An open connector consent request; a continuation's projection carries another status. */
+function pendingConnectionsOf(output) {
+    return output
+        .filter((i) => i.type === "backbone:connector_auth_request" && (i.status === undefined || i.status === "in_progress"))
+        .map((i) => ({
+        serverLabel: String(i.server_label),
+        host: String(i.host),
+        reason: String(i.reason),
+        ...(Array.isArray(i.destinations) && i.destinations.length > 0
+            ? { destinations: i.destinations.map((d) => String(d)) }
+            : {}),
+    }));
+}
+/**
+ * The call ids a connect pause withholds from the caller: the call each request names, and every
+ * `mcp__<label>__connect` call for a pending connector (the model may call it more than once; one
+ * request stands for all of them).
+ */
+function connectCallIds(output, connections) {
+    const connectNames = new Set(connections.map((c) => `mcp__${c.serverLabel}__connect`));
+    const ids = new Set();
+    for (const item of output) {
+        if (item.type === "backbone:connector_auth_request" && (item.status === undefined || item.status === "in_progress")) {
+            ids.add(String(item.call_id));
+        }
+        else if (item.type === "function_call" && connectNames.has(String(item.name))) {
+            ids.add(String(item.call_id));
+        }
+    }
+    return ids;
+}
+function connectionPhrase(c) {
+    const target = `${c.serverLabel} (${c.host})`;
+    if (c.reason === "allow")
+        return `allow the agent to use ${target}`;
+    if (c.reason === "reconnect")
+        return `reconnect ${target}`;
+    return `connect ${target}`;
+}
+/** "Connect a (h), allow the agent to use b (h) and reconnect c (h)". */
+export function connectionsSentence(connections) {
+    const phrases = connections.map(connectionPhrase);
+    const joined = phrases.length > 1 ? `${phrases.slice(0, -1).join(", ")} and ${phrases.at(-1)}` : phrases[0] ?? "";
+    return joined.charAt(0).toUpperCase() + joined.slice(1);
+}
+/** Joins a connect pause's instruction to the command that continues it; {@link printRunText} breaks the line there. */
+const THEN_RUN = ", then run: ";
+/**
+ * Output item types the envelope decodes, or that never hold a run: text, reasoning and finished
+ * connector calls. A pause on anything else (a connector approval's `mcp_approval_request`) is named.
+ */
+const DECODED_ITEM_TYPES = new Set([
+    "message",
+    "reasoning",
+    "function_call",
+    "function_call_output",
+    "backbone:approval_request",
+    "backbone:connector_auth_request",
+    "mcp_call",
+    "mcp_list_tools",
+]);
+function undecodedPause(output) {
+    const types = [...new Set(output.map((i) => String(i.type)).filter((t) => !DECODED_ITEM_TYPES.has(t)))];
+    return types.length > 0
+        ? `This CLI cannot show or answer ${types.join(", ")}.`
+        : "This CLI cannot tell what the run waits for.";
+}
+/**
+ * @param chatUrl the chat web host of the API the run went to ({@link chatUrlFor}); a connect pause's
+ *   `next` sends the user to its Connectors page.
+ */
+export function buildRunEnvelope(result, agentRef, chatUrl = DEFAULT_CHAT_URL) {
     const output = result?.output ?? [];
     const { agent, version } = parseAgentModel(result?.model);
     // call_id → status of its tool output; a failed server-side tool run is marked `incomplete`.
@@ -113,7 +185,8 @@ export function buildRunEnvelope(result, agentRef) {
         reason: typeof i.reason === "string" && i.reason ? i.reason : null,
         preview: i.preview && typeof i.preview === "object" && !Array.isArray(i.preview) ? i.preview : null,
     }));
-    const withheldCallIds = new Set(pendingApprovals.map((a) => a.callId));
+    const pendingConnections = pendingConnectionsOf(output);
+    const withheldCallIds = new Set([...pendingApprovals.map((a) => a.callId), ...connectCallIds(output, pendingConnections)]);
     const toolCalls = [];
     const pendingToolCalls = [];
     for (const item of output) {
@@ -137,16 +210,35 @@ export function buildRunEnvelope(result, agentRef) {
             status = "incomplete";
             break;
         case "requires_action":
-            status = pendingToolCalls.length > 0 || pendingApprovals.length === 0 ? "requires_tool_output" : "requires_approval";
+            // A connect pause keeps exit 4 (§8, CLI agents D14): the CLI cannot answer it either.
+            status =
+                pendingToolCalls.length > 0 || pendingConnections.length > 0 || pendingApprovals.length === 0
+                    ? "requires_tool_output"
+                    : "requires_approval";
             break;
         default:
             throw new Error(`Unexpected response status: ${result?.status}`);
     }
     const responseId = result?.id ?? null;
     const ref = agentRef ?? agent;
-    const next = status === "requires_approval" && ref && responseId
-        ? `2kw agents decide ${shellQuote(ref)} --response ${responseId} --approve-all`
-        : null;
+    let next = null;
+    if (status === "requires_approval" && ref && responseId) {
+        next = `2kw agents decide ${shellQuote(ref)} --response ${responseId} --approve-all`;
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length > 0 && pendingToolCalls.length === 0 && responseId) {
+        // Not with a relayed call beside it: a continuation without that call's output is refused.
+        // `agents run --continue` needs no input: the continuation re-checks access itself.
+        const resume = ref
+            ? `${THEN_RUN}2kw agents run ${shellQuote(ref)} --continue ${shellQuote(responseId)}`
+            : `, then run the agent again with --continue ${shellQuote(responseId)}`;
+        next = `${connectionsSentence(pendingConnections)} in ${chatUrl}/connectors${resume}`;
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length === 0 && pendingToolCalls.length === 0 && responseId) {
+        // Paused on nothing the envelope decodes: say so, rather than exit 4 without a word.
+        next =
+            `${undecodedPause(output)} Response ${responseId} stays paused: answer it in ${chatUrl}/ ` +
+                "or from a client that continues it by previous_response_id.";
+    }
     return {
         status,
         mode: responseMode(result),
@@ -158,6 +250,7 @@ export function buildRunEnvelope(result, agentRef) {
         toolCalls,
         pendingApprovals,
         pendingToolCalls,
+        pendingConnections,
         incompleteReason: result?.incomplete_details?.reason ?? null,
         usage: result?.usage
             ? { inputTokens: result.usage.input_tokens ?? 0, outputTokens: result.usage.output_tokens ?? 0 }
@@ -192,8 +285,26 @@ export function printRunText(env) {
             console.log(`\nDecide with:\n  ${s(env.next)}`);
     }
     else if (env.status === "requires_tool_output") {
-        console.log(chalk.yellow("\nPaused: the agent needs client-side tool output this CLI cannot provide:"));
-        env.pendingToolCalls.forEach((c) => console.log(`  - ${s(c.tool)} (${s(c.callId)})`));
+        if (env.pendingConnections.length) {
+            console.log(chalk.yellow("\nPaused: the agent needs you to connect in chat:"));
+            env.pendingConnections.forEach((c) => {
+                console.log(`  - ${s(connectionsSentence([c]))}`);
+                if (c.destinations?.length)
+                    console.log(chalk.dim(`    new destinations: ${s(c.destinations.join(", "))}`));
+            });
+            // The continue command on its own line, ready to copy.
+            if (env.next)
+                console.log(`\n${s(env.next.replace(THEN_RUN, ", then run:\n  "))}`);
+        }
+        if (env.pendingToolCalls.length) {
+            console.log(chalk.yellow("\nPaused: the agent needs client-side tool output this CLI cannot provide:"));
+            env.pendingToolCalls.forEach((c) => console.log(`  - ${s(c.tool)} (${s(c.callId)})`));
+        }
+        if (!env.pendingConnections.length && !env.pendingToolCalls.length) {
+            console.log(chalk.yellow("\nPaused on something this CLI cannot show:"));
+            if (env.next)
+                console.log(`  ${s(env.next)}`);
+        }
     }
     else if (env.status === "incomplete") {
         console.log(chalk.yellow(`\nIncomplete: ${s(env.incompleteReason ?? "unknown reason")}`));

package/dist/lib/config.d.ts

@@ -52,6 +52,14 @@ export declare const DEFAULT_BASE_URL: string;
  */
 export declare const DEFAULT_AUTH_URL: string;
 export declare function defaultAuthUrlFor(baseUrl: string): string;
+/** Fallback chat.2kw.ai origin when the API host is not one we recognise. */
+export declare const DEFAULT_CHAT_URL = "https://chat.2kw.ai";
+/**
+ * The chat web host that belongs to an API base URL, where a member connects a connector
+ * (`<chat>/connectors`). `AI_2KW_CHAT_URL` overrides the mapping, for deployments the map
+ * does not know; a trailing slash is dropped so callers can append a path.
+ */
+export declare function chatUrlFor(baseUrl: string, env?: NodeJS.ProcessEnv): string;
 declare const store: Conf<BackboneConfigStore>;
 export { store };
 export declare function validateContextName(name: string): void;

package/dist/lib/config.js

@@ -36,6 +36,34 @@ export function defaultAuthUrlFor(baseUrl) {
         return DEFAULT_AUTH_URL;
     }
 }
+/** Fallback chat.2kw.ai origin when the API host is not one we recognise. */
+export const DEFAULT_CHAT_URL = "https://chat.2kw.ai";
+/** Known API-host → chat web host mappings; a connect pause points the user there (#807 R11). */
+const CHAT_URL_BY_API_HOST = {
+    "api.2kw.ai": "https://chat.2kw.ai",
+    "api-dev.2kw.ai": "https://chat-dev.2kw.ai",
+    "backbone.manfred-kunze.dev": "https://chat.2kw.ai",
+    "localhost:8080": "http://localhost:3000",
+    "127.0.0.1:8080": "http://localhost:3000",
+};
+/**
+ * The chat web host that belongs to an API base URL, where a member connects a connector
+ * (`<chat>/connectors`). `AI_2KW_CHAT_URL` overrides the mapping, for deployments the map
+ * does not know; a trailing slash is dropped so callers can append a path.
+ */
+export function chatUrlFor(baseUrl, env = process.env) {
+    const override = env.AI_2KW_CHAT_URL?.trim();
+    if (override)
+        return override.replace(/\/+$/, "");
+    try {
+        const host = new URL(baseUrl).host;
+        // hasOwn, as in defaultAuthUrlFor: a host named after an Object.prototype key must not resolve.
+        return Object.hasOwn(CHAT_URL_BY_API_HOST, host) ? CHAT_URL_BY_API_HOST[host] : DEFAULT_CHAT_URL;
+    }
+    catch {
+        return DEFAULT_CHAT_URL;
+    }
+}
 // One-shot flag so we only print the deprecation warning once per process,
 // even if resolveConfig is called multiple times across commands.
 let legacyEnvWarned = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai",
-  "version": "6.3.0-dev.75",
+  "version": "6.3.0-dev.84",
   "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",