@nexusbloom/mcp-server 1.0.2 → 2.0.0

package/src/manifests.js

@@ -0,0 +1,247 @@
+/**
+ * Manifest normalisation and caching.
+ *
+ * The API's tool rows are not identical to the manifest contract: `description`
+ * and `short_description` are the same value, `tags` may arrive as a nested
+ * array from Postgres, and community tools have a `category` that built-ins do
+ * not. Everything downstream should be able to assume one shape.
+ */
+
+import { NexusBloomError, ErrorCode } from "./errors.js";
+
+/** Empty but valid — a schema saying "takes nothing" is not the same as null. */
+export function emptyInputSchema() {
+  return { type: "object", properties: {}, required: [] };
+}
+
+/**
+ * Flatten and clean a Postgres text[] column.
+ *
+ * Postgres returns `{{a,b},{c}}` for a `text[][]` column, so a naive read gives
+ * nested arrays that stringify as "a,b". One level of flattening covers every
+ * shape seen in the data.
+ */
+export function normaliseTags(tags) {
+  if (!tags) return [];
+  const flat = (Array.isArray(tags) ? tags.flat(Infinity) : [tags])
+    .filter((t) => typeof t === "string")
+    .map((t) => t.trim().toLowerCase())
+    .filter(Boolean);
+  return [...new Set(flat)];
+}
+
+/**
+ * Coerce one API row into the canonical manifest shape.
+ *
+ * Returns null for anything without a usable slug: a tool that cannot be named
+ * cannot be called, and letting it through would surface as a tool the agent
+ * sees in the list but can never invoke.
+ */
+export function normaliseTool(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const slug = typeof raw.slug === "string" ? raw.slug.trim() : "";
+  if (!slug) return null;
+
+  const description = (raw.short_description || raw.description || "").trim();
+
+  return {
+    slug,
+    name: (raw.name || slug).trim(),
+    short_description: description,
+    // Kept alongside because MCP's ListTools description is the agent's only
+    // disambiguator when two tools have similar names.
+    description,
+    category: raw.category || raw.tool_type || "uncategorized",
+    runtime: raw.runtime || "both",
+    version: raw.version || "1.0.0",
+    icon: raw.icon || "🔧",
+    type: ["builtin", "community", "local"].includes(raw.type) ? raw.type : "tool",
+    price_type: raw.price_type || "free",
+    pricing: raw.pricing || null,
+    timeout_ms: typeof raw.timeout_ms === "number" ? raw.timeout_ms : null,
+    tags: normaliseTags(raw.tags),
+    input_schema: normaliseSchema(raw.input_schema),
+    output_schema: normaliseSchema(raw.output_schema, { allowNull: true }),
+    // Distinguishes "published with no schema" from "genuinely takes no
+    // parameters". Normalisation erases the difference — both become an empty
+    // object — but an agent needs to know which one it is, because the first
+    // means call `schema` before trying and the second means just call it.
+    hasSchema: isSchemaPresent(raw.input_schema),
+  };
+}
+
+/**
+ * Was a schema actually declared by the publisher?
+ *
+ * Distinct from "does it have properties": a tool may legitimately declare
+ * `{type:"object", properties:{}, required:[]}` to mean it takes nothing, which
+ * is different from having no `input_schema` at all. Only the latter is unknown.
+ */
+function isSchemaPresent(schema) {
+  return Boolean(schema) && typeof schema === "object" && !Array.isArray(schema);
+}
+
+/**
+ * Coerce a stored schema into one a strict MCP client will accept.
+ *
+ * Schemas in the database predate the current contract, so some are missing
+ * `type: "object"` or carry a `required` that is not an array. Forwarding those
+ * verbatim makes the host reject the whole tool list.
+ */
+export function normaliseSchema(schema, { allowNull = false } = {}) {
+  if (schema === null || schema === undefined) {
+    return allowNull ? null : emptyInputSchema();
+  }
+  if (typeof schema !== "object" || Array.isArray(schema)) {
+    return allowNull ? null : emptyInputSchema();
+  }
+  if (schema.type !== "object") {
+    // A schema missing `type: "object"` is rejected by strict MCP clients, so
+    // normalise rather than forward it.
+    return {
+      ...schema,
+      type: "object",
+      properties: schema.properties && typeof schema.properties === "object" ? schema.properties : {},
+      required: Array.isArray(schema.required) ? schema.required : [],
+    };
+  }
+  return {
+    ...schema,
+    properties: schema.properties && typeof schema.properties === "object" ? schema.properties : {},
+    required: Array.isArray(schema.required) ? schema.required : [],
+  };
+}
+
+/**
+ * Unwrap the several shapes an API list endpoint may return.
+ *
+ * The response has been `{tools:[…]}`, `{data:{tools:[…]}}` and a bare array at
+ * different points in its history; clients pinning an old version see all three
+ * depending on deployment.
+ */
+export function unwrapToolsList(body) {
+  const candidates = [
+    body,
+    body?.tools,
+    body?.data,
+    body?.data?.tools,
+    body?.results,
+  ];
+  for (const c of candidates) {
+    if (Array.isArray(c)) return c.filter(Boolean);
+  }
+  return [];
+}
+
+/**
+ * Unwrap a manifest out of `{success,data:{manifest}}`, `{manifest}` or bare.
+ *
+ * Returns null for an object that carries no recognisable manifest. Without the
+ * last check, a `{success:true,data:{}}` response unwraps to `{}` — truthy, so
+ * the caller would fabricate a tool from an empty object and report a schema
+ * that the publisher never declared.
+ */
+export function unwrapManifest(body) {
+  const candidates = [body?.data?.manifest, body?.manifest, body?.data, body];
+  for (const m of candidates) {
+    if (m && typeof m === "object" && !Array.isArray(m) && hasManifestFields(m)) return m;
+  }
+  return null;
+}
+
+/** Any of the keys that make an object recognisable as a tool manifest. */
+function hasManifestFields(o) {
+  return (
+    "slug" in o ||
+    "input_schema" in o ||
+    "output_schema" in o ||
+    "short_description" in o ||
+    "tool_type" in o
+  );
+}
+
+/**
+ * TTL cache for the tool list.
+ *
+ * The list is re-fetched on every TTL expiry rather than on a timer, so an idle
+ * server makes no requests at all. A failed refresh keeps serving the stale list
+ * rather than emptying it — an agent discovering zero tools because one blip
+ * occurred is worse than an agent seeing slightly old metadata.
+ */
+export class ManifestCache {
+  constructor(client, { ttlMs, now = () => Date.now() } = {}) {
+    this.client = client;
+    this.ttlMs = ttlMs;
+    this.now = now;
+    this._tools = null;
+    this._cachedAt = 0;
+    this._inflight = null;
+  }
+
+  /** True when a cached list exists and has not expired. */
+  isFresh() {
+    return this._tools !== null && this.now() - this._cachedAt < this.ttlMs;
+  }
+
+  /**
+   * Return the tool list, refreshing if stale.
+   *
+   * Concurrent callers share one in-flight request; without that, N agents
+   * starting at once produce N identical catalogue fetches.
+   */
+  async tools({ force = false } = {}) {
+    if (!force && this.isFresh()) return this._tools;
+    if (this._inflight) return this._inflight;
+
+    this._inflight = this._refresh().finally(() => {
+      this._inflight = null;
+    });
+    return this._inflight;
+  }
+
+  async _refresh() {
+    try {
+      const body = await this.client.request("/tools");
+      const tools = unwrapToolsList(body).map(normaliseTool).filter(Boolean);
+
+      // An empty list from a live API is almost always a failure upstream, and
+      // overwriting a good cache with it would strand every agent. Keep the old
+      // value and let the caller see an empty result with a clear reason.
+      if (tools.length === 0 && this._tools) {
+        this._cachedAt = this.now();
+        return this._tools;
+      }
+
+      this._tools = tools;
+      this._cachedAt = this.now();
+      return tools;
+    } catch (err) {
+      if (this._tools) {
+        this._cachedAt = this.now();
+        return this._tools;
+      }
+      throw err instanceof NexusBloomError
+        ? err
+        : new NexusBloomError(err.message, ErrorCode.API_ERROR);
+    }
+  }
+
+  /** Fetch one tool's full manifest, bypassing the list cache. */
+  async manifest(slug) {
+    const body = await this.client.request(`/run/${encodeURIComponent(slug)}`);
+    const manifest = unwrapManifest(body);
+    if (!manifest) {
+      throw new NexusBloomError(
+        `Tool "${slug}" returned no manifest from the API.`,
+        ErrorCode.NOT_FOUND,
+      );
+    }
+    return normaliseTool(manifest) || normaliseTool({ slug, ...manifest });
+  }
+
+  /** Drop cached state; used by tests and the `refresh` meta-command. */
+  clear() {
+    this._tools = null;
+    this._cachedAt = 0;
+  }
+}

