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

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

@@ -25,6 +25,26 @@ 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[];
+}
+/** 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 the server's API base URL (`AI_2KW_BASE_URL`), where a member
+ * connects a connector. `AI_2KW_CHAT_URL` overrides the mapping; a trailing slash is dropped.
+ */
+export declare function chatUrlFor(baseUrl: string | undefined, env?: NodeJS.ProcessEnv): 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[];
@@ -55,6 +75,7 @@ export interface RunEnvelope {
     toolCalls: ToolCallSummary[];
     pendingApprovals: PendingApproval[];
     pendingToolCalls: PendingToolCall[];
+    pendingConnections: PendingConnection[];
     incompleteReason: string | null;
     usage: {
         inputTokens: number;
@@ -95,7 +116,9 @@ export declare function parseAgentModel(model?: string): {
 /**
  * @param agentRef the reference the run was started with (`name[@label][#model]`); `next` names it so
  *   the decision continues on the same label and model (D11). Falls back to the echoed agent name.
+ * @param chatUrl the chat web host of the API ({@link chatUrlFor}); a connect pause's `next` names its
+ *   Connectors page.
  */
-export declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string): RunEnvelope;
+export declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string, chatUrl?: string): RunEnvelope;
 export {};
 //# sourceMappingURL=agent-run.d.ts.map

package/dist/lib/agent-run.js

@@ -3,6 +3,33 @@
  * from `cli/src/lib/agent-run.ts` because cli/ and mcp/ share no package (#667). Keep the two in step;
  * only the text of `next` differs, because an MCP caller decides through a tool, not a shell command.
  */
+/** 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, as the CLI's `CHAT_URL_BY_API_HOST` (#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 the server's API base URL (`AI_2KW_BASE_URL`), where a member
+ * connects a connector. `AI_2KW_CHAT_URL` overrides the mapping; a trailing slash is dropped.
+ */
+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: 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;
+    }
+}
 export const CONVERSATION_MODES = ["plan", "ask", "auto"];
 /**
  * Who may change the mode (#656 D8), stated in both tool descriptions: the mode outlives the request
@@ -67,11 +94,73 @@ function parseArguments(raw) {
         return raw;
     }
 }
+/** An open connector consent request; a continuation's projection carries another status. */
+function isOpenConnectRequest(item) {
+    return item.type === "backbone:connector_auth_request" && (item.status === undefined || item.status === "in_progress");
+}
+function pendingConnectionsOf(output) {
+    return output.filter(isOpenConnectRequest).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 (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 (isOpenConnectRequest(item) || (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}`;
+}
+function connectionsPhrase(connections) {
+    const phrases = connections.map(connectionPhrase);
+    return phrases.length > 1 ? `${phrases.slice(0, -1).join(", ")} and ${phrases.at(-1)}` : phrases[0] ?? "";
+}
+/**
+ * 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 server cannot show or answer ${types.join(", ")}.`
+        : "This server cannot tell what the run waits for.";
+}
 /**
  * @param agentRef the reference the run was started with (`name[@label][#model]`); `next` names it so
  *   the decision continues on the same label and model (D11). Falls back to the echoed agent name.
+ * @param chatUrl the chat web host of the API ({@link chatUrlFor}); a connect pause's `next` names its
+ *   Connectors page.
  */
-export function buildRunEnvelope(result, agentRef) {
+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`.
@@ -92,7 +181,8 @@ export function buildRunEnvelope(result, agentRef) {
         policyClass: String(i.policy_class),
         reason: typeof i.reason === "string" && i.reason ? i.reason : 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) {
@@ -116,17 +206,38 @@ 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 is requires_tool_output too (#807 R12): no tool here can answer it.
+            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;
-    // Never an "approve all" hint: the assistant decides only what the user decided (D12).
-    const next = status === "requires_approval" && ref && responseId
-        ? `Show the pending approvals to the user; after they decide each one, call 2kw_decide_agent_approvals with agent ${JSON.stringify(ref)} and responseId ${JSON.stringify(responseId)}.`
-        : null;
+    let next = null;
+    if (status === "requires_approval" && ref && responseId) {
+        // Never an "approve all" hint: the assistant decides only what the user decided (D12).
+        next = `Show the pending approvals to the user; after they decide each one, call 2kw_decide_agent_approvals with agent ${JSON.stringify(ref)} and responseId ${JSON.stringify(responseId)}.`;
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length > 0 && pendingToolCalls.length === 0 && responseId) {
+        // No tool here takes previous_response_id, and a connect pause cannot be continued by
+        // conversation (the gateway answers 400), so the honest ways on are a fresh request or a
+        // client that continues by response id.
+        next =
+            `Tell the user to ${connectionsPhrase(pendingConnections)} in ${chatUrl}/connectors. ` +
+                `This server cannot continue response ${JSON.stringify(responseId)}: once they have connected, send the request again ` +
+                "with 2kw_create_response without `conversation` (a connect pause cannot be continued by conversation), " +
+                "or continue the response by its id from n8n (Previous Response ID) or any client that sends previous_response_id.";
+    }
+    else if (status === "requires_tool_output" && pendingConnections.length === 0 && pendingToolCalls.length === 0 && responseId) {
+        // Paused on nothing the envelope decodes: say so, rather than hand back a pause with no way on.
+        next =
+            `${undecodedPause(output)} Response ${JSON.stringify(responseId)} stays paused: tell the user to answer it ` +
+                `in ${chatUrl}/, or continue it from a client that sends previous_response_id.`;
+    }
     return {
         status,
         mode: responseMode(result),
@@ -138,6 +249,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 }

package/dist/tools/agents.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
 import { continueWithDecisions, fetchPendingApprovals, planDecisions, resolveAgentId, splitAgentRef } from "../lib/agent-decide.js";
-import { buildRunEnvelope, MODE_RULE } from "../lib/agent-run.js";
+import { buildRunEnvelope, chatUrlFor, MODE_RULE } from "../lib/agent-run.js";
 const modelSchema = z
     .string()
     .min(1)
@@ -537,7 +537,8 @@ export function register(server, client) {
     server.tool("2kw_decide_agent_approvals", "Answer the tool approvals a paused agent run is waiting for (a 2kw_create_response envelope with status requires_approval), then continue the run. "
         + "Decide only what the user decided: show them each pending approval (tool, arguments, policy class) first and never approve on your own. "
         + "Every pending approval of the response must be decided in this one call. Pass `agent` exactly as the run was started (keep '@label' and '#model'). "
-        + "Returns the continuation's run envelope, which can pause again."
+        + "Returns the continuation's run envelope, which can pause again: for approval, or on a connector the user must connect "
+        + "in chat.2kw.ai → Connectors (`pendingConnections`; follow its `next`)."
         + " " + MODE_RULE, {
         agent: z.string().min(1).describe("Agent id or name as the run used it: 'ref[@label][#model]'"),
         responseId: z.string().min(1).describe("The paused response's id (envelope `responseId`)"),
@@ -567,7 +568,7 @@ export function register(server, client) {
             const pending = await fetchPendingApprovals(client, agentId, responseId);
             const items = planDecisions(pending, { decisions, decideAll, reason, remember }, responseId);
             const result = await continueWithDecisions(client, agentId, responseId, items, label, model, mode);
-            const envelope = buildRunEnvelope(result, agent);
+            const envelope = buildRunEnvelope(result, agent, chatUrlFor(client._config?.baseUrl));
             return { content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }] };
         }
         catch (error) {

package/dist/tools/ai-gateway.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
-import { buildRunEnvelope, MODE_RULE, modeItem } from "../lib/agent-run.js";
+import { buildRunEnvelope, chatUrlFor, MODE_RULE, modeItem } from "../lib/agent-run.js";
 /**
  * The `model` value for an agent run: `agent/<ref>[@<label>]`, plus `#<model>` when the
  * request switches to another entry of the version's `models` list (#626, spec #591 §4.1).
@@ -93,7 +93,7 @@ export function register(server, client) {
         }
     });
     // ── create_response ─────────────────────────────────────────────────────
-    server.tool("2kw_create_response", "Send a request through Backbone's OpenAI-compatible OpenResponses endpoint (POST /v1/responses). Model format: 'provider/model' for a direct gateway call via `model`, or use `agent` to invoke a stored agent by id or name (optionally 'ref@label', e.g. 'support-bot@latest'). With `agent`, `agentModel` runs this one request on another model from the agent version's `models` list. With `agent`, the reply is the run envelope as JSON (status, text, tool calls, pending approvals, response id, next step) followed by the model that answered; answer a pause with 2kw_decide_agent_approvals. Always non-streaming. " + MODE_RULE, {
+    server.tool("2kw_create_response", "Send a request through Backbone's OpenAI-compatible OpenResponses endpoint (POST /v1/responses). Model format: 'provider/model' for a direct gateway call via `model`, or use `agent` to invoke a stored agent by id or name (optionally 'ref@label', e.g. 'support-bot@latest'). With `agent`, `agentModel` runs this one request on another model from the agent version's `models` list. With `agent`, the reply is the run envelope as JSON (status, text, tool calls, pending approvals, response id, next step) followed by the model that answered; answer an approval pause with 2kw_decide_agent_approvals. A run that needs the user's own sign-in to a connector pauses with status requires_tool_output and `pendingConnections` (label, host, reason): no tool here can answer that; tell the user to connect it in chat.2kw.ai → Connectors, as the envelope's `next` says. Always non-streaming. " + MODE_RULE, {
         input: z.string().min(1).describe("The input text (sent as a single user message)"),
         agent: z
             .string()
@@ -148,7 +148,7 @@ export function register(server, client) {
             if (agent) {
                 // The reference the run used, so the envelope's `next` keeps its label and model (D11).
                 const agentRef = agentModel !== undefined ? `${agent}#${agentModel}` : agent;
-                const envelope = buildRunEnvelope(result, agentRef);
+                const envelope = buildRunEnvelope(result, agentRef, chatUrlFor(client._config?.baseUrl));
                 const content = [{ type: "text", text: JSON.stringify(envelope, null, 2) }];
                 // The echoed model is 'agent/<name>@<version>', plus '#<model>' when the request switched it (#591).
                 if (typeof result.model === "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai-mcp-server",
-  "version": "6.3.0-dev.75",
+  "version": "6.3.0-dev.84",
   "description": "MCP server for 2kw.ai — EU-hosted AI platform: OpenAI-compatible LLM gateway, schema-driven document extraction, transcription, agents with a knowledge base, and cost observability. 158 tools for Claude Code, Cursor, and Windsurf.",
   "mcpName": "ai.2kw/mcp-server",
   "keywords": [