@stigmer/mcp-server 3.5.3 → 3.7.0

package/src/domains/channels/errors.ts

@@ -0,0 +1,94 @@
+// The channels-domain error mapper — the records-domain sibling
+// (DD-004 S-7's recorded posture: siblings share the idiom, never an
+// abstraction over it; each domain documents its own contract).
+//
+// Channel-messaging domain errors carry agent-relayable messages that
+// are contract bytes (proactive-messaging DD-002 D4's error table):
+// "this agent has no proactive-messaging channel it can use", "channel
+// is required: this agent serves multiple proactive-enabled channels:
+// …", the OSS "proactive channel messaging requires Stigmer Cloud".
+// The shared ../rpcerr.ts would rewrite them into transport advice and
+// discard google.rpc.ErrorInfo; here the domain codes pass the server's
+// message through VERBATIM as isError JSON `{error, code, reason}` so
+// the model can self-correct (name the channel on INVALID_ARGUMENT;
+// stop and relay on PERMISSION_DENIED). Transport codes still delegate
+// to the shared helper, whose advice is right for them.
+//
+// Typed send outcomes (accepted/queued/refused) never reach this file:
+// they are successful responses by design (DD-002 D4 — policy refusals
+// are answers, not errors).
+
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { ErrorInfoSchema } from "@stigmer/protos/google/rpc/error_details_pb";
+import { rpcError } from "../rpcerr.js";
+import { errorResult, textResult } from "../toolresult.js";
+
+/**
+ * The gRPC codes whose messages are the channel-messaging domain
+ * contract: reach denials (PERMISSION_DENIED, one fail-closed text per
+ * failure class), contract misuse with corrective copy
+ * (INVALID_ARGUMENT — ambiguous channel, ambiguous template language),
+ * and actionable preconditions (FAILED_PRECONDITION — the OSS refusal,
+ * not-installed, registry misconfiguration with its ErrorInfo reason).
+ */
+const DOMAIN_CODES: ReadonlySet<Code> = new Set([
+  Code.PermissionDenied,
+  Code.InvalidArgument,
+  Code.FailedPrecondition,
+]);
+
+/** The structured error payload channel tools return for domain errors. */
+export interface ChannelToolError {
+  /** The server's relayable message, byte-for-byte. */
+  error: string;
+  /** gRPC status name in SCREAMING_SNAKE (e.g. PERMISSION_DENIED). */
+  code: string;
+  /** ErrorInfo reason (e.g. WHATSAPP_MANAGEMENT_SCOPE_MISSING), when present. */
+  reason?: string;
+}
+
+/**
+ * Run a channel-tool body: a string payload becomes a text result; a
+ * domain error becomes an isError JSON result carrying the verbatim
+ * message + ErrorInfo reason; a transport error delegates to the shared
+ * classifier. The only try/catch in this domain.
+ */
+export async function channelResult(
+  toolContext: string,
+  produce: () => Promise<string>,
+): Promise<CallToolResult> {
+  try {
+    return textResult(await produce());
+  } catch (err) {
+    const ce = ConnectError.from(err);
+    if (DOMAIN_CODES.has(ce.code)) {
+      return {
+        content: [{ type: "text", text: JSON.stringify(domainError(ce)) }],
+        isError: true,
+      };
+    }
+    return errorResult(rpcError(ce, toolContext));
+  }
+}
+
+/** Project a domain ConnectError into the structured tool payload. */
+export function domainError(ce: ConnectError): ChannelToolError {
+  const payload: ChannelToolError = {
+    error: ce.rawMessage,
+    code: grpcStatusName(ce.code),
+  };
+  // The messaging RPCs attach google.rpc.ErrorInfo to operator-actionable
+  // preconditions (DD-005 D8); absence means the message alone carries
+  // the contract.
+  const details = ce.findDetails(ErrorInfoSchema);
+  if (details.length > 0 && details[0].reason !== "") {
+    payload.reason = details[0].reason;
+  }
+  return payload;
+}
+
+/** Connect's PascalCase code name → the gRPC SCREAMING_SNAKE status name. */
+function grpcStatusName(code: Code): string {
+  return Code[code].replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+}

package/src/domains/channels/tools.ts

