@2kw/ai-mcp-server 6.3.0-dev.3 → 6.3.0-dev.31

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

@@ -31,6 +31,7 @@ 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 * as memory from "./tools/memory.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.
@@ -67,7 +68,8 @@ async function main() {
     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,
@@ -98,6 +100,7 @@ async function main() {
     conversations.register(server, client);
     knowledge.register(server, client);
     files.register(server, client);
+    memory.register(server, client);
     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,53 @@
+import type { ApiClient } from "../client.js";
+import type { components } from "../generated/openapi.js";
+import 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.
+ */
+export declare function continueWithDecisions(client: ApiClient, agentId: string, responseId: string, items: ApprovalItem[], label?: string, model?: string): Promise<ResponsesResult>;
+//# sourceMappingURL=agent-decide.d.ts.map

package/dist/lib/agent-decide.js

@@ -0,0 +1,121 @@
+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.
+ */
+export async function continueWithDecisions(client, agentId, responseId, items, label, model) {
+    const body = {
+        model: `agent/${agentId}${label ? `@${label}` : ""}${model ? `#${model}` : ""}`,
+        previous_response_id: responseId,
+        stream: false,
+        input: 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,82 @@
+/**
+ * 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;
+}
+export interface RunEnvelope {
+    status: RunStatus;
+    /** Reserved for the server-side conversation mode (#656); always null until then. */
+    mode: null;
+    agent: string | null;
+    version: number | null;
+    responseId: string | null;
+    conversationId: string | null;
+    text: string;
+    toolCalls: ToolCallSummary[];
+    pendingApprovals: PendingApproval[];
+    pendingToolCalls: PendingToolCall[];
+    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;
+}
+/** 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.
+ */
+export declare function buildRunEnvelope(result: ResponsesResult | undefined, agentRef?: string): RunEnvelope;
+export {};
+//# sourceMappingURL=agent-run.d.ts.map

package/dist/lib/agent-run.js

@@ -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.
+ */
+/** The assistant's text: every `output_text` part of every `message` item, in order. */
+export function extractResponseText(result) {
+    const parts = [];
+    for (const item of result?.output ?? []) {
+        if (item.type !== "message")
+            continue;
+        for (const part of item.content ?? []) {
+            if (part.type === "output_text" && part.text)
+                parts.push(part.text);
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * 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 function parseAgentModel(model) {
+    // Strip the `#<model>` override (from the last `#`, as the server splits it) before matching.
+    const hash = (model ?? "").lastIndexOf("#");
+    const ref = hash >= 0 ? (model ?? "").slice(0, hash) : model ?? "";
+    const withVersion = /^agent\/(.+)@(\d+)$/.exec(ref);
+    if (withVersion)
+        return { agent: withVersion[1], version: Number(withVersion[2]) };
+    const bare = /^agent\/(.+)$/.exec(ref);
+    if (bare)
+        return { agent: bare[1], version: null };
+    return { agent: null, version: null };
+}
+function parseArguments(raw) {
+    if (typeof raw !== "string")
+        return raw ?? {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * @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.
+ */
+export function buildRunEnvelope(result, agentRef) {
+    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`.
+    const outputStatuses = new Map(output
+        .filter((i) => i.type === "function_call_output")
+        .map((i) => [
+        String(i.call_id),
+        i.status === "incomplete" ? "incomplete" : "completed",
+    ]));
+    const pendingApprovals = output
+        // Only an open request is pending; judge- or grant-decided requests (#634, #629) carry another status.
+        .filter((i) => i.type === "backbone:approval_request" && (i.status === undefined || i.status === "in_progress"))
+        .map((i) => ({
+        approvalId: String(i.id),
+        callId: String(i.call_id),
+        tool: String(i.tool),
+        arguments: parseArguments(i.arguments),
+        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 toolCalls = [];
+    const pendingToolCalls = [];
+    for (const item of output) {
+        if (item.type !== "function_call")
+            continue;
+        const callId = String(item.call_id);
+        const outputStatus = outputStatuses.get(callId);
+        if (outputStatus) {
+            toolCalls.push({ tool: String(item.name), callId, status: outputStatus });
+        }
+        else if (!withheldCallIds.has(callId)) {
+            pendingToolCalls.push({ tool: String(item.name), callId, arguments: parseArguments(item.arguments) });
+        }
+    }
+    let status;
+    switch (result?.status) {
+        case "completed":
+            status = "completed";
+            break;
+        case "incomplete":
+            status = "incomplete";
+            break;
+        case "requires_action":
+            status = pendingToolCalls.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;
+    return {
+        status,
+        mode: null,
+        agent,
+        version,
+        responseId,
+        conversationId: result?.conversation?.id ?? null,
+        text: extractResponseText(result),
+        toolCalls,
+        pendingApprovals,
+        pendingToolCalls,
+        incompleteReason: result?.incomplete_details?.reason ?? null,
+        usage: result?.usage
+            ? { inputTokens: result.usage.input_tokens ?? 0, outputTokens: result.usage.output_tokens ?? 0 }
+            : null,
+        next,
+    };
+}
+//# sourceMappingURL=agent-run.js.map

package/dist/tools/agents.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+import { continueWithDecisions, fetchPendingApprovals, planDecisions, resolveAgentId, splitAgentRef } from "../lib/agent-decide.js";
+import { buildRunEnvelope } from "../lib/agent-run.js";
 const modelSchema = z
     .string()
     .min(1)
@@ -301,6 +303,30 @@ export function register(server, client) {
             };
         }
     });
+    // ── list_agent_skills ───────────────────────────────────────────────────
+    server.tool("2kw_list_agent_skills", "List the skills an agent's latest published version binds, in authored order. This is the "
+        + "read a chat-only USER key may perform; 2kw_get_latest_agent_version carries the full version "
+        + "and needs VIEWER or above. An agent with no published version lists none.", { agentId: z.string().describe("The agent ID") }, async ({ agentId }) => {
+        try {
+            const { data } = await client.GET("/v1/agents/{agentId}/skills", {
+                params: { path: { agentId } },
+            });
+            const lines = (data ?? []).map((s) => {
+                const plugin = s.pluginName ? `, plugin: ${s.pluginName}` : "";
+                const description = s.description ? ` — ${s.description}` : "";
+                return `- ${s.name} (v${s.versionNumber}, ref: ${s.ref}${plugin})${description}`;
+            });
+            return {
+                content: [{ type: "text", text: `Agent skills:\n${lines.join("\n") || "(none)"}` }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
     // ── get_agent_version ───────────────────────────────────────────────────
     server.tool("2kw_get_agent_version", "Retrieve a specific version of an agent.", {
         agentId: z.string().describe("The agent ID"),
@@ -503,6 +529,45 @@ export function register(server, client) {
             };
         }
     });
+    // ── decide_agent_approvals ──────────────────────────────────────────────
+    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.", {
+        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`)"),
+        decisions: z
+            .array(z.object({
+            approvalId: z.string().min(1).describe("Envelope `pendingApprovals[].approvalId`"),
+            decision: z.enum(["approve", "reject"]),
+            reason: z.string().optional().describe("Stored with the decision; the model sees it on a reject"),
+            remember: z.boolean().optional().describe("Approve this tool for the rest of the conversation; not on destructive tools"),
+        }))
+            .optional()
+            .describe("One entry per pending approval. Mutually exclusive with `decideAll`."),
+        decideAll: z.enum(["approve", "reject"]).optional().describe("Decide every pending approval the same way"),
+        reason: z.string().optional().describe("Only with `decideAll`: reason stored on every decision"),
+        remember: z.boolean().optional().describe("Only with `decideAll`: remember every approval for the conversation"),
+    }, async ({ agent, responseId, decisions, decideAll, reason, remember }) => {
+        try {
+            if (decisions !== undefined && (reason !== undefined || remember !== undefined)) {
+                throw new Error("With `decisions`, give `reason` and `remember` per entry.");
+            }
+            const { name, label, model } = splitAgentRef(agent);
+            const agentId = await resolveAgentId(client, name);
+            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);
+            const envelope = buildRunEnvelope(result, agent);
+            return { content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }] };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
     // ── list_agent_tool_catalogs ─────────────────────────────────────────────
     server.tool("2kw_list_agent_tool_catalogs", "List an agent's tool-catalog sync history, newest first. Optionally narrow to one installation. The signed bytes and their signature are never returned.", {
         agentId: z.string().describe("The agent ID"),

package/dist/tools/ai-gateway.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+import { buildRunEnvelope } 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).
@@ -92,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. The reply ends with the model that answered. Always non-streaming.", {
+    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.", {
         input: z.string().min(1).describe("The input text (sent as a single user message)"),
         agent: z
             .string()
@@ -137,6 +138,17 @@ export function register(server, client) {
                 body: body,
             });
             const result = data;
+            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 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") {
+                    content.push({ type: "text", text: `[model: ${result.model}]` });
+                }
+                return { content };
+            }
             const parts = [];
             const output = result.output;
             for (const item of output ?? []) {
@@ -162,11 +174,6 @@ export function register(server, client) {
             if (parts.length === 0) {
                 parts.push({ type: "text", text: JSON.stringify(result, null, 2) });
             }
-            // The response echoes the model that answered: for an agent run
-            // 'agent/<name>@<version>', plus '#<model>' when the request switched it (#591).
-            if (agent && typeof result.model === "string") {
-                parts.push({ type: "text", text: `[model: ${result.model}]` });
-            }
             return { content: parts };
         }
         catch (error) {

package/dist/tools/knowledge.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
-import { BackboneApiError, formatErrorForMcp } from "../errors.js";
+import { formatErrorForMcp } from "../errors.js";
 import { getMimeType } from "../mime.js";
 const ChunkingStrategy = z.enum(["AUTO", "FIXED", "HIERARCHICAL", "CUSTOM"]);
 const DocumentStatus = z.enum(["PENDING", "PARSING", "CHUNKING", "EMBEDDING", "READY", "ERROR"]);
@@ -203,29 +203,13 @@ export function register(server, client) {
                 const filename = basename(filePath);
                 formData.append("files", new Blob([buffer], { type: getMimeType(filename) }), filename);
             }
-            const { baseUrl, apiKey } = client._config;
-            const res = await fetch(`${baseUrl}/v1/knowledge-bases/${encodeURIComponent(knowledgeBaseId)}/documents`, {
-                method: "POST",
-                headers: { Authorization: `Bearer ${apiKey}` },
-                body: formData,
+            const { data } = await client.POST("/v1/knowledge-bases/{knowledgeBaseId}/documents", {
+                params: { path: { knowledgeBaseId } },
+                // Provide placeholder body for type checking; actual payload comes from bodySerializer
+                body: { files: [] },
+                bodySerializer: () => formData,
             });
-            if (!res.ok) {
-                let body;
-                try {
-                    body = await res.json();
-                }
-                catch {
-                    body = {
-                        error: res.statusText,
-                        message: `HTTP ${res.status}: ${res.statusText}`,
-                        status: res.status,
-                        timestamp: new Date().toISOString(),
-                    };
-                }
-                throw new BackboneApiError(body);
-            }
-            const data = (await res.json());
-            const lines = data.map((r) => r.error
+            const lines = (data ?? []).map((r) => r.error
                 ? `- ${r.filename}: rejected — ${r.error}`
                 : `- ${r.filename}: accepted, documentId=${r.upload?.document?.id}, versionId=${r.upload?.acceptedVersion?.id}, status=${r.upload?.acceptedVersion?.status}`);
             return {

package/dist/tools/memory.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ApiClient } from "../client.js";
+/**
+ * Agent memory of organization members (agent memory spec §7.1, §7.4). The "my" tools act on
+ * the API key owner's own memory; the member tools are for ADMIN and OWNER keys and never
+ * show paths or content.
+ */
+export declare function register(server: McpServer, client: ApiClient): void;
+//# sourceMappingURL=memory.d.ts.map

package/dist/tools/memory.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { formatErrorForMcp } from "../errors.js";
+async function reply(action) {
+    try {
+        const data = await action();
+        return {
+            content: [{ type: "text", text: data === undefined ? "Done." : JSON.stringify(data, null, 2) }],
+        };
+    }
+    catch (error) {
+        return { content: [{ type: "text", text: formatErrorForMcp(error) }], isError: true };
+    }
+}
+const path = z.string().min(1).describe("Memory path, /memories or below, e.g. /memories/preferences.md");
+/**
+ * Agent memory of organization members (agent memory spec §7.1, §7.4). The "my" tools act on
+ * the API key owner's own memory; the member tools are for ADMIN and OWNER keys and never
+ * show paths or content.
+ */
+export function register(server, client) {
+    server.tool("2kw_list_my_memory_files", "List the files in your agent memory (the API key owner's), ordered by path, without content.", {}, async () => reply(async () => (await client.GET("/v1/memories/me/files")).data));
+    server.tool("2kw_read_my_memory_file", "Read one of your agent memory files: the raw content, its version (for ifMatchVersion) and which agent wrote it last.", { path }, async ({ path }) => reply(async () => (await client.GET("/v1/memories/me/file", { params: { query: { path } } })).data));
+    server.tool("2kw_write_my_memory_file", "Create or replace one of your agent memory files with the complete content. Pass ifMatchVersion (the version from 2kw_read_my_memory_file) to refuse the write if the file changed since. Credentials are refused; files are limited to 32 KB.", {
+        path,
+        content: z.string().describe("The complete UTF-8 text content of the file"),
+        ifMatchVersion: z.number().int().min(0).optional().describe("Only replace the file if it still has this version"),
+    }, async ({ path, content, ifMatchVersion }) => reply(async () => (await client.PUT("/v1/memories/me/file", {
+        params: { query: { path } },
+        body: { content },
+        headers: ifMatchVersion === undefined ? undefined : { "If-Match": `"${ifMatchVersion}"` },
+    })).data));
+    server.tool("2kw_delete_my_memory_file", "Delete one of your agent memory files, or a directory with everything below it. Irreversible.", { path }, async ({ path }) => reply(async () => {
+        await client.DELETE("/v1/memories/me/file", { params: { query: { path } } });
+    }));
+    server.tool("2kw_forget_my_memory", "Delete your whole agent memory. Irreversible: confirm with the user before calling.", {}, async () => reply(async () => {
+        await client.DELETE("/v1/memories/me");
+    }));
+    server.tool("2kw_list_member_memory_usage", "Agent memory totals per organization member: file count, total bytes and last write. Never paths or content. Needs an ADMIN or OWNER key.", {}, async () => reply(async () => (await client.GET("/v1/memories/users")).data));
+    server.tool("2kw_erase_member_memory", "Erase one member's whole agent memory in this organization. Irreversible: confirm with the user before calling. Needs an ADMIN or OWNER key.", { userId: z.string().min(1).describe("The member's user id, from 2kw_list_member_memory_usage") }, async ({ userId }) => reply(async () => {
+        await client.DELETE("/v1/memories/users/{userId}", { params: { path: { userId } } });
+    }));
+}
+//# sourceMappingURL=memory.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2kw/ai-mcp-server",
-  "version": "6.3.0-dev.3",
+  "version": "6.3.0-dev.31",
   "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": [