@slock-ai/daemon 0.34.0 → 0.36.1-alpha.0

package/dist/chat-bridge.js

@@ -1,12 +1,205 @@
 #!/usr/bin/env node
 import {
-  buildFetchDispatcher
-} from "./chunk-GX2DVINN.js";
+  buildFetchDispatcher,
+  logger
+} from "./chunk-E6OOH3IC.js";
 
 // src/chat-bridge.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+
+// src/historyFormatting.ts
+function toLocalHistoryTime(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())} ${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+function formatHistorySenderHandle(message) {
+  return message.senderDescription ? `@${message.senderName} \u2014 ${message.senderDescription}` : `@${message.senderName}`;
+}
+function formatHistoryMessageLine(message) {
+  const headerParts = [
+    `seq=${message.seq}`,
+    `msg=${message.id || "-"}`,
+    `time=${message.createdAt ? toLocalHistoryTime(message.createdAt) : "-"}`
+  ];
+  if (message.senderType) {
+    headerParts.push(`type=${message.senderType}`);
+  }
+  if (message.threadId) {
+    headerParts.push(`threadId=${message.threadId}`);
+  }
+  if ((message.replyCount ?? 0) > 0) {
+    headerParts.push(`replyCount=${message.replyCount}`);
+  }
+  const attachSuffix = message.attachments?.length ? ` [${message.attachments.length} attachment${message.attachments.length > 1 ? "s" : ""}: ${message.attachments.map((attachment) => `${attachment.filename} (id:${attachment.id})`).join(", ")} \u2014 use view_file to download]` : "";
+  const taskSuffix = message.taskStatus ? ` [task #${message.taskNumber} status=${message.taskStatus}${message.taskAssigneeId ? ` assignee=${message.taskAssigneeType}:${message.taskAssigneeId}` : ""}]` : "";
+  return `[${headerParts.join(" ")}] ${formatHistorySenderHandle(message)}: ${message.content}${attachSuffix}${taskSuffix}`;
+}
+
+// src/chatBridgeRequest.ts
+var DEFAULT_CHAT_BRIDGE_TOOL_TIMEOUT_MS = Number.parseInt(
+  process.env.SLOCK_CHAT_BRIDGE_TOOL_TIMEOUT_MS || "",
+  10
+) || 6e4;
+var ChatBridgeToolTimeoutError = class extends Error {
+  toolName;
+  target;
+  timeoutMs;
+  durationMs;
+  constructor(toolName, target, timeoutMs, durationMs) {
+    super(`${toolName} timed out after ${timeoutMs}ms${target ? ` (target: ${target})` : ""}`);
+    this.name = "ChatBridgeToolTimeoutError";
+    this.toolName = toolName;
+    this.target = target;
+    this.timeoutMs = timeoutMs;
+    this.durationMs = durationMs;
+  }
+};
+function describeError(err) {
+  if (err instanceof Error) return `${err.name}: ${err.message}`;
+  return String(err);
+}
+async function executeJsonRequest(url, init, {
+  toolName,
+  target = null,
+  timeoutMs = DEFAULT_CHAT_BRIDGE_TOOL_TIMEOUT_MS,
+  fetchImpl,
+  now = () => Date.now(),
+  warn = (message) => logger.warn(message)
+}) {
+  const startedAt = now();
+  const timeoutController = new AbortController();
+  const signals = [timeoutController.signal];
+  if (init.signal) signals.push(init.signal);
+  const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+  const timeout = setTimeout(() => {
+    timeoutController.abort();
+  }, timeoutMs);
+  timeout.unref?.();
+  try {
+    const response = await fetchImpl(url, { ...init, signal });
+    const data = await response.json();
+    return { response, data, durationMs: now() - startedAt };
+  } catch (err) {
+    const durationMs = now() - startedAt;
+    if (timeoutController.signal.aborted && !init.signal?.aborted) {
+      warn(
+        `[ChatBridgeTimeout] tool=${toolName} target=${target ?? "-"} duration_ms=${durationMs} timeout_ms=${timeoutMs} outcome=timeout`
+      );
+      throw new ChatBridgeToolTimeoutError(toolName, target, timeoutMs, durationMs);
+    }
+    warn(
+      `[ChatBridgeError] tool=${toolName} target=${target ?? "-"} duration_ms=${durationMs} outcome=error error=${describeError(err)}`
+    );
+    throw err;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function executeResponseRequest(url, init, {
+  toolName,
+  target = null,
+  timeoutMs = DEFAULT_CHAT_BRIDGE_TOOL_TIMEOUT_MS,
+  fetchImpl,
+  now = () => Date.now(),
+  warn = (message) => logger.warn(message)
+}) {
+  const startedAt = now();
+  const timeoutController = new AbortController();
+  const signals = [timeoutController.signal];
+  if (init.signal) signals.push(init.signal);
+  const signal = signals.length === 1 ? signals[0] : AbortSignal.any(signals);
+  const timeout = setTimeout(() => {
+    timeoutController.abort();
+  }, timeoutMs);
+  timeout.unref?.();
+  try {
+    const response = await fetchImpl(url, { ...init, signal });
+    return { response, durationMs: now() - startedAt };
+  } catch (err) {
+    const durationMs = now() - startedAt;
+    if (timeoutController.signal.aborted && !init.signal?.aborted) {
+      warn(
+        `[ChatBridgeTimeout] tool=${toolName} target=${target ?? "-"} duration_ms=${durationMs} timeout_ms=${timeoutMs} outcome=timeout`
+      );
+      throw new ChatBridgeToolTimeoutError(toolName, target, timeoutMs, durationMs);
+    }
+    warn(
+      `[ChatBridgeError] tool=${toolName} target=${target ?? "-"} duration_ms=${durationMs} outcome=error error=${describeError(err)}`
+    );
+    throw err;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// src/chatBridgeSendRequest.ts
+import { randomUUID } from "crypto";
+async function executeRetrySafeSendRequest(url, buildInit, {
+  fetchImpl,
+  target,
+  timeoutMs = DEFAULT_CHAT_BRIDGE_TOOL_TIMEOUT_MS,
+  now = () => Date.now(),
+  warn = (message) => logger.warn(message),
+  idempotencyKey = randomUUID()
+}) {
+  let lastError;
+  for (let attempt = 1; attempt <= 2; attempt += 1) {
+    try {
+      const result = await executeJsonRequest(
+        url,
+        buildInit(idempotencyKey),
+        {
+          toolName: "send_message",
+          target,
+          timeoutMs,
+          fetchImpl,
+          now,
+          warn
+        }
+      );
+      return {
+        ...result,
+        idempotencyKey,
+        attempts: attempt
+      };
+    } catch (error) {
+      lastError = error;
+      if (attempt === 2) break;
+      warn(
+        `[ChatBridgeRetry] tool=send_message target=${target} attempt=${attempt + 1} reason=${describeRetryReason(error)}`
+      );
+    }
+  }
+  throw lastError;
+}
+function describeRetryReason(error) {
+  if (error && typeof error === "object" && "name" in error && error.name === "ChatBridgeToolTimeoutError") {
+    return error.message;
+  }
+  return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}
+
+// src/perfAttribution.ts
+var PERF_CALLER_CONTEXT_HEADER = "X-Perf-Caller-Context";
+var AGENT_ORIGINATED_CALLER_CONTEXT = "agent_originated";
+function buildChatBridgeCommonHeaders(authToken2, { includeContentType = true } = {}) {
+  const headers = {
+    [PERF_CALLER_CONTEXT_HEADER]: AGENT_ORIGINATED_CALLER_CONTEXT
+  };
+  if (includeContentType) {
+    headers["Content-Type"] = "application/json";
+  }
+  if (authToken2) {
+    headers.Authorization = `Bearer ${authToken2}`;
+  }
+  return headers;
+}
+
+// src/chat-bridge.ts
 function toLocalTime(iso) {
   const d = new Date(iso);
   if (isNaN(d.getTime())) return iso;
@@ -26,15 +219,123 @@ if (!agentId) {
   console.error("Missing --agent-id");
   process.exit(1);
 }
-var commonHeaders = { "Content-Type": "application/json" };
-if (authToken) {
-  commonHeaders["Authorization"] = `Bearer ${authToken}`;
-}
+var commonHeaders = buildChatBridgeCommonHeaders(authToken);
 function bridgeFetch(url, init = {}) {
   const dispatcher = buildFetchDispatcher(url, process.env);
   const requestInit = dispatcher ? { ...init, dispatcher } : init;
   return fetch(url, requestInit);
 }
+var RECENT_DELIVERY_CACHE_LIMIT = 5e3;
+var deliveredMessageKeys = /* @__PURE__ */ new Set();
+var deliveredMessageOrder = [];
+function messageDeliveryKey(message) {
+  if (message.seq) return `seq:${message.seq}`;
+  if (message.message_id) return `msg:${message.message_id}`;
+  return null;
+}
+function rememberDeliveredMessages(messages) {
+  const unseen = [];
+  for (const message of messages) {
+    const key = messageDeliveryKey(message);
+    if (!key) {
+      unseen.push(message);
+      continue;
+    }
+    if (deliveredMessageKeys.has(key)) {
+      continue;
+    }
+    deliveredMessageKeys.add(key);
+    deliveredMessageOrder.push(key);
+    unseen.push(message);
+  }
+  while (deliveredMessageOrder.length > RECENT_DELIVERY_CACHE_LIMIT) {
+    const evicted = deliveredMessageOrder.shift();
+    if (evicted) deliveredMessageKeys.delete(evicted);
+  }
+  return unseen;
+}
+async function acknowledgeReceivedMessages(messages) {
+  const seqs = [...new Set(
+    messages.map((message) => message.seq).filter((seq) => typeof seq === "number" && Number.isInteger(seq) && seq > 0)
+  )];
+  if (seqs.length === 0) return;
+  try {
+    const res = await bridgeFetch(`${serverUrl}/internal/agent/${agentId}/receive-ack`, {
+      method: "POST",
+      headers: commonHeaders,
+      body: JSON.stringify({ seqs })
+    });
+    if (!res.ok) {
+      console.warn(`[chat-bridge] receive-ack failed (${res.status}) for agent ${agentId}; delivery will replay on the next poll`);
+    }
+  } catch (err) {
+    console.warn(
+      `[chat-bridge] receive-ack errored for agent ${agentId}; delivery will replay on the next poll: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function formatAttachmentSuffix(attachments) {
+  if (!attachments?.length) return "";
+  return ` [${attachments.length} attachment${attachments.length > 1 ? "s" : ""}: ${attachments.map((a) => `${a.filename} (id:${a.id})`).join(", ")} \u2014 use view_file to download]`;
+}
+function guessMimeTypeFromFilename(filename) {
+  const ext = filename.includes(".") ? filename.slice(filename.lastIndexOf(".")).toLowerCase() : "";
+  const mimeMap = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".pdf": "application/pdf",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".json": "application/json",
+    ".csv": "text/csv",
+    ".zip": "application/zip",
+    ".tar": "application/x-tar",
+    ".gz": "application/gzip",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    ".xls": "application/vnd.ms-excel",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    ".ppt": "application/vnd.ms-powerpoint",
+    ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation"
+  };
+  return mimeMap[ext] || "application/octet-stream";
+}
+function parseFilenameFromContentDisposition(contentDisposition) {
+  if (!contentDisposition) return null;
+  const utf8Match = contentDisposition.match(/filename\*\s*=\s*UTF-8''([^;]+)/i);
+  if (utf8Match?.[1]) return decodeURIComponent(utf8Match[1]);
+  const plainMatch = contentDisposition.match(/filename\s*=\s*"([^"]+)"/i) || contentDisposition.match(/filename\s*=\s*([^;]+)/i);
+  return plainMatch?.[1] ? plainMatch[1].trim() : null;
+}
+function extensionForContentType(contentType) {
+  const normalized = contentType.split(";")[0]?.trim().toLowerCase();
+  const extMap = {
+    "image/jpeg": ".jpg",
+    "image/png": ".png",
+    "image/gif": ".gif",
+    "image/webp": ".webp",
+    "application/pdf": ".pdf",
+    "text/plain": ".txt",
+    "text/markdown": ".md",
+    "application/json": ".json",
+    "text/csv": ".csv",
+    "application/zip": ".zip",
+    "application/x-tar": ".tar",
+    "application/gzip": ".gz",
+    "audio/mpeg": ".mp3",
+    "audio/wav": ".wav",
+    "video/mp4": ".mp4",
+    "video/quicktime": ".mov"
+  };
+  return extMap[normalized] || ".bin";
+}
 function formatTarget(m) {
   if (m.channel_type === "thread" && m.parent_channel_name) {
     const shortId = m.channel_name.startsWith("thread-") ? m.channel_name.slice(7) : m.channel_name;
@@ -61,6 +362,11 @@ function formatSearchTarget(result) {
   }
   return `#${result.channelName}`;
 }
+function formatSenderHandle(message) {
+  const senderName = message.sender_name ?? message.senderName ?? "unknown";
+  const senderDescription = message.sender_description ?? message.senderDescription ?? null;
+  return senderDescription ? `@${senderName} \u2014 ${senderDescription}` : `@${senderName}`;
+}
 var server = new McpServer({
   name: "chat",
   version: "1.0.0"
@@ -77,12 +383,18 @@ server.tool(
   },
   async ({ target, content, attachment_ids }) => {
     try {
-      const res = await bridgeFetch(`${serverUrl}/internal/agent/${agentId}/send`, {
-        method: "POST",
-        headers: commonHeaders,
-        body: JSON.stringify({ target, content, attachmentIds: attachment_ids })
-      });
-      const data = await res.json();
+      const { response: res, data } = await executeRetrySafeSendRequest(
+        `${serverUrl}/internal/agent/${agentId}/send`,
+        (idempotencyKey) => ({
+          method: "POST",
+          headers: commonHeaders,
+          body: JSON.stringify({ target, content, attachmentIds: attachment_ids, idempotencyKey })
+        }),
+        {
+          target,
+          fetchImpl: bridgeFetch
+        }
+      );
       if (!res.ok) {
         return {
           content: [
@@ -94,10 +406,14 @@ server.tool(
       const replyHint = shortId ? ` (to reply in this message's thread, use target "${target.includes(":") ? target : target + ":" + shortId}")` : "";
       let unreadSection = "";
       if (data.recentUnread && data.recentUnread.length > 0) {
-        unreadSection = `
+        await acknowledgeReceivedMessages(data.recentUnread);
+        const unreadToShow = rememberDeliveredMessages(data.recentUnread);
+        if (unreadToShow.length > 0) {
+          unreadSection = `
 
 --- New messages you may have missed ---
-${formatMessages(data.recentUnread)}`;
+${formatMessages(unreadToShow)}`;
+        }
       }
       return {
         content: [
@@ -117,9 +433,9 @@ ${formatMessages(data.recentUnread)}`;
 );
 server.tool(
   "upload_file",
-  "Upload an image file to attach to a message. Returns an attachment ID that you can pass to send_message's attachment_ids parameter. Supported formats: JPEG, PNG, GIF, WebP. Max size: 5MB.",
+  "Upload a file to attach to a message. Returns an attachment ID that you can pass to send_message's attachment_ids parameter. Images keep preview behavior; other files are sent as downloadable attachments. Max size: 10MB.",
   {
-    file_path: z.string().describe("Absolute path to the image file on your local filesystem"),
+    file_path: z.string().describe("Absolute path to the file on your local filesystem"),
     channel: z.string().describe("The channel target where this file will be used (e.g. '#general', 'dm:@richard')")
   },
   async ({ file_path, channel }) => {
@@ -133,52 +449,53 @@ server.tool(
         };
       }
       const stat = fs.statSync(file_path);
-      if (stat.size > 5 * 1024 * 1024) {
+      if (stat.size > 10 * 1024 * 1024) {
         return {
           isError: true,
-          content: [{ type: "text", text: `Error: File too large (${(stat.size / 1024 / 1024).toFixed(1)}MB). Max 5MB.` }]
+          content: [{ type: "text", text: `Error: File too large (${(stat.size / 1024 / 1024).toFixed(1)}MB). Max 10MB per file.` }]
         };
       }
-      const listRes = await bridgeFetch(`${serverUrl}/internal/agent/${agentId}/resolve-channel`, {
-        method: "POST",
-        headers: commonHeaders,
-        body: JSON.stringify({ target: channel })
-      });
-      let channelId;
-      if (listRes.ok) {
-        const listData = await listRes.json();
-        channelId = listData.channelId;
-      } else {
+      const { response: listRes, data: listData } = await executeJsonRequest(
+        `${serverUrl}/internal/agent/${agentId}/resolve-channel`,
+        {
+          method: "POST",
+          headers: commonHeaders,
+          body: JSON.stringify({ target: channel })
+        },
+        {
+          toolName: "upload_file.resolve_channel",
+          target: channel,
+          fetchImpl: bridgeFetch
+        }
+      );
+      if (!listRes.ok || !listData.channelId) {
         return {
           isError: true,
-          content: [{ type: "text", text: `Error: Could not resolve channel: ${channel}` }]
+          content: [{ type: "text", text: `Error: ${listData.error || `Could not resolve channel: ${channel}`}` }]
         };
       }
+      const channelId = listData.channelId;
       const fileBuffer = fs.readFileSync(file_path);
       const filename = path.basename(file_path);
-      const ext = path.extname(file_path).toLowerCase();
-      const mimeMap = {
-        ".jpg": "image/jpeg",
-        ".jpeg": "image/jpeg",
-        ".png": "image/png",
-        ".gif": "image/gif",
-        ".webp": "image/webp"
-      };
-      const mimeType = mimeMap[ext] || "application/octet-stream";
+      const mimeType = guessMimeTypeFromFilename(filename);
       const blob = new Blob([fileBuffer], { type: mimeType });
       const formData = new FormData();
       formData.append("file", blob, filename);
       formData.append("channelId", channelId);
-      const uploadHeaders = {};
-      if (authToken) {
-        uploadHeaders["Authorization"] = `Bearer ${authToken}`;
-      }
-      const res = await bridgeFetch(`${serverUrl}/internal/agent/${agentId}/upload`, {
-        method: "POST",
-        headers: uploadHeaders,
-        body: formData
-      });
-      const data = await res.json();
+      const uploadHeaders = buildChatBridgeCommonHeaders(authToken, { includeContentType: false });
+      const { response: res, data } = await executeJsonRequest(
+        `${serverUrl}/internal/agent/${agentId}/upload`,
+        {
+          method: "POST",
+          headers: uploadHeaders,
+          body: formData
+        },
+        {
+          toolName: "upload_file",
+          target: channel,
+          fetchImpl: bridgeFetch
+        }
+      );
       if (!res.ok) {
         return {
           isError: true,
@@ -206,7 +523,7 @@ Use this ID in send_message's attachment_ids parameter to include it in a messag
 );
 server.tool(
   "view_file",
-  "Download an attached image by its attachment ID and save it locally so you can view it. Returns the local file path. Use this when you see '[use view_file to see]' in a message with images.",
+  "Download an attached file by its attachment ID and save it locally so you can inspect it. Returns the local file path.",
   {
     attachment_id: z.string().describe("The attachment UUID (from the 'id:...' shown in the message)")
   },
@@ -221,19 +538,22 @@ server.tool(
       if (existing) {
         const cachedPath = path.join(cacheDir, existing);
         return {
-          content: [{ type: "text", text: `File already cached at: ${cachedPath}
-
-Use your Read tool to view this image.` }]
+          content: [{ type: "text", text: `File already cached at: ${cachedPath}` }]
         };
       }
-      const downloadHeaders = {};
-      if (authToken) {
-        downloadHeaders["Authorization"] = `Bearer ${authToken}`;
-      }
-      const res = await bridgeFetch(`${serverUrl}/api/attachments/${attachment_id}`, {
-        headers: downloadHeaders,
-        redirect: "follow"
-      });
+      const downloadHeaders = buildChatBridgeCommonHeaders(authToken, { includeContentType: false });
+      const { response: res } = await executeResponseRequest(
+        `${serverUrl}/api/attachments/${attachment_id}`,
+        {
+          headers: downloadHeaders,
+          redirect: "follow"
+        },
+        {
+          toolName: "view_file",
+          target: attachment_id,
+          fetchImpl: bridgeFetch
+        }
+      );
       if (!res.ok) {
         return {
           isError: true,
@@ -241,20 +561,13 @@ Use your Read tool to view this image.` }]
         };
       }
       const contentType = res.headers.get("content-type") || "application/octet-stream";
-      const extMap = {
-        "image/jpeg": ".jpg",
-        "image/png": ".png",
-        "image/gif": ".gif",
-        "image/webp": ".webp"
-      };
-      const ext = extMap[contentType] || ".bin";
+      const filename = parseFilenameFromContentDisposition(res.headers.get("content-disposition"));
+      const ext = filename ? path.extname(filename) || extensionForContentType(contentType) : extensionForContentType(contentType);
       const filePath = path.join(cacheDir, `${attachment_id}${ext}`);
       const buffer = Buffer.from(await res.arrayBuffer());
       fs.writeFileSync(filePath, buffer);
       return {
-        content: [{ type: "text", text: `Downloaded to: ${filePath}
-
-Use your Read tool to view this image.` }]
+        content: [{ type: "text", text: `Downloaded to: ${filePath}` }]
       };
     } catch (err) {
       return {
@@ -270,17 +583,25 @@ server.tool(
   {},
   async () => {
     try {
-      const res = await bridgeFetch(
+      const { response: res, data } = await executeJsonRequest(
         `${serverUrl}/internal/agent/${agentId}/receive`,
-        { method: "GET", headers: commonHeaders }
+        { method: "GET", headers: commonHeaders },
+        {
+          toolName: "check_messages",
+          timeoutMs: 1e4,
+          fetchImpl: bridgeFetch
+        }
       );
       if (!res.ok) {
-        const errData = await res.json().catch(() => ({}));
-        return { isError: true, content: [{ type: "text", text: `Error: ${errData.error || res.statusText}` }] };
+        return { isError: true, content: [{ type: "text", text: `Error: ${data.error || res.statusText}` }] };
       }
-      const data = await res.json();
-      if (data.messages?.length > 0) {
-        return { content: [{ type: "text", text: formatMessages(data.messages) }] };
+      const messages = data.messages ?? [];
+      if (messages.length > 0) {
+        await acknowledgeReceivedMessages(messages);
+        const messagesToShow = rememberDeliveredMessages(messages);
+        if (messagesToShow.length > 0) {
+          return { content: [{ type: "text", text: formatMessages(messagesToShow) }] };
+        }
       }
       return {
         content: [{ type: "text", text: "No new messages." }]
@@ -298,11 +619,11 @@ function formatMessages(messages) {
     const target = formatTarget(m);
     const msgId = m.message_id ? m.message_id.slice(0, 8) : "-";
     const time = m.timestamp ? toLocalTime(m.timestamp) : "-";
-    const senderType = m.sender_type === "agent" ? " type=agent" : "";
+    const senderType = ` type=${m.sender_type}`;
     const renderedContent = m.content;
-    const attachSuffix = m.attachments?.length ? ` [${m.attachments.length} image${m.attachments.length > 1 ? "s" : ""}: ${m.attachments.map((a) => `${a.filename} (id:${a.id})`).join(", ")} \u2014 use view_file to see]` : "";
+    const attachSuffix = formatAttachmentSuffix(m.attachments);
     const taskSuffix = m.task_status ? ` [task #${m.task_number} status=${m.task_status}${m.task_assignee_id ? ` assignee=${m.task_assignee_type}:${m.task_assignee_id}` : ""}]` : "";
-    return `[target=${target} msg=${msgId} time=${time}${senderType}] @${m.sender_name}: ${renderedContent}${attachSuffix}${taskSuffix}`;
+    return `[target=${target} msg=${msgId} time=${time}${senderType}] ${formatSenderHandle(m)}: ${renderedContent}${attachSuffix}${taskSuffix}`;
   }).join("\n");
 }
 server.tool(
@@ -311,16 +632,22 @@ server.tool(
   {},
   async () => {
     try {
-      const res = await bridgeFetch(
+      const { response: res, data } = await executeJsonRequest(
         `${serverUrl}/internal/agent/${agentId}/server`,
-        { method: "GET", headers: commonHeaders }
+        { method: "GET", headers: commonHeaders },
+        {
+          toolName: "list_server",
+          fetchImpl: bridgeFetch
+        }
       );
-      const data = await res.json();
       let text = "## Server\n\n";
+      const channels = data.channels ?? [];
+      const agents = data.agents ?? [];
+      const humans = data.humans ?? [];
       text += "### Channels\n";
       text += "Use `#channel-name` with send_message to post in a channel. `joined` means you currently belong to that channel.\n";
-      if (data.channels?.length > 0) {
-        for (const t of data.channels) {
+      if (channels.length > 0) {
+        for (const t of channels) {
           const status = t.joined ? "joined" : "not joined";
           text += t.description ? `  - #${t.name} [${status}] \u2014 ${t.description}
 ` : `  - #${t.name} [${status}]
@@ -331,9 +658,10 @@ server.tool(
       }
       text += "\n### Agents\n";
       text += "Other AI agents in this server.\n";
-      if (data.agents?.length > 0) {
-        for (const a of data.agents) {
-          text += `  - @${a.name} (${a.status})
+      if (agents.length > 0) {
+        for (const a of agents) {
+          text += a.description ? `  - @${a.name} (${a.status}) \u2014 ${a.description}
+` : `  - @${a.name} (${a.status})
 `;
         }
       } else {
@@ -341,9 +669,10 @@ server.tool(
       }
       text += "\n### Humans\n";
       text += 'To start a new DM: send_message(target="dm:@name"). To reply in an existing DM: reuse the target from received messages.\n';
-      if (data.humans?.length > 0) {
-        for (const u of data.humans) {
-          text += `  - @${u.name}
+      if (humans.length > 0) {
+        for (const u of humans) {
+          text += u.description ? `  - @${u.name} \u2014 ${u.description}
+` : `  - @${u.name}
 `;
         }
       } else {
@@ -386,11 +715,15 @@ server.tool(
       if (sender_id) params.set("senderId", sender_id);
       if (after) params.set("after", after);
       if (before) params.set("before", before);
-      const res = await bridgeFetch(
+      const { response: res, data } = await executeJsonRequest(
         `${serverUrl}/internal/agent/${agentId}/search?${params}`,
-        { method: "GET", headers: commonHeaders }
+        { method: "GET", headers: commonHeaders },
+        {
+          toolName: "search_messages",
+          target: channel ?? null,
+          fetchImpl: bridgeFetch
+        }
       );
-      const data = await res.json();
       if (!res.ok) {
         return {
           content: [{ type: "text", text: `Error: ${data.error}` }]
@@ -408,7 +741,7 @@ thread: ${result.parentChannelName} -> ${target}` : "";
         return [
           `[${index + 1}] msg=${result.id} seq=${result.seq} time=${toLocalTime(result.createdAt)}`,
           `target: ${target}${threadInfo}`,
-          `sender: @${result.senderName}${result.senderType === "agent" ? " (agent)" : ""}`,
+          `sender: @${result.senderName} (${result.senderType})`,
           `content: ${result.content}`,
           `match: ${result.snippet}`,
           `next: read_history(channel="${target}", around="${result.id}", limit=20)`
@@ -448,11 +781,15 @@ server.tool(
       if (around !== void 0) params.set("around", String(around));
       if (before) params.set("before", String(before));
       if (after) params.set("after", String(after));
-      const res = await bridgeFetch(
+      const { response: res, data } = await executeJsonRequest(
         `${serverUrl}/internal/agent/${agentId}/history?${params}`,
-        { method: "GET", headers: commonHeaders }
+        { method: "GET", headers: commonHeaders },
+        {
+          toolName: "read_history",
+          target: channel,
+          fetchImpl: bridgeFetch
+        }
       );
-      const data = await res.json();
       if (!res.ok) {
         return {
           content: [
@@ -467,15 +804,11 @@ server.tool(
           ]
         };
       }
-      const formatted = data.messages.map((m) => {
-        const senderType = m.senderType === "agent" ? " type=agent" : "";
-        const time = m.createdAt ? toLocalTime(m.createdAt) : "-";
-        const msgId = m.id || "-";
-        const renderedContent = m.content;
-        const attachSuffix = m.attachments?.length ? ` [${m.attachments.length} image${m.attachments.length > 1 ? "s" : ""}: ${m.attachments.map((a) => `${a.filename} (id:${a.id})`).join(", ")} \u2014 use view_file to see]` : "";
-        const taskSuffix = m.taskStatus ? ` [task #${m.taskNumber} status=${m.taskStatus}${m.taskAssigneeId ? ` assignee=${m.taskAssigneeType}:${m.taskAssigneeId}` : ""}]` : "";
-        return `[seq=${m.seq} msg=${msgId} time=${time}${senderType}] @${m.senderName}: ${renderedContent}${attachSuffix}${taskSuffix}`;
-      }).join("\n");
+      const formatted = data.messages.map((m) => formatHistoryMessageLine({
+        ...m,
+        senderName: m.senderName ?? m.sender_name ?? "unknown",
+        senderDescription: m.senderDescription ?? m.sender_description ?? null
+      })).join("\n");
       let footer = "";
       if (data.historyLimited) {
         footer = `
@@ -501,7 +834,7 @@ server.tool(
         }
       }
       let header = `## Message History for ${channel}${around ? ` around ${around}` : ""} (${data.messages.length} messages)`;
-      if (data.last_read_seq > 0 && !after && !before && !around) {
+      if ((data.last_read_seq ?? 0) > 0 && !after && !before && !around) {
         header += `
 Your last read position: seq ${data.last_read_seq}. Use read_history(channel="${channel}", after=${data.last_read_seq}) to see only unread messages.`;
       }
@@ -535,11 +868,15 @@ server.tool(
       const params = new URLSearchParams();
       params.set("channel", channel);
       if (status !== "all") params.set("status", status);
-      const res = await bridgeFetch(
+      const { response: res, data } = await executeJsonRequest(
         `${serverUrl}/internal/agent/${agentId}/tasks?${params}`,
-        { method: "GET", headers: commonHeaders }
+        { method: "GET", headers: commonHeaders },
+        {
+          toolName: "list_tasks",
+          target: channel,
+          fetchImpl: bridgeFetch
+        }
       );
-      const data = await res.json();
       if (!res.ok) {
         return {
           isError: true,
@@ -589,12 +926,19 @@ server.tool(
   },
   async ({ channel, tasks }) => {
     try {
-      const res = await bridgeFetch(`${serverUrl}/internal/agent/${agentId}/tasks`, {
-        method: "POST",
-        headers: commonHeaders,
-        body: JSON.stringify({ channel, tasks })
-      });
-      const data = await res.json();
+      const { response: res, data } = await executeJsonRequest(
+        `${serverUrl}/internal/agent/${agentId}/tasks`,
+        {
+          method: "POST",
+          headers: commonHeaders,
+          body: JSON.stringify({ channel, tasks })
+        },
+        {
+          toolName: "create_tasks",
+          target: channel,
+          fetchImpl: bridgeFetch
+        }
+      );
       if (!res.ok) {
         return {
           isError: true,
@@ -645,15 +989,19 @@ Thread messages cannot be claimed or converted into tasks. If a task is in "todo
       const body = { channel };
       if (task_numbers && task_numbers.length > 0) body.task_numbers = task_numbers;
       if (message_ids && message_ids.length > 0) body.message_ids = message_ids;
-      const res = await bridgeFetch(
+      const { response: res, data } = await executeJsonRequest(
         `${serverUrl}/internal/agent/${agentId}/tasks/claim`,
         {
           method: "POST",
           headers: commonHeaders,
           body: JSON.stringify(body)
+        },
+        {
+          toolName: "claim_tasks",
+          target: channel,
+          fetchImpl: bridgeFetch
         }
       );
-      const data = await res.json();
       if (!res.ok) {
         return {
           isError: true,
@@ -703,15 +1051,19 @@ server.tool(
   },
   async ({ channel, task_number }) => {
     try {
-      const res = await bridgeFetch(
+      const { response: res, data } = await executeJsonRequest(
         `${serverUrl}/internal/agent/${agentId}/tasks/unclaim`,
         {
           method: "POST",
           headers: commonHeaders,
           body: JSON.stringify({ channel, task_number })
+        },
+        {
+          toolName: "unclaim_task",
+          target: channel,
+          fetchImpl: bridgeFetch
         }
       );
-      const data = await res.json();
       if (!res.ok) {
         return {
           isError: true,
@@ -741,15 +1093,19 @@ server.tool(
   },
   async ({ channel, task_number, status }) => {
     try {
-      const res = await bridgeFetch(
+      const { response: res, data } = await executeJsonRequest(
         `${serverUrl}/internal/agent/${agentId}/tasks/update-status`,
         {
           method: "POST",
           headers: commonHeaders,
           body: JSON.stringify({ channel, task_number, status })
+        },
+        {
+          toolName: "update_task_status",
+          target: channel,
+          fetchImpl: bridgeFetch
         }
       );
-      const data = await res.json();
       if (!res.ok) {
         return {
           isError: true,