@cursor/july 0.1.61 → 0.1.68

package/src/channels/github/github-channel.ts

@@ -70,7 +70,7 @@ import type {
  */
 type GitHubParsedContext = Omit<
   GitHubEventContext,
-  "github" | "thread" | "host" | "artifacts"
+  "github" | "thread" | "host" | "artifacts" | "payload"
 >;
 
 const DEFAULT_PULL_REQUEST_ACTIONS: ReadonlySet<string> = new Set([
@@ -787,6 +787,7 @@ async function handlePullRequest(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -879,6 +880,7 @@ async function handleIssueComment(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -970,6 +972,7 @@ async function handleReviewComment(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1050,6 +1053,7 @@ async function handleIssue(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1111,6 +1115,7 @@ async function handleCheckSuite(input: {
       enrichCiContext({
         bindingConfig: input.bindingConfig,
         ctx: parsed.unanchoredCtx,
+        payload: input.payload,
         installationId,
         host: input.args.host,
         artifacts: input.args.artifacts,
@@ -1137,6 +1142,7 @@ async function handleCheckSuite(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1203,6 +1209,7 @@ async function handleCheckRun(input: {
       enrichCiContext({
         bindingConfig: input.bindingConfig,
         ctx: parsed.unanchoredCtx,
+        payload: input.payload,
         installationId,
         host: input.args.host,
         artifacts: input.args.artifacts,
@@ -1229,6 +1236,7 @@ async function handleCheckRun(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1291,6 +1299,7 @@ async function handleWorkflowRun(input: {
       enrichCiContext({
         bindingConfig: input.bindingConfig,
         ctx: parsed.unanchoredCtx,
+        payload: input.payload,
         installationId,
         host: input.args.host,
         artifacts: input.args.artifacts,
@@ -1317,6 +1326,7 @@ async function handleWorkflowRun(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1389,6 +1399,7 @@ async function handleStatus(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -1463,6 +1474,7 @@ async function handleGenericEvent(input: {
   const ctx = enrichEventContext({
     bindingConfig: input.bindingConfig,
     ctx: parsed.ctx,
+    payload: input.payload,
     bindingState: binding,
     installationId,
     host: input.args.host,
@@ -2353,10 +2365,11 @@ function escapeRegExp(value: string): string {
  */
 function enrichEventContext(input: {
   bindingConfig: GitHubBindingConfig;
-  ctx: Omit<GitHubEventContext, "github" | "thread" | "host" | "artifacts"> &
+  ctx: GitHubParsedContext &
     Partial<Pick<GitHubEventContext, "github" | "thread">>;
   bindingState: GitHubBindingState;
   installationId?: number;
+  payload: unknown;
   host: HostContext;
   artifacts: ArtifactsApi;
 }): GitHubEventContext {
@@ -2366,6 +2379,7 @@ function enrichEventContext(input: {
   });
   return {
     ...input.ctx,
+    payload: input.payload,
     ...(input.installationId === undefined
       ? {}
       : { installationId: input.installationId }),
@@ -2384,6 +2398,7 @@ function enrichCiContext(input: {
   bindingConfig: GitHubBindingConfig;
   ctx: GitHubParsedContext;
   installationId?: number;
+  payload: unknown;
   host: HostContext;
   artifacts: ArtifactsApi;
 }): GitHubEventContext {
@@ -2400,6 +2415,7 @@ function enrichCiContext(input: {
     ctx: input.ctx,
     bindingState: binding,
     installationId: input.installationId,
+    payload: input.payload,
     host: input.host,
     artifacts: input.artifacts,
   });

package/src/channels/github/types.ts

@@ -320,6 +320,8 @@ export interface GitHubEventContext {
   sender?: GitHubUser;
   /** Installation id from the webhook payload, when present. */
   installationId?: number;
+  /** Verified webhook body for this delivery. */
+  payload: unknown;
   /** Authenticated GitHub helpers (`getOctokit`, `request`, `createStatus`). */
   github: GitHubHandle;
   /** Post / react on the conversation thread. */

package/src/channels/slack/channel-watch.ts

@@ -21,10 +21,11 @@ import type { SlackChannelPostsOptions, SlackMessage } from "./types.js";
 
 const CHANNEL_ID_PATTERN = /^[CG][A-Z0-9]+$/;
 
-/** Allowlist over channel ids and `#names` (names resolve lazily). */
+/** Allowlist over channel ids and `#names` (names resolve lazily), or `*`. */
 export class SlackChannelAllowlist {
   private readonly ids = new Set<string>();
   private readonly names = new Set<string>();
+  private all = false;
 
   constructor(entries: readonly string[]) {
     for (const raw of entries) {
@@ -32,7 +33,9 @@ export class SlackChannelAllowlist {
       if (entry === "") {
         continue;
       }
-      if (entry.startsWith("#")) {
+      if (entry === "*") {
+        this.all = true;
+      } else if (entry.startsWith("#")) {
         this.names.add(entry.slice(1).toLowerCase());
       } else if (CHANNEL_ID_PATTERN.test(entry)) {
         this.ids.add(entry);
@@ -44,7 +47,7 @@ export class SlackChannelAllowlist {
   }
 
   matches(channelId: string): boolean {
-    return this.ids.has(channelId);
+    return this.all || this.ids.has(channelId);
   }
 
   unresolvedNames(): string[] {

package/src/channels/slack/dispatch.ts

@@ -142,6 +142,13 @@ export interface SlackInboundDispatchDeps extends SlackContinuationProbes {
    * dropped at parse time (loop safety).
    */
   botMentionGate?: SlackBotMentionGate;
+  /**
+   * When false, do not write `assistant.threads.setStatus` on a coalesced
+   * follow-up. Defaults to `true`. Channels that report progress their own
+   * way turn this off: the chip has no owner to clear it once the default
+   * `message.completed` handler is replaced, so it lingers past the turn.
+   */
+  followUpStatus?: boolean;
   /**
    * When false, skip the built-in `eval` directive. Defaults to true when
    * `host.evals` is present.
@@ -195,6 +202,8 @@ export async function dispatchInboundMessage(args: {
   log?: SlackLog;
   eventId?: string;
   evalCommandsEnabled?: boolean;
+  /** See {@link SlackInboundDispatchDeps.followUpStatus}. Defaults to `true`. */
+  followUpStatus?: boolean;
   /**
    * cursorAccount agent display name — stripped before parsing `eval …`
    * (`OncallBuddy eval list`).
@@ -477,8 +486,9 @@ export async function dispatchInboundMessage(args: {
         event_id: args.eventId,
       }
     );
-    // Coalesce admits leave the active turn running; follow-ups drain into one
-    // boundary turn when it finishes (no mid-turn tool/hook inject).
+    // Coalesce admits leave the active turn running: the follow-up is queued
+    // for the carrier to inject at the next tool boundary, and anything it
+    // does not reach in time drains into the boundary turn instead.
     if (session.coalesced === true) {
       log.info("session busy; coalescing follow-up", {
         kind,
@@ -487,8 +497,32 @@ export async function dispatchInboundMessage(args: {
         continuation,
         event_id: args.eventId,
       });
+      // Queue it for mid-turn injection too. The carrier drains this at the
+      // running turn's next tool boundary; whatever it does not reach in time
+      // still drains into the boundary turn, deduped by sourceTs.
+      try {
+        await args.host.slackNudges?.append({
+          continuationKey: continuation,
+          sourceTs: message.ts,
+          text: media.userText,
+          ...(message.author?.userName === undefined
+            ? {}
+            : { author: message.author.userName }),
+        });
+      } catch (nudgeError) {
+        log.warn("nudge append failed", {
+          error:
+            nudgeError instanceof Error
+              ? nudgeError.message
+              : String(nudgeError),
+          continuation,
+          event_id: args.eventId,
+        });
+      }
       try {
-        await binding.thread.startTyping(FOLLOWUP_TYPING);
+        if (args.followUpStatus !== false) {
+          await binding.thread.startTyping(FOLLOWUP_TYPING);
+        }
       } catch (typingError) {
         log.error(
           `follow-up typing failed: ${
@@ -581,6 +615,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}
@@ -623,6 +658,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: deps.evalCommandsEnabled,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}
@@ -659,6 +695,7 @@ export function dispatchInboundFromEventBody(
         log,
         evalCommandsEnabled: false,
         cursorAgentName: deps.cursorAgentName,
+        followUpStatus: deps.followUpStatus,
         blockExternals: deps.blockExternals,
         ...(deps.hasContinuationSession === undefined
           ? {}

package/src/channels/slack/manifest.ts

@@ -69,6 +69,7 @@ const BOT_SCOPES = [
   "channels:history",
   "chat:write",
   "files:read",
+  "files:write",
   "groups:history",
   "im:history",
   "im:read",

package/src/channels/slack/nudge-store.ts

@@ -202,6 +202,24 @@ export class SlackNudgeStore {
     return (await this.listPending(continuationKey)).length > 0;
   }
 
+  /**
+   * How many follow-ups have reached the agent on this thread. Monotonic
+   * within a continuation, so a caller can spot a delivery by comparing two
+   * readings — unlike {@link hasUndelivered}, which races the carrier: both
+   * run at the same tool boundary, and a queued nudge drained before the
+   * first reading never looks pending at all.
+   */
+  async deliveredCount(continuationKey: string): Promise<number> {
+    if (continuationKey.trim() === "") {
+      return 0;
+    }
+    try {
+      return (await readdir(this.deliveredDir(continuationKey))).length;
+    } catch {
+      return 0;
+    }
+  }
+
   /**
    * Atomically move all pending nudges to delivered and return them.
    * Already-delivered source ts values are dropped (exactly-once).
@@ -238,6 +256,44 @@ export class SlackNudgeStore {
     return delivered;
   }
 
+  /**
+   * Settle a follow-up the caller is handling itself, so the carrier cannot
+   * inject it again. Used by the boundary drain: a follow-up the carrier did
+   * not reach becomes the next turn's prompt, and without this its pending
+   * record survives into that turn and gets injected on top of the ask it
+   * already is.
+   */
+  async markDelivered(
+    continuationKey: string,
+    sourceTs: string
+  ): Promise<void> {
+    const key = continuationKey.trim();
+    const ts = sourceTs.trim();
+    if (key === "" || ts === "") {
+      return;
+    }
+    const pending = await this.listPending(key);
+    const record = pending.find((item) => item.sourceTs === ts);
+    await mkdir(this.deliveredDir(key), { recursive: true });
+    const dest = this.deliveredPath(key, ts);
+    const tmp = `${dest}.${process.pid}.tmp`;
+    try {
+      await writeFile(
+        tmp,
+        `${JSON.stringify(record ?? { continuationKey: key, sourceTs: ts })}\n`,
+        "utf8"
+      );
+      await rename(tmp, dest);
+    } catch {
+      await rm(tmp, { force: true }).catch(() => {});
+    }
+    if (record !== undefined) {
+      await rm(join(this.pendingDir(key), `${record.id}.json`), {
+        force: true,
+      }).catch(() => {});
+    }
+  }
+
   async clear(continuationKey: string): Promise<void> {
     await rm(this.continuationDir(continuationKey), {
       recursive: true,

package/src/channels/slack/slack-channel.ts

@@ -219,6 +219,7 @@ export function slackChannel<const Name extends string = string>(
   const mentionsEnabled = engagement.mentions !== false;
   const directMessagesEnabled = engagement.directMessages !== false;
   const evalCommandsEnabled = options.evalCommands !== false;
+  const followUpStatus = options.followUpStatus !== false;
   const channelPosts = engagement.channelPosts;
   if (channelPosts !== undefined) {
     const entries = channelPosts.allow.filter((entry) => entry.trim() !== "");
@@ -296,6 +297,7 @@ export function slackChannel<const Name extends string = string>(
       mentionsEnabled,
       directMessagesEnabled,
       evalCommandsEnabled,
+      followUpStatus,
       // cursorAccount: backend router already refuses externals.
       blockExternals: cursorAccount ? false : blockExternals,
       ...(args.hasContinuationSession === undefined
@@ -484,6 +486,7 @@ export function slackChannel<const Name extends string = string>(
                   artifacts: args.artifacts,
                   log: getLog(),
                   evalCommandsEnabled,
+                  followUpStatus,
                   blockExternals,
                   ...(args.hasContinuationSession === undefined
                     ? {}

package/src/channels/slack/types.ts

@@ -330,11 +330,18 @@ export type SlackBlockActionHandler = (
  */
 export interface SlackChannelPostsOptions {
   /**
-   * Channels to watch: ids (`C…` / `G…`) or `#names`. Must be non-empty
-   * (empty is a definition error). `#names` are resolved to ids via
-   * `conversations.list` when the channel starts; the bot must be a member
-   * of each watched channel to receive its messages. Socket Mode only —
-   * `cursorAccount: true` rejects `engagement.channelPosts`.
+   * Channels to watch: ids (`C…` / `G…`), `#names`, or `"*"` for every
+   * channel the bot is in. Must be non-empty (empty is a definition error).
+   * `#names` are resolved to ids via `conversations.list` when the channel
+   * starts; the bot must be a member of each watched channel to receive its
+   * messages. Socket Mode only — `cursorAccount: true` rejects
+   * `engagement.channelPosts`.
+   *
+   * `"*"` suits agents whose handler decides per message (a thread the agent
+   * is already in, say) rather than per channel. Every delivered message then
+   * reaches {@link SlackChannelOptions.onChannelPost}, and each one costs a
+   * `users.info` external-sender check first unless
+   * {@link SlackAccessPolicy.blockExternals} is off.
    */
   allow: string[];
   /**
@@ -571,6 +578,16 @@ export interface SlackChannelOptions {
    * Defaults to `true`.
    */
   thinkingSteps?: boolean;
+  /**
+   * Write Slack's assistant status chip ("Saw your follow-up…") when a
+   * follow-up coalesces into a running turn. Defaults to `true`.
+   *
+   * Set to `false` on channels that report progress themselves: the chip is
+   * cleared by the default `message.completed` handler, so a channel that
+   * replaces that handler has nothing to take it down and it outlives the
+   * turn.
+   */
+  followUpStatus?: boolean;
   /**
    * Opt in to Slack delivery for human-in-the-loop tool approvals.
    *

package/src/index.ts

@@ -132,6 +132,8 @@ export type {
 export { defineSchedule } from "./schedules.js";
 export { defineSkill } from "./skills.js";
 export type {
+  DurableSessionRecord,
+  DurableSessionSummary,
   StorageABTable,
   StorageCasTable,
   StorageConfig,
@@ -144,8 +146,11 @@ export type {
 } from "./storage.js";
 export {
   defineStorage,
+  isDurableSessionRecordKey,
+  parseDurableSessionRecord,
   STORAGE_KEY_ROOT,
   storageKeys,
+  summarizeDurableSessionRecord,
 } from "./storage.js";
 export { defineTool } from "./tools.js";
 export type * from "./types.js";

package/src/internal/advertise-tools.ts

@@ -0,0 +1,229 @@
+/**
+ * Advertised connection tools (`defineConnection({ advertiseTools: true })`).
+ *
+ * The session engine calls {@link resolveAdvertisedTools} while building
+ * every local turn: for each advertising connection it lists the server's
+ * tools and synthesizes a named 1:1 passthrough server tool per entry —
+ * the server's own names, descriptions, and live schemas — merged into the
+ * authored `agent/tools/` catalog. Because it runs at turn-build time it
+ * covers every way a turn starts (dispatcher sends, follow-ups, reminder
+ * fires that call the engine directly) and survives process restarts,
+ * since nothing is parked in memory between turns.
+ *
+ * Connections with per-session `auth` are listed and called through a
+ * one-off client carrying that session's headers (the registry's cached
+ * per-name client would leak one session's identity into another);
+ * auth-less connections go through the shared `host.mcp` registry, which
+ * also covers serve-resolved transports (Cursor account bridges, peers).
+ *
+ * Everything here fails closed: a listing failure, an invalid tool name,
+ * or a name collision throws, and the engine fails the turn rather than
+ * running it with a silently shrunken toolset.
+ */
+
+import type {
+  DiscoveredConnection,
+  DiscoveredTool,
+  HostMcpCallResult,
+  HostMcpToolInfo,
+  JsonSchemaObject,
+  ResolvedAgent,
+  SessionInfo,
+  ToolDefinition,
+} from "../types.js";
+import { brandDefinition } from "./brand.js";
+import type { HostMcpOneOff } from "./mcp-host.js";
+
+/**
+ * What the resolver needs from the host MCP registry: the shared cached
+ * clients for auth-less connections, and one-off clients (per-session
+ * headers, never cached) for auth'd ones. `McpHost` implements this.
+ */
+export interface AdvertiseHostMcp {
+  listTools(connectionName: string): Promise<HostMcpToolInfo[]>;
+  callTool(
+    connectionName: string,
+    toolName: string,
+    args?: Record<string, unknown>
+  ): Promise<HostMcpCallResult>;
+  oneOff(connection: DiscoveredConnection): HostMcpOneOff;
+}
+
+/**
+ * The rule advertised tool names must match — the same shape discovery
+ * enforces for authored tool filenames (its `NAME_PATTERN`), since both
+ * become the tool name the model sees.
+ */
+export const ADVERTISED_TOOL_NAME_PATTERN: RegExp =
+  /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+const ANY_OBJECT_SCHEMA: JsonSchemaObject = {
+  type: "object",
+  additionalProperties: true,
+};
+
+/** How one advertising connection is listed and called. */
+export interface AdvertisedToolSource {
+  listTools(): Promise<HostMcpToolInfo[]>;
+  callTool(
+    toolName: string,
+    args: Record<string, unknown>
+  ): Promise<HostMcpCallResult>;
+}
+
+/**
+ * Resolve the advertised tools for one session. Returns `[]` when no
+ * connection advertises; throws (failing the turn) when a listing fails
+ * or a definition is invalid.
+ */
+export async function resolveAdvertisedTools(args: {
+  agent: ResolvedAgent;
+  session: SessionInfo;
+  hostMcp: AdvertiseHostMcp;
+  /** Test seam; defaults to {@link sourceForConnection}. */
+  sourceFor?: (
+    connection: DiscoveredConnection,
+    session: SessionInfo,
+    hostMcp: AdvertiseHostMcp
+  ) => Promise<AdvertisedToolSource>;
+}): Promise<DiscoveredTool[]> {
+  const advertising = args.agent.connections.filter(
+    (connection) => connection.advertiseTools === true
+  );
+  if (advertising.length === 0) {
+    return [];
+  }
+  const sourceFor = args.sourceFor ?? sourceForConnection;
+  const claimed = new Set(args.agent.tools.map((tool) => tool.name));
+  const resolved: DiscoveredTool[] = [];
+  for (const connection of advertising) {
+    const source = await sourceFor(connection, args.session, args.hostMcp);
+    let listed: HostMcpToolInfo[];
+    try {
+      listed = await source.listTools();
+    } catch (error) {
+      throw new Error(
+        `Failed to list tools on advertised connection "${connection.name}": ${describeError(error)}`,
+        { cause: error }
+      );
+    }
+    for (const info of listed) {
+      resolved.push(toDiscoveredTool(connection, info, claimed, source));
+      claimed.add(info.name);
+    }
+  }
+  return resolved;
+}
+
+/**
+ * The production source for one advertising connection: the shared
+ * `host.mcp` registry client for auth-less connections (which also covers
+ * serve-resolved transports — Cursor account bridges, peers), or a
+ * registry one-off with the session's headers substituted when the
+ * connection has per-session `auth`. The auth callback is evaluated once
+ * per turn, here; the one-off opens a fresh client per operation so one
+ * session's identity can never serve another's call.
+ */
+export async function sourceForConnection(
+  connection: DiscoveredConnection,
+  session: SessionInfo,
+  hostMcp: AdvertiseHostMcp
+): Promise<AdvertisedToolSource> {
+  if (connection.auth === undefined) {
+    return {
+      listTools: () => hostMcp.listTools(connection.name),
+      callTool: (toolName, callArgs) =>
+        hostMcp.callTool(connection.name, toolName, callArgs),
+    };
+  }
+  const transport = connection.transport;
+  if (!("url" in transport)) {
+    // Discovery rejects auth on non-URL transports; guard for callers that
+    // bypass discovery (hand-built projects).
+    throw new Error(
+      `Connection "${connection.name}" has per-session auth but no URL transport.`
+    );
+  }
+  const evaluated = await connection.auth(session);
+  return hostMcp.oneOff({
+    ...connection,
+    transport: {
+      ...transport,
+      headers: { ...transport.headers, ...evaluated.headers },
+    },
+  });
+}
+
+function toDiscoveredTool(
+  connection: DiscoveredConnection,
+  info: HostMcpToolInfo,
+  claimed: ReadonlySet<string>,
+  source: AdvertisedToolSource
+): DiscoveredTool {
+  if (!ADVERTISED_TOOL_NAME_PATTERN.test(info.name)) {
+    throw new Error(
+      `Advertised connection "${connection.name}" serves tool name "${info.name}", which must match ${ADVERTISED_TOOL_NAME_PATTERN} (it becomes the tool name the model sees).`
+    );
+  }
+  if (claimed.has(info.name)) {
+    throw new Error(
+      `Advertised connection "${connection.name}" serves tool "${info.name}", which collides with an authored agent/tools/ tool or another advertised connection.`
+    );
+  }
+  const description =
+    info.description === undefined || info.description.trim() === ""
+      ? `${info.name} — MCP tool on the "${connection.name}" connection, forwarded 1:1.`
+      : info.description;
+  const inputSchema = info.inputSchema ?? ANY_OBJECT_SCHEMA;
+  const definition: ToolDefinition = brandDefinition("tool", {
+    description,
+    inputSchema,
+    execute: async (input: Record<string, unknown>) =>
+      formatMcpToolResult(
+        connection.name,
+        info.name,
+        await source.callTool(info.name, input ?? {})
+      ),
+  } as unknown as ToolDefinition);
+  return {
+    name: info.name,
+    description,
+    inputSchema,
+    execution: "server",
+    needsApproval: false,
+    definition,
+  };
+}
+
+/**
+ * Render an MCP call result for the model: text parts joined, non-text
+ * parts noted by type, `isError` surfaced as a thrown error so the turn
+ * records a tool error instead of error-shaped prose.
+ */
+export function formatMcpToolResult(
+  connectionName: string,
+  toolName: string,
+  result: HostMcpCallResult
+): string {
+  const parts = result.content.map((item) =>
+    item.type === "text" && typeof item.text === "string"
+      ? item.text
+      : `[${item.type} content omitted]`
+  );
+  const text = parts.join("\n").trim();
+  if (result.isError === true) {
+    throw new Error(
+      text === "" ? `${connectionName} tool ${toolName} failed` : text
+    );
+  }
+  if (text !== "") {
+    return text;
+  }
+  return result.structuredContent !== undefined
+    ? JSON.stringify(result.structuredContent, null, 2)
+    : "(empty result)";
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}