@channlize/mcp 0.4.0 → 0.6.0

package/dist/agents.mjs

@@ -0,0 +1,1332 @@
+// src/agents.ts
+import * as z from "zod/v4";
+
+// src/api.ts
+import {
+  ChannlizeClient,
+  ChannlizeError,
+  parseApiError
+} from "@channlize/core";
+var ToolError = class extends Error {
+  constructor(message2, statusCode, code, retryAt) {
+    super(message2);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.retryAt = retryAt;
+    this.name = "ToolError";
+  }
+  statusCode;
+  code;
+  retryAt;
+};
+
+// src/agents-summary.ts
+var num = (v) => typeof v === "number" ? v : Number(v) || 0;
+var arr = (v) => Array.isArray(v) ? v : [];
+var obj = (v) => v && typeof v === "object" ? v : {};
+var str = (v) => typeof v === "string" ? v : null;
+function money(v) {
+  return Math.round(num(v) * 1e4) / 1e4;
+}
+function fmtMoney(v) {
+  return money(v).toFixed(4).replace(/\.?0+$/, "") || "0";
+}
+function pct(v) {
+  return v === null || v === void 0 ? "n/a" : `${Math.round(num(v) * 1e3) / 10}%`;
+}
+function fmtMs(v) {
+  if (v === null || v === void 0) return "n/a";
+  const ms = num(v);
+  if (ms < 1e3) return `${Math.round(ms)}ms`;
+  if (ms < 6e4) return `${Math.round(ms / 100) / 10}s`;
+  if (ms < 36e5) return `${Math.round(ms / 6e3) / 10}m`;
+  return `${Math.round(ms / 36e4) / 10}h`;
+}
+function highlightText(html) {
+  return html.replace(/<mark>/g, "**").replace(/<\/mark>/g, "**").replace(/<[^>]*>/g, "").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+}
+function clip(text, max) {
+  const s = typeof text === "string" ? text : "";
+  return s.length > max ? `${s.slice(0, max - 1)}\u2026` : s;
+}
+function rangeSummary(range2) {
+  const r = obj(range2);
+  return {
+    from: String(r.from ?? ""),
+    to: String(r.to ?? ""),
+    days: num(r.days),
+    historyStart: str(r.history_start),
+    retentionDays: r.retention_days === void 0 ? null : num(r.retention_days),
+    clamped: Boolean(r.clamped),
+    empty: Boolean(r.empty)
+  };
+}
+function rangeNote(r) {
+  const base = `${r.from}..${r.to} (${r.days} day${r.days === 1 ? "" : "s"}, UTC)`;
+  return r.clamped ? `${base}; clamped to the plan's history start ${r.historyStart}` : base;
+}
+function latency(v) {
+  const l = obj(v);
+  return {
+    count: num(l.count),
+    avgMs: l.avg_ms === null || l.avg_ms === void 0 ? null : num(l.avg_ms),
+    p50Ms: l.p50_ms === null || l.p50_ms === void 0 ? null : num(l.p50_ms),
+    p90Ms: l.p90_ms === null || l.p90_ms === void 0 ? null : num(l.p90_ms)
+  };
+}
+function summarizeSearch(r) {
+  const results = arr(r.results).map((x) => {
+    const channel = x.channel ? obj(x.channel) : null;
+    const base = {
+      kind: String(x.kind),
+      highlight: clip(highlightText(String(x.highlight ?? "")), 400),
+      rank: Math.round(num(x.rank) * 1e3) / 1e3,
+      channel: channel ? str(channel.slug) ?? str(channel.id) : null,
+      channelId: channel ? str(channel.id) : null,
+      threadId: str(x.thread_id),
+      slackPermalink: str(x.slack_permalink)
+    };
+    if (x.kind === "question") {
+      const q = obj(x.question);
+      const answer = q.answer ? obj(q.answer) : null;
+      return {
+        ...base,
+        id: String(q.id ?? ""),
+        type: "question",
+        text: clip(q.question, 500),
+        status: str(q.status),
+        answer: answer ? clip(
+          [answer.option_label ?? answer.option_id, answer.text].filter(Boolean).join(" / "),
+          200
+        ) || null : null,
+        sender: str(q.agent_id) ? `agent:${String(q.agent_id)}` : null,
+        createdAt: str(q.created_at)
+      };
+    }
+    const m = obj(x.message);
+    const sender = obj(m.sender);
+    const senderId = sender.agent_id ?? sender.user_id ?? sender.slack_user_id;
+    return {
+      ...base,
+      id: String(m.id ?? ""),
+      type: String(m.type ?? "message"),
+      text: clip(m.text, 500),
+      status: str(m.task_status),
+      answer: null,
+      sender: sender.kind ? `${String(sender.kind)}${senderId ? `:${String(senderId)}` : ""}` : null,
+      createdAt: str(m.created_at)
+    };
+  });
+  const window = obj(r.window);
+  return {
+    results,
+    nextCursor: str(r.next_cursor),
+    window: { from: String(window.from ?? ""), days: num(window.days) }
+  };
+}
+function summarizeGraph(r, top2) {
+  const range2 = rangeSummary(r.range);
+  const nodes = arr(r.nodes);
+  const labels = new Map(nodes.map((n) => [String(n.id), String(n.label)]));
+  const topNodes = [...nodes].sort(
+    (a, b) => num(b.sent) + num(b.received) - (num(a.sent) + num(a.received))
+  ).slice(0, top2).map((n) => ({
+    id: String(n.id),
+    kind: String(n.kind),
+    label: String(n.label),
+    slug: str(n.slug),
+    sent: num(n.sent),
+    received: num(n.received),
+    tokens: num(n.tokens),
+    cost: money(n.cost)
+  }));
+  const edges = arr(r.edges);
+  const topEdges = [...edges].sort((a, b) => num(b.messages) - num(a.messages)).slice(0, top2).map((e) => {
+    const l = latency(e.reply_latency);
+    return {
+      source: String(e.source),
+      target: String(e.target),
+      from: labels.get(String(e.source)) ?? String(e.source),
+      to: labels.get(String(e.target)) ?? String(e.target),
+      messages: num(e.messages),
+      replies: num(e.replies),
+      cost: money(e.cost),
+      replyAvgMs: l.avgMs,
+      replyP90Ms: l.p90Ms,
+      lastAt: str(e.last_at)
+    };
+  });
+  const totals = obj(r.totals);
+  const truncated = obj(r.truncated);
+  const t = {
+    nodes: num(totals.nodes),
+    edges: num(totals.edges),
+    messages: num(totals.messages),
+    tokens: num(totals.tokens),
+    cost: money(totals.cost)
+  };
+  const busiest = topEdges[0];
+  return {
+    range: range2,
+    totals: t,
+    topNodes,
+    topEdges,
+    /** Not shown here: beyond `top`, or folded / dropped by the API's cap. */
+    omitted: {
+      nodes: Math.max(0, nodes.length - topNodes.length),
+      edges: Math.max(0, edges.length - topEdges.length),
+      cappedNodes: num(truncated.nodes),
+      cappedEdges: num(truncated.edges)
+    },
+    summary: range2.empty ? `No visible activity in ${rangeNote(range2)}.` : `${t.nodes} participants, ${t.edges} edges, ${t.messages} messages, cost ${fmtMoney(t.cost)} over ${rangeNote(range2)}.` + (busiest ? ` Busiest edge: ${busiest.from} \u2192 ${busiest.to} (${busiest.messages} messages, reply avg ${fmtMs(busiest.replyAvgMs)}).` : "")
+  };
+}
+function summarizeCost(r, top2) {
+  const range2 = rangeSummary(r.range);
+  const totals = obj(r.totals);
+  const t = {
+    messages: num(totals.messages),
+    pricedMessages: num(totals.priced_messages),
+    tokens: num(totals.tokens),
+    cost: money(totals.cost)
+  };
+  const all = arr(r.groups);
+  const groups = all.slice(0, top2).map((g) => ({
+    key: String(g.key),
+    label: clip(g.label, 120),
+    messages: num(g.messages),
+    tokens: num(g.tokens),
+    cost: money(g.cost),
+    share: g.share === null || g.share === void 0 ? null : num(g.share)
+  }));
+  const active = arr(r.series).filter(
+    (d) => num(d.messages) > 0 || num(d.cost) > 0
+  );
+  const daily = active.slice(-31).map((d) => ({
+    day: String(d.day),
+    messages: num(d.messages),
+    tokens: num(d.tokens),
+    cost: money(d.cost)
+  }));
+  const peak = active.reduce(
+    (best, d) => !best || num(d.cost) > num(best.cost) ? d : best,
+    null
+  );
+  const groupBy = String(r.group_by ?? "agent");
+  const head = groups.slice(0, 3).map((g) => `${g.label} ${fmtMoney(g.cost)} (${pct(g.share)})`).join(", ");
+  return {
+    range: range2,
+    groupBy,
+    totals: t,
+    groups,
+    omittedGroups: Math.max(0, all.length - groups.length),
+    /** The API had more groups than it returned. */
+    truncated: Boolean(r.truncated),
+    daily,
+    peakDay: peak ? { day: String(peak.day), cost: money(peak.cost) } : null,
+    summary: range2.empty ? `No visible activity in ${rangeNote(range2)}.` : `Total cost ${fmtMoney(t.cost)} (as reported by agents), ${t.tokens} tokens, ${t.messages} messages (${t.pricedMessages} priced) over ${rangeNote(range2)}.` + (head ? ` Top by ${groupBy}: ${head}.` : "")
+  };
+}
+function pair(v) {
+  const p = obj(v);
+  const l = latency(p.latency);
+  return {
+    messages: num(p.messages),
+    replied: num(p.replied),
+    replyRate: p.reply_rate === null || p.reply_rate === void 0 ? null : num(p.reply_rate),
+    avgMs: l.avgMs,
+    p50Ms: l.p50Ms,
+    p90Ms: l.p90Ms
+  };
+}
+function summarizeMetrics(r, top2) {
+  const range2 = rangeSummary(r.range);
+  const replies = obj(r.replies);
+  const q = obj(r.questions);
+  const qLatency = latency(q.time_to_human_answer);
+  const byUrgency = obj(q.by_urgency);
+  const d = obj(r.deliveries);
+  const byMode = obj(d.by_mode);
+  const backlog = obj(r.backlog);
+  const rate = (v) => v === null || v === void 0 ? null : num(v);
+  const out = {
+    range: range2,
+    replies: {
+      agentToAgent: pair(replies.agent_to_agent),
+      humanToAgent: pair(replies.human_to_agent),
+      agentToHuman: pair(replies.agent_to_human),
+      byAgent: arr(replies.by_agent).slice(0, top2).map((a) => {
+        const l = latency(a.latency);
+        return {
+          agentId: String(a.agent_id),
+          name: str(a.name),
+          messages: num(a.messages),
+          replied: num(a.replied),
+          avgMs: l.avgMs,
+          p90Ms: l.p90Ms
+        };
+      })
+    },
+    questions: {
+      asked: num(q.asked),
+      answered: num(q.answered),
+      answeredByUser: num(q.answered_by_user),
+      answeredByAgent: num(q.answered_by_agent),
+      expired: num(q.expired),
+      expiredDefault: num(q.expired_default),
+      canceled: num(q.canceled),
+      answerRate: rate(q.answer_rate),
+      timeToHumanAnswer: {
+        count: qLatency.count,
+        avgMs: qLatency.avgMs,
+        p50Ms: qLatency.p50Ms,
+        p90Ms: qLatency.p90Ms
+      },
+      byUrgency: Object.fromEntries(
+        ["low", "normal", "high", "urgent"].map((u) => {
+          const b = obj(byUrgency[u]);
+          return [
+            u,
+            {
+              asked: num(b.asked),
+              answerRate: rate(b.answer_rate),
+              p50Ms: latency(b.time_to_human_answer).p50Ms
+            }
+          ];
+        })
+      )
+    },
+    deliveries: {
+      deliveries: num(d.deliveries),
+      failed: num(d.failed),
+      retried: num(d.retried),
+      failureRate: rate(d.failure_rate),
+      retryRate: rate(d.retry_rate),
+      byMode: Object.fromEntries(
+        ["webhook", "inbox", "a2a"].map((m) => {
+          const b = obj(byMode[m]);
+          return [
+            m,
+            {
+              deliveries: num(b.deliveries),
+              failed: num(b.failed),
+              held: num(b.held),
+              failureRate: rate(b.failure_rate),
+              retryRate: rate(b.retry_rate)
+            }
+          ];
+        })
+      )
+    },
+    backlog: {
+      asOf: String(backlog.as_of ?? ""),
+      unacked: num(backlog.unacked),
+      held: num(backlog.held),
+      agentsWithBacklog: num(backlog.agents_with_backlog),
+      agents: arr(backlog.agents).slice(0, top2).map((a) => ({
+        agentId: String(a.agent_id),
+        name: str(a.name),
+        delivery: str(a.delivery),
+        unacked: num(a.unacked),
+        held: num(a.held),
+        oldestAgeSeconds: a.oldest_age_seconds === null || a.oldest_age_seconds === void 0 ? null : num(a.oldest_age_seconds)
+      }))
+    },
+    summary: ""
+  };
+  const h2a = out.replies.humanToAgent;
+  const a2a = out.replies.agentToAgent;
+  out.summary = `Over ${rangeNote(range2)}: agents answered people in avg ${fmtMs(h2a.avgMs)} (p90 ${fmtMs(h2a.p90Ms)}, ${pct(h2a.replyRate)} replied) and other agents in avg ${fmtMs(a2a.avgMs)} (p90 ${fmtMs(a2a.p90Ms)}). Questions: ${out.questions.asked} asked, ${pct(out.questions.answerRate)} answered, human answer p50 ${fmtMs(out.questions.timeToHumanAnswer.p50Ms)}. Deliveries: ${out.deliveries.deliveries}, ${pct(out.deliveries.failureRate)} failed, ${pct(out.deliveries.retryRate)} retried. Backlog now: ${out.backlog.unacked} unacked, ${out.backlog.held} held.`;
+  return out;
+}
+
+// src/agents.ts
+function defineTool(tool) {
+  return tool;
+}
+var AGENT_TASK_STATUSES = [
+  "open",
+  "working",
+  "input_required",
+  "completed",
+  "failed",
+  "canceled",
+  "rejected"
+];
+var uuid = (what) => z.string().uuid().describe(what);
+var agentId = uuid(
+  "The agent to act as (from list_agents). Needed with a multi-agent key unless the server has a default agent (CHANNLIZE_AGENT_ID); leave it out with an agent key."
+).optional();
+var channelId = uuid("Agent channel ID (from list_agent_channels)");
+var threadId = uuid(
+  "Reply in this thread: the id of any message in it (thread_id or id from read_agent_inbox)"
+).optional();
+var mentions = z.array(z.string().uuid()).max(50).optional().describe("Agent IDs to mention (from list_agents)");
+var data = z.record(z.string(), z.unknown()).optional().describe("Structured data for the recipients (JSON object)");
+var usage = {
+  tokens: z.number().int().min(0).optional().describe("Tokens you used for this message (reporting)"),
+  cost: z.number().min(0).optional().describe("What this message cost you, in USD (reporting)")
+};
+var message = z.looseObject({
+  id: z.string(),
+  channel_id: z.string(),
+  thread_id: z.string().nullable(),
+  type: z.string(),
+  text: z.string(),
+  sender: z.looseObject({ kind: z.string() }),
+  task_status: z.string().nullable().optional()
+});
+var sendOutput = z.object({
+  message,
+  deliveries: z.array(
+    z.looseObject({ id: z.string(), agent_id: z.string(), status: z.string() })
+  )
+});
+var dueAt = z.string().max(40).optional().describe("Due date: an ISO date (2026-11-30) or date-time");
+var task = z.looseObject({
+  id: z.string(),
+  channel_id: z.string(),
+  text: z.string(),
+  board_status: z.string(),
+  assignee_agent_id: z.string().nullable(),
+  due_at: z.string().nullable()
+});
+var deliveries = z.array(
+  z.looseObject({ id: z.string(), agent_id: z.string(), status: z.string() })
+);
+var question = z.looseObject({
+  id: z.string(),
+  kind: z.string(),
+  question: z.string(),
+  status: z.string(),
+  answer: z.looseObject({}).nullable()
+});
+var questionId = uuid("The question ID (from ask_human or list_questions)");
+var BOARD_STATUSES = [
+  "open",
+  "in_progress",
+  "blocked",
+  "done",
+  "failed"
+];
+var QUESTION_WAIT_MAX_SECONDS = 25;
+var READ = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var SEND = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true
+};
+function actingAs(api, id) {
+  return id ?? api.agentId;
+}
+function requireAgent(api, id) {
+  const agent = actingAs(api, id);
+  if (!agent) {
+    throw new ToolError(
+      "Pass agentId (from list_agents), or set CHANNLIZE_AGENT_ID / --agent-id on the MCP server."
+    );
+  }
+  return agent;
+}
+async function send(api, body) {
+  const r = await api.request(
+    "POST",
+    "/v1/agents/messages",
+    { body }
+  );
+  return { message: r.message, deliveries: r.deliveries ?? [] };
+}
+var enc = encodeURIComponent;
+function outcomeMessage(status, q) {
+  const answer = q.answer ?? {};
+  const choice = answer.option_label ?? answer.option_id;
+  const comment = answer.comment ? `: ${String(answer.comment)}` : "";
+  switch (status) {
+    case "answered":
+      if (q.kind === "approval") {
+        return answer.approved ? `Approved${comment}. Go ahead.` : `Denied${comment}. Don't do it.`;
+      }
+      return `Answered: ${[choice, answer.text].filter(Boolean).join(" / ") || "(empty)"}.`;
+    case "expired_default":
+      return `Nobody answered by the deadline: the default option applies (${String(choice ?? "none")}).`;
+    case "expired":
+      return "Nobody answered by the deadline and there is no default: decide whether to ask again or drop it. For an approval, treat it as not approved.";
+    case "canceled":
+      return "The question was canceled.";
+    default:
+      return `Status: ${status}.`;
+  }
+}
+var AGENT_MESSAGE_TYPES = [
+  "message",
+  "task",
+  "question",
+  "escalation",
+  "status"
+];
+var insightsDay = (what) => z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "expected a YYYY-MM-DD date").optional().describe(what);
+var insightsRange = {
+  from: insightsDay(
+    "First UTC day, YYYY-MM-DD (default: 30 days before to). Clamped to the plan history window."
+  ),
+  to: insightsDay("Last UTC day, inclusive, YYYY-MM-DD (default: today)"),
+  channelId: channelId.optional().describe("Only this agent channel")
+};
+var insightsAgent = uuid(
+  "Only this agent (from list_agents): pass your own id to see your own numbers"
+).optional();
+var mine = z.boolean().optional().describe(
+  "true: only your own agent (the server's default agent, CHANNLIZE_AGENT_ID), when you don't know your id"
+);
+var top = (dflt) => z.number().int().min(1).max(50).default(dflt).describe(`How many rows to return in each list (1-50, default ${dflt})`);
+function filterAgent(api, a) {
+  if (a.agentId) return a.agentId;
+  return a.mine ? requireAgent(api, void 0) : void 0;
+}
+var range = z.looseObject({
+  from: z.string(),
+  to: z.string(),
+  days: z.number(),
+  clamped: z.boolean(),
+  empty: z.boolean()
+});
+var nullableNumber = z.number().nullable();
+var AGENT_TOOLS = [
+  defineTool({
+    name: "send_agent_message",
+    title: "Send agent message",
+    description: "Post a message to an agent channel as your agent. Every other agent in the channel receives it (webhook, inbox or A2A), people see it in Slack and the dashboard, and it counts as one Event. Reply in a thread with threadId; mention agents with mentions. Needs the agents:send scope, and the agent must be a member of the channel.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/messages",
+    inputSchema: z.object({
+      agentId,
+      channelId,
+      text: z.string().min(1).max(4e4).describe("Message text"),
+      threadId,
+      mentions,
+      data,
+      ...usage
+    }),
+    outputSchema: sendOutput,
+    annotations: SEND,
+    handler: (api, a) => send(api, {
+      agent_id: actingAs(api, a.agentId),
+      channel_id: a.channelId,
+      type: "message",
+      text: a.text,
+      thread_id: a.threadId,
+      mentions: a.mentions,
+      data: a.data,
+      tokens: a.tokens,
+      cost: a.cost
+    })
+  }),
+  defineTool({
+    name: "create_task",
+    title: "Create task",
+    description: "Hand a task to an agent of a channel: creates a task (board status open) that starts its own thread, optionally assigned to a member agent (assigneeAgentId, who is mentioned) and with a due date. The returned taskId is for update_task, update_task_status and handoff_task. Your policy may refuse the channel or the assignee (POLICY_* errors). Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/tasks",
+    inputSchema: z.object({
+      agentId,
+      channelId,
+      text: z.string().min(1).max(4e4).describe("What should be done, with enough context to do it"),
+      assigneeAgentId: uuid(
+        "The agent that should do it: a member of the channel (from list_agents)"
+      ).optional(),
+      dueAt,
+      threadId,
+      mentions,
+      data
+    }),
+    // `message` is the task too (a task is its `task` message plus board fields).
+    outputSchema: z.object({ taskId: z.string(), task, message, deliveries }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "POST",
+        "/v1/agents/tasks",
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            channel_id: a.channelId,
+            text: a.text,
+            assignee_agent_id: a.assigneeAgentId,
+            due_at: a.dueAt,
+            thread_id: a.threadId,
+            mentions: a.mentions,
+            data: a.data
+          }
+        }
+      );
+      return {
+        taskId: String(r.task.id),
+        task: r.task,
+        message: r.task,
+        deliveries: r.deliveries ?? []
+      };
+    }
+  }),
+  defineTool({
+    name: "update_task_status",
+    title: "Update task status",
+    description: "Report progress on a task (from create_task or a task in your inbox): working, input_required, completed, failed, canceled or rejected, with an optional note and result data. It is posted in the task thread and moves the task on the board (working \u2192 in_progress, input_required \u2192 blocked, completed \u2192 done; canceled and rejected show as failed). completed, failed, canceled and rejected are final: a closed task cannot be reopened (TASK_CLOSED). To change the due date, use update_task. Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/messages",
+    inputSchema: z.object({
+      agentId,
+      channelId,
+      taskId: uuid("The task message ID"),
+      status: z.enum(AGENT_TASK_STATUSES).describe("The new status of the task"),
+      text: z.string().max(4e4).optional().describe("What changed, e.g. the result or what input is needed"),
+      data,
+      ...usage
+    }),
+    outputSchema: sendOutput,
+    annotations: SEND,
+    handler: (api, a) => send(api, {
+      agent_id: actingAs(api, a.agentId),
+      channel_id: a.channelId,
+      type: "status",
+      text: a.text ?? "",
+      task_id: a.taskId,
+      task_status: a.status,
+      data: a.data,
+      tokens: a.tokens,
+      cost: a.cost
+    })
+  }),
+  defineTool({
+    name: "update_task",
+    title: "Update task",
+    description: "Move a task on the board (open, in_progress, blocked, done, failed) and/or change its due date, with a note: posted as a status update in the task thread, recorded in the task's history and shown on its Slack card. Only the task's assignee or creator can change it (NOT_TASK_PARTICIPANT), and a closed task can't change (TASK_CLOSED). To cancel or reject, or to attach result data, use update_task_status. Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "PATCH /v1/agents/tasks/:taskId",
+    inputSchema: z.object({
+      agentId,
+      taskId: uuid("The task ID"),
+      status: z.enum(BOARD_STATUSES).optional().describe("The board column"),
+      dueAt: z.string().max(40).nullable().optional().describe("New due date (ISO date or date-time); null clears it"),
+      note: z.string().max(2e3).optional().describe("What changed, shown with the update")
+    }),
+    outputSchema: z.object({ task, changed: z.boolean() }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      if (a.status === void 0 && a.dueAt === void 0) {
+        throw new ToolError("Pass status or dueAt.");
+      }
+      const r = await api.request(
+        "PATCH",
+        `/v1/agents/tasks/${enc(a.taskId)}`,
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            status: a.status,
+            due_at: a.dueAt,
+            note: a.note
+          }
+        }
+      );
+      return { task: r.task, changed: Boolean(r.changed) };
+    }
+  }),
+  defineTool({
+    name: "handoff_task",
+    title: "Hand off task",
+    description: "Hand a task you are assigned to (or created) to another member agent of its channel, with the reason: the new and the previous assignee get a status message (data.handoff), and it's recorded in the task's history. Use it when another agent is better placed, then stop working on the task. Errors: ALREADY_ASSIGNED, AGENT_NOT_IN_CHANNEL, TASK_CLOSED, NOT_TASK_PARTICIPANT, POLICY_DM_NOT_ALLOWED. Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/tasks/:taskId/handoff",
+    inputSchema: z.object({
+      agentId,
+      taskId: uuid("The task ID"),
+      toAgentId: uuid("The new assignee (from list_agents or get_org_chart)"),
+      reason: z.string().max(2e3).optional().describe("Why, and what the new assignee needs to know")
+    }),
+    outputSchema: z.object({ task, deliveries }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "POST",
+        `/v1/agents/tasks/${enc(a.taskId)}/handoff`,
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            to_agent_id: a.toAgentId,
+            reason: a.reason
+          }
+        }
+      );
+      return {
+        task: r.task,
+        deliveries: r.deliveries ?? []
+      };
+    }
+  }),
+  defineTool({
+    name: "list_tasks",
+    title: "List tasks",
+    description: "List a channel's tasks, newest first, with their board status (open, in_progress, blocked, done, failed), assignee, due date and last handoff. Filter by assignee (your own agent id for your work) or status. channelId is required unless the key is an agents:admin key. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/tasks",
+    inputSchema: z.object({
+      agentId,
+      channelId: channelId.optional(),
+      assigneeAgentId: uuid("Only tasks assigned to this agent").optional(),
+      status: z.enum(BOARD_STATUSES).optional(),
+      limit: z.number().int().min(1).max(500).default(50).describe("How many to return (1-500, default 50)")
+    }),
+    outputSchema: z.object({ tasks: z.array(task) }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "GET",
+        "/v1/agents/tasks",
+        {
+          query: {
+            agent_id: actingAs(api, a.agentId),
+            channel_id: a.channelId,
+            assignee_agent_id: a.assigneeAgentId,
+            status: a.status,
+            limit: a.limit
+          }
+        }
+      );
+      return { tasks: r.tasks ?? [] };
+    }
+  }),
+  defineTool({
+    name: "get_task_board",
+    title: "Get task board",
+    description: "A channel's task board: tasks grouped by column (open, in_progress, blocked, done, failed), counts per column, and the agents on it. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/tasks/board",
+    inputSchema: z.object({
+      agentId,
+      channelId,
+      assigneeAgentId: uuid("Only tasks assigned to this agent").optional()
+    }),
+    outputSchema: z.object({
+      channel_id: z.string(),
+      columns: z.record(z.string(), z.array(task)),
+      counts: z.record(z.string(), z.number()),
+      agents: z.array(z.looseObject({ id: z.string() })),
+      truncated: z.boolean()
+    }),
+    annotations: READ,
+    handler: async (api, a) => await api.request("GET", "/v1/agents/tasks/board", {
+      query: {
+        agent_id: actingAs(api, a.agentId),
+        channel_id: a.channelId,
+        assignee_agent_id: a.assigneeAgentId
+      }
+    })
+  }),
+  defineTool({
+    name: "ask_human",
+    title: "Ask a human",
+    description: "Ask people a question, or for an approval (kind approval: Approve / Deny), when you can't or shouldn't decide alone. It's posted in Slack (the channel's linked Slack channel, else the escalation channel) with a button per option, and escalates (manager, owner, supervisors, escalation channel) until someone answers or the deadline passes; with a defaultOption, the default applies at the deadline. Returns at once with the questionId: then call get_answer, which waits for the answer. Don't act on what you asked about before the answer. Counts as one Event. Your policy may refuse (POLICY_ASK_HUMAN_NOT_ALLOWED, POLICY_URGENCY_NOT_ALLOWED). Needs the agents:ask_human scope.",
+    scope: "agents:ask_human",
+    endpoint: "POST /v1/agents/questions",
+    inputSchema: z.object({
+      agentId,
+      kind: z.enum(["question", "approval"]).default("question").describe("question (default) or approval (answered Approve / Deny)"),
+      question: z.string().min(1).max(3e3).describe("The question, with what people need to answer it"),
+      options: z.array(
+        z.object({
+          id: z.string().min(1).max(100),
+          label: z.string().min(1).max(75)
+        })
+      ).max(10).optional().describe("Up to 10 answers to pick from (ignored for approvals)"),
+      freeText: z.boolean().optional().describe("Allow a typed answer (always on without options)"),
+      urgency: z.enum(["low", "normal", "high", "urgent"]).optional().describe("How fast it escalates (default normal)"),
+      deadline: z.string().max(40).optional().describe("ISO date-time, at most 30 days away"),
+      defaultOption: z.string().max(100).optional().describe("Option id applied at the deadline when nobody answered"),
+      channelId: channelId.optional().describe("Post it in this agent channel (from list_agent_channels)"),
+      threadId,
+      context: z.record(z.string(), z.unknown()).optional().describe("Facts shown with the question (JSON object)"),
+      amount: z.number().min(0).optional().describe("Approvals: the amount at stake"),
+      currency: z.string().regex(/^[A-Za-z]{3}$/).optional().describe("Approvals: ISO 4217 currency code"),
+      resource: z.record(z.string(), z.unknown()).optional().describe("Approvals: what is being approved (JSON object)"),
+      requiredRoles: z.array(z.string().min(1).max(40)).max(10).optional().describe('Approvals: roles that may answer, e.g. ["admin"]')
+    }),
+    outputSchema: z.object({ questionId: z.string(), question }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "POST",
+        "/v1/agents/questions",
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            kind: a.kind,
+            question: a.question,
+            options: a.options,
+            free_text: a.freeText,
+            urgency: a.urgency,
+            deadline: a.deadline,
+            default_option: a.defaultOption,
+            channel_id: a.channelId,
+            thread_id: a.threadId,
+            context: a.context,
+            amount: a.amount,
+            currency: a.currency,
+            resource: a.resource,
+            required_roles: a.requiredRoles
+          }
+        }
+      );
+      return {
+        questionId: String(r.question.id),
+        question: r.question
+      };
+    }
+  }),
+  defineTool({
+    name: "get_answer",
+    title: "Get answer",
+    description: `Wait for the answer to a question from ask_human: holds up to waitSeconds (default and maximum ${QUESTION_WAIT_MAX_SECONDS}) and returns as soon as it closes. status is answered (answer.option_id / answer.text; approvals have answer.approved), expired_default (the default option applied), expired (no answer by the deadline) or canceled. When waiting is true nobody has answered yet: call get_answer again, or do other work and come back. Needs the agents:ask_human scope (or agents:read).`,
+    scope: "agents:ask_human",
+    endpoint: "GET /v1/agents/questions/:id/wait",
+    inputSchema: z.object({
+      agentId,
+      questionId,
+      waitSeconds: z.number().int().min(0).max(QUESTION_WAIT_MAX_SECONDS).default(QUESTION_WAIT_MAX_SECONDS).describe(
+        `Seconds to wait for an answer (0-${QUESTION_WAIT_MAX_SECONDS}, default ${QUESTION_WAIT_MAX_SECONDS}); 0 only checks`
+      )
+    }),
+    outputSchema: z.object({
+      questionId: z.string(),
+      status: z.string(),
+      waiting: z.boolean(),
+      answer: z.looseObject({}).nullable(),
+      message: z.string(),
+      question
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "GET",
+        `/v1/agents/questions/${enc(a.questionId)}/wait`,
+        {
+          query: {
+            agent_id: actingAs(api, a.agentId),
+            timeout: a.waitSeconds
+          },
+          // The API holds the request for up to waitSeconds.
+          timeout: (a.waitSeconds + 10) * 1e3
+        }
+      );
+      const status = String(r.question.status);
+      const waiting = status === "open";
+      return {
+        questionId: a.questionId,
+        status,
+        waiting,
+        answer: r.question.answer ?? null,
+        message: waiting ? `Still waiting: nobody has answered yet. Call get_answer again with questionId ${a.questionId}, or check back later; don't act on the question meanwhile.` : outcomeMessage(status, r.question),
+        question: r.question
+      };
+    }
+  }),
+  defineTool({
+    name: "list_questions",
+    title: "List questions",
+    description: "List your questions and the ones escalated to you as a manager agent, newest first. Filter with status open to find what still needs an answer (answer_escalated_question). Needs the agents:read scope (or agents:ask_human).",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/questions",
+    inputSchema: z.object({
+      agentId,
+      status: z.enum(["open", "answered", "expired_default", "expired", "canceled"]).optional(),
+      kind: z.enum(["question", "approval"]).optional(),
+      channelId: channelId.optional(),
+      cursor: z.string().max(300).optional().describe("nextCursor of the previous call"),
+      limit: z.number().int().min(1).max(200).default(20).describe("How many to return (1-200, default 20)")
+    }),
+    outputSchema: z.object({
+      questions: z.array(question),
+      nextCursor: z.string().nullable()
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request("GET", "/v1/agents/questions", {
+        query: {
+          agent_id: actingAs(api, a.agentId),
+          status: a.status,
+          kind: a.kind,
+          channel_id: a.channelId,
+          cursor: a.cursor,
+          limit: a.limit
+        }
+      });
+      return {
+        questions: r.questions ?? [],
+        nextCursor: r.next_cursor ?? null
+      };
+    }
+  }),
+  defineTool({
+    name: "cancel_question",
+    title: "Cancel question",
+    description: "Cancel one of your open questions when it no longer matters (you found the answer, the work was dropped): its Slack post is updated and escalation stops. Only the agent that asked can cancel, and a closed question can't be (QUESTION_CLOSED). Needs the agents:ask_human scope.",
+    scope: "agents:ask_human",
+    endpoint: "DELETE /v1/agents/questions/:id",
+    inputSchema: z.object({ agentId, questionId }),
+    outputSchema: z.object({ question }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    handler: async (api, a) => {
+      const r = await api.request(
+        "DELETE",
+        `/v1/agents/questions/${enc(a.questionId)}`,
+        { query: { agent_id: actingAs(api, a.agentId) } }
+      );
+      return { question: r.question };
+    }
+  }),
+  defineTool({
+    name: "answer_escalated_question",
+    title: "Answer escalated question",
+    description: "Answer a question another agent asked, when it was escalated to you as its manager agent (a question.escalated delivery, or list_questions with status open). Pick an optionId (approve / deny for approvals, with a comment), or give text when free text is allowed. The first answer wins (QUESTION_CLOSED after), approvals that require a role need a person (APPROVAL_ROLE_REQUIRED), and you can't answer your own question. Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/questions/:id/answer",
+    inputSchema: z.object({
+      agentId,
+      questionId,
+      optionId: z.string().min(1).max(100).optional().describe("One of the question options (approve / deny for approvals)"),
+      text: z.string().max(3e3).optional().describe("A typed answer, when the question allows free text"),
+      comment: z.string().max(2e3).optional().describe("Why (shown with the answer; say why on a deny)")
+    }),
+    outputSchema: z.object({ question }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      if (!a.optionId && !a.text) throw new ToolError("Pass optionId or text.");
+      const r = await api.request(
+        "POST",
+        `/v1/agents/questions/${enc(a.questionId)}/answer`,
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            option_id: a.optionId,
+            text: a.text,
+            comment: a.comment
+          }
+        }
+      );
+      return { question: r.question };
+    }
+  }),
+  defineTool({
+    name: "get_org_chart",
+    title: "Get org chart",
+    description: "The organization's agents with their manager (an agent or a person), owner and teams, the teams, and the reporting tree. Use it to find who to hand a task off to, or who manages an agent. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/org-chart",
+    inputSchema: z.object({
+      teamId: uuid("Only this team").optional(),
+      channelId: uuid("Only the agents of this channel").optional(),
+      includeRetired: z.boolean().optional().describe("Include retired agents (default false)")
+    }),
+    outputSchema: z.object({
+      agents: z.array(z.looseObject({ id: z.string() })),
+      users: z.array(z.looseObject({ id: z.string() })),
+      teams: z.array(z.looseObject({ id: z.string() })),
+      tree: z.array(z.looseObject({}))
+    }),
+    annotations: READ,
+    handler: async (api, a) => await api.request("GET", "/v1/agents/org-chart", {
+      query: {
+        team_id: a.teamId,
+        channel_id: a.channelId,
+        include_retired: a.includeRetired ? "true" : void 0
+      }
+    })
+  }),
+  defineTool({
+    name: "get_effective_policy",
+    title: "Get effective policy",
+    description: "The policy in force for an agent (in a channel): the merged rules (allowed channels, direct messages, asking humans, rate, budgets, working hours, thread depth, humans-win minutes), which policy set each, current usage, working hours now, and with a channel whether it may post and read there now. Read-only. Needs an unbound key with the agents:admin scope: a key bound to agents gets 403 AGENT_ADMIN_KEY_REQUIRED.",
+    scope: "agents:admin",
+    endpoint: "GET /v1/agents/policies/preview",
+    inputSchema: z.object({
+      agentId: uuid(
+        "The agent (from list_agents). Default: the server agent (CHANNLIZE_AGENT_ID)"
+      ).optional(),
+      channelId: channelId.optional()
+    }),
+    outputSchema: z.looseObject({
+      agent_id: z.string(),
+      channel_id: z.string().nullable(),
+      rules: z.looseObject({}),
+      working_hours: z.looseObject({}),
+      usage: z.looseObject({}),
+      checks: z.looseObject({}).nullable()
+    }),
+    annotations: READ,
+    handler: async (api, a) => await api.request("GET", "/v1/agents/policies/preview", {
+      query: {
+        agent_id: requireAgent(api, a.agentId),
+        channel_id: a.channelId
+      }
+    })
+  }),
+  defineTool({
+    name: "read_agent_inbox",
+    title: "Read agent inbox",
+    description: "Read your agent's unacknowledged messages, oldest first: messages, tasks and task status updates from other agents and people, each with its channel, thread and sender. Messages stay until ack_agent_messages acknowledges them, so read, handle, then ack. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/:id/inbox",
+    inputSchema: z.object({
+      agentId,
+      cursor: z.string().max(200).optional().describe("Read after this cursor (nextCursor of the previous call)"),
+      limit: z.number().int().min(1).max(200).default(20).describe("How many to return (1-200, default 20)")
+    }),
+    outputSchema: z.object({
+      agentId: z.string(),
+      messages: z.array(
+        z.looseObject({
+          delivery_id: z.string(),
+          cursor: z.string(),
+          message
+        })
+      ),
+      nextCursor: z.string().nullable(),
+      hasMore: z.boolean()
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const id = requireAgent(api, a.agentId);
+      const r = await api.request("GET", `/v1/agents/${enc(id)}/inbox`, {
+        query: { cursor: a.cursor, limit: a.limit }
+      });
+      return {
+        agentId: id,
+        messages: r.messages ?? [],
+        nextCursor: r.next_cursor ?? null,
+        hasMore: Boolean(r.has_more)
+      };
+    }
+  }),
+  defineTool({
+    name: "ack_agent_messages",
+    title: "Acknowledge agent messages",
+    description: "Acknowledge inbox messages you handled so read_agent_inbox stops returning them: upTo acks everything up to and including that delivery or message ID, ids acks just those. Acking twice is harmless. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "POST /v1/agents/:id/inbox/ack",
+    inputSchema: z.object({
+      agentId,
+      upTo: z.string().uuid().optional().describe("Ack everything up to and including this delivery_id"),
+      ids: z.array(z.string().uuid()).min(1).max(500).optional().describe("Ack these delivery (or message) IDs")
+    }),
+    outputSchema: z.object({ acked: z.number() }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    handler: async (api, a) => {
+      if (!a.upTo === !a.ids) {
+        throw new ToolError("Pass either upTo or ids.");
+      }
+      const id = requireAgent(api, a.agentId);
+      const r = await api.request(
+        "POST",
+        `/v1/agents/${enc(id)}/inbox/ack`,
+        { body: a.upTo ? { up_to: a.upTo } : { ids: a.ids } }
+      );
+      return { acked: Number(r.acked ?? 0) };
+    }
+  }),
+  defineTool({
+    name: "search_agent_messages",
+    title: "Search agent messages",
+    description: `Full-text search over agent channel history: messages, tasks, status updates and questions to people (with their answers), best match first. Use it to find what was said or decided before, a past task, or an answer a human already gave, instead of asking again. q takes websearch syntax: "exact phrase", or, -word; codes and ids match as substrings (INV-20 finds INV-2041). Each result has a highlight (hits in **bold**), the channel, threadId and a Slack link when mirrored. Searches the channels your key's agents can read and their own questions (the whole org for an agents:admin key), within the plan's history window. Page with cursor. Needs the agents:read scope.`,
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/search",
+    inputSchema: z.object({
+      q: z.string().trim().min(2).max(200).describe("What to look for (2-200 characters)"),
+      agentId: uuid(
+        "Only messages sent by or mentioning this agent, and questions it asked (from list_agents). With a multi-agent key it also picks whose channels are searched."
+      ).optional(),
+      channelId: channelId.optional().describe("Only this agent channel"),
+      type: z.enum(AGENT_MESSAGE_TYPES).optional().describe("Only this message type"),
+      include: z.enum(["messages", "questions", "both"]).default("both").describe("messages, questions, or both (default)"),
+      from: z.string().max(40).optional().describe("ISO date-time: the earliest to search"),
+      to: z.string().max(40).optional().describe("ISO date-time: the latest to search"),
+      cursor: z.string().max(300).optional().describe("nextCursor of the previous call"),
+      limit: z.number().int().min(1).max(50).default(10).describe("How many results (1-50, default 10)")
+    }),
+    outputSchema: z.object({
+      results: z.array(
+        z.looseObject({
+          kind: z.string(),
+          id: z.string(),
+          type: z.string(),
+          text: z.string(),
+          highlight: z.string(),
+          channel: z.string().nullable(),
+          threadId: z.string().nullable()
+        })
+      ),
+      nextCursor: z.string().nullable(),
+      window: z.object({ from: z.string(), days: z.number() })
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request("GET", "/v1/agents/search", {
+        query: {
+          q: a.q,
+          agent_id: a.agentId,
+          channel_id: a.channelId,
+          type: a.type,
+          include: a.include === "both" ? void 0 : a.include,
+          from: a.from,
+          to: a.to,
+          cursor: a.cursor,
+          limit: a.limit
+        }
+      });
+      return summarizeSearch(r);
+    }
+  }),
+  defineTool({
+    name: "get_agent_graph",
+    title: "Get agent communication graph",
+    description: "Who talks to whom among agents and people over a range of days: the busiest participants (messages sent and received, tokens, cost) and the busiest sender \u2192 recipient edges (messages, replies, reply latency), with totals and a one-line summary. Rows beyond top are counted in omitted. Filter to one agent (agentId, or mine for your own), a team or a channel. Sees the channels your key's agents can read (the whole org for an agents:admin key). Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/insights/graph",
+    inputSchema: z.object({
+      ...insightsRange,
+      agentId: insightsAgent,
+      mine,
+      teamId: uuid("Only edges touching this team").optional(),
+      top: top(10)
+    }),
+    outputSchema: z.object({
+      range,
+      totals: z.object({
+        nodes: z.number(),
+        edges: z.number(),
+        messages: z.number(),
+        tokens: z.number(),
+        cost: z.number()
+      }),
+      topNodes: z.array(
+        z.looseObject({ id: z.string(), label: z.string(), sent: z.number() })
+      ),
+      topEdges: z.array(
+        z.looseObject({
+          source: z.string(),
+          target: z.string(),
+          messages: z.number(),
+          replyAvgMs: nullableNumber
+        })
+      ),
+      omitted: z.looseObject({ nodes: z.number(), edges: z.number() }),
+      summary: z.string()
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request("GET", "/v1/agents/insights/graph", {
+        query: {
+          from: a.from,
+          to: a.to,
+          channel_id: a.channelId,
+          agent_id: filterAgent(api, a),
+          team_id: a.teamId
+        }
+      });
+      return summarizeGraph(r, a.top);
+    }
+  }),
+  defineTool({
+    name: "get_agent_cost",
+    title: "Get agent cost",
+    description: "What agents spent, from the tokens and cost they reported on their messages: the range's totals, the top groups by cost (groupBy agent, channel, team, task or day) with their share, the active days and the peak day, and a one-line summary. Check your own spend with mine (or agentId), e.g. before starting expensive work or to report it. Cost is in whatever currency agents report (usually USD). Sees the channels your key's agents can read (the whole org for an agents:admin key). Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/insights/cost",
+    inputSchema: z.object({
+      ...insightsRange,
+      groupBy: z.enum(["agent", "channel", "team", "task", "day"]).default("agent").describe("How to break the cost down (default agent)"),
+      agentId: insightsAgent,
+      mine,
+      teamId: uuid("Only what this team's agents sent").optional(),
+      top: top(10)
+    }),
+    outputSchema: z.object({
+      range,
+      groupBy: z.string(),
+      totals: z.object({
+        messages: z.number(),
+        pricedMessages: z.number(),
+        tokens: z.number(),
+        cost: z.number()
+      }),
+      groups: z.array(
+        z.looseObject({
+          key: z.string(),
+          label: z.string(),
+          cost: z.number(),
+          share: nullableNumber
+        })
+      ),
+      omittedGroups: z.number(),
+      truncated: z.boolean(),
+      daily: z.array(z.looseObject({ day: z.string(), cost: z.number() })),
+      peakDay: z.object({ day: z.string(), cost: z.number() }).nullable(),
+      summary: z.string()
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request("GET", "/v1/agents/insights/cost", {
+        query: {
+          from: a.from,
+          to: a.to,
+          channel_id: a.channelId,
+          agent_id: filterAgent(api, a),
+          team_id: a.teamId,
+          group_by: a.groupBy,
+          // Day groups come back whole; the others only need the top ones.
+          limit: a.groupBy === "day" ? void 0 : a.top
+        }
+      });
+      return summarizeCost(r, a.top);
+    }
+  }),
+  defineTool({
+    name: "get_agent_metrics",
+    title: "Get agent metrics",
+    description: "Response metrics over a range of days: reply latency (agent \u2192 agent, human \u2192 agent, agent \u2192 human: avg, p50, p90 and reply rate) and per responding agent, questions to people (answer rate, time to a human answer, by urgency), delivery failure and retry rates per mode, and the inbox backlog right now, with a one-line summary. Use mine (or agentId) to check how fast you answer and whether your inbox is backing up. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/insights/metrics",
+    inputSchema: z.object({
+      ...insightsRange,
+      agentId: insightsAgent,
+      mine,
+      top: top(5)
+    }),
+    outputSchema: z.object({
+      range,
+      replies: z.looseObject({
+        agentToAgent: z.looseObject({ avgMs: nullableNumber }),
+        humanToAgent: z.looseObject({ avgMs: nullableNumber }),
+        agentToHuman: z.looseObject({ avgMs: nullableNumber }),
+        byAgent: z.array(z.looseObject({ agentId: z.string() }))
+      }),
+      questions: z.looseObject({ asked: z.number() }),
+      deliveries: z.looseObject({ deliveries: z.number() }),
+      backlog: z.looseObject({ unacked: z.number(), held: z.number() }),
+      summary: z.string()
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request("GET", "/v1/agents/insights/metrics", {
+        query: {
+          from: a.from,
+          to: a.to,
+          channel_id: a.channelId,
+          agent_id: filterAgent(api, a)
+        }
+      });
+      return summarizeMetrics(r, a.top);
+    }
+  }),
+  defineTool({
+    name: "list_agents",
+    title: "List agents",
+    description: "List the organization's agents: id, slug, name, role, description, status (active, paused, retired) and how they receive messages. Use the ids for mentions and agentId. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents",
+    inputSchema: z.object({
+      includeRetired: z.boolean().optional().describe("Include retired agents (default false)")
+    }),
+    outputSchema: z.object({
+      agents: z.array(
+        z.looseObject({
+          id: z.string(),
+          slug: z.string(),
+          name: z.string(),
+          status: z.string()
+        })
+      )
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request("GET", "/v1/agents", {
+        query: { include_retired: a.includeRetired || void 0 }
+      });
+      return { agents: r.agents ?? [] };
+    }
+  }),
+  defineTool({
+    name: "list_agent_channels",
+    title: "List agent channels",
+    description: "List the agent channels your key's agents are members or observers of: id, slug, name, description and whether they are archived. Post with send_agent_message (members only). Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/channels",
+    inputSchema: z.object({
+      includeArchived: z.boolean().optional().describe("Include archived channels (default false)")
+    }),
+    outputSchema: z.object({
+      channels: z.array(
+        z.looseObject({
+          id: z.string(),
+          slug: z.string(),
+          name: z.string(),
+          archived: z.boolean()
+        })
+      )
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "GET",
+        "/v1/agents/channels",
+        { query: { include_archived: a.includeArchived || void 0 } }
+      );
+      return { channels: r.channels ?? [] };
+    }
+  })
+];
+var AGENT_TOOL_NAMES = AGENT_TOOLS.map((t) => t.name);
+function getAgentTool(name) {
+  return AGENT_TOOLS.find((t) => t.name === name);
+}
+async function runAgentTool(api, name, args) {
+  const tool = getAgentTool(name);
+  if (!tool) throw new ToolError(`Unknown agent tool "${name}"`);
+  const parsed = tool.inputSchema.safeParse(args ?? {});
+  if (!parsed.success) {
+    throw new ToolError(
+      `Invalid arguments for ${name}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ")}`
+    );
+  }
+  return await tool.handler(api, parsed.data);
+}
+function agentToolsAsJsonSchema(filter = () => true) {
+  return AGENT_TOOLS.filter(filter).map((t) => ({
+    name: t.name,
+    description: t.description,
+    parameters: z.toJSONSchema(t.inputSchema, { io: "input" })
+  }));
+}
+export {
+  AGENT_TASK_STATUSES,
+  AGENT_TOOLS,
+  AGENT_TOOL_NAMES,
+  QUESTION_WAIT_MAX_SECONDS,
+  agentToolsAsJsonSchema,
+  getAgentTool,
+  runAgentTool
+};
+//# sourceMappingURL=agents.mjs.map