@@ -0,0 +1,116 @@
+// The send_channel_message tool — the ONE tool of the channels roster
+// (proactive-messaging DD-002 D7, arguments amended by DD-006 D5 to
+// mirror the ChannelOutboundPayload oneof: `text` | `template`, exactly
+// one).
+//
+// Agent audience only, by construction: this roster is what the
+// runner-synthesized channel attachment connects to, and a session-bound
+// caller's org derives from its token (an explicit org is rejected —
+// the records T05 R3 rule), so no `org` argument exists to invite
+// rejected calls. A direct-audience variant on the full roster is
+// deliberately NOT registered: operators send through the console, CLI,
+// and SDK, which carry the org+channel addressing the direct reach path
+// requires.
+//
+// The typed outcome is the tool's answer, verbatim proto JSON:
+// `accepted` (delivered to the provider), `queued` (transient failure —
+// the platform retries in the background; do NOT resend), `refused`
+// (terminal; `detail` says why — adapt, never retry the same send).
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { resolveToken, type BackendTarget } from "../client.js";
+import { sendChannelMessage, type TemplateArg } from "./calls.js";
+import { channelResult } from "./errors.js";
+import { errorResult } from "../toolresult.js";
+
+const templateShape = z.object({
+  name: z.string().describe("Approved template name on the channel's provider registry."),
+  language: z
+    .string()
+    .optional()
+    .describe(
+      "Template language code (e.g. en, en_US). Omit when the template exists in exactly one language.",
+    ),
+  parameters: z
+    .record(z.string())
+    .optional()
+    .describe(
+      'Placeholder values. Positional templates key by position ("1", "2", …); ' +
+        'named templates key by parameter name ("member_name").',
+    ),
+  header_image_link: z
+    .string()
+    .optional()
+    .describe(
+      "Public HTTPS URL for the image header. Required exactly when the template " +
+        "declares an image header.",
+    ),
+});
+
+/** Register the channel messaging tool; returns the tool names. */
+export function registerChannelTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "send_channel_message",
+    {
+      description:
+        "Send a business-initiated message to a recipient on this agent's messaging channel " +
+        "(e.g. WhatsApp). Exactly one of text | template. Outside a 24-hour customer-service " +
+        "window the provider only accepts a pre-approved template, so prefer a template from " +
+        "<available_channel_templates>. The result carries a typed outcome: accepted (sent), " +
+        "queued (the platform retries in the background — do not resend), or refused " +
+        "(terminal; detail says why — adapt, never retry the same send).",
+      inputSchema: {
+        recipient: z
+          .string()
+          .describe(
+            "Recipient's key on the channel's provider, passed to the provider verbatim. " +
+              'WhatsApp: the wa_id — digits only INCLUDING the country code, no "+" or ' +
+              'separators (e.g. "919912850490"). Never reformat a wa_id another tool returned.',
+          ),
+        text: z
+          .string()
+          .optional()
+          .describe(
+            "Plain text body. Only deliverable inside an open 24-hour customer-service window.",
+          ),
+        template: templateShape
+          .optional()
+          .describe("Pre-approved template send — required outside a 24-hour window."),
+        channel: z
+          .string()
+          .optional()
+          .describe(
+            "Channel slug. Only needed when this agent serves more than one " +
+              "proactive-messaging channel (a refusal will list them).",
+          ),
+      },
+    },
+    (args, extra) => {
+      // Exactly-one, checked here with corrective copy the model can act
+      // on immediately; the server's required-oneof validation is the
+      // backstop (DD-006 D5).
+      const hasText = args.text !== undefined && args.text !== "";
+      const hasTemplate = args.template !== undefined;
+      if (hasText === hasTemplate) {
+        return Promise.resolve(errorResult(
+          hasText
+            ? "supply exactly one of text | template, not both"
+            : "supply exactly one of text | template — text for an open 24-hour window, " +
+              "template otherwise",
+        ));
+      }
+      return channelResult(`message to "${args.recipient}"`, () =>
+        sendChannelMessage(target.serverAddress, resolveToken(extra, target.apiKey), {
+          recipient: args.recipient,
+          text: args.text,
+          template: args.template as TemplateArg | undefined,
+          channel: args.channel,
+        }),
+      );
+    },
+  );
+
+  return ["send_channel_message"];
+}

package/src/domains/conversation/calls.ts

