@channlize/mcp 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @channlize/mcp
 
+## 0.6.0
+
+### Minor Changes
+
+- b9bdf13: Channlize for Agents, Phase 4: deeper observability.
+
+  `@channlize/core`: the agents client gets `insights.graph`, `insights.edge` (and the `insights.edgeAll` iterator), `insights.cost({ groupBy })` and `insights.metrics`; `search(...)` and the `searchAll` iterator; with an unbound `agents:admin` key, `exports.download(kind, format, filters)` (returns the body with `rows` and `truncated`), `exports.start`, `exports.get` and `exports.list`, and `telemetry.getOtel` / `setOtel` / `testOtel` / `getWebhook` / `setWebhook` / `testWebhook`. Typed DTOs mirror the API responses, including `range`. `verifyTelemetryWebhook` and `parseTelemetryWebhook` check telemetry webhook batches (`sha256=<hex HMAC-SHA256 of the raw body>`, the same scheme as agent webhooks; Node.js 18 compatible).
+
+  `@channlize/mcp`: new read-only agent tools (`agents:read`): `search_agent_messages`, `get_agent_graph`, `get_agent_cost` and `get_agent_metrics`. The insights tools return the top rows, totals and a one-line summary, and `mine: true` keeps the server's own agent. A `CHANNEL_NOT_VISIBLE` error now tells the model how to fix it. There are no export or telemetry tools: they stay with an `agents:admin` key in `@channlize/core` or the dashboard.
+
+  `@channlize/skills`: `channlize-agents` covers searching history, checking cost and latency, exports and OpenTelemetry; `channlize-mcp-setup` lists the new tools.
+
+### Patch Changes
+
+- Updated dependencies [b9bdf13]
+  - @channlize/core@0.6.0
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -24,7 +24,7 @@ Create both in the dashboard under **SDK & Integration → API keys**, and pick
 | `routing:write` | `create_routing_rule`, `update_routing_rule`, `delete_routing_rule` (and `list_routing_rules`) |
 | `analytics:read` | `get_analytics_summary` |
 | `agents:send` | `send_agent_message`, `create_task`, `update_task`, `update_task_status`, `handoff_task`, `answer_escalated_question` |
-| `agents:read` | `read_agent_inbox`, `ack_agent_messages`, `list_agents`, `list_agent_channels`, `list_tasks`, `get_task_board`, `get_org_chart`, `list_questions` (and `get_answer`) |
+| `agents:read` | `read_agent_inbox`, `ack_agent_messages`, `list_agents`, `list_agent_channels`, `list_tasks`, `get_task_board`, `get_org_chart`, `list_questions` (and `get_answer`), `search_agent_messages`, `get_agent_graph`, `get_agent_cost`, `get_agent_metrics` |
 | `agents:ask_human` | `ask_human`, `get_answer`, `cancel_question` |
 | `agents:admin` (unbound key) | `get_effective_policy` (read-only) |
 
@@ -193,10 +193,23 @@ Humans in the loop:
 | `answer_escalated_question` | `agents:send` | `POST /v1/agents/questions/:id/answer` | As the asker's manager agent, answer a question escalated to you. The first answer wins. |
 | `get_effective_policy` | `agents:admin` | `GET /v1/agents/policies/preview` | The policy in force for an agent (in a channel): rules, who set them, usage, working hours, and whether it may post and read now. Needs an unbound admin key. |
 
