@2kw/ai-mcp-server 6.3.0-dev.36 → 6.3.0-dev.42

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

@@ -1,6 +1,6 @@
 import type { ApiClient } from "../client.js";
 import type { components } from "../generated/openapi.js";
-import type { ResponsesResult } from "./agent-run.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
@@ -48,6 +48,7 @@ export declare function planDecisions(pending: ApprovalRow[], input: DecideInput
  * 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): Promise<ResponsesResult>;
+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

@@ -1,3 +1,4 @@
+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;
@@ -105,13 +106,15 @@ export function planDecisions(pending, input, responseId) {
  * 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) {
+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,
-        input: items,
+        // 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

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

@@ -25,10 +25,28 @@ export interface PendingToolCall {
     callId: string;
     arguments: unknown;
 }
+/** 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;
-    /** Reserved for the server-side conversation mode (#656); always null until then. */
-    mode: null;
+    /** 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;
@@ -61,6 +79,7 @@ export interface ResponsesResult {
     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;

package/dist/lib/agent-run.js

@@ -3,6 +3,30 @@
  * 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.
  */
+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 = [];
@@ -105,7 +129,7 @@ export function buildRunEnvelope(result, agentRef) {
         : null;
     return {
         status,
-        mode: null,
+        mode: responseMode(result),
         agent,
         version,
         responseId,

package/dist/tools/agents.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
 import { continueWithDecisions, fetchPendingApprovals, planDecisions, resolveAgentId, splitAgentRef } from "../lib/agent-decide.js";
-import { buildRunEnvelope } from "../lib/agent-run.js";
+import { buildRunEnvelope, MODE_RULE } from "../lib/agent-run.js";
 const modelSchema = z
     .string()
     .min(1)
@@ -533,7 +533,8 @@ export function register(server, client) {
     server.tool("2kw_decide_agent_approvals", "Answer the tool approvals a paused agent run is waiting for (a 2kw_create_response envelope with status requires_approval), then continue the run. "
         + "Decide only what the user decided: show them each pending approval (tool, arguments, policy class) first and never approve on your own. "
         + "Every pending approval of the response must be decided in this one call. Pass `agent` exactly as the run was started (keep '@label' and '#model'). "
-        + "Returns the continuation's run envelope, which can pause again.", {
+        + "Returns the continuation's run envelope, which can pause again."
+        + " " + 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
@@ -548,7 +549,11 @@ export function register(server, client) {
         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 }) => {
+        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.");
@@ -557,7 +562,7 @@ export function register(server, client) {
             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 result = await continueWithDecisions(client, agentId, responseId, items, label, model, mode);
             const envelope = buildRunEnvelope(result, agent);
             return { content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }] };
         }

package/dist/tools/ai-gateway.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { formatErrorForMcp } from "../errors.js";
-import { buildRunEnvelope } from "../lib/agent-run.js";
+import { buildRunEnvelope, MODE_RULE, modeItem } from "../lib/agent-run.js";
 /**
  * The `model` value for an agent run: `agent/<ref>[@<label>]`, plus `#<model>` when the
  * request switches to another entry of the version's `models` list (#626, spec #591 §4.1).
@@ -93,7 +93,7 @@ export function register(server, client) {
         }
     });
     // ── create_response ─────────────────────────────────────────────────────
-    server.tool("2kw_create_response", "Send a request through Backbone's OpenAI-compatible OpenResponses endpoint (POST /v1/responses). Model format: 'provider/model' for a direct gateway call via `model`, or use `agent` to invoke a stored agent by id or name (optionally 'ref@label', e.g. 'support-bot@latest'). With `agent`, `agentModel` runs this one request on another model from the agent version's `models` list. With `agent`, the reply is the run envelope as JSON (status, text, tool calls, pending approvals, response id, next step) followed by the model that answered; answer a pause with 2kw_decide_agent_approvals. Always non-streaming.", {
+    server.tool("2kw_create_response", "Send a request through Backbone's OpenAI-compatible OpenResponses endpoint (POST /v1/responses). Model format: 'provider/model' for a direct gateway call via `model`, or use `agent` to invoke a stored agent by id or name (optionally 'ref@label', e.g. 'support-bot@latest'). With `agent`, `agentModel` runs this one request on another model from the agent version's `models` list. With `agent`, the reply is the run envelope as JSON (status, text, tool calls, pending approvals, response id, next step) followed by the model that answered; answer a pause with 2kw_decide_agent_approvals. Always non-streaming. " + MODE_RULE, {
         input: z.string().min(1).describe("The input text (sent as a single user message)"),
         agent: z
             .string()
@@ -109,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.");
@@ -123,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 }),
             };

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/package.json

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