@@ -0,0 +1,41 @@
+// Conversation RPC invocations for the escalate_to_human tool — a 1:1
+// projection of ChannelConversationCommandController.escalate
+// (channel-conversations DD-008: the tool layer adds no semantics; the
+// reach, the idempotent writer, and the attention projection all live
+// in the cloud handler, and the OSS edition refuses with the documented
+// FAILED_PRECONDITION).
+//
+// The channels-domain calls.ts shape, with one deliberate divergence:
+// the RPC's ChannelConversation response is DISCARDED instead of
+// marshaled back as proto JSON. A15 rules the tool's answer is fixed
+// behavioral copy (tools.ts owns it) — the row's control state,
+// timestamps, and conversation key give the model nothing actionable,
+// and reflecting them would only invite the model to narrate internal
+// state to the customer.
+
+import { create } from "@bufbuild/protobuf";
+import {
+  ChannelConversationCommandController,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_command_pb";
+import {
+  EscalateConversationInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { withClient } from "../client.js";
+
+/**
+ * Flag the calling session's conversation for human attention. The input
+ * carries only the reason: the conversation identity derives server-side
+ * from the session-scoped credential's channel labels (the DD-003
+ * identity doctrine), so there is nothing else a caller could
+ * legitimately send.
+ */
+export async function escalateConversation(
+  serverAddress: string,
+  token: string,
+  reason: string,
+): Promise<void> {
+  const request = create(EscalateConversationInputSchema, { reason });
+  await withClient(ChannelConversationCommandController, serverAddress, token,
+    (client, opts) => client.escalate(request, opts),
+  );
+}

package/src/domains/conversation/conversation.integration.test.ts

@@ -0,0 +1,233 @@
+// In-process integration test for the conversation roster (the
+// channels.integration.test.ts pattern: real Connect backend with a
+// stubbed conversation service, real MCP client over an in-memory
+// transport).
+//
+// Verifies the DD-008 D-b / A14 / A15 contract surface:
+//   - the conversation-only roster is exactly escalate_to_human with a
+//     single `reason` argument (agent audience — identity is
+//     server-derived, so nothing else exists to send);
+//   - the success answer is the A15 fixed copy, never the RPC's
+//     ChannelConversation row, and claims nothing the platform cannot
+//     keep (no console claim until the T04+ surface renders attention);
+//   - the conversation-own error mapper passes domain messages verbatim
+//     as {error, code} JSON — including NOT_FOUND, this domain's
+//     deliberate addition — while transport errors delegate to the
+//     shared classifier;
+//   - the zod bounds mirror the protovalidate constraints, refusing an
+//     empty or over-budget reason before any RPC.
+
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError, type ConnectRouter } from "@connectrpc/connect";
+import { connectNodeAdapter } from "@connectrpc/connect-node";
+import {
+  createServer as createHttp2Server,
+  type Http2Server,
+  type ServerHttp2Session,
+} from "node:http2";
+import type { AddressInfo } from "node:net";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { ChannelConversationCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_command_pb";
+import {
+  ChannelConversationSchema,
+  type EscalateConversationInput,
+} from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/conversation_io_pb";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { configureLogger } from "../../logger";
+import { CONVERSATION_ROUTE, createConversationServer } from "../../server";
+
+configureLogger({ level: "error", format: "text" });
+
+let backend: Http2Server;
+let client: Client;
+const openSessions = new Set<ServerHttp2Session>();
+
+/** The next stubbed outcome; tests set this. */
+let escalateResponse: () => ReturnType<typeof create<typeof ChannelConversationSchema>>;
+
+/** Requests the stub captured (object property for closure narrowing). */
+const captured: { escalate?: EscalateConversationInput } = {};
+
+interface ToolResult {
+  content: Array<{ type: string; text?: string }>;
+  isError?: boolean;
+}
+
+async function escalate(args: Record<string, unknown>): Promise<ToolResult> {
+  return (await client.callTool({
+    name: "escalate_to_human",
+    arguments: args,
+  })) as ToolResult;
+}
+
+beforeAll(async () => {
+  const routes = (router: ConnectRouter) => {
+    router.service(ChannelConversationCommandController, {
+      escalate: (req) => {
+        captured.escalate = req;
+        return escalateResponse();
+      },
+    });
+  };
+  backend = createHttp2Server(connectNodeAdapter({ routes }));
+  backend.on("session", (session) => {
+    openSessions.add(session);
+    session.on("close", () => openSessions.delete(session));
+  });
+  await new Promise<void>((resolve) => backend.listen(0, "127.0.0.1", resolve));
+  const port = (backend.address() as AddressInfo).port;
+
+  const mcp = createConversationServer({ serverAddress: `127.0.0.1:${port}`, apiKey: "" });
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  client = new Client({ name: "conversation-integration", version: "test" });
+  await Promise.all([mcp.connect(serverTransport), client.connect(clientTransport)]);
+});
+
+afterAll(async () => {
+  await client?.close();
+  for (const session of openSessions) session.destroy();
+  await new Promise<void>((resolve) => backend.close(() => resolve()));
+});
+
+describe("conversation roster (DD-008 D-c / A14)", () => {
+  it("exposes exactly escalate_to_human with a single reason argument", async () => {
+    const { tools } = await client.listTools();
+    expect(tools.map((t) => t.name)).toEqual(["escalate_to_human"]);
+
+    // The conversation identity is server-derived from the session
+    // credential's channel labels (the DD-003 identity doctrine), so
+    // reason is the ONLY argument — a channel or conversation id here
+    // would be a caller-supplied identity the reach must never trust.
+    const properties = (tools[0].inputSchema as { properties?: Record<string, unknown> })
+      .properties;
+    expect(Object.keys(properties ?? {})).toEqual(["reason"]);
+  });
+
+  it("pins the cross-repo route string (the TOOL_CALL_LIMIT precedent)", () => {
+    // The runner's conversation-attachment.ts builds the URL
+    // independently (shared/conversation-attachment.ts and its route
+    // pin); a drift here strands every synthesized attachment on a 404.
+    expect(CONVERSATION_ROUTE).toBe("/conversation");
+  });
+});
+
+describe("the success answer is the A15 copy, not the row", () => {
+  it("sends the reason verbatim and answers with fixed copy", async () => {
+    escalateResponse = () =>
+      create(ChannelConversationSchema, {
+        agentChannelId: "agch_1",
+        conversationKey: "919000000001",
+        needsAttention: true,
+        attentionReason: "customer wants a refund decision",
+      });
+    captured.escalate = undefined;
+
+    const result = await escalate({ reason: "customer wants a refund decision" });
+
+    expect(result.isError).toBeFalsy();
+    const req = captured.escalate as EscalateConversationInput | undefined;
+    expect(req?.reason).toBe("customer wants a refund decision");
+
+    const text = result.content[0]?.text ?? "";
+    expect(text).toContain("recorded on this conversation");
+    // A15: the answer instructs against the promise at the moment of
+    // temptation — the model's next message to the customer.
+    expect(text).toContain("do not");
+    // The row must never leak back: its control state and conversation
+    // key are internal, and reflecting them invites the model to
+    // narrate platform state to the customer.
+    expect(text).not.toContain("919000000001");
+    expect(text).not.toContain("needs_attention");
+    // No console surface renders attention yet (T04+); the copy must
+    // not claim one. Delete this pin when the Conversations surface
+    // ships and the copy gains the claim.
+    expect(text.toLowerCase()).not.toContain("console");
+  });
+});
+
+describe("zod bounds mirror the protovalidate constraints", () => {
+  it("refuses an empty and an over-budget reason before any RPC", async () => {
+    captured.escalate = undefined;
+
+    const empty = await escalate({ reason: "" });
+    expect(empty.isError).toBe(true);
+
+    const overBudget = await escalate({ reason: "x".repeat(1025) });
+    expect(overBudget.isError).toBe(true);
+
+    expect(captured.escalate).toBeUndefined();
+  });
+});
+
+describe("conversation error mapper", () => {
+  it("passes a reach denial through verbatim — never the shared rewrite", async () => {
+    escalateResponse = () => {
+      throw new ConnectError(
+        "escalate is agent-audience only: it requires a session-scoped runner credential",
+        Code.PermissionDenied,
+      );
+    };
+
+    const result = await escalate({ reason: "needs a human" });
+
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual({
+      error: "escalate is agent-audience only: it requires a session-scoped runner credential",
+      code: "PERMISSION_DENIED",
+    });
+  });
+
+  it("passes the OSS refusal through verbatim as FAILED_PRECONDITION", async () => {
+    escalateResponse = () => {
+      throw new ConnectError(
+        "conversation participation requires Stigmer Cloud",
+        Code.FailedPrecondition,
+      );
+    };
+
+    const result = await escalate({ reason: "needs a human" });
+
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual({
+      error: "conversation participation requires Stigmer Cloud",
+      code: "FAILED_PRECONDITION",
+    });
+  });
+
+  it("passes NOT_FOUND through verbatim — this domain's deliberate addition", async () => {
+    // The shared classifier rewrites NotFound into "Verify the org and
+    // slug are correct" — advice naming arguments escalate does not
+    // take. The domain set includes NotFound so the handler's honest
+    // answer reaches the model.
+    escalateResponse = () => {
+      throw new ConnectError(
+        "no conversation with this key exists on channel agch_1",
+        Code.NotFound,
+      );
+    };
+
+    const result = await escalate({ reason: "needs a human" });
+
+    expect(result.isError).toBe(true);
+    expect(JSON.parse(result.content[0]?.text ?? "{}")).toEqual({
+      error: "no conversation with this key exists on channel agch_1",
+      code: "NOT_FOUND",
+    });
+  });
+
+  it("delegates transport codes to the shared classifier", async () => {
+    escalateResponse = () => {
+      throw new ConnectError("upstream down", Code.Unavailable);
+    };
+
+    const result = await escalate({ reason: "needs a human" });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0]?.text).toBe(
+      "Stigmer server is unavailable. Ensure it is running and reachable.",
+    );
+  });
+});

