@2kw/ai-mcp-server 6.2.2 → 6.3.0-dev.105

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/lib/overlay.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The body for a PUT that replaces the whole row: the stored resource as its GET returned it, with
+ * every change the caller gave written over it. A change that is `undefined` was not given and keeps
+ * the stored value; the backend would store it as null otherwise (#1195). Server-managed fields in
+ * `current` (a dataset's or prompt's latestVersionId) go back as read, which is what keeps them.
+ */
+export declare function overlay<T extends object>(current: T, changes: Record<string, unknown>): T;
+/** Refuses a name that is present but blank, which a full-replace PUT would otherwise store. */
+export declare function assertNameNotBlank(name: string | undefined): void;
+//# sourceMappingURL=overlay.d.ts.map

package/dist/lib/overlay.js

@@ -0,0 +1,20 @@
+/**
+ * The body for a PUT that replaces the whole row: the stored resource as its GET returned it, with
+ * every change the caller gave written over it. A change that is `undefined` was not given and keeps
+ * the stored value; the backend would store it as null otherwise (#1195). Server-managed fields in
+ * `current` (a dataset's or prompt's latestVersionId) go back as read, which is what keeps them.
+ */
+export function overlay(current, changes) {
+    const body = { ...current };
+    for (const [key, value] of Object.entries(changes)) {
+        if (value !== undefined)
+            body[key] = value;
+    }
+    return body;
+}
+/** Refuses a name that is present but blank, which a full-replace PUT would otherwise store. */
+export function assertNameNotBlank(name) {
+    if (name !== undefined && !name.trim())
+        throw new Error("name must not be empty.");
+}
+//# sourceMappingURL=overlay.js.map

package/dist/tools/agents.js

@@ -1,5 +1,8 @@
 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";
+import { assertNameNotBlank } from "../lib/overlay.js";
 const modelSchema = z
     .string()
     .min(1)
@@ -157,9 +160,9 @@ export function register(server, client) {
         }
     });
     // ── update_agent ────────────────────────────────────────────────────────
-    server.tool("2kw_update_agent", "Update an agent's metadata and configuration. name is required on every update. `model` or `models` replaces the stored model list (a shorter list leaves no tail); omit both to keep the current models. Does not create a version.", {
+    server.tool("2kw_update_agent", "Update an agent's metadata and configuration. Omitted fields keep their current values (the tool reads the agent's name and description first when either is omitted). `model` or `models` replaces the stored model list (a shorter list leaves no tail); omit both to keep the current models. Does not create a version.", {
         agentId: z.string().describe("The agent ID"),
-        name: z.string().min(1).describe("Agent name"),
+        name: z.string().optional().describe("New agent name"),
         model: modelSchema.optional(),
         models: modelsSchema.optional(),
         description: z.string().optional().describe("Agent description"),
@@ -170,6 +173,18 @@ export function register(server, client) {
         hitlPolicy: z.unknown().optional().describe("Human-in-the-loop approval policy (JSON object)"),
     }, async ({ agentId, name, model, models, description, instructions, options, tools, skills, hitlPolicy }) => {
         try {
+            assertNameNotBlank(name);
+            // PUT /v1/agents/{id} keeps the configuration fields a body omits, but name is required and
+            // description is written as sent, so an omitted description would be cleared (#1195).
+            if (name === undefined || description === undefined) {
+                const { data: current } = await client.GET("/v1/agents/{id}", {
+                    params: { path: { id: agentId } },
+                });
+                if (!current)
+                    throw new Error(`Agent ${agentId} could not be read.`);
+                name ??= current.name;
+                description ??= current.description;
+            }
             const body = { name, ...modelFields(model, models, false) };
             if (description !== undefined)
                 body.description = description;
@@ -301,6 +316,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 +372,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 +546,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). With it, the backbone:mode item follows the message (#656);
+                // that literal item array is what the cast below is for.
+                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/datasets.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
+import { assertNameNotBlank, overlay } from "../lib/overlay.js";
 async function resolveLatestVersionId(client, datasetId) {
     const { data } = await client.GET("/v1/datasets/{id}/versions/latest", { params: { path: { id: datasetId } } });
     const versionId = data?.id;
@@ -104,7 +105,7 @@ export function register(server, client) {
         }
     });
     // ── update_dataset ─────────────────────────────────────────────
-    server.tool("2kw_update_dataset", "Update an existing dataset's details.", {
+    server.tool("2kw_update_dataset", "Update an existing dataset's details. Omitted fields keep their current values (the tool reads the dataset first).", {
         datasetId: z.string().describe("The dataset ID"),
         name: z.string().optional().describe("New name"),
         description: z.string().optional().describe("New description"),
@@ -114,22 +115,16 @@ export function register(server, client) {
         metadata: z.unknown().optional().describe("Arbitrary metadata (JSON object)"),
     }, async ({ datasetId, name, description, type, inputSchema, expectedOutputSchema, metadata }) => {
         try {
-            const body = {};
-            if (name !== undefined)
-                body.name = name;
-            if (description !== undefined)
-                body.description = description;
-            if (type !== undefined)
-                body.type = type;
-            if (inputSchema !== undefined)
-                body.inputSchema = inputSchema;
-            if (expectedOutputSchema !== undefined)
-                body.expectedOutputSchema = expectedOutputSchema;
-            if (metadata !== undefined)
-                body.metadata = metadata;
+            assertNameNotBlank(name);
+            // PUT /v1/datasets/{id} replaces the whole dataset, so an omitted field would be stored as null.
+            const { data: current } = await client.GET("/v1/datasets/{id}", {
+                params: { path: { id: datasetId } },
+            });
+            if (!current)
+                throw new Error(`Dataset ${datasetId} could not be read.`);
             const { data } = await client.PUT("/v1/datasets/{id}", {
                 params: { path: { id: datasetId } },
-                body: body,
+                body: overlay(current, { name, description, type, inputSchema, expectedOutputSchema, metadata }),
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(data, null, 2) }],