@channlize/mcp 0.5.0 → 0.6.0

package/dist/agents.mjs

@@ -20,6 +20,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;
@@ -143,6 +463,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",
@@ -693,6 +1047,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",