package/src/render.js

@@ -0,0 +1,348 @@
+/**
+ * Response rendering — the part of the server an agent actually reads.
+ *
+ * Design rules, in priority order:
+ *
+ * 1. **A tool that cannot be called is a defect.** Every schema response states
+ *    the exact arguments to pass, in a copy-pasteable form. An agent should
+ *    never have to assemble a call by reading a JSON Schema.
+ * 2. **Errors carry a next action.** "Tool not found" is a dead end; "no tool
+ *    named `env-validatr`. Did you mean: env-validator" is recoverable.
+ * 3. **Output first.** The result leads, with framing kept to two lines. Agents
+ *    parse the payload, not prose.
+ * 4. **Machine-readable is always attached.** The text block is optimised for
+ *    reading; a structured block carries the same data for extraction.
+ */
+
+import { describeParameters, groupByCategory } from "./discovery.js";
+import { ErrorCode } from "./errors.js";
+import { normaliseTool } from "./manifests.js";
+
+/**
+ * Build an MCP response.
+ *
+ * Always a text block, because that is what a model reads. A resource block is
+ * appended when there is structured data, so an agent that prefers extraction
+ * over prose gets an exact payload instead of parsing markdown.
+ */
+export function respond(payload) {
+  const content = [{ type: "text", text: payload.text }];
+  if (payload.data !== undefined) {
+    content.push({
+      type: "resource",
+      resource: {
+        uri: "data:application/json,",
+        mimeType: "application/json",
+        text: safeStringify(payload.data),
+      },
+    });
+  }
+  return { content };
+}
+
+/** Error response. Never throws — the agent gets a value it can branch on. */
+export function respondError(err) {
+  const message = err?.message || String(err) || "Unknown error.";
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+    structuredContent:
+      typeof err?.toJSON === "function"
+        ? err.toJSON()
+        : { success: false, error: message, code: err?.code || ErrorCode.API_ERROR, retryable: false },
+  };
+}
+
+/**
+ * How many required parameters a tool has, or -1 when it has no schema at all.
+ *
+ * The three-way result matters: "no parameters" and "parameters I can't see" are
+ * different situations for an agent, and conflating them would present an
+ * unknown schema as a tool that takes nothing.
+ */
+export function requiredCount(tool) {
+  const schema = tool?.input_schema;
+  const required = Array.isArray(schema?.required) ? schema.required.length : 0;
+  if (required > 0) return required;
+
+  // No required fields, but the schema may simply be absent — normaliseTool
+  // records which, so a tool with no published schema is not mislabelled as a
+  // tool that takes nothing.
+  return tool?.hasSchema === false ? -1 : 0;
+}
+
+/**
+ * The catalogue.
+ *
+ * With 30+ tools a flat dump is unusable in a context window, so this lists a
+ * compact one-line-per-tool summary and points at `search` for anything narrower.
+ */
+export function renderToolList(tools, { total } = {}) {
+  const count = total ?? tools.length;
+  if (count === 0) {
+    return {
+      text:
+        `# NexusBloom Tools\n\nNo tools are currently published.\n\n` +
+        `This usually means the API is unreachable or the catalogue is empty. ` +
+        `Check that NEXUSBLOOM_API_URL points at a working deployment.`,
+      data: { tools: [], count: 0 },
+    };
+  }
+
+  const lines = tools.map((t) => {
+    const req = requiredCount(t);    const input =
+      req > 0 ? `${req} required` : req === 0 ? "no required" : "schema unknown";
+    const tags = t.tags?.length ? ` · ${t.tags.slice(0, 3).join(", ")}` : "";
+    return `- **${t.name}** (\`${t.slug}\`) — ${t.short_description || "No description"} · ${input}${tags}`;
+  });
+
+  const text =
+    `# NexusBloom Tools\n\n` +
+    `${count} tool${count === 1 ? "" : "s"} available.\n\n${lines.join("\n")}\n\n` +
+    `---\n` +
+    `Next steps:\n` +
+    `• Need something specific? Call \`nexusbloom\` with \`{"command":"search","query":"what you need"}\` — it ranks by relevance.\n` +
+    `• Before running a tool, call \`{"command":"schema","slug":"<slug>"}\` to get its exact parameters.\n` +
+    `• To run: call the tool by its slug directly, e.g. \`{"name":"${tools[0].slug}","arguments":{…}}\`.`;
+
+  return { text, data: { tools, count } };
+}
+
+/**
+ * Search results.
+ *
+ * Explains the query when nothing matched — an empty list with no reason is
+ * indistinguishable from a broken server.
+ */
+export function renderSearchResults(query, tools, catalogueSize, categories = []) {
+  if (tools.length === 0) {
+    const categoryHint = categories.length
+      ? `\n• A category name: ${categories.slice(0, 8).join(", ")}`
+      : "";
+    return {
+      text:
+        `# No tools match "${query}"\n\n` +
+        `${catalogueSize} tools are published, none matching that query. Try:\n` +
+        `• Fewer or more general words — e.g. "validate" rather than "validate my dotenv file in production"` +
+        `${categoryHint}\n` +
+        `• \`{"command":"list"}\` to see everything.`,
+      data: { query, tools: [], count: 0 },
+    };
+  }
+
+  const lines = tools.map(
+    (t) => `- **${t.name}** (\`${t.slug}\`) — ${t.short_description || "No description"}`,
+  );
+
+  const text =
+    `# Tools matching "${query}"\n\n` +
+    `${tools.length} of ${catalogueSize} tools.\n\n${lines.join("\n")}\n\n` +
+    `Call \`{"command":"schema","slug":"<slug>"}\` for parameters, or invoke the tool directly by slug.`;
+
+  return { text, data: { query, tools, count: tools.length } };
+}
+
+/**
+ * A tool's full contract.
+ *
+ * The example invocation at the end is the load-bearing part: it is valid JSON
+ * containing every required parameter with a placeholder, so an agent can call
+ * it back by changing only the values.
+ */
+export function renderSchema(rawSchema, tools = []) {
+  // Defensive normalisation: a caller may hand over a bare object rather than a
+  // normalised tool, and a missing name must read as a fallback, never as the
+  // literal string "undefined".
+  const schema = normaliseTool({ slug: "tool", ...rawSchema }) || normaliseTool({ slug: "tool" });
+
+  const params = describeParameters(schema.input_schema);
+  const required = params.filter((p) => p.required);
+
+  const paramLines = params.length
+    ? params
+        .map((p) => {
+          const detail = p.description ? ` — ${p.description}` : "";
+          return `- \`${p.name}\` (${p.summary || "any"})${detail}`;
+        })
+        .join("\n")
+    : "_This tool takes no parameters._";
+
+  const exampleArgs = buildExampleArgs(schema);
+
+  let example;
+  if (params.length === 0) {
+    example = `Call it with no arguments:\n\`\`\`json\n{"name": "${schema.slug}", "arguments": {}}\n\`\`\``;
+  } else if (required.length === 0) {
+    example =
+      `Only optional parameters exist, so \`{}\` is valid:\n` +
+      `\`\`\`json\n{"name": "${schema.slug}", "arguments": {}}\n\`\`\``;
+  } else {
+    example =
+      `Replace the placeholder values, then call:\n` +
+      `\`\`\`json\n{"name": "${schema.slug}", "arguments": ${JSON.stringify(exampleArgs, null, 2)}}\n\`\`\``;
+  }
+
+  const outputNote = schema.output_schema
+    ? `\n**Returns:** shaped per \`output_schema\` (${describeOutputShape(schema.output_schema)}).`
+    : "";
+
+  const priceNote =
+    schema.price_type && schema.price_type !== "free"
+      ? `\n**Pricing:** ${schema.price_type} — this tool may consume API quota.`
+      : "";
+
+  const related = suggestRelated(tools, schema);
+
+  const meta = [
+    `**Slug:** \`${schema.slug}\``,
+    `**Category:** ${schema.category}`,
+    `**Runtime:** ${schema.runtime}`,
+    schema.short_description ? `**Description:** ${schema.short_description}` : null,
+    schema.tags?.length ? `**Tags:** ${schema.tags.join(", ")}` : null,
+  ].filter(Boolean);
+
+  const text =
+    `# ${schema.icon} ${schema.name}\n\n` +
+    `${meta.join("\n")}\n${outputNote}${priceNote}\n` +
+    `\n## Parameters\n\n${paramLines}\n` +
+    (required.length ? `\nRequired: ${required.map((r) => `\`${r.name}\``).join(", ")}\n` : "") +
+    `\n## How to call it\n\n${example}` +
+    (related ? `\n\n## Related\n\n${related}` : "");
+
+  return { text, data: schema };
+}
+
+/** Describe an output schema's top-level shape in one clause. */
+function describeOutputShape(schema) {
+  const props = schema?.properties || {};
+  const keys = Object.keys(props);
+  if (keys.length === 0) return "no documented fields";
+  if (keys.length <= 4) return keys.map((k) => `\`${k}\``).join(", ");
+  return `${keys.slice(0, 4).map((k) => `\`${k}\``).join(", ")} +${keys.length - 4} more`;
+}
+
+/** Other tools sharing tags or category, so an agent can compose. */
+function suggestRelated(tools, schema) {
+  const tags = new Set(schema.tags || []);
+  const others = tools.filter((t) => t.slug !== schema.slug);
+  const byTag = others.filter((t) => (t.tags || []).some((tag) => tags.has(tag)));
+  const pool = (byTag.length ? byTag : others.filter((t) => t.category === schema.category))
+    .slice(0, 4);
+  if (!pool.length) return null;
+  return pool.map((t) => `- \`${t.slug}\` — ${t.short_description || t.name}`).join("\n");
+}
+
+/**
+ * Build a valid example argument object from a schema.
+ *
+ * Required parameters get a placeholder derived from their declared type — a
+ * string gets "string", a number gets 0, and so on — because a placeholder the
+ * agent can recognise and replace is worth more than one it has to guess the
+ * type of. Returns null when the tool requires nothing.
+ */
+export function buildExampleArgs(schema) {
+  const inputSchema = schema?.input_schema;
+  const properties = inputSchema?.properties || {};
+  const required = inputSchema?.required || [];
+  if (required.length === 0) return {};
+
+  const args = {};
+  for (const key of required) {
+    const prop = properties[key] || {};
+    args[key] = placeholderFor(prop);
+  }
+  return args;
+}
+
+function placeholderFor(prop) {
+  if (prop.enum?.length) return prop.enum[0];
+  const t = Array.isArray(prop.type) ? prop.type[0] : prop.type;
+  switch (t) {
+    case "string":
+      return prop.format === "date-time" ? "2026-01-01T00:00:00Z" : "string";
+    case "integer":
+      return 0;
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    case "array":
+      return [];
+    case "object":
+      return {};
+    default:
+      return null;
+  }
+}
+
+/**
+ * A successful execution result.
+ *
+ * The payload is fenced as JSON and unindented-by-default is avoided: agents
+ * re-read it, and deeply indented JSON costs tokens on every turn. Kept at 2
+ * spaces because it is far easier to diff and reason about.
+ */
+export function renderResult(slug, data, { durationMs, execution = "remote" } = {}) {
+  const json = safeStringify(data);
+  const meta = [`Tool: \`${slug}\``, `Execution: ${execution}`];
+  if (typeof durationMs === "number") meta.push(`Duration: ${durationMs}ms`);
+
+  return {
+    text: `# Result: ${slug}\n\n${meta.join(" · ")}\n\n\`\`\`json\n${json}\n\`\`\``,
+    data,
+  };
+}
+
+/** A failure that still succeeded as a call — a tool returning `{error:…}`. */
+export function renderToolReportedError(slug, data) {
+  const message =
+    data?.error || data?.message || "The tool reported an error.";
+  const code = data?.code ? ` (${data.code})` : "";
+  return {
+    text:
+      `# ${slug} reported an error${code}\n\n${message}\n\n` +
+      `This is the tool's own response, not a transport failure. The tool ran; check its parameters and try again.`,
+    data,
+  };
+}
+
+function safeStringify(value) {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Startup diagnostics. Always stderr — never part of an MCP response. */
+export function renderConnectivityReport({ connected, roots, apiBase, anonymous, errors }) {
+  const lines = [];
+  if (connected) {
+    lines.push(`NexusBloom MCP server connected to ${connected}`);
+  } else {
+    lines.push("WARNING: could not reach the NexusBloom API. Starting in degraded mode.");
+    lines.push("Tool discovery and execution will fail until this is fixed.");
+    lines.push("");
+    lines.push("Checked:");
+    for (const r of roots) lines.push(`  - ${r}/tools`);
+    if (errors?.length) {
+      lines.push("");
+      lines.push("Errors:");
+      for (const e of errors) lines.push(`  - ${e}`);
+    }
+    lines.push("");
+    lines.push(
+      `To fix: set NEXUSBLOOM_API_URL to a reachable deployment ` +
+        `(currently "${apiBase}"), or check the API is deployed.`,
+    );
+  }
+  if (anonymous) {
+    lines.push("");
+    lines.push("No NEXUSBLOOM_API_KEY set — running anonymously under the free-tier rate limit.");
+    lines.push("Set NEXUSBLOOM_API_KEY for authenticated execution and higher limits.");
+  }
+  lines.push(`API base: ${apiBase}`);
+  return lines.join("\n");
+}
+
+export { ErrorCode };

package/src/server.js

@@ -0,0 +1,83 @@
+/**
+ * MCP SDK adapter.
+ *
+ * Deliberately thin: it translates JSON-RPC into calls on the handler set and
+ * nothing else. All behaviour lives in handlers.js where it can be tested
+ * without a transport, so this file is the only place the SDK is imported.
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+import { buildToolList, createHandlers } from "./handlers.js";
+
+export const SERVER_NAME = "nexusbloom-mcp";
+export const SERVER_VERSION = "2.0.0";
+
+/**
+ * Wire a handler set onto an MCP Server.
+ *
+ * @param {object} deps { client, cache, config }
+ * @param {object} [deps.handlers]  Prebuilt handler set. Supplying one is the
+ *   seam that lets the error-containment path be tested directly.
+ * @returns {{server: Server, handlers: object}}
+ */
+export function createServer({ client, cache, config, handlers: provided }) {
+  const handlers = provided ?? createHandlers({ client, cache, config });
+  const listTools = provided ? buildToolList(cache) : handlers.listTools;
+
+  const server = new Server(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { capabilities: { tools: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => listTools());
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name: toolName, arguments: args } = request.params ?? {};
+
+    // No handler may throw: an exception here becomes a JSON-RPC protocol error,
+    // which a model cannot recover from, whereas an isError result is a normal
+    // tool outcome it can reason about.
+    try {
+      if (!toolName) {
+        return {
+          content: [{ type: "text", text: "No tool name was provided in the request." }],
+          isError: true,
+        };
+      }
+      return toolName === "nexusbloom"
+        ? await handlers.meta(args ?? {})
+        : await handlers.callDirect(toolName, args ?? {});
+    } catch (err) {
+      return handlers.handleError ? handlers.handleError(err) : fallbackError(err);
+    }
+  });
+
+  return { server, handlers };
+}
+
+/**
+ * Last-resort error shape.
+ *
+ * `createHandlers` always supplies `handleError`, so this only runs if a future
+ * caller wires up a partial handler set. It exists because an uncaught throw at
+ * this boundary becomes a JSON-RPC protocol error, which a model cannot recover
+ * from — strictly worse than a value it can read.
+ */
+export function fallbackError(err) {
+  const message = err?.message || "Unknown error.";
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+    structuredContent: {
+      success: false,
+      error: message,
+      code: err?.code || "API_ERROR",
+      retryable: err?.retryable ?? false,
+    },
+  };
+}