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

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,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

package/dist/lib/agent-run.js

@@ -0,0 +1,260 @@
+/**
+ * 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.
+ */
+/** 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
+ * that sets it, so a model that switched on its own would lift the user's choice for every later turn.
+ */
+export const MODE_RULE = "Set `mode` only when the user explicitly asks for that mode. Never set it to retry a refused approval " +
+    "or to leave plan mode on your own: ask the user first. plan = read-only; ask = no automatic approver, " +
+    "calls that need approval wait for a person; auto = the operator's policy as written. Leave it out to " +
+    "keep the conversation's mode.";
+function isConversationMode(value) {
+    return typeof value === "string" && CONVERSATION_MODES.includes(value);
+}
+/** 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;
+}
+/** 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;
+    }
+}
+/** 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, 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`.
+    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 pendingConnections = pendingConnectionsOf(output);
+    const withheldCallIds = new Set([...pendingApprovals.map((a) => a.callId), ...connectCallIds(output, pendingConnections)]);
+    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":
+            // 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;
+    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),
+        agent,
+        version,
+        responseId,
+        conversationId: result?.conversation?.id ?? null,
+        text: extractResponseText(result),
+        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 }
+            : 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, chatUrlFor, MODE_RULE } 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"),
@@ -333,12 +359,16 @@ export function register(server, client) {
             .string()
             .optional()
             .describe("Resolve this installation's module tool catalog, the way a run of that installation would. Omit to answer for the agent's own tools only."),
-    }, async ({ agentId, versionId, tool, installationId }) => {
+        mode: z
+            .enum(["plan", "ask", "auto"])
+            .optional()
+            .describe("Answer as a conversation in this mode would be gated: plan refuses every call that is not read-only, ask puts a person where the policy would ask the judge, auto is the policy as written. A mode that contributed is listed in matchedRules as conversation_mode.<mode>. Omit for no mode."),
+    }, async ({ agentId, versionId, tool, installationId, mode }) => {
         try {
             const { data } = await client.GET("/v1/agents/{agentId}/versions/{versionId}/policy", {
                 params: {
                     path: { agentId, versionId },
-                    query: { tool, installation: installationId },
+                    query: { tool, installation: installationId, mode },
                 },
             });
             return {
@@ -503,6 +533,51 @@ 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: 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`)"),
+        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"),
+        mode: z
+            .enum(["plan", "ask", "auto"])
+            .optional()
+            .describe("The conversation mode this continuation and later turns run under. Only on the user's explicit request."),
+    }, async ({ agent, responseId, decisions, decideAll, reason, remember, mode }) => {
+        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, mode);
+            const envelope = buildRunEnvelope(result, agent, chatUrlFor(client._config?.baseUrl));
+            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, 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).
@@ -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 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()
@@ -108,7 +109,11 @@ export function register(server, client) {
             .optional()
             .describe("Model identifier in 'provider/model' format. Mutually exclusive with `agent`."),
         conversation: z.string().optional().describe("Conversation ID this response belongs to"),
-    }, async ({ input, agent, agentModel, model, conversation }) => {
+        mode: z
+            .enum(["plan", "ask", "auto"])
+            .optional()
+            .describe("Only with `agent`: the conversation mode for this and later turns (plan, ask or auto). Only on the user's explicit request."),
+    }, async ({ input, agent, agentModel, model, conversation, mode }) => {
         try {
             if (agent && model) {
                 throw new Error("Use either `agent` or `model`, not both.");
@@ -122,13 +127,16 @@ export function register(server, client) {
             if (agentModel !== undefined && agent?.includes("#")) {
                 throw new Error("Give the model switch once: either 'ref#model' in `agent` or `agentModel`.");
             }
+            if (mode !== undefined && !agent) {
+                throw new Error("`mode` applies to agent runs; it needs `agent`.");
+            }
             const resolvedModel = agentModelReference(agent, agentModel) ?? model;
             const body = {
                 model: resolvedModel,
-                // The wire `input` field also accepts a bare string (shorthand for
-                // a single user message; see ResponseItemInputDeserializer), which
-                // the generated type does not model.
-                input,
+                // Without `mode` the wire `input` is the bare string (shorthand for one user message; see
+                // ResponseItemInputDeserializer), which the generated type does not model. With it, the
+                // backbone:mode item follows the message (#656).
+                input: mode ? [{ type: "message", role: "user", content: input }, modeItem(mode)] : input,
                 stream: false,
                 ...(conversation !== undefined && { conversation }),
             };
@@ -137,6 +145,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, 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") {
+                    content.push({ type: "text", text: `[model: ${result.model}]` });
+                }
+                return { content };
+            }
             const parts = [];
             const output = result.output;
             for (const item of output ?? []) {
@@ -162,11 +181,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/conversations.js

@@ -134,6 +134,32 @@ export function register(server, client) {
             };
         }
     });
+    // ── cancel_conversation_turn ─────────────────────────────────────────────
+    server.tool("2kw_cancel_conversation_turn", "Ask a running turn of a conversation to stop. turnId is the value the client sent as the Backbone-Turn-Id header on the responses call. The stop is accepted, not confirmed: the turn's own response reports status cancelled, or completed when the stop arrived too late.", {
+        conversationId: z.string().describe("The conversation ID"),
+        turnId: z
+            .string()
+            .regex(/^[A-Za-z0-9_-]{1,64}$/)
+            .describe("The turn id from the Backbone-Turn-Id header: 1-64 characters of A-Z, a-z, 0-9, '_' or '-'"),
+    }, async ({ conversationId, turnId }) => {
+        try {
+            await client.POST("/v1/conversations/{conversationId}/cancel", {
+                params: { path: { conversationId } },
+                body: { turn_id: turnId },
+            });
+            return {
+                content: [
+                    { type: "text", text: `Stop requested for turn ${turnId} of conversation ${conversationId}.` },
+                ],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: "text", text: formatErrorForMcp(error) }],
+                isError: true,
+            };
+        }
+    });
     // ── list_conversation_items ──────────────────────────────────────────────
     server.tool("2kw_list_conversation_items", "Fetch a conversation's items in replay order, oldest first.", { conversationId: z.string().describe("The conversation ID") }, async ({ conversationId }) => {
         try {

package/dist/tools/experiments.js

@@ -157,7 +157,7 @@ export function register(server, client) {
     server.tool("2kw_add_variant", "Add a variant to an experiment with a task type and configuration.", {
         experimentId: z.string().describe("The experiment ID"),
         name: z.string().min(1).describe("Variant name"),
-        taskType: z.string().min(1).describe("Task type (e.g., EXTRACTION, CLASSIFICATION)"),
+        taskType: z.string().min(1).describe("Task type: extraction or agent"),
         configuration: z.unknown().describe("Variant configuration (JSON object)"),
         description: z.string().optional().describe("Variant description"),
         sortOrder: z.number().optional().describe("Sort order for display"),
@@ -214,7 +214,7 @@ export function register(server, client) {
         experimentId: z.string().describe("The experiment ID"),
         variantId: z.string().describe("The variant ID"),
         name: z.string().optional().describe("New variant name"),
-        taskType: z.string().optional().describe("New task type"),
+        taskType: z.string().optional().describe("Task type; must equal the variant's current one (it cannot change)"),
         configuration: z.unknown().optional().describe("New variant configuration (JSON object)"),
         description: z.string().optional().describe("New variant description"),
         sortOrder: z.number().optional().describe("New sort order for display"),

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/dist/tools/tracing.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
 export function register(server, client) {
     // ── settings ────────────────────────────────────────────────────────────
-    server.tool("2kw_get_tracing_settings", "Return the org's tracing settings (includePrompts / includeCompletions). These control whether raw prompt and completion content are persisted on ingested spans. Defaults are false for both.", {}, async () => {
+    server.tool("2kw_get_tracing_settings", "Return the org's tracing settings: includePrompts / includeCompletions (whether raw prompt and completion content are persisted on ingested spans; false by default) and trace retention: retentionDays (the org's choice, null = follow the plan), planRetentionDays and effectiveRetentionDays.", {}, async () => {
         try {
             const { data } = await client.GET("/v1/tracing/settings");
             return {
@@ -16,7 +16,7 @@ export function register(server, client) {
             };
         }
     });
-    server.tool("2kw_update_tracing_settings", "Update the org's tracing settings. Admin-only. Omit a field to leave it at its current value — the tool reads the current setting first and merges.", {
+    server.tool("2kw_update_tracing_settings", "Update the org's tracing settings. Admin-only. Omit a field to leave it at its current value — the tool reads the current setting first and merges. Shortening retentionDays deletes older traces at the next daily sweep.", {
         includePrompts: z
             .boolean()
             .optional()
@@ -25,12 +25,20 @@ export function register(server, client) {
             .boolean()
             .optional()
             .describe("Retain completion content on ingested spans (default false)"),
+        retentionDays: z
+            .number()
+            .int()
+            .min(1)
+            .nullable()
+            .optional()
+            .describe("Trace retention in days, at most the plan's limit (planRetentionDays). null follows the plan. Shortening deletes older traces at the next daily sweep."),
     }, async (params) => {
         try {
             const { data: current } = await client.GET("/v1/tracing/settings");
             const merged = {
                 includePrompts: params.includePrompts ?? current?.includePrompts ?? false,
                 includeCompletions: params.includeCompletions ?? current?.includeCompletions ?? false,
+                retentionDays: params.retentionDays !== undefined ? params.retentionDays : (current?.retentionDays ?? null),
             };
             const { data } = await client.PUT("/v1/tracing/settings", {
                 body: merged,

package/package.json

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