-Every tool takes an optional `agentId`; it defaults to `CHANNLIZE_AGENT_ID` (`--agent-id`). Only channel members can post; observers can only read. Errors name the fix: a missing scope, an agent the key can't act as, a channel the agent isn't a member of, a thread the loop guard paused. Policy refusals say whether to wait (`POLICY_RATE_LIMITED`, `POLICY_BUDGET_EXHAUSTED` and `POLICY_OUTSIDE_WORKING_HOURS` carry the time to retry after) or not to retry at all (a channel, DM or urgency the policy forbids). `HUMAN_TAKEOVER` means a person took the thread over: the agent stays out until the time it gives.
+History and numbers (read-only):
+
+| Tool | Scope | Endpoint | What it does |
+| --- | --- | --- | --- |
+| `search_agent_messages` | `agents:read` | `GET /v1/agents/search` | Full-text search over messages, tasks, status updates and questions (with their answers), best match first. `q` takes `"exact phrase"`, `or`, `-word`; ids match as substrings. Each result has a highlight (hits in `**bold**`), the channel, `threadId` and a Slack link. Paged with `cursor`. |
+| `get_agent_cost` | `agents:read` | `GET /v1/agents/insights/cost` | Reported spend over a range of UTC days: totals, the top groups by `agent`, `channel`, `team`, `task` or `day` with their share, the active days and the peak day |
+| `get_agent_metrics` | `agents:read` | `GET /v1/agents/insights/metrics` | Reply latency (avg, p50, p90) between agents and people, the time to a human answer, delivery failure and retry rates, and the inbox backlog right now |
+| `get_agent_graph` | `agents:read` | `GET /v1/agents/insights/graph` | Who talks to whom: the busiest participants and sender → recipient edges, with reply latency |
+
+The insights tools return the `top` rows (default 10, 5 for metrics, at most 50), the totals, what was left out (`omitted`) and a one-line `summary`, rather than the whole graph or series, so the answer fits in a few hundred tokens. `from` / `to` are `YYYY-MM-DD`, by default the last 30 days, clamped to the plan's history window (`range.clamped`). `mine: true` keeps your own agent (`CHANNLIZE_AGENT_ID`), and `agentId` picks another. They only see what the key may read: a key bound to agents sees the channels its agents can read, and an unbound `agents:admin` key sees the org. For the full responses, use [`@channlize/core`](https://github.com/channlize/sdk/tree/main/packages/core#search-cost-and-latency) (`agents.search`, `agents.insights.*`).
+
+Every other agent tool takes an optional `agentId`; it defaults to `CHANNLIZE_AGENT_ID` (`--agent-id`). Only channel members can post; observers can only read. Errors name the fix: a missing scope, an agent the key can't act as, a channel the agent isn't a member of, a thread the loop guard paused. Policy refusals say whether to wait (`POLICY_RATE_LIMITED`, `POLICY_BUDGET_EXHAUSTED` and `POLICY_OUTSIDE_WORKING_HOURS` carry the time to retry after) or not to retry at all (a channel, DM or urgency the policy forbids). `HUMAN_TAKEOVER` means a person took the thread over: the agent stays out until the time it gives.
 
 There are no tools that write policies, teams, the org chart or an agent's status. Those are the guardrails on what an agent may do, so the agent shouldn't hold the pen: change them in the dashboard, or in code with an `agents:admin` key and the [`@channlize/core` agents client](https://github.com/channlize/sdk/tree/main/packages/core#channlize-for-agents) (`agents.policies`, `agents.teams`, `agents.orgChart`, `agents.setStatus`). For a webhook or polling agent in code, see the same client.
 
+There are no export or telemetry tools either. An export dumps the org's whole history (messages, tasks, questions, the audit log), and the telemetry settings decide where every agent's traces are sent, with the collector's credentials. Both need an unbound `agents:admin` key and belong to the people who run Channlize. Use the dashboard, or [`agents.exports` and `agents.telemetry`](https://github.com/channlize/sdk/tree/main/packages/core#exports-and-opentelemetry-admin) in `@channlize/core`. An agent reads its own history with `search_agent_messages`.
+
 ### Contacts, Events and logs (server API key)
 
 | Tool | Scope | What it does |

package/dist/agents.d.mts

@@ -20,13 +20,23 @@ import '@channlize/core';
  *
  * Scopes: `agents:send` (post messages, create, update and hand off
  * tasks, answer escalated questions), `agents:read` (directory, channels,
- * inbox and ack, tasks, the org chart), `agents:ask_human` (ask people and
- * read the answer) and `agents:admin` (`get_effective_policy` only).
+ * inbox and ack, tasks, the org chart, search, and the graph, cost and
+ * metrics insights), `agents:ask_human` (ask people and read the answer)
+ * and `agents:admin` (`get_effective_policy` only).
  *
  * No admin-write tools: changing policies, teams, the org chart or an
  * agent's status stays in the dashboard or `@channlize/core` with an
  * `agents:admin` key. Policies are the guardrails on what an agent may do,
  * so the agent that runs these tools shouldn't be able to rewrite them.
+ *
+ * No export or telemetry tools either (Phase 4): exports dump the org's
+ * whole history (messages, tasks, questions, the audit log), and the
+ * telemetry settings choose where every agent's traces go, with
+ * credentials. Both need an unbound `agents:admin` key and belong to the
+ * people who run Channlize: the dashboard, or `@channlize/core`
+ * (`agents.exports`, `agents.telemetry`). An agent reads its own history
+ * with `search_agent_messages` and its numbers with the insights tools,
+ * which only see what its key may read.
  */
 
 type Json = Record<string, unknown>;

package/dist/agents.d.ts

@@ -20,13 +20,23 @@ import '@channlize/core';
  *
  * Scopes: `agents:send` (post messages, create, update and hand off
  * tasks, answer escalated questions), `agents:read` (directory, channels,
- * inbox and ack, tasks, the org chart), `agents:ask_human` (ask people and
- * read the answer) and `agents:admin` (`get_effective_policy` only).
+ * inbox and ack, tasks, the org chart, search, and the graph, cost and
+ * metrics insights), `agents:ask_human` (ask people and read the answer)
+ * and `agents:admin` (`get_effective_policy` only).
  *
  * No admin-write tools: changing policies, teams, the org chart or an
  * agent's status stays in the dashboard or `@channlize/core` with an
  * `agents:admin` key. Policies are the guardrails on what an agent may do,
  * so the agent that runs these tools shouldn't be able to rewrite them.
+ *
+ * No export or telemetry tools either (Phase 4): exports dump the org's
+ * whole history (messages, tasks, questions, the audit log), and the
+ * telemetry settings choose where every agent's traces go, with
+ * credentials. Both need an unbound `agents:admin` key and belong to the
+ * people who run Channlize: the dashboard, or `@channlize/core`
+ * (`agents.exports`, `agents.telemetry`). An agent reads its own history
+ * with `search_agent_messages` and its numbers with the insights tools,
+ * which only see what its key may read.
  */
 
 type Json = Record<string, unknown>;

package/dist/agents.js

@@ -56,6 +56,326 @@ var ToolError = class extends Error {
   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;
@@ -179,6 +499,40 @@ function outcomeMessage(status, q) {
       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",
@@ -729,6 +1083,200 @@ var AGENT_TOOLS = [
       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",