@2kw/ai-mcp-server 6.3.0-dev.8 → 6.3.0-dev.89

package/README.md

@@ -42,6 +42,7 @@ Get an API key from your [2kw.ai dashboard](https://2kw.ai) — paid plans start
 |----------|----------|---------|-------------|
 | `AI_2KW_API_KEY` | Yes | — | API key for the 2kw.ai platform (legacy alias: `BACKBONE_API_KEY`) |
 | `AI_2KW_BASE_URL` | No | 2kw.ai cloud API | Point at a self-hosted deployment (legacy alias: `BACKBONE_BASE_URL`) |
+| `AI_2KW_MEMORY` | No | off | `true` makes agent runs through `2kw_create_response` and `2kw_decide_agent_approvals` opt into agent memory (`X-Backbone-Memory: enabled`) |
 | `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
 | `MCP_HTTP_PORT` | No | `3100` | Port for HTTP transport |
 
@@ -56,10 +57,11 @@ Get an API key from your [2kw.ai dashboard](https://2kw.ai) — paid plans start
 | **Schemas** | CRUD, versioning, labels, validation, and testing against sample documents |
 | **Prompts** | Versioned prompt management, labels, compilation, testing |
 | **Datasets & experiments** | Build datasets, run experiments, manage evaluators, record scores |
-| **Agents** | CRUD, versioning, labels, tool-approval history, and tool-catalog sync history |
+| **Agents** | CRUD, versioning, labels, runs with the full result envelope, approval decisions, tool-approval history, and tool-catalog sync history |
 | **Conversations** | Create/inspect/delete conversations and replay their items for the responses API |
 | **Knowledge base** | CRUD, document upload/attach/versioning, hybrid search, and citation resolution |
 | **Files** | Upload, list, download, and delete files (agent input or knowledge documents) |
+| **Memory** | List, read, write and delete your own agent memory files, forget everything; admins see member totals and erase a member |
 | **Observability** | Analytics (spend, quality, providers, errors), traces, billing limits |
 | **API docs** | Browse the platform API documentation by section |
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import createClient from "openapi-fetch";
+import createClient, { type Middleware } from "openapi-fetch";
 import type { paths } from "./generated/openapi.js";
 export type ApiClient = ReturnType<typeof createClient<paths>> & {
     /** Exposed config for raw fetch calls (e.g. multipart uploads). */
@@ -7,8 +7,15 @@ export type ApiClient = ReturnType<typeof createClient<paths>> & {
         apiKey: string;
     };
 };
+/** The per-request opt-in to agent memory for API-key runs (agent memory spec §3.3, D6, D7). */
+export declare const MEMORY_HEADER = "X-Backbone-Memory";
+/** Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses` only, the call that starts or resumes a run. */
+export declare const memoryHeaderMiddleware: Middleware;
 /**
  * Create a typed openapi-fetch client with Bearer auth and error middleware.
+ * `memory: true` opts agent runs into agent memory (see {@link memoryHeaderMiddleware}).
  */
-export declare function createApiClient(baseUrl: string, apiKey: string): ApiClient;
+export declare function createApiClient(baseUrl: string, apiKey: string, options?: {
+    memory?: boolean;
+}): ApiClient;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -34,10 +34,22 @@ const errorMiddleware = {
         });
     },
 };
+/** The per-request opt-in to agent memory for API-key runs (agent memory spec §3.3, D6, D7). */
+export const MEMORY_HEADER = "X-Backbone-Memory";
+/** Adds `X-Backbone-Memory: enabled` to `POST …/v1/responses` only, the call that starts or resumes a run. */
+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;
+    },
+};
 /**
  * Create a typed openapi-fetch client with Bearer auth and error middleware.
+ * `memory: true` opts agent runs into agent memory (see {@link memoryHeaderMiddleware}).
  */
