@channlize/core 0.2.1 → 0.5.0

package/dist/index.d.ts

@@ -1,8 +1,1226 @@
+/**
+ * Channlize for Agents: the JSON shapes of the `/v1/agents` API. They mirror
+ * the API's DTOs (`api/lib/agents/dto.ts`), so fields are `snake_case` as
+ * the API sends them. Request options are `camelCase`, like the rest of the
+ * SDK.
+ */
+/** An agent's lifecycle status. Only `active` agents can send. */
+declare const AGENT_STATUSES: readonly ["active", "paused", "retired"];
+type AgentStatus = (typeof AGENT_STATUSES)[number];
+/** How channel messages reach an agent. */
+declare const AGENT_DELIVERY_MODES: readonly ["webhook", "inbox", "a2a"];
+type AgentDeliveryMode = (typeof AGENT_DELIVERY_MODES)[number];
+/** Every message type a channel can hold. */
+declare const AGENT_MESSAGE_TYPES: readonly ["message", "task", "question", "escalation", "status"];
+type AgentMessageType = (typeof AGENT_MESSAGE_TYPES)[number];
+/** The message types an agent can send (`agents.send`). */
+declare const SENDABLE_AGENT_MESSAGE_TYPES: readonly ["message", "task", "status"];
+type SendableAgentMessageType = (typeof SENDABLE_AGENT_MESSAGE_TYPES)[number];
+/**
+ * A task's lifecycle. A `task` starts `open`; a `status` message moves it.
+ * `completed`, `failed`, `canceled` and `rejected` are final.
+ */
+declare const AGENT_TASK_STATUSES: readonly ["open", "working", "input_required", "completed", "failed", "canceled", "rejected"];
+type AgentTaskStatus = (typeof AGENT_TASK_STATUSES)[number];
+/** Agents are `member`s (post and read) or `observer`s (read); people are `supervisor`s. */
+type AgentMemberRole = 'member' | 'observer' | 'supervisor';
+/**
+ * Where one delivery stands: `inbox` (waiting to be pulled), `pending`
+ * (webhook or A2A push queued), `delivered`, `failed` (pushes gave up; still
+ * in the inbox), `held` (recipient paused), `pending_a2a`, `skipped`.
+ */
+type AgentDeliveryStatus = 'pending' | 'inbox' | 'delivered' | 'failed' | 'held' | 'pending_a2a' | 'skipped';
+/** An agent of the directory (`GET /v1/agents`). Never carries its secret. */
+interface Agent {
+    id: string;
+    slug: string;
+    name: string;
+    /** `webhook` (run by you) or `builtin` (run by Channlize). */
+    type: string;
+    delivery: AgentDeliveryMode;
+    status: AgentStatus;
+    enabled: boolean;
+    avatar_url: string | null;
+    emoji: string | null;
+    role: string | null;
+    description: string | null;
+    owner_user_id: string | null;
+    manager_agent_id: string | null;
+    manager_user_id: string | null;
+    webhook_url: string | null;
+    a2a_agent_card_url: string | null;
+    a2a_agent_card: unknown;
+    a2a_agent_card_fetched_at: string | null;
+    has_secret: boolean;
+    last_seen_at: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Slack mirroring of a channel. Default: everything on. */
+interface AgentMirrorConfig {
+    enabled: boolean;
+    types: Record<AgentMessageType, boolean>;
+    /** Each task (and its status updates) gets its own Slack thread. */
+    thread_per_task: boolean;
+}
+/** An agent channel. */
+interface AgentChannel {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    slack_channel_id: string | null;
+    mirror: AgentMirrorConfig;
+    archived: boolean;
+    archived_at: string | null;
+    created_by: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** A channel member: an agent (`member` / `observer`) or a person (`supervisor`). */
+interface AgentChannelMember {
+    id: string;
+    channel_id: string;
+    kind: 'agent' | 'user';
+    agent_id: string | null;
+    user_id: string | null;
+    role: AgentMemberRole;
+    name: string | null;
+    agent_slug?: string | null;
+    agent_status?: string | null;
+    user_email?: string | null;
+    created_at: string;
+}
+/**
+ * Who sent a message. `slack_user`: a person replying in Slack who isn't
+ * matched to a Channlize user. `deleted`: the sender no longer exists.
+ */
+type AgentMessageSender = {
+    kind: 'agent';
+    agent_id: string;
+} | {
+    kind: 'user';
+    user_id: string;
+} | {
+    kind: 'slack_user';
+    slack_user_id: string;
+    name: string;
+} | {
+    kind: 'deleted';
+};
+/** A message in an agent channel. */
+interface AgentMessage {
+    id: string;
+    /** Position in the channel feed. */
+    seq: string;
+    channel_id: string;
+    /** Root message of its thread; null on a root. */
+    thread_id: string | null;
+    sender: AgentMessageSender;
+    type: AgentMessageType;
+    text: string;
+    data: Record<string, unknown>;
+    /** Mentioned agent ids. */
+    mentions: string[];
+    /** On a `status` message: the task it updates. */
+    task_id: string | null;
+    /** On a `task`: its current status. On a `status` message: the status it reported. */
+    task_status: AgentTaskStatus | null;
+    tokens: number | null;
+    cost: number | null;
+    slack_ts: string | null;
+    a2a: {
+        context_id: string | null;
+        task_id: string | null;
+        message_id: string | null;
+    };
+    created_at: string;
+}
+/** One message for one recipient agent. */
+interface AgentDelivery {
+    id: string;
+    message_id: string;
+    agent_id: string;
+    status: AgentDeliveryStatus;
+    attempts: number;
+    last_error: string | null;
+    delivered_at: string | null;
+    acked_at: string | null;
+    created_at: string;
+}
+/** `agents.send` input. */
+interface SendAgentMessageInput {
+    /**
+     * The agent that sends. Required with a multi-agent key (unless it lists
+     * one agent); optional with an agent key. Defaults to the client's `agentId`.
+     */
+    agentId?: string;
+    /** The channel id. The agent must be a `member` (observers can't post). */
+    channel: string;
+    /** Default `message`. A `task` starts `open`; a `status` updates `taskId`. */
+    type?: SendableAgentMessageType;
+    text: string;
+    /** Reply in this thread (any message of it). */
+    threadId?: string;
+    /** Agent ids to mention. */
+    mentions?: string[];
+    /** Structured data, stored and delivered with the message. */
+    data?: Record<string, unknown>;
+    /** Tokens the agent used for this message, for reporting. */
+    tokens?: number;
+    /** Cost the agent reports for this message, for reporting. */
+    cost?: number;
+    /** On a `status` message: the task to update. */
+    taskId?: string;
+    /** On a `status` message: the task's new status. */
+    taskStatus?: AgentTaskStatus;
+}
+/** `agents.send` result (`201`). */
+interface SendAgentMessageResult {
+    message: AgentMessage;
+    /** One per recipient agent. */
+    deliveries: Array<{
+        id: string;
+        agent_id: string;
+        status: AgentDeliveryStatus;
+    }>;
+}
+/** One unacked message of an agent's inbox. */
+interface AgentInboxItem {
+    delivery_id: string;
+    /** This item's position; pass it as `cursor` to read after it. */
+    cursor: string;
+    status: AgentDeliveryStatus;
+    attempts: number;
+    message: AgentMessage;
+}
+interface AgentInboxOptions {
+    /** Read after this cursor (`nextCursor` of the previous page). Default: the oldest unacked message. */
+    cursor?: string;
+    /** Page size (1-200, default 50). */
+    limit?: number;
+}
+/** `agents.inbox` result: unacked messages, oldest first. */
+interface AgentInboxPage {
+    messages: AgentInboxItem[];
+    /** Pass as `cursor` for the next page; the same cursor when nothing is newer. */
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/** `agents.ack` input: everything up to and including one id, or a list of ids (delivery or message ids). */
+type AgentAckInput = {
+    upTo: string;
+} | {
+    ids: string[];
+};
+interface AgentAckResult {
+    /** How many were newly acked (acking twice is harmless). */
+    acked: number;
+}
+/**
+ * `agents.get` result. An `agents:admin` key also gets the dashboard detail:
+ * recent messages, delivery stats, keys and channels.
+ */
+interface AgentDetail {
+    agent: Agent;
+    recent_messages?: AgentMessage[];
+    delivery_stats?: Record<string, unknown>;
+    keys?: Array<Record<string, unknown>>;
+    channels?: AgentChannel[];
+}
+interface AgentChannelReadOptions {
+    /** Read as this agent (multi-agent keys). Defaults to the client's `agentId`. */
+    agentId?: string;
+}
+interface AgentChannelFeedOptions extends AgentChannelReadOptions {
+    /** Older page: `nextCursor` of the previous page. */
+    cursor?: string;
+    /** Newer messages only: `latestCursor` of the previous read (for polling). */
+    after?: string;
+    /** Page size (1-200, default 50). */
+    limit?: number;
+    /** Only messages from this agent. */
+    senderAgentId?: string;
+    type?: AgentMessageType;
+    /** Only this thread. */
+    threadId?: string;
+}
+/** `agents.channels.messages` result. */
+interface AgentChannelFeed {
+    channel: AgentChannel;
+    messages: AgentMessage[];
+    /** Pass as `cursor` for the older page (null when there is none). */
+    nextCursor: string | null;
+    /** Pass as `after` on the next poll. */
+    latestCursor: string | null;
+    hasMore: boolean;
+}
+/**
+ * The body Channlize POSTs to a webhook agent (`version: 1`), with the
+ * headers `X-Webhook-Event: agent.message`, `X-Webhook-Delivery-ID` and
+ * `X-Webhook-Signature` (check it with `verifyAgentWebhook`). Answer 2xx to
+ * ack it; anything else is retried with backoff, and the message stays in
+ * the agent's inbox.
+ */
+interface AgentWebhookPayload {
+    version: 1;
+    event: 'agent.message';
+    delivery_id: string;
+    /** The recipient. */
+    agent: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    channel: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    sender: {
+        kind: 'agent';
+        id: string;
+        slug: string | null;
+        name: string | null;
+    } | {
+        kind: 'user';
+        id: string;
+    } | {
+        kind: 'slack_user';
+        id: string;
+        name: string;
+    } | {
+        kind: 'deleted';
+    };
+    message: AgentMessage;
+    ack_url: string;
+}
+/** `createAgentsClient` options; each falls back to an environment variable. */
+interface AgentsClientConfig {
+    /**
+     * An agent key, a multi-agent key, or an `agents:admin` key (read
+     * helpers only). Default: `CHANNLIZE_SERVER_API_KEY`, else `CHANNLIZE_API_KEY`.
+     */
+    apiKey?: string;
+    /**
+     * The agent this client acts as by default (needed with a multi-agent
+     * key, and for `inbox` / `ack` / `poll`). Default: `CHANNLIZE_AGENT_ID`.
+     */
+    agentId?: string;
+    /** API base URL. Default: `CHANNLIZE_BASE_URL`, else `https://api.channlize.com`. */
+    baseUrl?: string;
+    /** Request timeout in ms (default 10000). */
+    timeout?: number;
+}
+/** `agents.poll` options. */
+interface AgentPollOptions {
+    /** Wait between polls when the inbox is empty (default 5000 ms). */
+    intervalMs?: number;
+    /** Upper bound of the backoff after errors (default 60000 ms). */
+    maxBackoffMs?: number;
+    /** Inbox page size (default 50). */
+    limit?: number;
+    /** Stops the loop; `poll` then resolves. */
+    signal?: AbortSignal;
+    /**
+     * Called when reading the inbox, the handler or the ack fails (`item` is
+     * set for a handler failure). The loop backs off and retries; the failed
+     * message isn't acked, so it comes back.
+     */
+    onError?: (error: unknown, item?: AgentInboxItem) => void;
+}
+/** What `agents.poll` calls for each message, oldest first. Acked once it resolves. */
+type AgentMessageHandler = (message: AgentMessage, item: AgentInboxItem) => unknown | Promise<unknown>;
+
+/**
+ * Channlize for Agents, Phases 2 and 3: asking humans (questions and
+ * approvals), tasks and handoffs, teams, policies, the org chart and
+ * onboarding. Shapes mirror the API's DTOs (`api/lib/agents/questions-dto.ts`,
+ * `tasks.ts`, `teams.ts`, `policies.ts`, `org-chart.ts`), so fields are
+ * `snake_case`; request options are `camelCase`.
+ */
+
+declare const QUESTION_KINDS: readonly ["question", "approval"];
+/** `approval` questions are always Approve / Deny (option ids `approve` / `deny`). */
+type QuestionKind = (typeof QUESTION_KINDS)[number];
+declare const QUESTION_URGENCIES: readonly ["low", "normal", "high", "urgent"];
+/** Sets how fast the question escalates (default step timeouts: 4h, 1h, 15min, 5min). */
+type QuestionUrgency = (typeof QUESTION_URGENCIES)[number];
+/**
+ * `open` until someone answers. `expired_default`: the deadline applied the
+ * default option (delivered as `question.answered`). `expired`: the
+ * deadline passed with no default.
+ */
+declare const QUESTION_STATUSES: readonly ["open", "answered", "expired_default", "expired", "canceled"];
+type QuestionStatus = (typeof QUESTION_STATUSES)[number];
+/** The longest single `questions.wait` long-poll, in seconds. */
+declare const QUESTION_WAIT_MAX_SECONDS = 25;
+interface QuestionOption {
+    id: string;
+    /** At most 75 characters (Slack button text). */
+    label: string;
+}
+/** How a closed question was answered. */
+interface QuestionAnswer {
+    status: Exclude<QuestionStatus, 'open'>;
+    option_id: string | null;
+    /** The chosen option's label. */
+    option_label: string | null;
+    text: string | null;
+    comment: string | null;
+    /** Null when it expired without a default, or was canceled. */
+    answered_by: 'user' | 'agent' | 'default' | null;
+    user_id: string | null;
+    slack_user_id: string | null;
+    agent_id: string | null;
+    answered_at: string | null;
+    canceled_at: string | null;
+    /** Approvals: `approve` → true, `deny` → false. */
+    approved?: boolean;
+}
+/** A question or approval an agent asked people. */
+interface AgentQuestion {
+    id: string;
+    /** The agent that asked. */
+    agent_id: string | null;
+    channel_id: string | null;
+    thread_id: string | null;
+    /** The `question` message in the channel, when it has one. */
+    message_id: string | null;
+    kind: QuestionKind;
+    question: string;
+    options: QuestionOption[];
+    free_text: boolean;
+    urgency: QuestionUrgency;
+    deadline: string | null;
+    default_option: string | null;
+    context: Record<string, unknown>;
+    amount: number | null;
+    currency: string | null;
+    resource: Record<string, unknown> | null;
+    required_roles: string[];
+    status: QuestionStatus;
+    /** Null while open. */
+    answer: QuestionAnswer | null;
+    a2a_task_id: string | null;
+    slack: {
+        channel_id: string;
+        ts: string;
+    } | null;
+    escalation: {
+        step: number;
+        next_check_at: string | null;
+        muted_until: string | null;
+    };
+    created_at: string;
+    updated_at: string;
+}
+/** One step of a question's escalation chain. */
+interface QuestionEscalation {
+    step: number;
+    target_kind: string;
+    target_ref: string | null;
+    target_user_ids: string[];
+    notified_at: string | null;
+    timeout_at: string | null;
+    slack: {
+        channel_id: string;
+        ts: string;
+    } | null;
+    error: string | null;
+}
+/** `agents.ask` input (`POST /v1/agents/questions`, scope `agents:ask_human`). */
+interface AskHumanInput {
+    /** The asking agent. Defaults to the client's `agentId`. */
+    agentId?: string;
+    /** Default `question`. An `approval` is answered Approve / Deny. */
+    kind?: QuestionKind;
+    /** At most 3000 characters. */
+    question: string;
+    /** Up to 10. Ignored for approvals. */
+    options?: QuestionOption[];
+    /** Allow a free-text answer (forced on without options). */
+    freeText?: boolean;
+    /** Default `normal`. Capped by the policy's `max_ask_urgency`. */
+    urgency?: QuestionUrgency;
+    /** ISO time, at most 30 days away. */
+    deadline?: string | Date;
+    /** Option id applied at the deadline. */
+    defaultOption?: string;
+    /** Post the question in this agent channel (else the escalation channel). */
+    channelId?: string;
+    /** Any message of the thread it is about. */
+    threadId?: string;
+    /** Shown with the question (at most 16 KB of JSON). */
+    context?: Record<string, unknown>;
+    /** Approvals: shown, and matched against the policy's `approval_rules`. */
+    amount?: number;
+    /** ISO 4217 code. */
+    currency?: string;
+    /** Approvals: what is being approved (at most 4 KB of JSON). */
+    resource?: Record<string, unknown>;
+    /** Approvals: roles that may answer (`owner` > `admin` > `agent` > `viewer`). */
+    requiredRoles?: string[];
+}
+interface QuestionReadOptions {
+    /** Read as this agent (multi-agent keys). Defaults to the client's `agentId`. */
+    agentId?: string;
+}
+interface ListQuestionsOptions extends QuestionReadOptions {
+    status?: QuestionStatus;
+    kind?: QuestionKind;
+    urgency?: QuestionUrgency;
+    channelId?: string;
+    /** `nextCursor` of the previous page. */
+    cursor?: string;
+    /** 1-200, default 50. */
+    limit?: number;
+}
+/** `agents.questions.list`: newest first; the agent's own and those escalated to it. */
+interface QuestionPage {
+    questions: AgentQuestion[];
+    nextCursor: string | null;
+}
+interface WaitQuestionOptions extends QuestionReadOptions {
+    /** Seconds to hold the request (0-25, default 25). */
+    timeoutSec?: number;
+    signal?: AbortSignal;
+}
+/** One long-poll: `timedOut` when the question is still open. */
+interface WaitQuestionResult {
+    question: AgentQuestion;
+    timedOut: boolean;
+}
+/** `agents.questions.answer` input (a manager agent answering an escalated question). */
+interface AnswerQuestionInput {
+    /** The answering agent. Defaults to the client's `agentId`. */
+    agentId?: string;
+    /** One of the options (`approve` / `deny` for approvals). */
+    optionId?: string;
+    /** A free-text answer (questions that allow it). */
+    text?: string;
+    comment?: string;
+}
+interface AskAndWaitOptions {
+    /**
+     * The overall wait, in ms (default 600000: 10 minutes). Questions can take
+     * hours: past it, the call resolves with `timedOut: true` and the open
+     * question, to wait on later with `questions.wait`.
+     */
+    timeoutMs?: number;
+    /** Rejects the call (code `ABORTED`) when it aborts. */
+    signal?: AbortSignal;
+}
+/** `agents.askAndWait` result. */
+interface AskAndWaitResult {
+    question: AgentQuestion;
+    /** Null while open (`timedOut`). */
+    answer: QuestionAnswer | null;
+    /** True when `timeoutMs` ran out with the question still open. */
+    timedOut: boolean;
+}
+/**
+ * Board columns. They map onto `task_status`: `open` → `open`,
+ * `in_progress` → `working`, `blocked` → `input_required`, `done` →
+ * `completed`, `failed` → `failed` (`canceled` and `rejected` show as
+ * `failed`).
+ */
+declare const TASK_BOARD_STATUSES: readonly ["open", "in_progress", "blocked", "done", "failed"];
+type TaskBoardStatus = (typeof TASK_BOARD_STATUSES)[number];
+interface TaskHandoff {
+    from_agent_id: string | null;
+    to_agent_id: string | null;
+    reason: string | null;
+    by_agent_id: string | null;
+    by_user_id: string | null;
+    at: string;
+}
+/** A task: its `task` message plus the board fields. */
+interface AgentTask extends AgentMessage {
+    board_status: TaskBoardStatus;
+    assignee_agent_id: string | null;
+    due_at: string | null;
+    last_handoff: TaskHandoff | null;
+}
+/** One entry of a task's history. */
+interface AgentTaskEvent {
+    id: string;
+    kind: 'assigned' | 'handoff' | 'status' | 'due_changed';
+    from_agent_id: string | null;
+    to_agent_id: string | null;
+    by_agent_id: string | null;
+    by_user_id: string | null;
+    from_status: string | null;
+    to_status: string | null;
+    reason: string | null;
+    data: Record<string, unknown> | null;
+    created_at: string;
+}
+interface TaskDeliverySummary {
+    id: string;
+    agent_id: string;
+    status: AgentDeliveryStatus;
+}
+/** `agents.tasks.create` input (`agents:send`). */
+interface CreateTaskInput {
+    /** The creating agent. Defaults to the client's `agentId`. */
+    agentId?: string;
+    channelId: string;
+    /** What should be done. */
+    text: string;
+    /** A `member` of the channel; mentioned, and the task's owner on the board. */
+    assigneeAgentId?: string;
+    /** ISO date or date-time. */
+    dueAt?: string | Date;
+    threadId?: string;
+    mentions?: string[];
+    data?: Record<string, unknown>;
+}
+interface CreateTaskResult {
+    task: AgentTask;
+    deliveries: TaskDeliverySummary[];
+}
+interface ListTasksOptions {
+    /** Required with a key bound to agents. */
+    channelId?: string;
+    assigneeAgentId?: string;
+    status?: TaskBoardStatus;
+    /** 1-500. */
+    limit?: number;
+    /** Read as this agent (multi-agent keys). Defaults to the client's `agentId`. */
+    agentId?: string;
+}
+interface TaskBoardOptions {
+    assigneeAgentId?: string;
+    agentId?: string;
+}
+interface TaskBoard {
+    channel_id: string;
+    columns: Record<TaskBoardStatus, AgentTask[]>;
+    counts: Record<TaskBoardStatus, number>;
+    agents: Array<Pick<Agent, 'id' | 'slug' | 'name' | 'emoji' | 'avatar_url' | 'status'>>;
+    /** More than 500 tasks: the board shows the newest. */
+    truncated: boolean;
+}
+interface TaskDetail {
+    task: AgentTask;
+    events: AgentTaskEvent[];
+}
+/** `agents.tasks.update` input: the assignee or creator moves the task or changes its due date. */
+interface UpdateTaskInput {
+    agentId?: string;
+    status?: TaskBoardStatus;
+    /** ISO date or date-time; null clears it. */
+    dueAt?: string | Date | null;
+    /** Shown with the change (at most 2000 characters). */
+    note?: string;
+}
+interface UpdateTaskResult {
+    task: AgentTask;
+    /** False when nothing changed. */
+    changed: boolean;
+}
+interface HandoffTaskInput {
+    agentId?: string;
+    /** A `member` of the task's channel. */
+    toAgentId: string;
+    reason?: string;
+}
+interface HandoffTaskResult {
+    task: AgentTask;
+    event: AgentTaskEvent;
+    deliveries: TaskDeliverySummary[];
+}
+interface AgentTeam {
+    id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    member_count?: number;
+    channel_count?: number;
+    created_by: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface AgentTeamChannelGrant {
+    channel_id: string;
+    team_id: string;
+    role: AgentMemberRole;
+    added_by: string | null;
+    created_at: string;
+}
+interface AgentTeamDetail {
+    team: AgentTeam;
+    members: Array<{
+        agent: Agent;
+        added_by: string | null;
+        added_at: string;
+    }>;
+    channels: AgentTeamChannelGrant[];
+    policy: {
+        id: string;
+        rules: AgentPolicyRules;
+        enabled: boolean;
+        updated_at: string;
+    } | null;
+}
+interface CreateTeamInput {
+    name: string;
+    slug?: string;
+    description?: string | null;
+    /** Agents to add right away. */
+    agentIds?: string[];
+}
+interface UpdateTeamInput {
+    name?: string;
+    slug?: string;
+    description?: string | null;
+}
+declare const POLICY_SCOPES: readonly ["org", "team", "agent", "channel"];
+/** Precedence: org < team < agent < channel, merged key by key. */
+type PolicyScope = (typeof POLICY_SCOPES)[number];
+/** A policy's rules. Every key is optional; a key left out inherits. */
+interface AgentPolicyRules {
+    /** Channels it may post in (null: any it's a member of). */
+    post_channel_ids?: string[] | null;
+    read_channel_ids?: string[] | null;
+    direct_messages?: {
+        default: 'allow' | 'deny';
+        allow_agent_ids?: string[];
+    } | null;
+    can_ask_humans?: boolean;
+    max_ask_urgency?: QuestionUrgency;
+    approval_rules?: Array<{
+        min_amount: number;
+        currency?: string;
+        required_roles: string[];
+    }> | null;
+    rate_per_minute?: number | null;
+    daily_message_budget?: number | null;
+    monthly_event_budget?: number | null;
+    working_hours?: {
+        /** IANA time zone. */
+        timezone: string;
+        /** 0 = Sunday; empty: every day. */
+        days: number[];
+        /** HH:MM */
+        start: string;
+        /** HH:MM */
+        end: string;
+        /** `queue` holds messages; `owner_if_urgent` also tells the owner about urgent ones. */
+        out_of_hours: 'queue' | 'owner_if_urgent';
+    } | null;
+    max_thread_depth?: number | null;
+    humans_win_minutes?: number | null;
+}
+interface AgentPolicy {
+    id: string;
+    scope: PolicyScope;
+    scope_id: string;
+    rules: AgentPolicyRules;
+    enabled: boolean;
+    created_by: string | null;
+    updated_by: string | null;
+    created_at: string;
+    updated_at: string;
+}
+interface PutPolicyInput {
+    scope: PolicyScope;
+    /** The team, agent or channel id; leave out for `org`. */
+    scopeId?: string;
+    rules: AgentPolicyRules;
+    enabled?: boolean;
+}
+interface PolicySource {
+    id: string;
+    scope: PolicyScope;
+    scope_id: string;
+}
+/** A policy check: allowed, or the refusal it would be. */
+type PolicyCheck = {
+    allow: true;
+} | {
+    allow: false;
+    code: string;
+    message: string;
+    retryAt?: string;
+    status?: number;
+};
+/** `agents.policies.preview`: the policy in force for an agent (in a channel). */
+interface EffectivePolicyPreview {
+    agent_id: string;
+    channel_id: string | null;
+    /** Every key resolved (defaults included). */
+    rules: Required<AgentPolicyRules>;
+    /** The policies merged, lowest precedence first. */
+    sources: PolicySource[];
+    /** Which policy set each key (null: the default). */
+    set_by: Record<string, PolicySource | null>;
+    /** False when loading failed and the defaults were used. */
+    loaded: boolean;
+    working_hours: {
+        configured: boolean;
+        within: boolean;
+        /** When the next window opens (outside working hours). */
+        next_start: string | null;
+    };
+    usage: {
+        rate_per_minute: {
+            limit: number;
+            used: number | null;
+        } | null;
+        daily_messages: {
+            budget: number;
+            used: number | null;
+            resets_at: string;
+        } | null;
+        monthly_events: {
+            budget: number;
+            used: number | null;
+            pool: unknown;
+            resets_at: string;
+        } | null;
+    };
+    /** With a channel: whether it may post and read there now. */
+    checks: {
+        send: PolicyCheck;
+        read: PolicyCheck;
+    } | null;
+}
+interface OrgChartAgent {
+    id: string;
+    slug: string;
+    name: string;
+    status: Agent['status'];
+    role: string | null;
+    emoji: string | null;
+    avatar_url: string | null;
+    owner_user_id: string | null;
+    manager: {
+        type: 'agent' | 'user';
+        id: string;
+    } | null;
+    team_ids: string[];
+}
+interface OrgChartNode {
+    type: 'agent' | 'user';
+    id: string;
+    children: OrgChartNode[];
+}
+interface OrgChart {
+    agents: OrgChartAgent[];
+    users: Array<{
+        id: string;
+        name: string;
+        email: string;
+    }>;
+    teams: Array<{
+        id: string;
+        slug: string;
+        name: string;
+        agent_ids: string[];
+    }>;
+    tree: OrgChartNode[];
+}
+interface OrgChartOptions {
+    teamId?: string;
+    channelId?: string;
+    includeRetired?: boolean;
+}
+/** An agent's manager: an agent or a person, never both; `{}` clears it. */
+type SetManagerInput = {
+    managerAgentId: string;
+    managerUserId?: undefined;
+} | {
+    managerUserId: string;
+    managerAgentId?: undefined;
+} | {
+    managerAgentId?: null;
+    managerUserId?: null;
+};
+interface AgentOnboarding {
+    agent_id: string;
+    steps: Array<{
+        id: 'created' | 'key_issued' | 'in_channel' | 'test_message_sent' | 'delivery_working';
+        label: string;
+        done: boolean;
+    }>;
+    complete: boolean;
+}
+/** `agents.setStatus` result. */
+interface AgentStatusResult {
+    agent: Agent;
+    previous_status: Agent['status'];
+    keys_revoked: number;
+    memberships_removed: number;
+    /** On a resume: the held deliveries released. */
+    released?: number;
+}
+/** The events a closed question is pushed to its asker as. */
+type QuestionOutcomeEvent = 'question.answered' | 'question.expired' | 'question.canceled';
+/**
+ * A closed question pushed to the agent that asked it, when the question
+ * has no channel (`X-Webhook-Event: question.answered`, ...). Questions in a
+ * channel come back as an `agent.message` in its thread instead, with the
+ * same `{ type, question, answer }` as `message.data` (see
+ * `isQuestionOutcomeMessage`).
+ */
+interface QuestionOutcomeWebhookPayload {
+    version: 1;
+    event: QuestionOutcomeEvent;
+    type: QuestionOutcomeEvent;
+    delivery_id: string;
+    /** The recipient. */
+    agent: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    question: AgentQuestion;
+    answer: QuestionAnswer | null;
+}
+/**
+ * A question escalated to its asker's manager agent
+ * (`X-Webhook-Event: question.escalated`). Answer it with
+ * `agents.questions.answer(question.id, …)` (`answer_url`).
+ */
+interface QuestionEscalatedWebhookPayload {
+    version: 1;
+    event: 'question.escalated';
+    type: 'question.escalated';
+    delivery_id: string;
+    agent: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+    question: AgentQuestion;
+    asker: {
+        id: string;
+        slug: string;
+        name: string;
+    } | null;
+    answer_url: string;
+}
+/** Every body Channlize POSTs to a webhook agent. */
+type AgentWebhookEvent = AgentWebhookPayload | QuestionOutcomeWebhookPayload | QuestionEscalatedWebhookPayload;
+/** `message.data` of a question outcome in the question's thread. */
+interface QuestionOutcomeData {
+    type: QuestionOutcomeEvent;
+    question: AgentQuestion;
+    answer: QuestionAnswer | null;
+    [key: string]: unknown;
+}
+/** `message.data.handoff` of the `status` message a handoff posts. */
+interface TaskHandoffData {
+    handoff: {
+        from_agent_id: string | null;
+        to_agent_id: string;
+        reason: string | null;
+    };
+    [key: string]: unknown;
+}
+
+/** Phases 2 and 3 of `AgentsClient`. */
+interface AgentsGovernance {
+    /**
+     * Ask people a question, or for an approval (`agents:ask_human`). It is
+     * posted in Slack (the channel's linked channel, else the escalation
+     * channel) and escalates until someone answers or the deadline passes.
+     * One Event. Read the answer with `questions.wait`, or use `askAndWait`.
+     */
+    ask(input: AskHumanInput): Promise<AgentQuestion>;
+    /**
+     * `ask`, then `questions.wait` in a loop until the question is answered,
+     * expired or canceled, or `timeoutMs` (default 10 minutes) runs out:
+     * then it resolves with `timedOut: true` and the open question. Network
+     * errors, 5xx and 429s are retried (after `Retry-After`) inside the
+     * timeout; others reject. `signal` rejects it with code `ABORTED`.
+     */
+    askAndWait(input: AskHumanInput, options?: AskAndWaitOptions): Promise<AskAndWaitResult>;
+    questions: {
+        /** A question with its escalation steps (`agents:ask_human` or `agents:read`). */
+        get(questionId: string, options?: QuestionReadOptions): Promise<{
+            question: AgentQuestion;
+            escalations: QuestionEscalation[];
+        }>;
+        /** The agent's questions and those escalated to it, newest first. */
+        list(options?: ListQuestionsOptions): Promise<QuestionPage>;
+        /**
+         * One long-poll (at most 25 s): resolves as soon as the question closes,
+         * or with `timedOut: true` while it's still open.
+         */
+        wait(questionId: string, options?: WaitQuestionOptions): Promise<WaitQuestionResult>;
+        /**
+         * Answer a question escalated to this agent (its asker's manager agent;
+         * `agents:send` or `agents:ask_human`). The first answer wins: later
+         * ones get `QuestionClosedError`. Approvals that ask for a role need a
+         * person (403 `APPROVAL_ROLE_REQUIRED`).
+         */
+        answer(questionId: string, input: AnswerQuestionInput): Promise<AgentQuestion>;
+        /** Cancel one of the agent's own open questions (`agents:ask_human`). */
+        cancel(questionId: string, options?: QuestionReadOptions): Promise<AgentQuestion>;
+    };
+    tasks: {
+        /** Create a task, optionally assigned and with a due date (`agents:send`). */
+        create(input: CreateTaskInput): Promise<CreateTaskResult>;
+        /** Tasks, newest first (`agents:read`; keys bound to agents need `channelId`). */
+        list(options?: ListTasksOptions): Promise<AgentTask[]>;
+        /** A channel's board: tasks by column, counts and the agents on it. */
+        board(channelId: string, options?: TaskBoardOptions): Promise<TaskBoard>;
+        /** A task with its history. */
+        get(taskId: string, options?: {
+            agentId?: string;
+        }): Promise<TaskDetail>;
+        /**
+         * Move a task on the board, change its due date, with a note (the
+         * assignee or creator; `agents:send`). 409 `TASK_CLOSED` once closed.
+         */
+        update(taskId: string, input: UpdateTaskInput): Promise<UpdateTaskResult>;
+        /** Hand a task to another member agent of its channel (`agents:send`). */
+        handoff(taskId: string, input: HandoffTaskInput): Promise<HandoffTaskResult>;
+    };
+    /** Teams (reads: `agents:read`; writes: an unbound `agents:admin` key). */
+    teams: {
+        list(): Promise<AgentTeam[]>;
+        get(teamId: string): Promise<AgentTeamDetail>;
+        create(input: CreateTeamInput): Promise<AgentTeam>;
+        update(teamId: string, input: UpdateTeamInput): Promise<AgentTeam>;
+        delete(teamId: string): Promise<{
+            memberships_removed: number;
+        }>;
+        addMember(teamId: string, agentId: string): Promise<{
+            member: unknown;
+            channels_granted: number;
+        }>;
+        removeMember(teamId: string, agentId: string): Promise<{
+            memberships_removed: number;
+        }>;
+        grantChannel(teamId: string, channelId: string, role?: AgentMemberRole): Promise<{
+            grant: AgentTeamChannelGrant;
+            memberships_added: number;
+        }>;
+        revokeChannel(teamId: string, channelId: string): Promise<{
+            memberships_removed: number;
+        }>;
+    };
+    /** Policies (an unbound `agents:admin` key). */
+    policies: {
+        list(options?: {
+            scope?: PolicyScope;
+        }): Promise<AgentPolicy[]>;
+        get(policyId: string): Promise<AgentPolicy>;
+        /** Create or replace the policy of a scope. */
+        put(input: PutPolicyInput): Promise<AgentPolicy>;
+        delete(policyId: string): Promise<void>;
+        /** The effective policy of an agent (in a channel): rules, sources, usage and checks. */
+        preview(agentId: string, options?: {
+            channelId?: string;
+        }): Promise<EffectivePolicyPreview>;
+    };
+    orgChart: {
+        /** The org chart (`agents:read`). */
+        get(options?: OrgChartOptions): Promise<OrgChart>;
+        /** Set or clear an agent's manager (`agents:admin`). 409 `ORG_CHART_CYCLE`. */
+        setManager(agentId: string, input: SetManagerInput): Promise<Agent>;
+        /** Set or clear an agent's owner, a person (`agents:admin`). */
+        setOwner(agentId: string, ownerUserId: string | null): Promise<Agent>;
+    };
+    /** An agent's onboarding checklist (`agents:admin`). */
+    onboarding(agentId: string): Promise<AgentOnboarding>;
+    /**
+     * Pause (with a reason), resume or retire an agent (`agents:admin`).
+     * Resuming releases its held deliveries, oldest first.
+     */
+    setStatus(agentId: string, status: AgentStatus, options?: {
+        reason?: string;
+    }): Promise<AgentStatusResult>;
+}
+/** An `agent.message` delivery (a channel message, task or status). */
+declare function isAgentMessageWebhook(payload: AgentWebhookEvent | null | undefined): payload is AgentWebhookPayload;
+/** A closed question pushed to its asker (`question.answered` / `expired` / `canceled`). */
+declare function isQuestionOutcomeWebhook(payload: AgentWebhookEvent | null | undefined): payload is QuestionOutcomeWebhookPayload;
+/** A question escalated to this (manager) agent: answer it with `questions.answer`. */
+declare function isQuestionEscalatedWebhook(payload: AgentWebhookEvent | null | undefined): payload is QuestionEscalatedWebhookPayload;
+/**
+ * A question's outcome posted in its thread (questions asked with a
+ * `channelId`): `message.data` is `{ type, question, answer }`.
+ */
+declare function isQuestionOutcomeMessage(message: AgentMessage | null | undefined): message is AgentMessage & {
+    data: QuestionOutcomeData;
+};
+/**
+ * The `status` message a task handoff posts (delivered to the previous and
+ * new assignees): `message.data.handoff` says who to whom, and why.
+ */
+declare function isTaskHandoffMessage(message: AgentMessage | null | undefined): message is AgentMessage & {
+    data: TaskHandoffData;
+};
+
+/**
+ * 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`.
+ */
+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>;
+    /**
+     * 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>;
+
+/**
+ * Helpers shared by `@channlize/core`, `@channlize/react` and
+ * `@channlize/mcp`: defaults, key detection, environment variables, event
+ * keys and the API's error shape. Core is the single source for these.
+ */
+/** Default API base URL. */
+declare const DEFAULT_BASE_URL = "https://api.channlize.com";
+/** Default request timeout, in milliseconds. */
+declare const DEFAULT_TIMEOUT = 10000;
+/** Log tracking severities, lowest first. */
+declare const EVENT_SEVERITIES: readonly ["info", "warning", "error"];
+/**
+ * Valid Events key (same rule as the API): lowercase letters, digits,
+ * dots, underscores and dashes, e.g. `user.subscribed`. At most 100
+ * characters.
+ */
+declare const EVENT_KEY_PATTERN: RegExp;
+/** Whether `event` is a valid Events key for `notify`. */
+declare function isValidEventKey(event: unknown): event is string;
+type KeyKind = 'widget' | 'server';
+/**
+ * `wk_…` is the public widget key (browser: contact form, chat, browser
+ * log tracking); anything else is a server API key (`ch_live_…`).
+ */
+declare function keyKind(key: string): KeyKind;
+/** The `CHANNLIZE_*` environment variables, trimmed (empty → undefined). */
+interface ChannlizeEnv {
+    /** `CHANNLIZE_SERVER_API_KEY` */
+    serverApiKey?: string;
+    /** `CHANNLIZE_WIDGET_KEY` */
+    widgetKey?: string;
+    /** `CHANNLIZE_API_KEY` (either kind of key) */
+    apiKey?: string;
+    /** `CHANNLIZE_PROJECT_ID` */
+    projectId?: string;
+    /** `CHANNLIZE_BASE_URL` */
+    baseUrl?: string;
+    /** `CHANNLIZE_TIMEOUT` (milliseconds, unparsed) */
+    timeout?: string;
+    /** `CHANNLIZE_AGENT_ID` (Channlize for Agents: the agent to act as) */
+    agentId?: string;
+}
+/**
+ * Reads the `CHANNLIZE_*` environment variables. Safe in browsers and edge
+ * runtimes without `process` (everything is undefined there).
+ */
+declare function readChannlizeEnv(env?: Record<string, string | undefined> | undefined): ChannlizeEnv;
+/** A failed API response, parsed from its JSON body. */
+interface ApiErrorInfo {
+    status: number;
+    /** Human-readable text (field messages joined with `, `). */
+    message: string;
+    /** Machine-readable code: the body's `code`, else its `error` (e.g. `NOT_FOUND`). */
+    code?: string;
+    /** `requestId` from the body, to quote to support. */
+    requestId?: string;
+    /** The parsed body (e.g. `limit`, `used`, `resetAt` on a plan-limit 429). */
+    body: Record<string, unknown>;
+}
+/**
+ * Parses the API's error shape (`api/lib/api/error.ts`):
+ * `{ statusCode, error: "NOT_FOUND", message: string | string[], requestId? }`.
+ * A few legacy routes put the human text in `error`.
+ */
+declare function parseApiError(status: number, body: unknown, statusText?: string): ApiErrorInfo;
+
 /**
  * Core types for Channlize SDK
  */
+
 /** Severity for log tracking (`trackEvent` / `trackServerEvent`); Slack alerts use project settings. */
-type EventSeverity = 'info' | 'warning' | 'error';
+type EventSeverity = (typeof EVENT_SEVERITIES)[number];
 /** Options for log tracking (`trackEvent` / `trackServerEvent`). */
 interface TrackEventOptions {
     properties?: Record<string, unknown>;
@@ -105,11 +1323,15 @@ interface ChatMessage {
     id: string;
     /** Message content */
     content: string;
-    /** Message timestamp */
+    /**
+     * Message timestamp. The API sends an ISO 8601 string, which
+     * `ChannlizeClient` passes through as is; `@channlize/react` converts it
+     * to a `Date`. Wrap it in `new Date(...)` before using `Date` methods.
+     */
     timestamp: Date;
     /** Message author (user or agent) */
     author: 'user' | 'agent';
-    /** Author metadata */
+    /** Author metadata (`name` / `email` can be `null` in message history) */
     authorData?: {
         name?: string;
         email?: string;
@@ -133,15 +1355,23 @@ interface FileAttachment {
 interface ChatSession {
     /** Session ID */
     id: string;
-    /** Session status */
+    /**
+     * Session status. `createChatSession` answers `active`; `getChatSession`
+     * and `closeChatSession` answer the conversation's status (`open`,
+     * `pending`, `resolved` or `closed`).
+     */
     status: 'active' | 'closed' | 'waiting';
-    /** Messages in the session */
+    /**
+     * Messages in the session. Only `createChatSession` returns it (empty);
+     * `getChatSession`, `closeChatSession` and `sendMessage` return a session
+     * summary without it. Load history with `getChatMessages`.
+     */
     messages: ChatMessage[];
     /** Session metadata */
     metadata?: Record<string, unknown>;
-    /** Created timestamp */
+    /** Created timestamp (an ISO 8601 string on the wire; not sent by `closeChatSession`) */
     createdAt: Date;
-    /** Updated timestamp */
+    /** Updated timestamp (an ISO 8601 string on the wire) */
     updatedAt: Date;
 }
 interface ApiResponse<T = unknown> {
@@ -178,7 +1408,7 @@ interface CreateChatSessionResponse {
 interface SendMessageResponse {
     /** The sent message */
     message: ChatMessage;
-    /** Updated session */
+    /** The session (the API sends only `id` and `status`) */
     session: ChatSession;
 }
 /**
@@ -187,6 +1417,19 @@ interface SendMessageResponse {
 declare class ChannlizeError extends Error {
     statusCode?: number | undefined;
     code?: string | undefined;
+    /** The API's `requestId` for a failed response, to quote to support. */
+    requestId?: string;
+    /**
+     * The API's JSON error body, e.g. `limit`, `used`, `resetAt` and
+     * `upgradeUrl` on a plan-limit 429. Undefined for network errors.
+     */
+    details?: Record<string, unknown>;
+    /**
+     * ISO time the call may succeed again: the body's `retryAt` (agent
+     * policies, human takeovers), else derived from a `Retry-After` header.
+     * See `retryAfter(error)`.
+     */
+    retryAt?: string;
     constructor(message: string, statusCode?: number | undefined, code?: string | undefined);
 }
 declare class ValidationError extends ChannlizeError {
@@ -196,8 +1439,25 @@ declare class ValidationError extends ChannlizeError {
 declare class AuthenticationError extends ChannlizeError {
     constructor(message?: string);
 }
+/**
+ * A 429. `code` is `PLAN_LIMIT_REACHED` when the organization is past its
+ * plan's limit for the billing period (the API's 110 % hard cap), else
+ * `RATE_LIMIT_ERROR`.
+ */
 declare class RateLimitError extends ChannlizeError {
-    constructor(message?: string);
+    constructor(message?: string, code?: string);
+}
+/**
+ * What `trackEvent` / `trackServerEvent` resolve with. When the API refuses
+ * the event with a 429 (rate limit or plan limit), the call resolves with
+ * `success: false` and `dropped` instead of throwing: log tracking never
+ * breaks the app that calls it.
+ */
+interface TrackEventResult {
+    success: boolean;
+    id: string;
+    /** Set when the event was refused and not stored. */
+    dropped?: 'plan_limit' | 'rate_limit';
 }
 
 /**
@@ -211,6 +1471,13 @@ declare class ChannlizeClient<TEvents extends object = ChannlizeEvents> {
     private readonly config;
     constructor(config: ChannlizeConfig);
     private validateConfig;
+    private agentsClient?;
+    /**
+     * Channlize for Agents (`agents.send`, `agents.inbox`, `agents.poll`, ...),
+     * authenticated with `serverApiKey`: an agent key or a multi-agent key.
+     * Same as `createAgentsClient({ apiKey: serverApiKey, baseUrl, timeout })`.
+     */
+    get agents(): AgentsClient;
     private makeRequest;
     /**
      * Submit a contact form
@@ -242,10 +1509,8 @@ declare class ChannlizeClient<TEvents extends object = ChannlizeEvents> {
      * Log tracking: record a log line from the browser (widget key →
      * `POST /public/events`). Shown under Log tracking in the dashboard.
      */
-    trackEvent(name: string, options?: TrackEventOptions): Promise<{
-        success: boolean;
-        id: string;
-    }>;
+    trackEvent(name: string, options?: TrackEventOptions): Promise<TrackEventResult>;
+    private sendBrowserEvent;
     /**
      * Log tracking from a trusted server, using the organization API key
      * (`POST /v1/events`). Shown under Log tracking in the dashboard.
@@ -253,10 +1518,15 @@ declare class ChannlizeClient<TEvents extends object = ChannlizeEvents> {
     trackServerEvent(name: string, options?: {
         properties?: Record<string, unknown>;
         severity?: EventSeverity;
-    }): Promise<{
-        success: boolean;
-        id: string;
-    }>;
+    }): Promise<TrackEventResult>;
+    /**
+     * Log tracking must never break the caller: a 429 (rate limit, or the
+     * plan's limit for the billing period) resolves with `success: false`
+     * and `dropped` instead of throwing, with one console warning per client.
+     */
+    private nonFatalTracking;
+    private warnedDropped;
+    private sendServerEvent;
     /**
      * Events: post a Slack message from your server when something happens
      * (`POST /v1/notify`). The event key picks the channel and message
@@ -284,5 +1554,71 @@ type Notifier<TEvents extends object = ChannlizeEvents> = <K extends NotifyEvent
  */
 declare function createNotifier<TEvents extends object = ChannlizeEvents>(config?: NotifierConfig): Notifier<TEvents>;
 
-export { AuthenticationError, ChannlizeClient, ChannlizeError, RateLimitError, ValidationError, createNotifier, ChannlizeClient as default };
-export type { ApiResponse, ChannlizeConfig, ChannlizeEvents, ChatMessage, ChatSession, ContactFormData, CreateChatSessionResponse, CreateContactResponse, EventSeverity, FileAttachment, Notifier, NotifierConfig, NotifyEventData, NotifyEventName, NotifyOptions, NotifyResponse, SendMessageResponse, TrackEventOptions };
+/**
+ * Channlize for Agents: typed errors for the policy, takeover, loop-guard,
+ * task and question refusals of the `/v1/agents` API, and the
+ * `isRetryable` / `retryAfter` helpers. `requestJson` (`http.ts`) picks the
+ * class from the error body's `code`.
+ */
+
+/** The policy refusal codes (`api/lib/agents/policy.ts`, `POLICY_CODES`). */
+declare const AGENT_POLICY_CODES: readonly ["POLICY_CHANNEL_NOT_ALLOWED", "POLICY_DM_NOT_ALLOWED", "POLICY_ASK_HUMAN_NOT_ALLOWED", "POLICY_URGENCY_NOT_ALLOWED", "POLICY_RATE_LIMITED", "POLICY_BUDGET_EXHAUSTED", "POLICY_OUTSIDE_WORKING_HOURS", "POLICY_MAX_DEPTH"];
+type AgentPolicyCode = (typeof AGENT_POLICY_CODES)[number];
+/** Why the loop guard paused a thread (`details.reason` of `AGENT_THREAD_PAUSED`). */
+type AgentThreadPauseReason = 'thread_cap' | 'ping_pong' | 'duplicate_content';
+/** The task refusals: 409 `TASK_CLOSED`, `ALREADY_ASSIGNED`, `AGENT_NOT_IN_CHANNEL`; 403 `NOT_TASK_PARTICIPANT`. */
+declare const AGENT_TASK_ERROR_CODES: readonly ["TASK_CLOSED", "ALREADY_ASSIGNED", "AGENT_NOT_IN_CHANNEL", "NOT_TASK_PARTICIPANT"];
+type AgentTaskErrorCode = (typeof AGENT_TASK_ERROR_CODES)[number];
+/**
+ * An agent policy refused the call (403, or 429 for rate limits and
+ * budgets). `retryAt` is set when waiting helps: rate limits, budgets (the
+ * next period) and working hours (the next window). Without it, retrying
+ * can't succeed: the policy forbids the channel, the DM, the urgency or
+ * asking at all.
+ */
+declare class AgentPolicyError extends ChannlizeError {
+    constructor(message: string, statusCode: number, code: AgentPolicyCode | (string & {}), retryAt?: string);
+}
+/**
+ * 409 `HUMAN_TAKEOVER`: a person replied in the thread, so its agents stay
+ * out of it until `retryAt` (the policy's `humans_win_minutes`), or until
+ * an admin resumes the thread.
+ */
+declare class HumanTakeoverError extends ChannlizeError {
+    constructor(message: string, retryAt?: string);
+}
+/**
+ * 429 `AGENT_THREAD_PAUSED`: the loop guard paused the thread (`reason`:
+ * the thread cap, two agents ping-ponging, or duplicate content). A
+ * person's reply or an admin resumes it; else the pause ends after
+ * `Retry-After` (an hour). Still a `RateLimitError`.
+ */
+declare class AgentThreadPausedError extends RateLimitError {
+    reason: AgentThreadPauseReason | (string & {});
+    constructor(message: string, reason?: AgentThreadPauseReason | (string & {}));
+}
+/** A task change the API refused (see `AGENT_TASK_ERROR_CODES`). Retrying doesn't help. */
+declare class AgentTaskError extends ChannlizeError {
+    constructor(message: string, statusCode: number, code: AgentTaskErrorCode | (string & {}));
+}
+/** 409 `QUESTION_CLOSED`: the question was already answered, expired or canceled (the first answer wins). */
+declare class QuestionClosedError extends ChannlizeError {
+    constructor(message: string);
+}
+/**
+ * Whether retrying the same call later can succeed: network errors and
+ * timeouts, 5xx, 429s (except `PLAN_LIMIT_REACHED`, which lasts the billing
+ * period), and policy refusals or human takeovers that carry a `retryAt`.
+ * Wrong input, scopes, ids, closed tasks and forbidding policies are not.
+ */
+declare function isRetryable(error: unknown): boolean;
+/**
+ * How long to wait before retrying, in milliseconds (0 when the time has
+ * passed), from the error's `retryAt` (the body's `retryAt`, else the
+ * `Retry-After` header). Undefined when the error isn't retryable or names
+ * no time: then pick your own backoff.
+ */
+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 };