package/src/domains/conversation/errors.ts

@@ -0,0 +1,88 @@
+// The conversation-domain error mapper — the channels-domain sibling
+// (DD-004 S-7's recorded posture: siblings share the idiom, never an
+// abstraction over it; each domain documents its own contract).
+//
+// Conversation domain errors carry agent-relayable messages that are
+// contract bytes (the ChannelConversationReach refusal matrix):
+// "escalate is agent-audience only: it requires a session-scoped runner
+// credential", "conversation identity could not be verified for this
+// session", "this session is not serving a channel conversation, so
+// there is nothing to escalate", the OSS "conversation participation
+// requires Stigmer Cloud". The shared ../rpcerr.ts would rewrite them
+// into transport advice; here the domain codes pass the server's
+// message through VERBATIM as isError JSON `{error, code}` so the model
+// can stop and adapt.
+//
+// Two deliberate differences from the channels set, each this domain's
+// own contract:
+//   - NOT_FOUND is a domain code HERE: the handler's "no conversation
+//     with this key exists on channel …" is contract copy, and the
+//     shared classifier's rewrite ("Verify the org and slug are
+//     correct") names arguments escalate does not take.
+//   - No google.rpc.ErrorInfo extraction: the conversation commands
+//     attach none — the message alone carries the contract.
+
+import { Code, ConnectError } from "@connectrpc/connect";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { rpcError } from "../rpcerr.js";
+import { errorResult, textResult } from "../toolresult.js";
+
+/**
+ * The gRPC codes whose messages are the conversation domain contract:
+ * reach denials (PERMISSION_DENIED, one fail-closed text per failure
+ * class), contract misuse with corrective copy (INVALID_ARGUMENT — an
+ * empty or over-budget reason), actionable preconditions
+ * (FAILED_PRECONDITION — the OSS refusal, a session serving no channel
+ * conversation), and the absent-conversation answer (NOT_FOUND).
+ */
+const DOMAIN_CODES: ReadonlySet<Code> = new Set([
+  Code.PermissionDenied,
+  Code.InvalidArgument,
+  Code.FailedPrecondition,
+  Code.NotFound,
+]);
+
+/** The structured error payload conversation tools return for domain errors. */
+export interface ConversationToolError {
+  /** The server's relayable message, byte-for-byte. */
+  error: string;
+  /** gRPC status name in SCREAMING_SNAKE (e.g. PERMISSION_DENIED). */
+  code: string;
+}
+
+/**
+ * Run a conversation-tool body: a string payload becomes a text result;
+ * a domain error becomes an isError JSON result carrying the verbatim
+ * message; a transport error delegates to the shared classifier. The
+ * only try/catch in this domain.
+ */
+export async function conversationResult(
+  toolContext: string,
+  produce: () => Promise<string>,
+): Promise<CallToolResult> {
+  try {
+    return textResult(await produce());
+  } catch (err) {
+    const ce = ConnectError.from(err);
+    if (DOMAIN_CODES.has(ce.code)) {
+      return {
+        content: [{ type: "text", text: JSON.stringify(domainError(ce)) }],
+        isError: true,
+      };
+    }
+    return errorResult(rpcError(ce, toolContext));
+  }
+}
+
+/** Project a domain ConnectError into the structured tool payload. */
+export function domainError(ce: ConnectError): ConversationToolError {
+  return {
+    error: ce.rawMessage,
+    code: grpcStatusName(ce.code),
+  };
+}
+
+/** Connect's PascalCase code name → the gRPC SCREAMING_SNAKE status name. */
+function grpcStatusName(code: Code): string {
+  return Code[code].replace(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase();
+}

package/src/domains/conversation/tools.ts

@@ -0,0 +1,87 @@
+// The escalate_to_human tool — the ONE tool of the conversation roster
+// (channel-conversations DD-008 D-b). A14 named the roster
+// stigmer-conversation, axis-named like stigmer-channels: the
+// conditioning axis is "this session IS a live channel conversation",
+// and the notes/loop-in tools DD-008 anticipates join this roster
+// instead of earning new routes.
+//
+// Agent audience only, by construction: escalate derives the
+// conversation identity server-side from the session-scoped credential
+// (the DD-003 identity doctrine), so a direct principal is always
+// refused PERMISSION_DENIED — which is why no variant exists on the
+// full roster and why the input surface is a single `reason`.
+//
+// The tool's answer is FIXED COPY, never the RPC's ChannelConversation
+// row — a deliberate divergence from the channels roster's
+// verbatim-proto-JSON convention. A15 rules the result states only what
+// the platform can keep at 3am (attention is a stored flag; no one is
+// paged; no console surface renders it yet) and instructs the agent
+// never to promise a human or a response time.
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+import { resolveToken, type BackendTarget } from "../client.js";
+import { escalateConversation } from "./calls.js";
+import { conversationResult } from "./errors.js";
+
+const ESCALATE_DESCRIPTION = [
+  "Flag this conversation for a human teammate to look at. Use this when you " +
+    "cannot resolve the customer's request yourself: you lack the information, " +
+    "the request needs a decision you are not authorized to make, or the " +
+    "customer has asked for a person.",
+  "You keep serving the conversation after calling this. Nothing is handed " +
+    "off automatically and no one is paged. Do not tell the customer a human " +
+    "will reply, and never promise a response time.",
+  "Write the reason for a teammate who has not read the conversation. " +
+    "Calling this again with a new reason is safe; the latest reason is what " +
+    "they see.",
+].join("\n\n");
+
+/**
+ * The success answer (A15): states only recorded fact and repeats the
+ * no-promise instruction at the moment of temptation — the model's next
+ * message to the customer. Deliberately does NOT claim the flag "shows
+ * in the team's console": no console surface renders needs_attention
+ * yet (the Conversations surface is T04+); add the claim when it ships.
+ */
+export const ESCALATION_RECORDED_COPY =
+  "Flagged for human attention. Your reason was recorded on this " +
+  "conversation. Keep helping the customer as best you can, and do not " +
+  "tell the customer a human will reply or when.";
+
+/** Register the conversation participation tool; returns the tool names. */
+export function registerConversationTools(server: McpServer, target: BackendTarget): string[] {
+  server.registerTool(
+    "escalate_to_human",
+    {
+      description: ESCALATE_DESCRIPTION,
+      inputSchema: {
+        // Bounds mirror the protovalidate constraints on
+        // EscalateConversationInput.reason (conversation_io.proto:
+        // min_len 1, max_len 1024) so the model gets corrective feedback
+        // without an RPC; the server's validation is the backstop.
+        reason: z
+          .string()
+          .min(1)
+          .max(1024)
+          .describe(
+            "Why you are escalating, written for a teammate who has not read " +
+              "the conversation. Staff see it as the conversation's attention " +
+              "reason. 1-1024 characters.",
+          ),
+      },
+    },
+    (args, extra) =>
+      conversationResult("escalation", async () => {
+        await escalateConversation(
+          target.serverAddress,
+          resolveToken(extra, target.apiKey),
+          args.reason,
+        );
+        return ESCALATION_RECORDED_COPY;
+      }),
+  );
+
+  return ["escalate_to_human"];
+}