-export function createApiClient(baseUrl, apiKey) {
+export function createApiClient(baseUrl, apiKey, options = {}) {
     const client = createClient({
         baseUrl: baseUrl.replace(/\/+$/, ""),
         headers: {
@@ -45,6 +57,8 @@ export function createApiClient(baseUrl, apiKey) {
         },
     });
     client.use(errorMiddleware);
+    if (options.memory)
+        client.use(memoryHeaderMiddleware);
     // Expose config for raw fetch calls (multipart uploads)
     const enriched = client;
     enriched._config = { baseUrl: baseUrl.replace(/\/+$/, ""), apiKey };

package/dist/index.js

@@ -6,31 +6,7 @@ import { createServer } from "node:http";
 import { createRequire } from "node:module";
 import { createApiClient } from "./client.js";
 const pkg = createRequire(import.meta.url)("../package.json");
-import * as conversion from "./tools/conversion.js";
-import * as extraction from "./tools/extraction.js";
-import * as aiGateway from "./tools/ai-gateway.js";
-import * as transcription from "./tools/transcription.js";
-import * as schemas from "./tools/schemas.js";
-import * as schemaLabels from "./tools/schema-labels.js";
-import * as schemaVersions from "./tools/schema-versions.js";
-import * as schemaTesting from "./tools/schema-testing.js";
-import * as datasets from "./tools/datasets.js";
-import * as experiments from "./tools/experiments.js";
-import * as evaluators from "./tools/evaluators.js";
-import * as prompts from "./tools/prompts.js";
-import * as skills from "./tools/skills.js";
-import * as plugins from "./tools/plugins.js";
-import * as providers from "./tools/providers.js";
-import * as billing from "./tools/billing.js";
-import * as scores from "./tools/scores.js";
-import * as annotationQueues from "./tools/annotation-queues.js";
-import * as tracing from "./tools/tracing.js";
-import * as analytics from "./tools/analytics.js";
-import * as docs from "./tools/docs.js";
-import * as agents from "./tools/agents.js";
-import * as conversations from "./tools/conversations.js";
-import * as knowledge from "./tools/knowledge.js";
-import * as files from "./tools/files.js";
+import { registerAllTools } from "./tools/index.js";
 // Read the canonical KW_* env var; fall back to legacy BACKBONE_* for
 // backwards compatibility. Warn once on stderr when the legacy name supplied
 // the value.
@@ -61,43 +37,19 @@ function requireEnv(canonical, legacy) {
 }
 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";
 async function main() {
     const apiKey = requireEnv("AI_2KW_API_KEY", "BACKBONE_API_KEY");
     const baseUrl = readEnv("AI_2KW_BASE_URL", "BACKBONE_BASE_URL") ?? DEFAULT_BASE_URL;
     const transport = process.env.MCP_TRANSPORT ?? "stdio";
     const httpPort = parseInt(process.env.MCP_HTTP_PORT ?? "3100", 10);
-    const client = createApiClient(baseUrl, apiKey);
+    // Opt API-key runs into agent memory (X-Backbone-Memory: enabled on responses calls, #721).
+    const client = createApiClient(baseUrl, apiKey, { memory: process.env.AI_2KW_MEMORY === "true" });
     const server = new McpServer({
         name: "2kw",
         version: pkg.version,
     });
-    // Register all tool groups
-    conversion.register(server, client);
-    extraction.register(server, client);
-    aiGateway.register(server, client);
-    transcription.register(server, client);
-    schemas.register(server, client);
-    schemaLabels.register(server, client);
-    schemaVersions.register(server, client);
-    schemaTesting.register(server, client);
-    datasets.register(server, client);
-    experiments.register(server, client);
-    evaluators.register(server, client);
-    prompts.register(server, client);
-    skills.register(server, client);
-    plugins.register(server, client);
-    providers.register(server, client);
-    billing.register(server, client);
-    scores.register(server, client);
-    annotationQueues.register(server, client);
-    tracing.register(server, client);
-    analytics.register(server, client);
-    docs.register(server, client, baseUrl, apiKey);
-    agents.register(server, client);
-    conversations.register(server, client);
-    knowledge.register(server, client);
-    files.register(server, client);
+    registerAllTools(server, { client, baseUrl, apiKey });
     if (transport === "http") {
         const httpTransport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         const httpServer = createServer(async (req, res) => {

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

@@ -0,0 +1,54 @@
+import type { ApiClient } from "../client.js";
+import type { components } from "../generated/openapi.js";
+import { type ConversationMode, type ResponsesResult } from "./agent-run.js";
+/**
+ * Decide the approvals a paused agent run is waiting for (#667; spec 2026-09-14-cli-agents-design.md
+ * §4.2, D10, D11). Mirrors `cli/src/lib/agent-decide.ts` and `agent-lookup.ts`, with a per-approval
+ * input instead of the CLI's flags.
+ */
+export type ApprovalRow = components["schemas"]["ToolApprovalDTO"];
+export interface DecisionInput {
+    approvalId: string;
+    decision: "approve" | "reject";
+    reason?: string;
+    remember?: boolean;
+}
+export interface DecideInput {
+    decisions?: DecisionInput[];
+    decideAll?: "approve" | "reject";
+    /** Only with `decideAll`: the reason stored on every decision. */
+    reason?: string;
+    /** Only with `decideAll`: remember every approval for the conversation. */
+    remember?: boolean;
+}
+/** The #660 wire item, byte for byte what n8n Decide Approval and `bb agents decide` send. */
+export interface ApprovalItem {
+    type: "backbone:approval_response";
+    approval_id: string;
+    decision: "approve" | "reject";
+    hmac: string;
+    reason?: string;
+    remember?: "conversation";
+}
+/** `name[@label][#model]`, split like the server: the model at the last `#`, then the label at the last `@`. */
+export declare function splitAgentRef(ref: string): {
+    name: string;
+    label: string | undefined;
+    model: string | undefined;
+};
+/** A UUID is taken as the id; a name is matched exactly (the REST API only offers a substring `search`). */
+export declare function resolveAgentId(client: ApiClient, name: string): Promise<string>;
+export declare function fetchPendingApprovals(client: ApiClient, agentId: string, responseId: string): Promise<ApprovalRow[]>;
+/**
+ * The backend refuses a continuation that leaves any pending approval of the paused response
+ * undecided (400 incomplete_tool_outputs, D10), so the whole set is checked here before sending.
+ */
+export declare function planDecisions(pending: ApprovalRow[], input: DecideInput, responseId: string): ApprovalItem[];
+/**
+ * Continues on `agent/<agentId>[@<label>][#<model>]`: the server resolves the continuation's tools,
+ * instructions and model from this reference, so label and model must be the run's (D11). Never the
+ * echoed `name@<versionNumber>` — it would 404 as a label.
+ * With `mode`, the `backbone:mode` item follows the decisions (#656).
+ */
+export declare function continueWithDecisions(client: ApiClient, agentId: string, responseId: string, items: ApprovalItem[], label?: string, model?: string, mode?: ConversationMode): Promise<ResponsesResult>;
+//# sourceMappingURL=agent-decide.d.ts.map

package/dist/lib/agent-decide.js

@@ -0,0 +1,124 @@
+import { modeItem } from "./agent-run.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PAGE_SIZE = 100;
+const MAX_PAGES = 50;
+/** `name[@label][#model]`, split like the server: the model at the last `#`, then the label at the last `@`. */
+export function splitAgentRef(ref) {
+    const hash = ref.lastIndexOf("#");
+    const model = hash >= 0 ? ref.slice(hash + 1) : undefined;
+    const base = hash >= 0 ? ref.slice(0, hash) : ref;
+    const at = base.lastIndexOf("@");
+    if (at <= 0)
+        return { name: base, label: undefined, model };
+    return { name: base.slice(0, at), label: base.slice(at + 1), model };
+}
+/** A UUID is taken as the id; a name is matched exactly (the REST API only offers a substring `search`). */
+export async function resolveAgentId(client, name) {
+    if (UUID.test(name))
+        return name;
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const { data } = await client.GET("/v1/agents", {
+            // A stable sort: offset paging over an unordered result can skip rows between pages.
+            params: { query: { search: name, pageable: { page, size: PAGE_SIZE, sort: ["id,asc"] } } },
+        });
+        // Typed loosely, as 2kw_list_agents does: the generated page type of this endpoint is not a PageAgentDTO.
+        const pageData = data;
+        const content = pageData?.content ?? [];
+        const hit = content.find((a) => a.name === name);
+        if (hit?.id)
+            return String(hit.id);
+        if (pageData?.last !== false || content.length === 0)
+            break;
+    }
+    throw new Error(`Agent '${name}' not found. List agents with 2kw_list_agents.`);
+}
+export async function fetchPendingApprovals(client, agentId, responseId) {
+    const rows = [];
+    for (let page = 0; page < MAX_PAGES; page++) {
+        const { data } = await client.GET("/v1/agents/{agentId}/approvals", {
+            params: { path: { agentId }, query: { status: "pending", pageable: { page, size: PAGE_SIZE } } },
+        });
+        const content = data?.content ?? [];
+        rows.push(...content.filter((r) => r.responseId === responseId));
+        if (data?.last !== false || content.length === 0)
+            break;
+    }
+    return rows;
+}
+/**
+ * The backend refuses a continuation that leaves any pending approval of the paused response
+ * undecided (400 incomplete_tool_outputs, D10), so the whole set is checked here before sending.
+ */
+export function planDecisions(pending, input, responseId) {
+    if (pending.length === 0) {
+        throw new Error(`No pending approvals for ${responseId} (already decided or superseded).`);
+    }
+    const hasList = input.decisions !== undefined && input.decisions.length > 0;
+    if (hasList === (input.decideAll !== undefined)) {
+        throw new Error("Give either `decisions` or `decideAll` (exactly one): one decision per pending approval, or one for all.");
+    }
+    const chosen = new Map();
+    if (input.decideAll !== undefined) {
+        for (const r of pending) {
+            chosen.set(String(r.id), { approvalId: String(r.id), decision: input.decideAll, reason: input.reason, remember: input.remember });
+        }
+    }
+    else {
+        const twice = new Set();
+        for (const d of input.decisions) {
+            if (chosen.has(d.approvalId))
+                twice.add(d.approvalId);
+            chosen.set(d.approvalId, d);
+        }
+        if (twice.size)
+            throw new Error(`Approvals decided more than once: ${[...twice].join(", ")}`);
+        const pendingIds = new Set(pending.map((r) => String(r.id)));
+        const foreign = [...chosen.keys()].filter((id) => !pendingIds.has(id));
+        if (foreign.length)
+            throw new Error(`Not pending on ${responseId}: ${foreign.join(", ")}`);
+        const undecided = [...pendingIds].filter((id) => !chosen.has(id));
+        if (undecided.length) {
+            throw new Error(`Every pending approval of a response must be decided in one call. Undecided: ${undecided.join(", ")}`);
+        }
+    }
+    return pending.map((r) => {
+        const id = String(r.id);
+        const d = chosen.get(id);
+        if (d.remember && d.decision !== "approve") {
+            throw new Error(`\`remember\` applies only to an approve: ${id}`);
+        }
+        if (d.remember && (r.policyClass ?? "").toUpperCase() === "DESTRUCTIVE") {
+            throw new Error(`\`remember\` cannot be used on a destructive tool call: ${id}`);
+        }
+        if (!r.hmac)
+            throw new Error(`Approval ${id} carries no hmac and cannot be decided here.`);
+        return {
+            type: "backbone:approval_response",
+            approval_id: id,
+            decision: d.decision,
+            hmac: r.hmac,
+            ...(d.reason ? { reason: d.reason } : {}),
+            ...(d.remember ? { remember: "conversation" } : {}),
+        };
+    });
+}
+/**
+ * Continues on `agent/<agentId>[@<label>][#<model>]`: the server resolves the continuation's tools,
+ * instructions and model from this reference, so label and model must be the run's (D11). Never the
+ * echoed `name@<versionNumber>` — it would 404 as a label.
+ * With `mode`, the `backbone:mode` item follows the decisions (#656).
+ */
+export async function continueWithDecisions(client, agentId, responseId, items, label, model, mode) {
+    const body = {
+        model: `agent/${agentId}${label ? `@${label}` : ""}${model ? `#${model}` : ""}`,
+        previous_response_id: responseId,
+        stream: false,
+        // With `mode`, the backbone:mode item follows the decisions (#656 D7); without it, nothing is added (D2).
+        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;
+}
+//# sourceMappingURL=agent-decide.js.map

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

@@ -0,0 +1,124 @@
+/**
+ * The run envelope of `bb agents run --json` (spec 2026-09-14-cli-agents-design.md §4.3), copied
+ * 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.
+ */
+type AnyRecord = Record<string, any>;
+export type RunStatus = "completed" | "requires_approval" | "requires_tool_output" | "incomplete";
+export interface PendingApproval {
+    approvalId: string;
+    callId: string;
+    tool: string;
+    arguments: unknown;
+    policyClass: string;
+    /** Why the automatic approver escalated this request to a human (#634); null when it did not. */
+    reason: string | null;
+}
+export interface ToolCallSummary {
+    tool: string;
+    callId: string;
+    /** `incomplete` when the server-side tool run failed (its `function_call_output` carries that status). */
+    status: "completed" | "incomplete";
+}
+export interface PendingToolCall {
+    tool: string;
+    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[];
+/**
+ * Who may change the mode (#656 D8), stated in both tool descriptions: the mode outlives the request
+ * that sets it, so a model that switched on its own would lift the user's choice for every later turn.
+ */
+export declare const MODE_RULE: string;
+/** The `backbone:mode` input item (S1 D7); always appended last. */
+export declare function modeItem(mode: ConversationMode): {
+    type: "backbone:mode";
+    mode: ConversationMode;
+};
+/**
+ * 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 declare function responseMode(result: ResponsesResult | undefined): ConversationMode | null;
+export interface RunEnvelope {
+    status: RunStatus;
+    /** The conversation mode the request ran under (`conversation_mode`); null when none is set. */
+    mode: ConversationMode | null;
+    agent: string | null;
+    version: number | null;
+    responseId: string | null;
+    conversationId: string | null;
+    text: string;
+    toolCalls: ToolCallSummary[];
+    pendingApprovals: PendingApproval[];
+    pendingToolCalls: PendingToolCall[];
+    pendingConnections: PendingConnection[];
+    incompleteReason: string | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    } | null;
+    next: string | null;
+}
+/** Loose wire shape of a `POST /v1/responses` result; the OpenAPI spec types it as `object`. */
+export interface ResponsesResult {
+    id?: string;
+    status?: string;
+    model?: string;
+    output?: AnyRecord[];
+    usage?: {
+        input_tokens?: number;
+        output_tokens?: number;
+        total_tokens?: number;
+    };
+    conversation?: {
+        id?: string;
+    } | null;
+    incomplete_details?: {
+        reason?: string;
+    } | null;
+    conversation_mode?: string | null;
+}
+/** The assistant's text: every `output_text` part of every `message` item, in order. */
+export declare function extractResponseText(result: ResponsesResult | undefined): string;
+/**
+ * The response echoes `model` as `agent/{name}@{versionNumber}` (all digits), optionally
+ * followed by a `#<model>` override. Only a trailing all-digit `@N` is read as a version;
+ * any other `@` suffix stays part of the name.
+ */
+export declare function parseAgentModel(model?: string): {
+    agent: string | null;
+    version: number | null;
+};
+/**
+ * @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, chatUrl?: string): RunEnvelope;
+export {};
+//# sourceMappingURL=agent-run.d.ts.map