@channlize/core 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -1058,96 +1058,572 @@ declare function isTaskHandoffMessage(message: AgentMessage | null | undefined):
 };
 
 /**
- * Channlize for Agents: post to agent channels, read the inbox and the
- * directory, ask humans and wait for the answer, work on tasks, as one of
- * your agents; and, with an `agents:admin` key, manage teams, policies and
- * the org chart. Create it with `createAgentsClient`, or use
- * `ChannlizeClient.agents`.
+ * Types for Channlize for Agents, Phase 4 (deeper observability): the
+ * insights (communication graph, edge threads, cost, response metrics),
+ * full-text search, CSV / JSON exports and the telemetry sinks
+ * (OpenTelemetry and the signed activity webhook).
+ *
+ * Response DTOs mirror the API (`/v1/agents/insights/*`, `/v1/agents/search`,
+ * `/v1/agents/export`, `/v1/agents/telemetry/*`), field for field, in
+ * snake_case. Options are camelCase.
  */
-interface AgentsClient extends AgentsGovernance {
-    /** The default agent id (`agentId` option or `CHANNLIZE_AGENT_ID`). */
-    readonly agentId: string | undefined;
-    /** Post a message, task or task status to a channel (`agents:send`). One Event per message. */
-    send(input: SendAgentMessageInput): Promise<SendAgentMessageResult>;
-    /** The agent's unacked messages, oldest first (`agents:read`). */
-    inbox(agentId?: string, options?: AgentInboxOptions): Promise<AgentInboxPage>;
-    /** Acknowledge inbox messages so they leave the inbox (`agents:read`). */
-    ack(agentId: string | undefined, input: AgentAckInput): Promise<AgentAckResult>;
+
+/** A UTC day, `YYYY-MM-DD`; a `Date` is sent as its UTC day. */
+type InsightsDay = string | Date;
+/**
+ * The range an insights response covers: `from` / `to` (UTC days,
+ * inclusive) after the defaults (the last 30 days), the cap at today and the
+ * plan's history window.
+ */
+interface InsightsRange {
+    from: string;
+    to: string;
+    days: number;
+    /** The plan's `log_retention_days`. */
+    retention_days: number;
+    /** The first day the plan shows. */
+    history_start: string;
+    /** `from` was moved forward to `history_start`. */
+    clamped: boolean;
+    /** No visible day in the range (it ends before `history_start`). */
+    empty: boolean;
+    /** Days read from the nightly rollup, and days computed live. */
+    rolled_days: number;
+    live_days: number;
+}
+/** Latencies; the numbers are null when `count` is 0. */
+interface LatencyStats {
+    count: number;
+    avg_ms: number | null;
+    /** Estimated from 17 latency buckets. */
+    p50_ms: number | null;
+    p90_ms: number | null;
+}
+/** Filters every insights endpoint takes. */
+interface InsightsFilters {
+    /** First UTC day (default: 30 days before `to`). */
+    from?: InsightsDay;
+    /** Last UTC day, inclusive (default: today). */
+    to?: InsightsDay;
+    channelId?: string;
+    /** Edges touching this agent (graph), what it sent (cost), its metrics. */
+    agentId?: string;
+}
+type InsightsNodeKind = 'agent' | 'user' | 'slack_user' | 'deleted' | 'other';
+/** A node id: `agent:<id>`, `user:<id>`, `slack_user:<slack id>`, `deleted:deleted` or `other:other`. */
+type InsightsNodeId = string;
+interface InsightsNode {
+    id: InsightsNodeId;
+    kind: InsightsNodeKind;
+    /** The agent / user id, the Slack user id; null for `deleted` and `other`. */
+    ref_id: string | null;
+    label: string;
+    slug: string | null;
+    emoji: string | null;
+    avatar_url: string | null;
+    /** Agents: active | paused | retired. */
+    status: AgentStatus | null;
+    sent: number;
+    received: number;
+    tokens: number;
+    cost: number;
+}
+/** A directed sender → recipient edge. */
+interface InsightsEdge {
+    /** `<source>|<target>`. */
+    id: string;
+    source: InsightsNodeId;
+    target: InsightsNodeId;
+    messages: number;
+    tokens: number;
+    cost: number;
+    /** Messages the target replied to (same thread, within 24 h). */
+    replies: number;
+    reply_latency: LatencyStats;
+    last_at: string | null;
+}
+interface InsightsGraphFilters extends InsightsFilters {
+    /** Edges with one of the team's agents at either end. */
+    teamId?: string;
+    /** Nodes kept (default 50, max 200); the rest fold into `other:other`. */
+    limit?: number;
+    /** Edges kept (default 300, max 1000). */
+    edgeLimit?: number;
+}
+interface InsightsGraph {
+    range: InsightsRange;
+    nodes: InsightsNode[];
+    edges: InsightsEdge[];
+    /** Before the cap. */
+    totals: {
+        nodes: number;
+        edges: number;
+        messages: number;
+        tokens: number;
+        cost: number;
+    };
+    /** Nodes folded into `other:other`, edges dropped. */
+    truncated: {
+        nodes: number;
+        edges: number;
+    };
+    limits: {
+        nodes: number;
+        edges: number;
+    };
+}
+type InsightsNodeRef = Pick<InsightsNode, 'id' | 'kind' | 'ref_id' | 'label' | 'slug' | 'emoji' | 'avatar_url'>;
+interface InsightsEdgeThread {
+    thread_id: string;
+    channel: {
+        id: string;
+        name: string | null;
+        slug: string | null;
+    };
+    root: {
+        id: string;
+        type: AgentMessageType;
+        /** At most 280 characters. */
+        text: string;
+        slack_ts: string | null;
+        created_at: string;
+    } | null;
+    messages: number;
+    tokens: number;
+    cost: number;
+    replies: number;
+    reply_latency: {
+        count: number;
+        avg_ms: number | null;
+    };
+    first_at: string;
+    last_at: string;
+}
+interface InsightsEdgeOptions {
+    from?: InsightsDay;
+    to?: InsightsDay;
+    channelId?: string;
+    /** `nextCursor` of the previous page. */
+    cursor?: string;
+    /** 1-100, default 25. */
+    limit?: number;
+}
+/** The threads behind one edge, newest activity first. */
+interface InsightsEdgePage {
+    range: InsightsRange;
+    source: InsightsNodeRef;
+    target: InsightsNodeRef;
+    threads: InsightsEdgeThread[];
+    nextCursor: string | null;
+}
+declare const COST_GROUPINGS: readonly ["agent", "channel", "team", "task", "day"];
+type CostGrouping = (typeof COST_GROUPINGS)[number];
+interface InsightsCostOptions extends InsightsFilters {
+    /** Default `agent`. */
+    groupBy?: CostGrouping;
+    teamId?: string;
+    /** Groups returned (default 50, max 200). */
+    limit?: number;
+}
+interface CostTotals {
+    messages: number;
+    /** Messages that reported tokens or cost. */
+    priced_messages: number;
+    tokens: number;
+    cost: number;
+}
+interface CostGroup {
+    /** The agent / channel / team / task id, or the day. */
+    key: string;
+    label: string;
+    messages: number;
+    tokens: number;
+    cost: number;
+    /** Share of `totals.cost` (0..1); null when the total is 0. */
+    share: number | null;
+    agent?: {
+        id: string;
+        slug: string | null;
+        status: AgentStatus | null;
+    };
+    channel?: {
+        id: string;
+        slug: string | null;
+        archived: boolean;
+    };
+    team?: {
+        id: string;
+        slug: string | null;
+    };
+    task?: {
+        id: string;
+        channel_id: string | null;
+        status: string | null;
+        assignee_agent_id: string | null;
+        created_at: string | null;
+    };
+}
+interface CostSeriesPoint {
+    day: string;
+    messages: number;
+    tokens: number;
+    cost: number;
+    /** Cost per `series_keys` group, plus `other` (not for teams, which overlap). */
+    groups: Record<string, number>;
+}
+interface InsightsCost {
+    range: InsightsRange;
+    group_by: CostGrouping;
+    /** The whole range with the filters. */
+    totals: CostTotals;
+    /** Sorted by cost (days by date). */
+    groups: CostGroup[];
+    /** Every day of the range. */
+    series: CostSeriesPoint[];
+    /** The top 8 groups broken out in `series`. */
+    series_keys: string[];
+    /** More groups than `limit`. */
+    truncated: boolean;
+}
+interface ReplyPairMetrics {
+    messages: number;
+    replied: number;
+    reply_rate: number | null;
+    latency: LatencyStats;
+}
+interface QuestionMetrics {
+    asked: number;
+    answered: number;
+    answered_by_user: number;
+    answered_by_agent: number;
+    expired: number;
+    expired_default: number;
+    canceled: number;
+    closed: number;
+    answer_rate: number | null;
+    expired_rate: number | null;
+    default_rate: number | null;
+    cancel_rate: number | null;
+    time_to_human_answer: LatencyStats;
+}
+interface DeliveryModeMetrics {
+    deliveries: number;
+    delivered: number;
+    inbox: number;
+    pending: number;
+    failed: number;
+    held: number;
+    skipped: number;
+    retried: number;
+    acked: number;
+    failure_rate: number | null;
+    retry_rate: number | null;
+    avg_attempts: number | null;
+}
+interface BacklogAgent {
+    agent_id: string;
+    name: string;
+    slug: string;
+    delivery: AgentDeliveryMode;
+    unacked: number;
+    held: number;
+    oldest_unacked_at: string | null;
+    oldest_age_seconds: number | null;
+}
+interface InsightsMetrics {
+    range: InsightsRange;
+    replies: {
+        agent_to_agent: ReplyPairMetrics;
+        human_to_agent: ReplyPairMetrics;
+        agent_to_human: ReplyPairMetrics;
+        /** As the responder, busiest first (at most 50). */
+        by_agent: Array<{
+            agent_id: string;
+            name: string | null;
+            slug: string | null;
+            messages: number;
+            replied: number;
+            latency: LatencyStats;
+        }>;
+    };
+    questions: QuestionMetrics & {
+        by_urgency: Record<'low' | 'normal' | 'high' | 'urgent', QuestionMetrics>;
+        by_kind: Record<'question' | 'approval', QuestionMetrics>;
+    };
+    deliveries: {
+        deliveries: number;
+        failed: number;
+        retried: number;
+        failure_rate: number | null;
+        retry_rate: number | null;
+        by_mode: Record<AgentDeliveryMode, DeliveryModeMetrics>;
+    };
+    /** Right now, whatever the range. */
+    backlog: {
+        as_of: string;
+        unacked: number;
+        held: number;
+        agents_with_backlog: number;
+        /** At most 50. */
+        agents: BacklogAgent[];
+    };
+    held: number;
+}
+type AgentSearchInclude = 'messages' | 'questions';
+interface AgentSearchOptions {
+    /** 2-200 characters; websearch syntax: `"exact phrase"`, `or`, `-word`. */
+    q: string;
     /**
-     * Read the inbox in a loop, call `handler` for each message (oldest
-     * first) and ack it once the handler resolves. Errors back off
-     * exponentially; the failed message isn't acked, so it comes back. 400,
-     * 401, 403 and 404 stop the loop (the returned promise rejects): retrying
-     * can't fix a wrong key, scope or agent. Resolves when `signal` aborts.
+     * Messages sent by or mentioning the agent, questions it asked. With a key
+     * bound to several agents it also picks whose channels are searched.
      */
-    poll(agentId: string | undefined, handler: AgentMessageHandler, options?: AgentPollOptions): Promise<void>;
-    /** The organization's agents (`agents:read`). */
-    list(options?: {
-        includeRetired?: boolean;
-    }): Promise<Agent[]>;
-    /** One agent (`agents:read`); an `agents:admin` key also gets the detail. */
-    get(agentId: string): Promise<AgentDetail>;
-    channels: {
-        /** Channels the key's agents are members or observers of (all of them for an `agents:admin` key). */
-        list(options?: {
-            includeArchived?: boolean;
-        }): Promise<AgentChannel[]>;
-        /** A channel and its members. */
-        get(channelId: string, options?: AgentChannelReadOptions): Promise<{
-            channel: AgentChannel;
-            members: AgentChannelMember[];
-        }>;
-        /** A channel's members and roles. */
-        members(channelId: string, options?: AgentChannelReadOptions): Promise<AgentChannelMember[]>;
-        /** A channel's messages: newest first with `cursor`, or newer than `after` (polling). */
-        messages(channelId: string, options?: AgentChannelFeedOptions): Promise<AgentChannelFeed>;
+    agentId?: string;
+    channelId?: string;
+    type?: AgentMessageType;
+    /** Default both. */
+    include?: AgentSearchInclude | AgentSearchInclude[];
+    /** ISO date-time (or a `Date`); clamped to the plan's history window. */
+    from?: string | Date;
+    to?: string | Date;
+    /** `nextCursor` of the previous page. */
+    cursor?: string;
+    /** 1-50, default 20. */
+    limit?: number;
+}
+interface AgentSearchChannelRef {
+    id: string;
+    slug: string;
+    name: string;
+}
+type AgentSearchResult = {
+    kind: 'message';
+    message: AgentMessage;
+    /** Safe HTML: an escaped snippet with the hits in `<mark>`. */
+    highlight: string;
+    /** 0..1, best first. */
+    rank: number;
+    channel: AgentSearchChannelRef;
+    /** The thread root (the message's own id for a root). */
+    thread_id: string;
+    slack_permalink: string | null;
+} | {
+    kind: 'question';
+    question: AgentQuestion;
+    highlight: string;
+    rank: number;
+    channel: AgentSearchChannelRef | null;
+    thread_id: string | null;
+    slack_permalink: string | null;
+};
+interface AgentSearchPage {
+    results: AgentSearchResult[];
+    nextCursor: string | null;
+    /** The history window searched: its start and the plan's days. */
+    window: {
+        from: string;
+        days: number;
     };
 }
+interface AgentSearchAllOptions extends Omit<AgentSearchOptions, 'cursor'> {
+    /** Stop after this many results (default: every page). */
+    max?: number;
+}
+declare const AGENT_EXPORT_KINDS: readonly ["messages", "tasks", "questions", "audit"];
+type AgentExportKind = (typeof AGENT_EXPORT_KINDS)[number];
+declare const AGENT_EXPORT_FORMATS: readonly ["csv", "json"];
+type AgentExportFormat = (typeof AGENT_EXPORT_FORMATS)[number];
+/** Rows in a synchronous download; larger ranges go through `exports.start`. */
+declare const AGENT_EXPORT_SYNC_MAX_ROWS = 10000;
 /**
- * Channlize for Agents client. Reads the key from `CHANNLIZE_SERVER_API_KEY`
- * or `CHANNLIZE_API_KEY`, and the default agent from `CHANNLIZE_AGENT_ID`,
- * unless given. Server-side only: never ship an agent key to a browser.
- *
- * ```ts
- * const agents = createAgentsClient({ agentId: process.env.CHANNLIZE_AGENT_ID });
- * await agents.send({ channel: channelId, text: 'Deploy finished' });
- * ```
- */
-declare function createAgentsClient(config?: AgentsClientConfig): AgentsClient;
-/**
- * Checks the `X-Webhook-Signature` header of a webhook agent delivery:
- * `sha256=<hex HMAC-SHA256 of the raw body>`, keyed with the agent's secret
- * (shown once when the agent is created or its secret rotated).
- *
- * Pass the body **exactly as received** (a string or bytes), before any JSON
- * parsing: re-serializing changes the bytes and the signature no longer
- * matches. The comparison is constant-time (Web Crypto `verify`). Uses
- * `globalThis.crypto.subtle`, or `node:crypto`'s `webcrypto` on Node.js 18.
- *
- * ```ts
- * const raw = await req.text();
- * if (!(await verifyAgentWebhook(raw, req.headers.get('x-webhook-signature'), secret))) {
- *   return new Response('bad signature', { status: 401 });
- * }
- * const payload = JSON.parse(raw) as AgentWebhookPayload;
- * ```
- */
-declare function verifyAgentWebhook(rawBody: string | Uint8Array, signatureHeader: string | string[] | null | undefined, secret: string): Promise<boolean>;
-/**
- * `verifyAgentWebhook`, then the parsed `agent.message` payload. Throws a
- * 401 `ChannlizeError` (`INVALID_SIGNATURE`) when the signature doesn't
- * match. A webhook agent that asks humans (or manages agents) also gets
- * question events: use `parseAgentWebhookEvent` for those.
+ * Export filters. `from`, `to` and `agentId` apply to every kind,
+ * `channelId` to all but `audit`; the others to one kind each. A filter the
+ * kind doesn't take is a 400.
  */
-declare function parseAgentWebhook(rawBody: string | Uint8Array, signatureHeader: string | string[] | null | undefined, secret: string): Promise<AgentWebhookPayload>;
+interface AgentExportFilters {
+    /** ISO date-time (or a `Date`); clamped to the plan's history window. */
+    from?: string | Date;
+    to?: string | Date;
+    agentId?: string;
+    channelId?: string;
+    /** `messages`. */
+    threadId?: string;
+    /** `messages`. */
+    type?: AgentMessageType;
+    /** `tasks`: task statuses; `questions`: question statuses. */
+    status?: string | string[];
+    /** `audit`: an action, exact or a namespace. */
+    action?: string;
+    /** `audit`. */
+    actorType?: string;
+    actorId?: string;
+    targetType?: string;
+    targetId?: string;
+}
+/** A synchronous download: the file and what the API said about it. */
+interface AgentExportDownload {
+    /** The CSV text, or the JSON array as text (parse it with `JSON.parse`). */
+    body: string;
+    /** `X-Export-Rows`. */
+    rows: number;
+    /** `X-Export-Truncated`: more than `AGENT_EXPORT_SYNC_MAX_ROWS` rows matched. */
+    truncated: boolean;
+    contentType: string;
+    /** From `Content-Disposition`, e.g. `agents-messages-2026-11-05.csv`. */
+    filename: string | null;
+}
+type AgentExportStatus = 'queued' | 'running' | 'completed' | 'failed';
+interface AgentExport {
+    id: string;
+    kind: AgentExportKind;
+    format: AgentExportFormat;
+    /** As sent, snake_case. */
+    filters: Record<string, unknown>;
+    status: AgentExportStatus;
+    rows: number;
+    /** More than 1,000,000 rows matched. */
+    truncated: boolean;
+    bytes: number;
+    error: string | null;
+    requested_by: {
+        user_id: string | null;
+        api_key_id: string | null;
+    };
+    /** A signed link (24 h), once completed; `exports.get` signs a fresh one. */
+    download: {
+        url: string;
+        expires_at: string;
+    } | null;
+    created_at: string;
+    started_at: string | null;
+    completed_at: string | null;
+}
+interface StartAgentExportInput {
+    kind: AgentExportKind;
+    /** Default `csv`. */
+    format?: AgentExportFormat;
+    filters?: AgentExportFilters;
+}
+interface StartAgentExportResult {
+    exportId: string;
+    status: AgentExportStatus;
+    export: AgentExport;
+}
+/** A `messages` row of the JSON export (and of the telemetry webhook). */
+interface AgentExportMessageRow extends AgentMessage {
+    channel: {
+        id: string;
+        slug: string | null;
+    };
+    sender_agent: {
+        slug: string;
+        name: string;
+    } | null;
+}
+/** A `tasks` row. */
+interface AgentExportTaskRow extends AgentTask {
+    channel: {
+        id: string;
+        slug: string | null;
+    };
+    assignee: {
+        slug: string;
+        name: string;
+    } | null;
+    events: AgentTaskEvent[];
+}
+/** A `questions` row. */
+interface AgentExportQuestionRow extends AgentQuestion {
+    channel: {
+        id: string;
+        slug: string | null;
+    } | null;
+    agent: {
+        slug: string;
+        name: string;
+    } | null;
+}
+interface TelemetrySinkStatus {
+    last_run_at: string | null;
+    last_success_at: string | null;
+    last_error: string | null;
+    last_error_at: string | null;
+    consecutive_failures: number;
+    items_sent: number;
+    /** `failing`: the last run failed; `idle`: never ran. */
+    health: 'ok' | 'failing' | 'idle' | 'disabled';
+}
+interface OtelSink {
+    enabled: boolean;
+    /** The OTLP/HTTP traces URL. */
+    endpoint_url: string | null;
+    protocol: 'http/json';
+    /** Header values are write-only: only their names come back. */
+    header_names: string[];
+    headers_configured: boolean;
+    status: TelemetrySinkStatus;
+    updated_at: string | null;
+}
+interface SetOtelSinkInput {
+    enabled?: boolean;
+    /** An OTLP/HTTP traces URL; a bare origin gets `/v1/traces`. null clears it. */
+    endpointUrl?: string | null;
+    /**
+     * Sent with every export (`Authorization`, `x-honeycomb-team`,
+     * `DD-API-KEY`, at most 10). Replaces them all; null clears them; leave it
+     * out to keep them.
+     */
+    headers?: Record<string, string> | null;
+}
+interface WebhookSink {
+    enabled: boolean;
+    url: string | null;
+    secret_configured: boolean;
+    status: TelemetrySinkStatus;
+    updated_at: string | null;
+}
+interface SetWebhookSinkInput {
+    enabled?: boolean;
+    url?: string | null;
+    /** Generate a new signing secret (returned once). */
+    rotateSecret?: boolean;
+}
+interface SetWebhookSinkResult {
+    webhook: WebhookSink;
+    /** The `whsec_…` signing secret: only on the first save with a URL or a rotation. Store it now. */
+    secret?: string;
+}
+interface TelemetryTestResult {
+    ok: boolean;
+    /** The endpoint's HTTP status. */
+    status?: number;
+    error?: string;
+    /** OpenTelemetry: the test span's trace id. */
+    trace_id?: string;
+}
+/** `X-Webhook-Event` of a telemetry batch. */
+type TelemetryWebhookEvent = 'agent.activity' | 'agent.test';
 /**
- * `verifyAgentWebhook`, then any webhook body: `agent.message`,
- * `question.answered` / `question.expired` / `question.canceled` or
- * `question.escalated` (the `X-Webhook-Event` header). Narrow it with
- * `isAgentMessageWebhook`, `isQuestionOutcomeWebhook` and
- * `isQuestionEscalatedWebhook`.
+ * The body of a telemetry webhook batch (`version: 1`): the rows of the
+ * JSON export. `agent.test` batches are empty.
  */
-declare function parseAgentWebhookEvent(rawBody: string | Uint8Array, signatureHeader: string | string[] | null | undefined, secret: string): Promise<AgentWebhookEvent>;
+interface TelemetryWebhookBatch {
+    version: 1;
+    event: TelemetryWebhookEvent;
+    /** `X-Webhook-Delivery-ID`; the same when a batch is retried. */
+    batch_id: string;
+    organization_id: string;
+    sent_at: string;
+    messages: AgentExportMessageRow[];
+    /** Tasks closed in this batch, with their history. */
+    tasks: AgentExportTaskRow[];
+    task_events: Array<AgentTaskEvent & {
+        task_id: string;
+    }>;
+    /** Questions closed (answered, expired, canceled) in this batch. */
+    questions: Array<AgentExportQuestionRow & {
+        status: QuestionStatus;
+    }>;
+}
 
 /**
  * Helpers shared by `@channlize/core`, `@channlize/react` and
@@ -1460,6 +1936,202 @@ interface TrackEventResult {
     dropped?: 'plan_limit' | 'rate_limit';
 }
 
+/**
+ * Channlize for Agents, Phase 4 on the agents client: insights (graph, edge
+ * threads, cost, metrics), full-text search, exports and the telemetry
+ * sinks. `createAgentsClient` mixes these in.
+ *
+ * Insights and search take `agents:read` (a key bound to agents sees what
+ * its agents can read) or an unbound `agents:admin` key (the org). Exports
+ * and telemetry need an unbound `agents:admin` key.
+ */
+
+/** Phase 4 of `AgentsClient`. */
+interface AgentsObservability {
+    /**
+     * The communication graph, cost and response metrics (`agents:read`: the
+     * key's agents' channels; an unbound `agents:admin` key: the org). Days
+     * are UTC; the default range is the last 30 days, clamped to the plan's
+     * history window (see `range`).
+     */
+    insights: {
+        /** Who talks to whom: nodes (agents, people) and directed edges, with tokens, cost and reply latency. */
+        graph(filters?: InsightsGraphFilters): Promise<InsightsGraph>;
+        /** The threads behind one edge (node ids from `graph`), newest activity first, one page. */
+        edge(source: InsightsNodeId, target: InsightsNodeId, options?: InsightsEdgeOptions): Promise<InsightsEdgePage>;
+        /** Every thread of an edge, page after page (`max` stops early). */
+        edgeAll(source: InsightsNodeId, target: InsightsNodeId, options?: Omit<InsightsEdgeOptions, 'cursor'> & {
+            max?: number;
+        }): AsyncIterableIterator<InsightsEdgeThread>;
+        /** Cost rollups from reported tokens / cost, by agent, channel, team, task or day, with a daily series. */
+        cost(options?: InsightsCostOptions): Promise<InsightsCost>;
+        /** Reply latency, time to a human answer, delivery failure and retry rates, inbox backlog. */
+        metrics(filters?: InsightsFilters): Promise<InsightsMetrics>;
+    };
+    /**
+     * Full-text search over agent messages and questions, best match first
+     * (`agents:read`: the channels the key's agents can read and their own
+     * questions; an unbound `agents:admin` key: the org). One page.
+     */
+    search(options: AgentSearchOptions): Promise<AgentSearchPage>;
+    /** `search`, page after page, one result at a time (`max` stops early). */
+    searchAll(options: AgentSearchAllOptions): AsyncIterableIterator<AgentSearchResult>;
+    /** CSV / JSON exports of messages, tasks, questions and the audit log (an unbound `agents:admin` key). */
+    exports: {
+        /**
+         * Download up to 10,000 rows now, oldest first. `truncated` says more
+         * matched: use `start` for the whole range. Audited `export.downloaded`.
+         */
+        download(kind: AgentExportKind, format?: AgentExportFormat, filters?: AgentExportFilters): Promise<AgentExportDownload>;
+        /**
+         * Queue an export of the whole range (up to 1,000,000 rows). Poll `get`
+         * until `status` is `completed`, then fetch `export.download.url` (a
+         * signed link, valid 24 hours, no auth header).
+         */
+        start(input: StartAgentExportInput): Promise<StartAgentExportResult>;
+        /** One export, with a freshly signed `download` link once completed. */
+        get(exportId: string): Promise<AgentExport>;
+        /** Recent exports, newest first (1-100, default 50). */
+        list(options?: {
+            limit?: number;
+        }): Promise<AgentExport[]>;
+    };
+    /** Push agent traces to OpenTelemetry or a signed webhook (an unbound `agents:admin` key). */
+    telemetry: {
+        getOtel(): Promise<OtelSink>;
+        /** Header values are stored encrypted and never returned. Audited `telemetry.updated`. */
+        setOtel(input: SetOtelSinkInput): Promise<OtelSink>;
+        /** Send one test span (its own trace) now. */
+        testOtel(): Promise<TelemetryTestResult>;
+        getWebhook(): Promise<WebhookSink>;
+        /**
+         * `secret` comes back once: on the first save with a URL, or with
+         * `rotateSecret`. Check batches with `verifyTelemetryWebhook`.
+         */
+        setWebhook(input: SetWebhookSinkInput): Promise<SetWebhookSinkResult>;
+        /** Send an empty signed `agent.test` batch now. */
+        testWebhook(): Promise<TelemetryTestResult>;
+    };
+}
+
+/**
+ * Channlize for Agents: post to agent channels, read the inbox and the
+ * directory, ask humans and wait for the answer, work on tasks, as one of
+ * your agents; and, with an `agents:admin` key, manage teams, policies and
+ * the org chart; search history and read the insights (graph, cost,
+ * latency); and, with an `agents:admin` key, export and stream traces.
+ * Create it with `createAgentsClient`, or use `ChannlizeClient.agents`.
+ */
+interface AgentsClient extends AgentsGovernance, AgentsObservability {
+    /** The default agent id (`agentId` option or `CHANNLIZE_AGENT_ID`). */
+    readonly agentId: string | undefined;
+    /** Post a message, task or task status to a channel (`agents:send`). One Event per message. */
+    send(input: SendAgentMessageInput): Promise<SendAgentMessageResult>;
+    /** The agent's unacked messages, oldest first (`agents:read`). */
+    inbox(agentId?: string, options?: AgentInboxOptions): Promise<AgentInboxPage>;
+    /** Acknowledge inbox messages so they leave the inbox (`agents:read`). */
+    ack(agentId: string | undefined, input: AgentAckInput): Promise<AgentAckResult>;
+    /**
+     * Read the inbox in a loop, call `handler` for each message (oldest
+     * first) and ack it once the handler resolves. Errors back off
+     * exponentially; the failed message isn't acked, so it comes back. 400,
+     * 401, 403 and 404 stop the loop (the returned promise rejects): retrying
+     * can't fix a wrong key, scope or agent. Resolves when `signal` aborts.
+     */
+    poll(agentId: string | undefined, handler: AgentMessageHandler, options?: AgentPollOptions): Promise<void>;
+    /** The organization's agents (`agents:read`). */
+    list(options?: {
+        includeRetired?: boolean;
+    }): Promise<Agent[]>;
+    /** One agent (`agents:read`); an `agents:admin` key also gets the detail. */
+    get(agentId: string): Promise<AgentDetail>;
+    channels: {
+        /** Channels the key's agents are members or observers of (all of them for an `agents:admin` key). */
+        list(options?: {
+            includeArchived?: boolean;
+        }): Promise<AgentChannel[]>;
+        /** A channel and its members. */
+        get(channelId: string, options?: AgentChannelReadOptions): Promise<{
+            channel: AgentChannel;
+            members: AgentChannelMember[];
+        }>;
+        /** A channel's members and roles. */
+        members(channelId: string, options?: AgentChannelReadOptions): Promise<AgentChannelMember[]>;
+        /** A channel's messages: newest first with `cursor`, or newer than `after` (polling). */
+        messages(channelId: string, options?: AgentChannelFeedOptions): Promise<AgentChannelFeed>;
+    };
+}
+/**
+ * Channlize for Agents client. Reads the key from `CHANNLIZE_SERVER_API_KEY`
+ * or `CHANNLIZE_API_KEY`, and the default agent from `CHANNLIZE_AGENT_ID`,
+ * unless given. Server-side only: never ship an agent key to a browser.
+ *
+ * ```ts
+ * const agents = createAgentsClient({ agentId: process.env.CHANNLIZE_AGENT_ID });
+ * await agents.send({ channel: channelId, text: 'Deploy finished' });
+ * ```
+ */
+declare function createAgentsClient(config?: AgentsClientConfig): AgentsClient;
+/**
+ * Checks the `X-Webhook-Signature` header of a webhook agent delivery:
+ * `sha256=<hex HMAC-SHA256 of the raw body>`, keyed with the agent's secret
+ * (shown once when the agent is created or its secret rotated).
+ *
+ * Pass the body **exactly as received** (a string or bytes), before any JSON
+ * parsing: re-serializing changes the bytes and the signature no longer
+ * matches. The comparison is constant-time (Web Crypto `verify`). Uses
+ * `globalThis.crypto.subtle`, or `node:crypto`'s `webcrypto` on Node.js 18.
+ *
+ * ```ts
+ * const raw = await req.text();
+ * if (!(await verifyAgentWebhook(raw, req.headers.get('x-webhook-signature'), secret))) {
+ *   return new Response('bad signature', { status: 401 });
+ * }
+ * const payload = JSON.parse(raw) as AgentWebhookPayload;
+ * ```
+ */
+declare function verifyAgentWebhook(rawBody: string | Uint8Array, signatureHeader: string | string[] | null | undefined, secret: string): Promise<boolean>;
+/**
+ * `verifyAgentWebhook`, then the parsed `agent.message` payload. Throws a
+ * 401 `ChannlizeError` (`INVALID_SIGNATURE`) when the signature doesn't
+ * match. A webhook agent that asks humans (or manages agents) also gets
+ * question events: use `parseAgentWebhookEvent` for those.
+ */
+declare function parseAgentWebhook(rawBody: string | Uint8Array, signatureHeader: string | string[] | null | undefined, secret: string): Promise<AgentWebhookPayload>;
+/**
+ * `verifyAgentWebhook`, then any webhook body: `agent.message`,
+ * `question.answered` / `question.expired` / `question.canceled` or
+ * `question.escalated` (the `X-Webhook-Event` header). Narrow it with
+ * `isAgentMessageWebhook`, `isQuestionOutcomeWebhook` and
+ * `isQuestionEscalatedWebhook`.
+ */
+declare function parseAgentWebhookEvent(rawBody: string | Uint8Array, signatureHeader: string | string[] | null | undefined, secret: string): Promise<AgentWebhookEvent>;
+/**
+ * Checks the `X-Webhook-Signature` header of a telemetry webhook batch
+ * (`agents.telemetry.setWebhook`): `sha256=<hex HMAC-SHA256 of the raw
+ * body>`, keyed with the sink's `whsec_…` secret as given (the whole string,
+ * not base64-decoded). The same scheme as agent webhooks.
+ *
+ * Pass the body **exactly as received**, before any JSON parsing. The
+ * comparison is constant-time (Web Crypto `verify`). Works on Node.js 18
+ * (`node:crypto` `webcrypto`), newer Node, Deno, Bun and edge runtimes.
+ *
+ * ```ts
+ * const raw = await req.text();
+ * const ok = await verifyTelemetryWebhook(raw, req.headers.get('x-webhook-signature'), secret);
+ * if (!ok) return new Response('bad signature', { status: 401 });
+ * const batch = JSON.parse(raw) as TelemetryWebhookBatch;
+ * ```
+ */
+declare function verifyTelemetryWebhook(rawBody: string | Uint8Array, signatureHeader: string | string[] | null | undefined, secret: string): Promise<boolean>;
+/**
+ * `verifyTelemetryWebhook`, then the parsed batch (`agent.activity`, or an
+ * empty `agent.test`). Throws a 401 `ChannlizeError` (`INVALID_SIGNATURE`)
+ * when the signature doesn't match. `batch_id` is the same when a batch is
+ * retried: use it to drop duplicates.
+ */
+declare function parseTelemetryWebhook(rawBody: string | Uint8Array, signatureHeader: string | string[] | null | undefined, secret: string): Promise<TelemetryWebhookBatch>;
+
 /**
  * Channlize API Client
  * Provides methods to interact with the Channlize platform.
@@ -1620,5 +2292,5 @@ declare function isRetryable(error: unknown): boolean;
  */
 declare function retryAfter(error: unknown, now?: number): number | undefined;
 
-export { AGENT_DELIVERY_MODES, AGENT_MESSAGE_TYPES, AGENT_POLICY_CODES, AGENT_STATUSES, AGENT_TASK_ERROR_CODES, AGENT_TASK_STATUSES, AgentPolicyError, AgentTaskError, AgentThreadPausedError, AuthenticationError, ChannlizeClient, ChannlizeError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, EVENT_KEY_PATTERN, EVENT_SEVERITIES, HumanTakeoverError, POLICY_SCOPES, QUESTION_KINDS, QUESTION_STATUSES, QUESTION_URGENCIES, QUESTION_WAIT_MAX_SECONDS, QuestionClosedError, RateLimitError, SENDABLE_AGENT_MESSAGE_TYPES, TASK_BOARD_STATUSES, ValidationError, createAgentsClient, createNotifier, ChannlizeClient as default, isAgentMessageWebhook, isQuestionEscalatedWebhook, isQuestionOutcomeMessage, isQuestionOutcomeWebhook, isRetryable, isTaskHandoffMessage, isValidEventKey, keyKind, parseAgentWebhook, parseAgentWebhookEvent, parseApiError, readChannlizeEnv, retryAfter, verifyAgentWebhook };
-export type { Agent, AgentAckInput, AgentAckResult, AgentChannel, AgentChannelFeed, AgentChannelFeedOptions, AgentChannelMember, AgentChannelReadOptions, AgentDelivery, AgentDeliveryMode, AgentDeliveryStatus, AgentDetail, AgentInboxItem, AgentInboxOptions, AgentInboxPage, AgentMemberRole, AgentMessage, AgentMessageHandler, AgentMessageSender, AgentMessageType, AgentMirrorConfig, AgentOnboarding, AgentPolicy, AgentPolicyCode, AgentPolicyRules, AgentPollOptions, AgentQuestion, AgentStatus, AgentStatusResult, AgentTask, AgentTaskErrorCode, AgentTaskEvent, AgentTaskStatus, AgentTeam, AgentTeamChannelGrant, AgentTeamDetail, AgentThreadPauseReason, AgentWebhookEvent, AgentWebhookPayload, AgentsClient, AgentsClientConfig, AgentsGovernance, AnswerQuestionInput, ApiErrorInfo, ApiResponse, AskAndWaitOptions, AskAndWaitResult, AskHumanInput, ChannlizeConfig, ChannlizeEnv, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, CreateTaskInput, CreateTaskResult, CreateTeamInput, EffectivePolicyPreview, EventSeverity, FileAttachment, HandoffTaskInput, HandoffTaskResult, KeyKind, ListQuestionsOptions, ListTasksOptions, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, OrgChart, OrgChartAgent, OrgChartNode, OrgChartOptions, PolicyCheck, PolicyScope, PolicySource, PutPolicyInput, QuestionAnswer, QuestionEscalatedWebhookPayload, QuestionEscalation, QuestionKind, QuestionOption, QuestionOutcomeData, QuestionOutcomeEvent, QuestionOutcomeWebhookPayload, QuestionPage, QuestionReadOptions, QuestionStatus, QuestionUrgency, SendAgentMessageInput, SendAgentMessageResult, SendMessageResponse, SendableAgentMessageType, SetManagerInput, TaskBoard, TaskBoardOptions, TaskBoardStatus, TaskDeliverySummary, TaskDetail, TaskHandoff, TaskHandoffData, TrackEventOptions, TrackEventResult, UpdateTaskInput, UpdateTaskResult, UpdateTeamInput, WaitQuestionOptions, WaitQuestionResult };
+export { AGENT_DELIVERY_MODES, AGENT_EXPORT_FORMATS, AGENT_EXPORT_KINDS, AGENT_EXPORT_SYNC_MAX_ROWS, AGENT_MESSAGE_TYPES, AGENT_POLICY_CODES, AGENT_STATUSES, AGENT_TASK_ERROR_CODES, AGENT_TASK_STATUSES, AgentPolicyError, AgentTaskError, AgentThreadPausedError, AuthenticationError, COST_GROUPINGS, ChannlizeClient, ChannlizeError, DEFAULT_BASE_URL, DEFAULT_TIMEOUT, EVENT_KEY_PATTERN, EVENT_SEVERITIES, HumanTakeoverError, POLICY_SCOPES, QUESTION_KINDS, QUESTION_STATUSES, QUESTION_URGENCIES, QUESTION_WAIT_MAX_SECONDS, QuestionClosedError, RateLimitError, SENDABLE_AGENT_MESSAGE_TYPES, TASK_BOARD_STATUSES, ValidationError, createAgentsClient, createNotifier, ChannlizeClient as default, isAgentMessageWebhook, isQuestionEscalatedWebhook, isQuestionOutcomeMessage, isQuestionOutcomeWebhook, isRetryable, isTaskHandoffMessage, isValidEventKey, keyKind, parseAgentWebhook, parseAgentWebhookEvent, parseApiError, parseTelemetryWebhook, readChannlizeEnv, retryAfter, verifyAgentWebhook, verifyTelemetryWebhook };
+export type { Agent, AgentAckInput, AgentAckResult, AgentChannel, AgentChannelFeed, AgentChannelFeedOptions, AgentChannelMember, AgentChannelReadOptions, AgentDelivery, AgentDeliveryMode, AgentDeliveryStatus, AgentDetail, AgentExport, AgentExportDownload, AgentExportFilters, AgentExportFormat, AgentExportKind, AgentExportMessageRow, AgentExportQuestionRow, AgentExportStatus, AgentExportTaskRow, AgentInboxItem, AgentInboxOptions, AgentInboxPage, AgentMemberRole, AgentMessage, AgentMessageHandler, AgentMessageSender, AgentMessageType, AgentMirrorConfig, AgentOnboarding, AgentPolicy, AgentPolicyCode, AgentPolicyRules, AgentPollOptions, AgentQuestion, AgentSearchAllOptions, AgentSearchChannelRef, AgentSearchInclude, AgentSearchOptions, AgentSearchPage, AgentSearchResult, AgentStatus, AgentStatusResult, AgentTask, AgentTaskErrorCode, AgentTaskEvent, AgentTaskStatus, AgentTeam, AgentTeamChannelGrant, AgentTeamDetail, AgentThreadPauseReason, AgentWebhookEvent, AgentWebhookPayload, AgentsClient, AgentsClientConfig, AgentsGovernance, AgentsObservability, AnswerQuestionInput, ApiErrorInfo, ApiResponse, AskAndWaitOptions, AskAndWaitResult, AskHumanInput, BacklogAgent, ChannlizeConfig, ChannlizeEnv, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CostGroup, CostGrouping, CostSeriesPoint, CostTotals, CreateChatSessionResponse, CreateContactResponse, CreateTaskInput, CreateTaskResult, CreateTeamInput, DeliveryModeMetrics, EffectivePolicyPreview, EventSeverity, FileAttachment, HandoffTaskInput, HandoffTaskResult, InsightsCost, InsightsCostOptions, InsightsDay, InsightsEdge, InsightsEdgeOptions, InsightsEdgePage, InsightsEdgeThread, InsightsFilters, InsightsGraph, InsightsGraphFilters, InsightsMetrics, InsightsNode, InsightsNodeId, InsightsNodeKind, InsightsNodeRef, InsightsRange, KeyKind, LatencyStats, ListQuestionsOptions, ListTasksOptions, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, OrgChart, OrgChartAgent, OrgChartNode, OrgChartOptions, OtelSink, PolicyCheck, PolicyScope, PolicySource, PutPolicyInput, QuestionAnswer, QuestionEscalatedWebhookPayload, QuestionEscalation, QuestionKind, QuestionMetrics, QuestionOption, QuestionOutcomeData, QuestionOutcomeEvent, QuestionOutcomeWebhookPayload, QuestionPage, QuestionReadOptions, QuestionStatus, QuestionUrgency, ReplyPairMetrics, SendAgentMessageInput, SendAgentMessageResult, SendMessageResponse, SendableAgentMessageType, SetManagerInput, SetOtelSinkInput, SetWebhookSinkInput, SetWebhookSinkResult, StartAgentExportInput, StartAgentExportResult, TaskBoard, TaskBoardOptions, TaskBoardStatus, TaskDeliverySummary, TaskDetail, TaskHandoff, TaskHandoffData, TelemetrySinkStatus, TelemetryTestResult, TelemetryWebhookBatch, TelemetryWebhookEvent, TrackEventOptions, TrackEventResult, UpdateTaskInput, UpdateTaskResult, UpdateTeamInput, WaitQuestionOptions, WaitQuestionResult, WebhookSink };