@2kw/ai 6.3.0-dev.14 → 6.3.0-dev.142

package/dist/lib/agent-run.js

@@ -1,4 +1,37 @@
 import chalk from "chalk";
+import { DEFAULT_CHAT_URL } from "./config.js";
+import { connectCallIds, connectionsPhrase, pendingConnectionsOf } from "./connect-pause.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). */
+export const MODE_OPTION_HELP = "Conversation mode: plan (read-only), ask (no automatic approver; calls that need approval wait for you), " +
+    "auto (the operator's policy as written). Without it, the conversation keeps its mode";
+function isConversationMode(value) {
+    return typeof value === "string" && CONVERSATION_MODES.includes(value);
+}
+/**
+ * The `--mode` value, checked before any request is sent: anything but the three exact values is a
+ * usage error (exit 2). Commander's `.choices()` is not used because it exits 1 through `process.exit`.
+ */
+export function parseModeOption(raw) {
+    if (raw === undefined)
+        return undefined;
+    if (isConversationMode(raw))
+        return raw;
+    throw new CliUsageError(`Invalid --mode '${raw}': use plan, ask or auto.`);
+}
+/** The `backbone:mode` input item (S1 D7); always appended last. */
+export function modeItem(mode) {
+    return { type: "backbone:mode", mode };
+}
+/**
+ * The mode the response ran under (`conversation_mode`, #656). An absent key (a server before #656)
+ * and any value other than the three read as null, which also means "none set".
+ */
+export function responseMode(result) {
+    const raw = result?.conversation_mode;
+    return isConversationMode(raw) ? raw : null;
+}
 export const EXIT_CODES = {
     completed: 0,
     requires_approval: 3,
@@ -60,7 +93,59 @@ export function shellQuote(value) {
         return value;
     return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-export function buildRunEnvelope(result, agentRef) {
+/** "Connect a (h), allow the agent to use b (h) and reconnect c (h)". */
+export function connectionsSentence(connections) {
+    const joined = connectionsPhrase(connections);
+    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: ";
+/**
+ * The `decide` command that answers a relay pause (#671 D7): one `--output <callId>=@<file>` per pending call,
+ * plus `--approve-all` when approvals wait too. The call id is chosen by the model, so the suggested file name
+ * keeps only `[A-Za-z0-9_-]` (P2) and never repeats: it can be neither `../…` nor an absolute path.
+ */
+function relayDecideCommand(ref, responseId, calls, withApprovals) {
+    const used = new Set();
+    const outputs = calls.map((c) => {
+        const safe = c.callId.replace(/[^A-Za-z0-9_-]/g, "_");
+        let file = safe;
+        // Compared without case: on Windows and macOS `callA.out` and `calla.out` are one file.
+        for (let n = 2; used.has(file.toLowerCase()); n++)
+            file = `${safe}-${n}`;
+        used.add(file.toLowerCase());
+        return ` --output ${shellQuote(`${c.callId}=@${file}.out`)}`;
+    });
+    return (`2kw agents decide ${shellQuote(ref)} --response ${shellQuote(responseId)}${outputs.join("")}` +
+        (withApprovals ? " --approve-all" : ""));
+}
+/**
+ * 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.
+ * `backbone:tool_image` is an image a finished `ViewImage` call attached (#1244): it never holds a run.
+ */
+const DECODED_ITEM_TYPES = new Set([
+    "message",
+    "reasoning",
+    "function_call",
+    "function_call_output",
+    "backbone:approval_request",
+    "backbone:connector_auth_request",
+    "backbone:tool_image",
+    "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`.
@@ -80,8 +165,17 @@ export function buildRunEnvelope(result, agentRef) {
         arguments: parseArguments(i.arguments),
         policyClass: String(i.policy_class),
         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));
+    // The one decoding rule (#1086): only an open request with its id, call id, label and host.
+    const connectRequests = pendingConnectionsOf(output);
+    const pendingConnections = connectRequests.map(({ serverLabel, host, reason, destinations }) => ({
+        serverLabel,
+        host,
+        reason,
+        ...(destinations ? { destinations } : {}),
+    }));
+    const withheldCallIds = new Set([...pendingApprovals.map((a) => a.callId), ...connectCallIds(output, connectRequests)]);
     const toolCalls = [];
     const pendingToolCalls = [];
     for (const item of output) {
@@ -105,19 +199,46 @@ 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" && pendingToolCalls.length > 0) {
+        // The engine answers the connect call itself on the continuation, so connecting first is enough.
+        if (ref && responseId) {
+            const decide = relayDecideCommand(ref, responseId, pendingToolCalls, pendingApprovals.length > 0);
+            next = pendingConnections.length > 0
+                ? `${connectionsSentence(pendingConnections)} in ${chatUrl}/connectors${THEN_RUN}${decide}`
+                : decide;
+        }
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length > 0 && responseId) {
+        // `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: null,
+        mode: responseMode(result),
         agent,
         version,
         responseId,
@@ -126,6 +247,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 }
@@ -147,21 +269,51 @@ export function printRunText(env) {
         console.log(chalk.dim(`\n── ${s(head.join(" · "))}`));
     if (env.toolCalls.length)
         console.log(chalk.dim(`   tools: ${env.toolCalls.map((c) => `${s(c.tool)} ${c.status === "incomplete" ? "✗" : "✓"}`).join("  ")}`));
+    const printApprovals = () => env.pendingApprovals.forEach((a, i) => {
+        console.log(`  ${i + 1}. ${s(a.tool)} [${s(a.policyClass)}] ${s(a.approvalId)}`);
+        // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
+        console.log(chalk.dim(`     ${s(JSON.stringify(a.arguments))}`));
+        if (a.reason)
+            console.log(chalk.dim(`     reason: ${s(a.reason)}`));
+    });
     if (env.status === "requires_approval") {
         console.log(chalk.yellow("\nPaused for approval:"));
-        env.pendingApprovals.forEach((a, i) => {
-            console.log(`  ${i + 1}. ${s(a.tool)} [${s(a.policyClass)}] ${s(a.approvalId)}`);
-            // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
-            console.log(chalk.dim(`     ${s(JSON.stringify(a.arguments))}`));
-            if (a.reason)
-                console.log(chalk.dim(`     reason: ${s(a.reason)}`));
-        });
+        printApprovals();
         if (env.next)
             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.pendingToolCalls.length) {
+            console.log(chalk.yellow("\nPaused: the agent waits for client-side tool output:"));
+            env.pendingToolCalls.forEach((c) => {
+                console.log(`  - ${s(c.tool)} (${s(c.callId)})`);
+                console.log(chalk.dim(`    ${s(JSON.stringify(c.arguments))}`));
+            });
+            // The printed command carries --approve-all, so show what it approves (#671 P3).
+            if (env.pendingApprovals.length) {
+                console.log(chalk.yellow("\nIt also waits for approval:"));
+                printApprovals();
+            }
+        }
+        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  "))}`);
+        }
+        else if (env.pendingToolCalls.length && env.next) {
+            console.log(`\nAnswer with:\n  ${s(env.next)}`);
+        }
+        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/approval-prompt.js

@@ -1,6 +1,7 @@
 import { createInterface } from "node:readline/promises";
 import chalk from "chalk";
 import { stripControl } from "./agent-run.js";
+import { REMEMBER_NOTE, previewIsIncomplete, previewLines } from "./skills-apply-preview.js";
 /** Raised when the prompt's input closes (EOF, Ctrl+C, Ctrl+D) before an answer arrives. */
 export class PromptAbortedError extends Error {
     constructor() {
@@ -54,7 +55,23 @@ export async function promptApprovals(pending, ask, write = (line) => console.er
         const destructive = a.policyClass.toLowerCase() === "destructive";
         write(chalk.yellow(`\nApproval ${index + 1}/${pending.length}: ${s(a.tool)} [${s(a.policyClass)}]`));
         // JSON.stringify escapes C0 controls but leaves DEL and C1 raw.
-        write(chalk.dim(s(JSON.stringify(a.arguments, null, 2))));
+        const request = () => write(chalk.dim(s(JSON.stringify(a.arguments, null, 2))));
+        if (a.preview) {
+            // A SkillsApply change reads as its diff (#782, spec §10). When the preview leaves changes
+            // out, the full arguments follow it: this prompt never runs with --json, so it is the only
+            // place the member can read what would persist (spec D7).
+            for (const line of previewLines(a.preview))
+                write(colourPreviewLine(s(line)));
+            if (previewIsIncomplete(a.preview)) {
+                write(chalk.dim("Full request (the preview leaves changes out):"));
+                request();
+            }
+            if (!destructive)
+                write(chalk.dim(REMEMBER_NOTE));
+        }
+        else {
+            request();
+        }
         if (a.reason)
             write(chalk.dim(`reason: ${s(a.reason)}`));
         const question = destructive ? "[a]pprove / [r]eject? " : "[a]pprove / [r]eject / approve and [R]emember? ";
@@ -81,4 +98,17 @@ export async function promptApprovals(pending, ask, write = (line) => console.er
     }
     return answers;
 }
+/** Diff lines sit indented six spaces under their file; only those are coloured. */
+function colourPreviewLine(line) {
+    if (!line.startsWith("      "))
+        return line;
+    const body = line.slice(6);
+    if (body.startsWith("+"))
+        return chalk.green(line);
+    if (body.startsWith("-"))
+        return chalk.red(line);
+    if (body.startsWith("@@"))
+        return chalk.cyan(line);
+    return chalk.dim(line);
+}
 //# sourceMappingURL=approval-prompt.js.map

package/dist/lib/client.d.ts

@@ -39,6 +39,14 @@ export declare function apiKeyAuthMiddleware(config: ApiKeyConfig): Middleware;
  * fires and cannot be replayed safely.
  */
 export declare function sessionAuthMiddleware(config: SessionConfig, deps?: SessionAuthDeps): Middleware;
+/** The per-request opt-in to agent memory for API-key runs (spec §3.3, D6, D7). */
+export declare const MEMORY_HEADER = "X-Backbone-Memory";
+/**
+ * Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses`, the call that starts a run
+ * and that also carries approval decisions (`lib/agent-decide.ts`). No other request gets
+ * it; the server reads it only there.
+ */
+export declare const memoryHeaderMiddleware: Middleware;
 /**
  * The middleware stack for a resolved config, in registration order.
  *

package/dist/lib/client.js

@@ -1,5 +1,5 @@
 import createClient from "openapi-fetch";
-import { resolveConfig, isJsonOutput } from "./config.js";
+import { resolveConfig, isJsonOutput, memoryEnabled } from "./config.js";
 import { ensureJwt } from "./auth-session.js";
 import { BackboneApiError, handleError } from "./errors.js";
 /**
@@ -85,6 +85,21 @@ export function sessionAuthMiddleware(config, deps = {}) {
         },
     };
 }
+/** The per-request opt-in to agent memory for API-key runs (spec §3.3, D6, D7). */
+export const MEMORY_HEADER = "X-Backbone-Memory";
+/**
+ * Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses`, the call that starts a run
+ * and that also carries approval decisions (`lib/agent-decide.ts`). No other request gets
+ * it; the server reads it only there.
+ */
+export const memoryHeaderMiddleware = {
+    onRequest({ request }) {
+        if (request.method === "POST" && new URL(request.url).pathname.endsWith("/v1/responses")) {
+            request.headers.set(MEMORY_HEADER, "enabled");
+        }
+        return request;
+    },
+};
 /**
  * The middleware stack for a resolved config, in registration order.
  *
@@ -125,6 +140,8 @@ export function getClient(command) {
         baseUrl: config.baseUrl.replace(/\/+$/, ""),
     });
     client.use(...buildMiddleware(config));
+    if (memoryEnabled())
+        client.use(memoryHeaderMiddleware);
     return client;
 }
 /**

package/dist/lib/config.d.ts

@@ -14,6 +14,8 @@ export interface ContextEntry {
     cachedJwt?: string;
     /** Epoch millis when cachedJwt expires. */
     cachedJwtExp?: number;
+    /** Send `X-Backbone-Memory: enabled` on responses calls (`2kw config set memory true`, #721). */
+    memory?: boolean;
 }
 export interface BackboneConfigStore {
     activeContext: string;
@@ -50,11 +52,25 @@ export declare const DEFAULT_BASE_URL: string;
  */
 export declare const DEFAULT_AUTH_URL: string;
 export declare function defaultAuthUrlFor(baseUrl: string): string;
+export { DEFAULT_CHAT_URL } from "./connect-pause.js";
+/**
+ * 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. The mapping itself
+ * is `connect-pause.ts`'s {@link chatOriginFor}, shared with the MCP server and n8n (#1086).
+ */
+export declare function chatUrlFor(baseUrl: string, env?: NodeJS.ProcessEnv): string;
 declare const store: Conf<BackboneConfigStore>;
 export { store };
 export declare function validateContextName(name: string): void;
 export declare function getActiveContextName(): string;
 export declare function getActiveContext(): ContextEntry | undefined;
+/**
+ * Whether responses calls opt into agent memory (spec §3.3, D6). `AI_2KW_MEMORY` wins when
+ * set (`true` on, anything else off), so CI can switch it without touching the store;
+ * otherwise the active context's `memory` key decides. Off by default.
+ */
+export declare function memoryEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare function getAllContexts(): Record<string, ContextEntry>;
 export declare function getContextCount(): number;
 export declare function setContext(name: string, entry: ContextEntry): void;

package/dist/lib/config.js

@@ -1,6 +1,7 @@
 import Conf from "conf";
 import { readFileSync, existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { chatOriginFor } from "./connect-pause.js";
 /**
  * Fallback base URL when the user has no context, env var, or local config.
  * Override at runtime by setting AI_2KW_DEFAULT_BASE_URL (or the legacy
@@ -9,7 +10,7 @@ import { resolve } from "node:path";
  */
 export const DEFAULT_BASE_URL = process.env.AI_2KW_DEFAULT_BASE_URL ??
     process.env.BACKBONE_DEFAULT_BASE_URL ??
-    "https://backbone.manfred-kunze.dev/api";
+    "https://api.2kw.ai";
 /**
  * Fallback auth-service URL used when the API host is not one we recognise.
  * Override at runtime with AI_2KW_DEFAULT_AUTH_URL.
@@ -36,6 +37,19 @@ export function defaultAuthUrlFor(baseUrl) {
         return DEFAULT_AUTH_URL;
     }
 }
+export { DEFAULT_CHAT_URL } from "./connect-pause.js";
+/**
+ * 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. The mapping itself
+ * is `connect-pause.ts`'s {@link chatOriginFor}, shared with the MCP server and n8n (#1086).
+ */
+export function chatUrlFor(baseUrl, env = process.env) {
+    const override = env.AI_2KW_CHAT_URL?.trim();
+    if (override)
+        return override.replace(/\/+$/, "");
+    return chatOriginFor(baseUrl);
+}
 // 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;
@@ -142,6 +156,17 @@ export function getActiveContext() {
     const contexts = store.get("contexts") ?? {};
     return contexts[name];
 }
+/**
+ * Whether responses calls opt into agent memory (spec §3.3, D6). `AI_2KW_MEMORY` wins when
+ * set (`true` on, anything else off), so CI can switch it without touching the store;
+ * otherwise the active context's `memory` key decides. Off by default.
+ */
+export function memoryEnabled(env = process.env) {
+    const fromEnv = env.AI_2KW_MEMORY;
+    if (fromEnv !== undefined && fromEnv !== "")
+        return fromEnv === "true";
+    return getActiveContext()?.memory === true;
+}
 export function getAllContexts() {
     return store.get("contexts") ?? {};
 }

package/dist/lib/connect-pause.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The connect pause, decoded one way for every client (#1086, spec §4, D4): an open
+ * `backbone:connector_auth_request` (#807 R12) is a connector the run waits for the user to
+ * connect, allow or reconnect in chat.2kw.ai.
+ *
+ * This file is canonical. `mcp/src/lib/connect-pause.ts` and
+ * `n8n/nodes/TwoKw/operations/connect-pause.ts` are byte copies of it under a header: edit it
+ * here, then run `npm run sync:connect-pause` in mcp/ and `npm run sync-connect-pause` in n8n/.
+ * Its golden fixture, `cli/tests/fixtures/connect-pause-cases.json`, is copied the same way into
+ * mcp/, n8n/ and surface/, and every client's decoder test runs every case of it.
+ *
+ * Plain TypeScript with no imports, no `process`, no Node types and no timers, so n8n's source
+ * scanner and its empty `dependencies` accept the copy. The CLI and the MCP server keep their
+ * `AI_2KW_CHAT_URL` override in their own code, around {@link chatOriginFor}.
+ */
+/** Fallback chat.2kw.ai origin when the API host is not one we recognise. */
+export declare const DEFAULT_CHAT_URL = "https://chat.2kw.ai";
+/** Known API-host → chat web host mappings; a connect pause points the user there (#807 R11). */
+export declare const CHAT_URL_BY_API_HOST: Readonly<Record<string, string>>;
+/**
+ * The chat web host that belongs to an API base URL, where a member connects a connector
+ * (`<chat>/connectors`). An unknown host, an unparsable URL or no URL at all is chat.2kw.ai.
+ */
+export declare function chatOriginFor(baseUrl: unknown): string;
+/** What the user is asked to do: connect, allow the agent, or reconnect. */
+export type ConnectReason = "connect" | "allow" | "reconnect";
+export declare const CONNECT_REASONS: readonly ConnectReason[];
+/**
+ * One open connect request. `id` (`cauth_<call id>`) and `callId` (the first connect call for
+ * this connector) are what a client needs to withhold the connect calls; the CLI and the MCP
+ * server drop both from what they publish.
+ */
+export interface PendingConnection {
+    id: string;
+    callId: string;
+    serverLabel: string;
+    /** The MCP server's host: what the user is asked to connect to. */
+    host: string;
+    reason: ConnectReason;
+    /** The egress difference an allow is asked again for (#807 R9); absent otherwise, never empty. */
+    destinations?: string[];
+}
+/** Enough of a connection to name it in a sentence. */
+export interface ConnectTarget {
+    serverLabel: string;
+    host: string;
+    reason: string;
+}
+/** The synthetic tool a connector's connect pause is raised through (#806). */
+export declare function connectToolName(serverLabel: string): string;
+/**
+ * The connectors a response's `output` still waits on: every `in_progress` connect request whose
+ * id no other-status projection in the same list resolved, one per id, in order. An item without
+ * a non-empty `id`, `call_id`, `server_label` or `host` cannot be acted on and is skipped; a
+ * `reason` outside the three reads as `connect`, the action that always applies; only the string
+ * entries of `destinations` are kept, and none at all omits the field.
+ */
+export declare function pendingConnectionsOf(output: unknown): PendingConnection[];
+/**
+ * The call ids a connect pause withholds from the caller: the call each pending request names;
+ * the own `call_id` of every open connect request, even one {@link pendingConnectionsOf} could not
+ * describe (a missing `server_label` or `host`), since a connect call is the engine's to answer,
+ * never the client's (R7); and every `mcp__<label>__connect` call for a connector in
+ * `connections` (the model may call it more than once; one request stands for all of them).
+ */
+export declare function connectCallIds(output: unknown, connections: readonly Pick<PendingConnection, "callId" | "serverLabel">[]): Set<string>;
+/** "connect erp (erp.example.com)", "allow the agent to use …" or "reconnect …". */
+export declare function connectionPhrase(c: ConnectTarget): string;
+/** "connect a (h), allow the agent to use b (h) and reconnect c (h)"; empty for none. */
+export declare function connectionsPhrase(connections: readonly ConnectTarget[]): string;
+//# sourceMappingURL=connect-pause.d.ts.map

package/dist/lib/connect-pause.js

@@ -0,0 +1,147 @@
+/**
+ * The connect pause, decoded one way for every client (#1086, spec §4, D4): an open
+ * `backbone:connector_auth_request` (#807 R12) is a connector the run waits for the user to
+ * connect, allow or reconnect in chat.2kw.ai.
+ *
+ * This file is canonical. `mcp/src/lib/connect-pause.ts` and
+ * `n8n/nodes/TwoKw/operations/connect-pause.ts` are byte copies of it under a header: edit it
+ * here, then run `npm run sync:connect-pause` in mcp/ and `npm run sync-connect-pause` in n8n/.
+ * Its golden fixture, `cli/tests/fixtures/connect-pause-cases.json`, is copied the same way into
+ * mcp/, n8n/ and surface/, and every client's decoder test runs every case of it.
+ *
+ * Plain TypeScript with no imports, no `process`, no Node types and no timers, so n8n's source
+ * scanner and its empty `dependencies` accept the copy. The CLI and the MCP server keep their
+ * `AI_2KW_CHAT_URL` override in their own code, around {@link chatOriginFor}.
+ */
+/** 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). */
+export 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`). An unknown host, an unparsable URL or no URL at all is chat.2kw.ai.
+ */
+export function chatOriginFor(baseUrl) {
+    try {
+        const host = new URL(String(baseUrl ?? "")).host;
+        // hasOwn, not a bare index: 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 : DEFAULT_CHAT_URL;
+    }
+    catch {
+        return DEFAULT_CHAT_URL;
+    }
+}
+export const CONNECT_REASONS = ["connect", "allow", "reconnect"];
+const CONNECT_REQUEST = "backbone:connector_auth_request";
+function itemsOf(output) {
+    if (!Array.isArray(output))
+        return [];
+    return output.filter((item) => typeof item === "object" && item !== null && !Array.isArray(item));
+}
+function text(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** The synthetic tool a connector's connect pause is raised through (#806). */
+export function connectToolName(serverLabel) {
+    return `mcp__${serverLabel}__connect`;
+}
+/**
+ * The connectors a response's `output` still waits on: every `in_progress` connect request whose
+ * id no other-status projection in the same list resolved, one per id, in order. An item without
+ * a non-empty `id`, `call_id`, `server_label` or `host` cannot be acted on and is skipped; a
+ * `reason` outside the three reads as `connect`, the action that always applies; only the string
+ * entries of `destinations` are kept, and none at all omits the field.
+ */
+export function pendingConnectionsOf(output) {
+    const items = itemsOf(output);
+    const resolved = new Set();
+    for (const item of items) {
+        const id = text(item.id);
+        if (item.type === CONNECT_REQUEST && id && item.status !== "in_progress")
+            resolved.add(id);
+    }
+    const pending = new Map();
+    for (const item of items) {
+        if (item.type !== CONNECT_REQUEST || item.status !== "in_progress")
+            continue;
+        const id = text(item.id);
+        const callId = text(item.call_id);
+        const serverLabel = text(item.server_label);
+        const host = text(item.host);
+        if (!id || !callId || !serverLabel || !host || resolved.has(id) || pending.has(id))
+            continue;
+        const reason = text(item.reason);
+        const destinations = Array.isArray(item.destinations)
+            ? item.destinations.filter((entry) => typeof entry === "string")
+            : [];
+        pending.set(id, {
+            id,
+            callId,
+            serverLabel,
+            host,
+            reason: reason && CONNECT_REASONS.includes(reason) ? reason : "connect",
+            ...(destinations.length > 0 ? { destinations } : {}),
+        });
+    }
+    return [...pending.values()];
+}
+/**
+ * The call ids a connect pause withholds from the caller: the call each pending request names;
+ * the own `call_id` of every open connect request, even one {@link pendingConnectionsOf} could not
+ * describe (a missing `server_label` or `host`), since a connect call is the engine's to answer,
+ * never the client's (R7); and every `mcp__<label>__connect` call for a connector in
+ * `connections` (the model may call it more than once; one request stands for all of them).
+ */
+export function connectCallIds(output, connections) {
+    const names = new Set(connections.map((c) => connectToolName(c.serverLabel)));
+    const ids = new Set(connections.map((c) => c.callId));
+    const items = itemsOf(output);
+    // Every open connect request's own call id is withheld, even one pendingConnectionsOf could
+    // not fully describe (a missing server_label or host): the paired function_call must never be
+    // left for the caller to fabricate an output for (R7).
+    const resolved = new Set();
+    for (const item of items) {
+        const id = text(item.id);
+        if (item.type === CONNECT_REQUEST && id && item.status !== "in_progress")
+            resolved.add(id);
+    }
+    for (const item of items) {
+        if (item.type !== CONNECT_REQUEST || item.status !== "in_progress")
+            continue;
+        const id = text(item.id);
+        if (id && resolved.has(id))
+            continue;
+        const callId = text(item.call_id);
+        if (callId)
+            ids.add(callId);
+    }
+    for (const item of items) {
+        const callId = text(item.call_id);
+        if (item.type === "function_call" && callId && typeof item.name === "string" && names.has(item.name))
+            ids.add(callId);
+    }
+    return ids;
+}
+/** "connect erp (erp.example.com)", "allow the agent to use …" or "reconnect …". */
+export 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)"; empty for none. */
+export function connectionsPhrase(connections) {
+    const phrases = connections.map(connectionPhrase);
+    if (phrases.length < 2)
+        return phrases[0] ?? "";
+    return `${phrases.slice(0, -1).join(", ")} and ${phrases[phrases.length - 1]}`;
+}
+//# sourceMappingURL=connect-pause.js.map

package/dist/lib/errors.js

@@ -95,7 +95,9 @@ const PENDING_APPROVALS_HINT = "The approval was already decided or its response
 const CODE_HINTS = {
     approval_hmac_mismatch: PENDING_APPROVALS_HINT,
     unknown_approval_id: PENDING_APPROVALS_HINT,
-    incomplete_tool_outputs: "Every pending approval of a paused response must be decided in one call. Use --approve-all or --reject-all, or name every id.",
+    incomplete_tool_outputs: "Every released tool call and every pending approval of a paused response must be answered in one call. " +
+        "Check pendingToolCalls and pendingApprovals in the run envelope.",
+    unknown_tool_output: "That call id was not released by this response. Use the responseId of the latest envelope.",
     conversation_agent_mismatch: "This conversation belongs to another agent. Start a new conversation or run the agent that owns it.",
 };
 /** The most specific hint for an API error: gateway code, then known messages, then the status table. */