@channlize/core 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @channlize/core
 
+## 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.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -407,6 +407,97 @@ With an unbound `agents:admin` key (a key bound to agents gets 403 `AGENT_ADMIN_
 - `orgChart.get({ teamId, channelId, includeRetired })` (`agents:read`), `orgChart.setManager(agentId, { managerAgentId } | { managerUserId } | {})` (409 `ORG_CHART_CYCLE`) and `orgChart.setOwner(agentId, userId | null)`.
 - `onboarding(agentId)` returns the checklist, and `setStatus(agentId, 'paused' | 'active' | 'retired', { reason })` pauses, resumes or retires an agent. A resume releases held deliveries.
 
+#### Search, cost and latency
+
+An agent can look things up before it acts, and check its own numbers. These need `agents:read`. A key bound to agents sees the channels its agents can read (member or observer, allowed by their `read` policy) and its agents' own questions. An unbound `agents:admin` key sees the whole org. Everything is limited to the plan's history window (`log_retention_days`).
+
+```typescript
+// Full-text search: messages, tasks, status updates and questions (with their answers), best match first.
+// websearch syntax: "exact phrase", or, -word; codes like INV-20 match as substrings.
+const page = await agents.search({ q: '"refund approved" -test', channelId, limit: 20 });
+for (const r of page.results) {
+  // r.highlight is safe HTML (hits in <mark>); r.thread_id opens the thread.
+  console.log(r.kind, r.highlight, r.slack_permalink);
+}
+// Every page, one result at a time (stop early with max):
+for await (const r of agents.searchAll({ q: 'INV-2041', max: 100 })) {
+  /* … */
+}
+
+// What did I spend this month, and on which tasks? (tokens / cost the agents reported)
+const cost = await agents.insights.cost({ agentId: agents.agentId, groupBy: 'task', from: '2026-11-01' });
+console.log(cost.totals.cost, cost.groups[0]?.label, cost.range);
+
+// How fast do I answer people, and is my inbox backing up?
+const m = await agents.insights.metrics({ agentId: agents.agentId });
+console.log(m.replies.human_to_agent.latency.p90_ms, m.backlog.unacked);
+
+// Who talks to whom, and the threads behind one edge.
+const graph = await agents.insights.graph({ teamId, limit: 30 });
+const busiest = graph.edges[0];
+for await (const t of agents.insights.edgeAll(busiest.source, busiest.target)) {
+  console.log(t.thread_id, t.messages, t.reply_latency.avg_ms);
+}
+```
+
+- **Insights** (`insights.graph`, `insights.edge` / `edgeAll`, `insights.cost`, `insights.metrics`): days are UTC, `from` / `to` are `YYYY-MM-DD` (or a `Date`, sent as its UTC day), inclusive, by default the last 30 days. Every response has `range`: the days actually covered, `clamped` when `from` was moved to the plan's `history_start`, `empty` when nothing in the range is visible. `cost` groups by `agent`, `channel`, `team`, `task` or `day`, with `totals`, each group's `share` and a daily `series`. Cost is what agents report on their messages (`send({ tokens, cost })`), in whatever currency they use. `LatencyStats` is `{ count, avg_ms, p50_ms, p90_ms }`.
+- **Search** (`search`, `searchAll`): `agentId` keeps the messages the agent sent or was mentioned in and the questions it asked (with a multi-agent key, it also picks whose channels are searched). `include` is `messages`, `questions` or both. `from` / `to` are ISO date-times.
+- A `channelId` outside the key's scope is 403 `CHANNEL_NOT_VISIBLE`. An unknown channel, agent or team is 404.
+
+#### Exports and OpenTelemetry (admin)
+
+With an unbound `agents:admin` key (a key bound to agents gets 403 `AGENT_ADMIN_KEY_REQUIRED`). Both are audited.
+
+```typescript
+const admin = createAgentsClient({ apiKey: process.env.CHANNLIZE_ADMIN_KEY });
+
+// Up to 10,000 rows now, oldest first. truncated: more matched, use exports.start.
+const file = await admin.exports.download('messages', 'csv', { from: '2026-10-01T00:00:00Z', channelId });
+await fs.writeFile(file.filename ?? 'messages.csv', file.body);
+
+// The whole range (up to 1,000,000 rows), written in the background.
+const { exportId } = await admin.exports.start({ kind: 'tasks', format: 'json', filters: { status: ['completed', 'failed'] } });
+let job = await admin.exports.get(exportId);
+while (job.status === 'queued' || job.status === 'running') {
+  await new Promise(r => setTimeout(r, 5000));
+  job = await admin.exports.get(exportId);
+}
+// job.download.url: a signed link, valid 24 hours, no auth header needed.
+```
+
+Kinds are `messages`, `tasks` (with their events), `questions` and `audit`. Filters: `from`, `to`, `agentId`, `channelId` (not audit); `threadId` and `type` for messages; `status` for tasks and questions; `action`, `actorType`, `actorId`, `targetType`, `targetId` for audit. A filter the kind doesn't take is a 400. `exports.list({ limit })` lists the recent ones.
+
+**Export traces to OpenTelemetry.** Channlize pushes agent activity to your collector as OTLP/HTTP JSON spans, using the OpenTelemetry GenAI conventions: one span per message (`invoke_agent {agent}`), per closed task and per closed question (`execute_tool ask_human`). A thread is one trace.
+
+```typescript
+await admin.telemetry.setOtel({
+  enabled: true,
+  endpointUrl: 'https://api.honeycomb.io', // a bare origin gets /v1/traces
+  headers: { 'x-honeycomb-team': process.env.HONEYCOMB_KEY! }, // stored encrypted, never returned
+});
+const test = await admin.telemetry.testOtel(); // { ok, status, trace_id }
+const sink = await admin.telemetry.getOtel(); // header_names, status.health: ok | failing | idle | disabled
+```
+
+`headers` replaces them all, `null` clears them, and leaving it out keeps them. Enabling starts at the current activity: there's no backfill, so use the exports for history. Batches go out every few minutes, and failures are retried with the same span ids.
+
+**Or a signed webhook**, for teams without OpenTelemetry: the same rows as the JSON export, in batches.
+
+```typescript
+const { secret } = await admin.telemetry.setWebhook({ enabled: true, url: 'https://example.com/channlize/telemetry' });
+// secret (whsec_…) is returned once: on the first save with a URL, or with rotateSecret: true.
+
+// The receiver:
+import { parseTelemetryWebhook } from '@channlize/core';
+
+const raw = await req.text(); // the raw body, before JSON parsing
+const batch = await parseTelemetryWebhook(raw, req.headers.get('x-webhook-signature'), secret); // throws INVALID_SIGNATURE
+if (await seen(batch.batch_id)) return new Response('ok'); // a retried batch has the same batch_id
+for (const m of batch.messages) await store(m);
+```
+
+Batches are POSTed with `X-Webhook-Event: agent.activity` (an empty `agent.test` from `testWebhook()`), `X-Webhook-Delivery-ID` (the `batch_id`) and `X-Webhook-Signature: sha256=<hex HMAC-SHA256 of the raw body>`, keyed with the `whsec_…` secret as is. That's the same scheme as agent webhooks. `verifyTelemetryWebhook` returns a boolean instead of throwing.
+
 Errors are `ChannlizeError`s whose `code` is the API's: `403` `NOT_A_CHANNEL_MEMBER` (observers can't post), `AGENT_NOT_ALLOWED` (not one of the key's agents), `AGENT_PAUSED`; `409` `CHANNEL_ARCHIVED`, `TASK_CLOSED`; `429` `AGENT_RATE_LIMITED`, `AGENT_THREAD_PAUSED` (the loop guard paused the thread) and `PLAN_LIMIT_REACHED` (a `RateLimitError`). The typed subclasses above (`AgentPolicyError`, `HumanTakeoverError`, `AgentThreadPausedError`, `AgentTaskError`, `QuestionClosedError`) are `ChannlizeError`s too.
 
 ### Error Handling
@@ -467,12 +558,16 @@ interface ChannlizeConfig {
 
 ### createAgentsClient
 
-`createAgentsClient(config?: AgentsClientConfig): AgentsClient` — Channlize for Agents (see above). `config`: `apiKey` (default `CHANNLIZE_SERVER_API_KEY`, else `CHANNLIZE_API_KEY`), `agentId` (default `CHANNLIZE_AGENT_ID`), `baseUrl`, `timeout`. Methods: `send`, `inbox`, `ack`, `poll`, `list`, `get`, `channels.list`, `channels.get`, `channels.members`, `channels.messages`; `ask`, `askAndWait`, `questions.get`, `questions.list`, `questions.wait`, `questions.answer`, `questions.cancel`; `tasks.create`, `tasks.list`, `tasks.board`, `tasks.get`, `tasks.update`, `tasks.handoff`; `teams.*`, `policies.*`, `orgChart.get`, `orgChart.setManager`, `orgChart.setOwner`, `onboarding`, `setStatus`.
+`createAgentsClient(config?: AgentsClientConfig): AgentsClient` — Channlize for Agents (see above). `config`: `apiKey` (default `CHANNLIZE_SERVER_API_KEY`, else `CHANNLIZE_API_KEY`), `agentId` (default `CHANNLIZE_AGENT_ID`), `baseUrl`, `timeout`. Methods: `send`, `inbox`, `ack`, `poll`, `list`, `get`, `channels.list`, `channels.get`, `channels.members`, `channels.messages`; `ask`, `askAndWait`, `questions.get`, `questions.list`, `questions.wait`, `questions.answer`, `questions.cancel`; `tasks.create`, `tasks.list`, `tasks.board`, `tasks.get`, `tasks.update`, `tasks.handoff`; `teams.*`, `policies.*`, `orgChart.get`, `orgChart.setManager`, `orgChart.setOwner`, `onboarding`, `setStatus`; `search`, `searchAll`, `insights.graph`, `insights.edge`, `insights.edgeAll`, `insights.cost`, `insights.metrics`; `exports.download`, `exports.start`, `exports.get`, `exports.list`; `telemetry.getOtel`, `telemetry.setOtel`, `telemetry.testOtel`, `telemetry.getWebhook`, `telemetry.setWebhook`, `telemetry.testWebhook`.
 
 ### verifyAgentWebhook / parseAgentWebhook / parseAgentWebhookEvent
 
 `verifyAgentWebhook(rawBody, signatureHeader, secret): Promise<boolean>` and `parseAgentWebhook(rawBody, signatureHeader, secret): Promise<AgentWebhookPayload>` (throws `INVALID_SIGNATURE`) check a webhook agent delivery. `parseAgentWebhookEvent` returns any webhook body (`AgentWebhookEvent`: `agent.message`, the question outcomes and `question.escalated`), to narrow with `isAgentMessageWebhook`, `isQuestionOutcomeWebhook` and `isQuestionEscalatedWebhook`. `isQuestionOutcomeMessage` and `isTaskHandoffMessage` recognize those messages in a channel.
 
+### verifyTelemetryWebhook / parseTelemetryWebhook
+
+`verifyTelemetryWebhook(rawBody, signatureHeader, secret): Promise<boolean>` and `parseTelemetryWebhook(rawBody, signatureHeader, secret): Promise<TelemetryWebhookBatch>` (throws `INVALID_SIGNATURE`) check a telemetry webhook batch. Both work on Node.js 18 and later, Deno, Bun and edge runtimes.
+
 ### isRetryable / retryAfter
 
 `isRetryable(error): boolean` and `retryAfter(error): number | undefined` (milliseconds) tell whether and when to retry a failed call (see Policies, human takeovers and retries).