@channlize/core 0.2.1 → 0.5.0

package/dist/index.js

@@ -30,19 +30,98 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AGENT_DELIVERY_MODES: () => AGENT_DELIVERY_MODES,
+  AGENT_MESSAGE_TYPES: () => AGENT_MESSAGE_TYPES,
+  AGENT_POLICY_CODES: () => AGENT_POLICY_CODES,
+  AGENT_STATUSES: () => AGENT_STATUSES,
+  AGENT_TASK_ERROR_CODES: () => AGENT_TASK_ERROR_CODES,
+  AGENT_TASK_STATUSES: () => AGENT_TASK_STATUSES,
+  AgentPolicyError: () => AgentPolicyError,
+  AgentTaskError: () => AgentTaskError,
+  AgentThreadPausedError: () => AgentThreadPausedError,
   AuthenticationError: () => AuthenticationError,
   ChannlizeClient: () => ChannlizeClient,
   ChannlizeError: () => ChannlizeError,
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  DEFAULT_TIMEOUT: () => DEFAULT_TIMEOUT,
+  EVENT_KEY_PATTERN: () => EVENT_KEY_PATTERN,
+  EVENT_SEVERITIES: () => EVENT_SEVERITIES,
+  HumanTakeoverError: () => HumanTakeoverError,
+  POLICY_SCOPES: () => POLICY_SCOPES,
+  QUESTION_KINDS: () => QUESTION_KINDS,
+  QUESTION_STATUSES: () => QUESTION_STATUSES,
+  QUESTION_URGENCIES: () => QUESTION_URGENCIES,
+  QUESTION_WAIT_MAX_SECONDS: () => QUESTION_WAIT_MAX_SECONDS,
+  QuestionClosedError: () => QuestionClosedError,
   RateLimitError: () => RateLimitError,
+  SENDABLE_AGENT_MESSAGE_TYPES: () => SENDABLE_AGENT_MESSAGE_TYPES,
+  TASK_BOARD_STATUSES: () => TASK_BOARD_STATUSES,
   ValidationError: () => ValidationError,
+  createAgentsClient: () => createAgentsClient,
   createNotifier: () => createNotifier,
-  default: () => ChannlizeClient
+  default: () => ChannlizeClient,
+  isAgentMessageWebhook: () => isAgentMessageWebhook,
+  isQuestionEscalatedWebhook: () => isQuestionEscalatedWebhook,
+  isQuestionOutcomeMessage: () => isQuestionOutcomeMessage,
+  isQuestionOutcomeWebhook: () => isQuestionOutcomeWebhook,
+  isRetryable: () => isRetryable,
+  isTaskHandoffMessage: () => isTaskHandoffMessage,
+  isValidEventKey: () => isValidEventKey,
+  keyKind: () => keyKind,
+  parseAgentWebhook: () => parseAgentWebhook,
+  parseAgentWebhookEvent: () => parseAgentWebhookEvent,
+  parseApiError: () => parseApiError,
+  readChannlizeEnv: () => readChannlizeEnv,
+  retryAfter: () => retryAfter,
+  verifyAgentWebhook: () => verifyAgentWebhook
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/http.ts
 var import_cross_fetch = __toESM(require("cross-fetch"));
 
+// src/shared.ts
+var DEFAULT_BASE_URL = "https://api.channlize.com";
+var DEFAULT_TIMEOUT = 1e4;
+var EVENT_SEVERITIES = ["info", "warning", "error"];
+var EVENT_KEY_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+function isValidEventKey(event) {
+  return typeof event === "string" && event.length <= 100 && EVENT_KEY_PATTERN.test(event);
+}
+function keyKind(key) {
+  return key.startsWith("wk_") ? "widget" : "server";
+}
+function clean(value) {
+  const v = value?.trim();
+  return v ? v : void 0;
+}
+function readChannlizeEnv(env = typeof process !== "undefined" ? process.env : void 0) {
+  return {
+    serverApiKey: clean(env?.CHANNLIZE_SERVER_API_KEY),
+    widgetKey: clean(env?.CHANNLIZE_WIDGET_KEY),
+    apiKey: clean(env?.CHANNLIZE_API_KEY),
+    projectId: clean(env?.CHANNLIZE_PROJECT_ID),
+    baseUrl: clean(env?.CHANNLIZE_BASE_URL),
+    timeout: clean(env?.CHANNLIZE_TIMEOUT),
+    agentId: clean(env?.CHANNLIZE_AGENT_ID)
+  };
+}
+function parseApiError(status, body, statusText = "") {
+  const data = body && typeof body === "object" ? body : {};
+  const raw = data.message;
+  const joined = Array.isArray(raw) ? raw.filter((m) => typeof m === "string").join(", ") : typeof raw === "string" ? raw : "";
+  const error = typeof data.error === "string" ? data.error : void 0;
+  const code = typeof data.code === "string" ? data.code : error;
+  const message = joined || (error && /\s/.test(error) ? error : "") || `HTTP ${status}: ${statusText}`.replace(/: $/, "");
+  return {
+    status,
+    message,
+    code,
+    requestId: typeof data.requestId === "string" ? data.requestId : void 0,
+    body: data
+  };
+}
+
 // src/types.ts
 var ChannlizeError = class extends Error {
   constructor(message, statusCode, code) {
@@ -53,6 +132,19 @@ var ChannlizeError = class extends Error {
   }
   statusCode;
   code;
+  /** The API's `requestId` for a failed response, to quote to support. */
+  requestId;
+  /**
+   * The API's JSON error body, e.g. `limit`, `used`, `resetAt` and
+   * `upgradeUrl` on a plan-limit 429. Undefined for network errors.
+   */
+  details;
+  /**
+   * 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;
 };
 var ValidationError = class extends ChannlizeError {
   constructor(message, field) {
@@ -69,17 +161,112 @@ var AuthenticationError = class extends ChannlizeError {
   }
 };
 var RateLimitError = class extends ChannlizeError {
-  constructor(message = "Rate limit exceeded") {
-    super(message, 429, "RATE_LIMIT_ERROR");
+  constructor(message = "Rate limit exceeded", code = "RATE_LIMIT_ERROR") {
+    super(message, 429, code);
     this.name = "RateLimitError";
   }
 };
 
+// src/agents-errors.ts
+var AGENT_POLICY_CODES = [
+  "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"
+];
+var AGENT_TASK_ERROR_CODES = [
+  "TASK_CLOSED",
+  "ALREADY_ASSIGNED",
+  "AGENT_NOT_IN_CHANNEL",
+  "NOT_TASK_PARTICIPANT"
+];
+var AgentPolicyError = class extends ChannlizeError {
+  constructor(message, statusCode, code, retryAt) {
+    super(message, statusCode, code);
+    this.name = "AgentPolicyError";
+    this.retryAt = retryAt;
+  }
+};
+var HumanTakeoverError = class extends ChannlizeError {
+  constructor(message, retryAt) {
+    super(message, 409, "HUMAN_TAKEOVER");
+    this.name = "HumanTakeoverError";
+    this.retryAt = retryAt;
+  }
+};
+var AgentThreadPausedError = class extends RateLimitError {
+  constructor(message, reason = "thread_cap") {
+    super(message, "AGENT_THREAD_PAUSED");
+    this.reason = reason;
+    this.name = "AgentThreadPausedError";
+  }
+  reason;
+};
+var AgentTaskError = class extends ChannlizeError {
+  constructor(message, statusCode, code) {
+    super(message, statusCode, code);
+    this.name = "AgentTaskError";
+  }
+};
+var QuestionClosedError = class extends ChannlizeError {
+  constructor(message) {
+    super(message, 409, "QUESTION_CLOSED");
+    this.name = "QuestionClosedError";
+  }
+};
+function agentErrorFor(status, message, code, body, retryAt) {
+  if (!code) return void 0;
+  if (code.startsWith("POLICY_")) {
+    return new AgentPolicyError(message, status, code, retryAt);
+  }
+  switch (code) {
+    case "HUMAN_TAKEOVER":
+      return new HumanTakeoverError(message, retryAt);
+    case "AGENT_THREAD_PAUSED":
+      return new AgentThreadPausedError(
+        message,
+        typeof body.reason === "string" ? body.reason : void 0
+      );
+    case "AGENT_RATE_LIMITED":
+      return new RateLimitError(message, code);
+    case "QUESTION_CLOSED":
+      return new QuestionClosedError(message);
+    default:
+      return AGENT_TASK_ERROR_CODES.includes(code) ? new AgentTaskError(message, status, code) : void 0;
+  }
+}
+function isRetryable(error) {
+  if (!(error instanceof ChannlizeError)) return false;
+  const { statusCode: status, code } = error;
+  if (code === "NETWORK_ERROR" || code === "TIMEOUT") return true;
+  if (status === void 0) return false;
+  if (status >= 500) return true;
+  if (error instanceof AgentPolicyError || error instanceof HumanTakeoverError) {
+    return Boolean(error.retryAt);
+  }
+  if (status === 429) return code !== "PLAN_LIMIT_REACHED";
+  return false;
+}
+function retryAfter(error, now = Date.now()) {
+  if (!isRetryable(error)) return void 0;
+  const at = error.retryAt;
+  const ms = at ? Date.parse(at) : NaN;
+  return Number.isFinite(ms) ? Math.max(0, ms - now) : void 0;
+}
+
 // src/http.ts
 async function requestJson(http, endpoint, options = {}) {
   const url = `${http.baseUrl}${endpoint}`;
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), http.timeout);
+  const external = options.signal ?? void 0;
+  const onAbort = () => controller.abort();
+  if (external?.aborted) controller.abort();
+  else external?.addEventListener("abort", onAbort, { once: true });
   try {
     const mergedHeaders = {
       "Content-Type": "application/json",
@@ -104,52 +291,93 @@ async function requestJson(http, endpoint, options = {}) {
     if (error instanceof ChannlizeError) {
       throw error;
     }
+    if (external?.aborted) {
+      throw new ChannlizeError("Request aborted", void 0, "ABORTED");
+    }
     if (error instanceof Error && error.name === "AbortError") {
       throw new ChannlizeError("Request timeout", 408, "TIMEOUT");
     }
     throw new ChannlizeError(
-      `Network error: ${error instanceof Error ? error.message : "Unknown error"}`
+      `Network error: ${error instanceof Error ? error.message : "Unknown error"}`,
+      void 0,
+      "NETWORK_ERROR"
     );
+  } finally {
+    external?.removeEventListener("abort", onAbort);
   }
 }
+function retryAfterHeader(value) {
+  if (!value) return void 0;
+  const seconds = Number(value);
+  const ms = Number.isFinite(seconds) ? Date.now() + seconds * 1e3 : Date.parse(value);
+  return Number.isFinite(ms) ? new Date(ms).toISOString() : void 0;
+}
 async function handleErrorResponse(response) {
-  const contentType = response.headers.get("content-type");
-  let errorData = {};
-  if (contentType?.includes("application/json")) {
+  let body = {};
+  if (response.headers.get("content-type")?.includes("application/json")) {
     try {
-      errorData = await response.json();
+      body = await response.json();
     } catch {
     }
   }
-  const rawMessage = errorData.message;
-  const message = (Array.isArray(rawMessage) ? rawMessage.join(", ") : rawMessage) || `HTTP ${response.status}: ${response.statusText}`;
-  const code = errorData.code ?? errorData.error;
-  switch (response.status) {
+  throw errorFromApi(
+    parseApiError(response.status, body, response.statusText),
+    retryAfterHeader(response.headers.get("retry-after"))
+  );
+}
+function errorFromApi(info, retryAfter2) {
+  const { status, message, code } = info;
+  const retryAt = typeof info.body.retryAt === "string" ? info.body.retryAt : retryAfter2;
+  let error = agentErrorFor(
+    status,
+    message,
+    code,
+    info.body,
+    retryAt
+  );
+  if (error) {
+    error.requestId = info.requestId;
+    error.details = info.body;
+    error.retryAt ??= retryAt;
+    return error;
+  }
+  switch (status) {
     case 401:
-      throw new AuthenticationError(message);
+      error = new AuthenticationError(message);
+      break;
     case 400:
-      throw new ValidationError(message, errorData.field);
+      error = new ValidationError(
+        message,
+        typeof info.body.field === "string" ? info.body.field : void 0
+      );
+      break;
     case 429:
-      throw new RateLimitError(message);
+      error = new RateLimitError(
+        message,
+        code === "PLAN_LIMIT_REACHED" ? code : void 0
+      );
+      break;
     default:
-      throw new ChannlizeError(message, response.status, code);
+      error = new ChannlizeError(message, status, code);
   }
+  error.requestId = info.requestId;
+  error.details = info.body;
+  error.retryAt = retryAt;
+  return error;
 }
 
 // src/notify.ts
-var EVENT_KEY = /^[a-z0-9][a-z0-9._-]*$/;
-var DEFAULT_BASE_URL = "https://api.channlize.com";
 async function sendNotify(http, auth, event, data, options = {}) {
   if (!auth.projectId) {
     throw new ValidationError("projectId is required for notify", "projectId");
   }
-  if (auth.serverApiKey.startsWith("wk_")) {
+  if (keyKind(auth.serverApiKey) === "widget") {
     throw new ValidationError(
       "notify needs a server API key (ch_live_\u2026, write scope), not the public widget key",
       "serverApiKey"
     );
   }
-  if (typeof event !== "string" || event.length > 100 || !EVENT_KEY.test(event)) {
+  if (!isValidEventKey(event)) {
     throw new ValidationError(
       `Invalid event key "${event}": use lowercase letters, digits, dots, underscores or dashes (e.g. user.subscribed)`,
       "event"
@@ -173,15 +401,11 @@ async function sendNotify(http, auth, event, data, options = {}) {
   });
   return res;
 }
-function readEnv(name) {
-  const env = typeof process !== "undefined" && process.env ? process.env : void 0;
-  const value = env?.[name];
-  return value && value.trim() ? value.trim() : void 0;
-}
 function createNotifier(config = {}) {
   return (event, data, options) => {
-    const serverApiKey = config.serverApiKey ?? readEnv("CHANNLIZE_SERVER_API_KEY") ?? readEnv("CHANNLIZE_API_KEY");
-    const projectId = config.projectId ?? readEnv("CHANNLIZE_PROJECT_ID");
+    const env = readChannlizeEnv();
+    const serverApiKey = config.serverApiKey ?? env.serverApiKey ?? env.apiKey;
+    const projectId = config.projectId ?? env.projectId;
     if (!serverApiKey) {
       return Promise.reject(
         new ValidationError(
@@ -198,9 +422,12 @@ function createNotifier(config = {}) {
         )
       );
     }
-    const baseUrl = config.baseUrl ?? readEnv("CHANNLIZE_BASE_URL") ?? DEFAULT_BASE_URL;
+    const baseUrl = config.baseUrl ?? env.baseUrl ?? DEFAULT_BASE_URL;
     return sendNotify(
-      { baseUrl: baseUrl.replace(/\/$/, ""), timeout: config.timeout ?? 1e4 },
+      {
+        baseUrl: baseUrl.replace(/\/$/, ""),
+        timeout: config.timeout ?? DEFAULT_TIMEOUT
+      },
       { serverApiKey, projectId },
       event,
       data,
@@ -209,6 +436,792 @@ function createNotifier(config = {}) {
   };
 }
 
+// src/agents-governance-types.ts
+var QUESTION_KINDS = ["question", "approval"];
+var QUESTION_URGENCIES = ["low", "normal", "high", "urgent"];
+var QUESTION_STATUSES = [
+  "open",
+  "answered",
+  "expired_default",
+  "expired",
+  "canceled"
+];
+var QUESTION_WAIT_MAX_SECONDS = 25;
+var TASK_BOARD_STATUSES = [
+  "open",
+  "in_progress",
+  "blocked",
+  "done",
+  "failed"
+];
+var POLICY_SCOPES = ["org", "team", "agent", "channel"];
+
+// src/agents-governance.ts
+var enc = encodeURIComponent;
+var iso = (v) => v instanceof Date ? v.toISOString() : v;
+function sleep(ms, signal) {
+  return new Promise((done) => {
+    if (signal?.aborted) return done();
+    const timer = setTimeout(finish, ms);
+    function finish() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", finish);
+      done();
+    }
+    signal?.addEventListener("abort", finish, { once: true });
+  });
+}
+function aborted() {
+  return new ChannlizeError("Request aborted", void 0, "ABORTED");
+}
+function need(value, what, field) {
+  if (typeof value !== "string" || !value) {
+    throw new ValidationError(`${what} is required`, field);
+  }
+}
+function createAgentsGovernance(request, defaultAgentId) {
+  const agentOf = (agentId) => agentId ?? defaultAgentId;
+  const safely = (fn) => {
+    try {
+      return fn();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  };
+  function ask(input) {
+    return safely(async () => {
+      if (!input || typeof input.question !== "string" || !input.question) {
+        throw new ValidationError("ask needs a question", "question");
+      }
+      const r = await request(
+        "POST",
+        "/v1/agents/questions",
+        {
+          body: {
+            agent_id: agentOf(input.agentId),
+            kind: input.kind,
+            question: input.question,
+            options: input.options,
+            free_text: input.freeText,
+            urgency: input.urgency,
+            deadline: iso(input.deadline),
+            default_option: input.defaultOption,
+            channel_id: input.channelId,
+            thread_id: input.threadId,
+            context: input.context,
+            amount: input.amount,
+            currency: input.currency,
+            resource: input.resource,
+            required_roles: input.requiredRoles
+          }
+        }
+      );
+      return r.question;
+    });
+  }
+  function wait(questionId, options = {}) {
+    return safely(async () => {
+      need(questionId, "The question id", "questionId");
+      const timeoutSec = Math.min(
+        QUESTION_WAIT_MAX_SECONDS,
+        Math.max(0, options.timeoutSec ?? QUESTION_WAIT_MAX_SECONDS)
+      );
+      const r = await request(
+        "GET",
+        `/v1/agents/questions/${enc(questionId)}/wait`,
+        {
+          query: { agent_id: agentOf(options.agentId), timeout: timeoutSec },
+          // The server holds the request for up to timeoutSec.
+          timeout: (timeoutSec + 10) * 1e3,
+          signal: options.signal
+        }
+      );
+      return {
+        question: r.question,
+        timedOut: r.timed_out ?? r.question?.status === "open"
+      };
+    });
+  }
+  async function askAndWait(input, options = {}) {
+    const { signal } = options;
+    const deadline = Date.now() + Math.max(0, options.timeoutMs ?? 6e5);
+    if (signal?.aborted) throw aborted();
+    let question = await ask(input);
+    let failures = 0;
+    while (question.status === "open") {
+      if (signal?.aborted) throw aborted();
+      const left = deadline - Date.now();
+      if (left < 1e3) break;
+      try {
+        const r = await wait(question.id, {
+          agentId: input.agentId,
+          timeoutSec: Math.min(
+            QUESTION_WAIT_MAX_SECONDS,
+            Math.floor(left / 1e3)
+          ),
+          signal
+        });
+        question = r.question;
+        failures = 0;
+      } catch (error) {
+        if (signal?.aborted) throw aborted();
+        if (!isRetryable(error)) throw error;
+        failures += 1;
+        const backoff = retryAfter(error) ?? Math.min(3e4, 1e3 * 2 ** (failures - 1));
+        const remaining = deadline - Date.now();
+        if (backoff >= remaining) break;
+        await sleep(backoff, signal);
+      }
+    }
+    if (signal?.aborted && question.status === "open") throw aborted();
+    return {
+      question,
+      answer: question.answer ?? null,
+      timedOut: question.status === "open"
+    };
+  }
+  const questionPath = (id) => {
+    need(id, "The question id", "questionId");
+    return `/v1/agents/questions/${enc(id)}`;
+  };
+  const taskPath = (id) => {
+    need(id, "The task id", "taskId");
+    return `/v1/agents/tasks/${enc(id)}`;
+  };
+  const teamPath = (id) => {
+    need(id, "The team id", "teamId");
+    return `/v1/agents/teams/${enc(id)}`;
+  };
+  const agentPath = (id) => {
+    need(id, "The agent id", "agentId");
+    return enc(id);
+  };
+  return {
+    ask,
+    askAndWait,
+    questions: {
+      get: (id, options = {}) => safely(async () => {
+        const r = await request("GET", questionPath(id), {
+          query: { agent_id: agentOf(options.agentId) }
+        });
+        return { question: r.question, escalations: r.escalations ?? [] };
+      }),
+      list: (options = {}) => safely(async () => {
+        const r = await request("GET", "/v1/agents/questions", {
+          query: {
+            agent_id: agentOf(options.agentId),
+            status: options.status,
+            kind: options.kind,
+            urgency: options.urgency,
+            channel_id: options.channelId,
+            cursor: options.cursor,
+            limit: options.limit
+          }
+        });
+        return {
+          questions: r.questions ?? [],
+          nextCursor: r.next_cursor ?? null
+        };
+      }),
+      wait,
+      answer: (id, input) => safely(async () => {
+        if (!input?.optionId && !input?.text) {
+          throw new ValidationError(
+            "answer needs optionId or text",
+            "optionId"
+          );
+        }
+        const r = await request(
+          "POST",
+          `${questionPath(id)}/answer`,
+          {
+            body: {
+              agent_id: agentOf(input.agentId),
+              option_id: input.optionId,
+              text: input.text,
+              comment: input.comment
+            }
+          }
+        );
+        return r.question;
+      }),
+      cancel: (id, options = {}) => safely(async () => {
+        const r = await request(
+          "DELETE",
+          questionPath(id),
+          { query: { agent_id: agentOf(options.agentId) } }
+        );
+        return r.question;
+      })
+    },
+    tasks: {
+      create: (input) => safely(async () => {
+        need(input?.channelId, "channelId", "channelId");
+        const r = await request(
+          "POST",
+          "/v1/agents/tasks",
+          {
+            body: {
+              agent_id: agentOf(input.agentId),
+              channel_id: input.channelId,
+              text: input.text,
+              assignee_agent_id: input.assigneeAgentId,
+              due_at: iso(input.dueAt),
+              thread_id: input.threadId,
+              mentions: input.mentions,
+              data: input.data
+            }
+          }
+        );
+        return { task: r.task, deliveries: r.deliveries ?? [] };
+      }),
+      list: (options = {}) => safely(async () => {
+        const r = await request(
+          "GET",
+          "/v1/agents/tasks",
+          {
+            query: {
+              agent_id: agentOf(options.agentId),
+              channel_id: options.channelId,
+              assignee_agent_id: options.assigneeAgentId,
+              status: options.status,
+              limit: options.limit
+            }
+          }
+        );
+        return r.tasks ?? [];
+      }),
+      board: (channelId, options = {}) => safely(() => {
+        need(channelId, "channelId", "channelId");
+        return request("GET", "/v1/agents/tasks/board", {
+          query: {
+            channel_id: channelId,
+            assignee_agent_id: options.assigneeAgentId,
+            agent_id: agentOf(options.agentId)
+          }
+        });
+      }),
+      get: (taskId, options = {}) => safely(async () => {
+        const r = await request("GET", taskPath(taskId), {
+          query: { agent_id: agentOf(options.agentId) }
+        });
+        return { task: r.task, events: r.events ?? [] };
+      }),
+      update: (taskId, input) => safely(() => {
+        if (!input || input.status === void 0 && input.dueAt === void 0) {
+          throw new ValidationError("update needs status or dueAt", "status");
+        }
+        return request("PATCH", taskPath(taskId), {
+          body: {
+            agent_id: agentOf(input.agentId),
+            status: input.status,
+            due_at: input.dueAt === null ? null : iso(input.dueAt),
+            note: input.note
+          }
+        });
+      }),
+      handoff: (taskId, input) => safely(() => {
+        need(input?.toAgentId, "toAgentId", "toAgentId");
+        return request(
+          "POST",
+          `${taskPath(taskId)}/handoff`,
+          {
+            body: {
+              agent_id: agentOf(input.agentId),
+              to_agent_id: input.toAgentId,
+              reason: input.reason
+            }
+          }
+        );
+      })
+    },
+    teams: {
+      list: () => safely(async () => {
+        const r = await request(
+          "GET",
+          "/v1/agents/teams"
+        );
+        return r.teams ?? [];
+      }),
+      get: (teamId) => safely(() => request("GET", teamPath(teamId))),
+      create: (input) => safely(async () => {
+        const r = await request(
+          "POST",
+          "/v1/agents/teams",
+          {
+            body: {
+              name: input.name,
+              slug: input.slug,
+              description: input.description,
+              agent_ids: input.agentIds
+            }
+          }
+        );
+        return r.team;
+      }),
+      update: (teamId, input) => safely(async () => {
+        const r = await request(
+          "PATCH",
+          teamPath(teamId),
+          { body: input }
+        );
+        return r.team;
+      }),
+      delete: (teamId) => safely(async () => {
+        const r = await request(
+          "DELETE",
+          teamPath(teamId)
+        );
+        return { memberships_removed: r.memberships_removed ?? 0 };
+      }),
+      addMember: (teamId, agentId) => safely(() => {
+        need(agentId, "agentId", "agentId");
+        return request(
+          "POST",
+          `${teamPath(teamId)}/members`,
+          { body: { agent_id: agentId } }
+        );
+      }),
+      removeMember: (teamId, agentId) => safely(async () => {
+        const r = await request(
+          "DELETE",
+          `${teamPath(teamId)}/members/${agentPath(agentId)}`
+        );
+        return { memberships_removed: r.memberships_removed ?? 0 };
+      }),
+      grantChannel: (teamId, channelId, role) => safely(() => {
+        need(channelId, "channelId", "channelId");
+        return request("POST", `${teamPath(teamId)}/channels`, {
+          body: { channel_id: channelId, role }
+        });
+      }),
+      revokeChannel: (teamId, channelId) => safely(async () => {
+        need(channelId, "channelId", "channelId");
+        const r = await request(
+          "DELETE",
+          `${teamPath(teamId)}/channels/${enc(channelId)}`
+        );
+        return { memberships_removed: r.memberships_removed ?? 0 };
+      })
+    },
+    policies: {
+      list: (options = {}) => safely(async () => {
+        const r = await request(
+          "GET",
+          "/v1/agents/policies",
+          { query: { scope: options.scope } }
+        );
+        return r.policies ?? [];
+      }),
+      get: (policyId) => safely(async () => {
+        need(policyId, "The policy id", "policyId");
+        const r = await request(
+          "GET",
+          `/v1/agents/policies/${enc(policyId)}`
+        );
+        return r.policy;
+      }),
+      put: (input) => safely(async () => {
+        const r = await request(
+          "PUT",
+          "/v1/agents/policies",
+          {
+            body: {
+              scope: input.scope,
+              scope_id: input.scopeId,
+              rules: input.rules,
+              enabled: input.enabled
+            }
+          }
+        );
+        return r.policy;
+      }),
+      delete: (policyId) => safely(async () => {
+        need(policyId, "The policy id", "policyId");
+        await request("DELETE", `/v1/agents/policies/${enc(policyId)}`);
+      }),
+      preview: (agentId, options = {}) => safely(() => {
+        need(agentId, "agentId", "agentId");
+        return request(
+          "GET",
+          "/v1/agents/policies/preview",
+          { query: { agent_id: agentId, channel_id: options.channelId } }
+        );
+      })
+    },
+    orgChart: {
+      get: (options = {}) => request("GET", "/v1/agents/org-chart", {
+        query: {
+          team_id: options.teamId,
+          channel_id: options.channelId,
+          include_retired: options.includeRetired ? "true" : void 0
+        }
+      }),
+      setManager: (agentId, input) => safely(async () => {
+        if (input?.managerAgentId && input?.managerUserId) {
+          throw new ValidationError(
+            "Set managerAgentId or managerUserId, not both",
+            "managerAgentId"
+          );
+        }
+        const r = await request(
+          "PUT",
+          `/v1/agents/org-chart/${agentPath(agentId)}/manager`,
+          {
+            body: {
+              manager_agent_id: input?.managerAgentId ?? null,
+              manager_user_id: input?.managerUserId ?? null
+            }
+          }
+        );
+        return r.agent;
+      }),
+      setOwner: (agentId, ownerUserId) => safely(async () => {
+        const r = await request(
+          "PUT",
+          `/v1/agents/org-chart/${agentPath(agentId)}/owner`,
+          { body: { owner_user_id: ownerUserId ?? null } }
+        );
+        return r.agent;
+      })
+    },
+    onboarding: (agentId) => safely(
+      () => request(
+        "GET",
+        `/v1/agents/${agentPath(agentId)}/onboarding`
+      )
+    ),
+    setStatus: (agentId, status, options = {}) => safely(
+      () => request(
+        "POST",
+        `/v1/agents/${agentPath(agentId)}/status`,
+        { body: { status, reason: options.reason } }
+      )
+    )
+  };
+}
+var QUESTION_OUTCOMES = /* @__PURE__ */ new Set([
+  "question.answered",
+  "question.expired",
+  "question.canceled"
+]);
+function isAgentMessageWebhook(payload) {
+  return payload?.event === "agent.message";
+}
+function isQuestionOutcomeWebhook(payload) {
+  return Boolean(payload && QUESTION_OUTCOMES.has(payload.event));
+}
+function isQuestionEscalatedWebhook(payload) {
+  return payload?.event === "question.escalated";
+}
+function isQuestionOutcomeMessage(message) {
+  const data = message?.data;
+  return Boolean(
+    data && typeof data.type === "string" && QUESTION_OUTCOMES.has(data.type) && data.question && typeof data.question === "object"
+  );
+}
+function isTaskHandoffMessage(message) {
+  const handoff = message?.data?.handoff;
+  return Boolean(
+    message?.type === "status" && handoff && typeof handoff === "object" && typeof handoff.to_agent_id === "string"
+  );
+}
+
+// src/agents.ts
+function resolve(config) {
+  const env = readChannlizeEnv();
+  const apiKey = config.apiKey ?? env.serverApiKey ?? env.apiKey;
+  if (!apiKey) {
+    throw new ValidationError(
+      "An agent API key is required: pass apiKey or set CHANNLIZE_API_KEY (or CHANNLIZE_SERVER_API_KEY)",
+      "apiKey"
+    );
+  }
+  if (keyKind(apiKey) === "widget") {
+    throw new ValidationError(
+      "Agents need an agent key or a multi-agent key (ch_live_\u2026, agents:send / agents:read scopes), not the public widget key",
+      "apiKey"
+    );
+  }
+  return {
+    apiKey,
+    agentId: config.agentId ?? env.agentId,
+    baseUrl: (config.baseUrl ?? env.baseUrl ?? DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    ),
+    timeout: config.timeout ?? DEFAULT_TIMEOUT
+  };
+}
+var enc2 = encodeURIComponent;
+function isFatal(error) {
+  return error instanceof ChannlizeError && [400, 401, 403, 404].includes(error.statusCode ?? 0);
+}
+function sleep2(ms, signal) {
+  return new Promise((done) => {
+    if (signal?.aborted) return done();
+    const timer = setTimeout(finish, ms);
+    function finish() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", finish);
+      done();
+    }
+    signal?.addEventListener("abort", finish, { once: true });
+  });
+}
+function createAgentsClient(config = {}) {
+  const cfg = resolve(config);
+  const request = async (method, path, options = {}) => {
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(options.query ?? {})) {
+      if (v !== void 0 && v !== "") params.set(k, String(v));
+    }
+    const qs = params.toString();
+    const http = { ...cfg, timeout: options.timeout ?? cfg.timeout };
+    const res = await requestJson(http, `${path}${qs ? `?${qs}` : ""}`, {
+      method,
+      headers: { Authorization: `Bearer ${cfg.apiKey}` },
+      body: options.body === void 0 ? void 0 : JSON.stringify(options.body),
+      signal: options.signal
+    });
+    return res;
+  };
+  function agentFor(agentId, what) {
+    const id = agentId ?? cfg.agentId;
+    if (!id) {
+      throw new ValidationError(
+        `${what} needs an agent id: pass it or set agentId (CHANNLIZE_AGENT_ID)`,
+        "agentId"
+      );
+    }
+    return id;
+  }
+  async function inbox(agentId, options = {}) {
+    const id = agentFor(agentId, "inbox");
+    const r = await request("GET", `/v1/agents/${enc2(id)}/inbox`, {
+      query: { cursor: options.cursor, limit: options.limit }
+    });
+    return {
+      messages: r.messages ?? [],
+      nextCursor: r.next_cursor ?? null,
+      hasMore: Boolean(r.has_more)
+    };
+  }
+  async function ack(agentId, input) {
+    const id = agentFor(agentId, "ack");
+    let body;
+    if ("upTo" in input && input.upTo) body = { up_to: input.upTo };
+    else if ("ids" in input && input.ids?.length) body = { ids: input.ids };
+    else {
+      throw new ValidationError(
+        "ack needs upTo or a non-empty ids list",
+        "ids"
+      );
+    }
+    return request("POST", `/v1/agents/${enc2(id)}/inbox/ack`, {
+      body
+    });
+  }
+  async function poll(agentId, handler, options = {}) {
+    const id = agentFor(agentId, "poll");
+    const interval = Math.max(0, options.intervalMs ?? 5e3);
+    const maxBackoff = Math.max(interval, options.maxBackoffMs ?? 6e4);
+    const { signal } = options;
+    let failures = 0;
+    while (!signal?.aborted) {
+      let failed = false;
+      let more = false;
+      try {
+        const page = await inbox(id, { limit: options.limit });
+        more = page.hasMore;
+        const done = [];
+        try {
+          for (const item of page.messages) {
+            if (signal?.aborted) break;
+            try {
+              await handler(item.message, item);
+            } catch (error) {
+              failed = true;
+              options.onError?.(error, item);
+              break;
+            }
+            done.push(item.delivery_id);
+          }
+        } finally {
+          if (done.length) await ack(id, { ids: done });
+        }
+      } catch (error) {
+        if (isFatal(error)) throw error;
+        failed = true;
+        options.onError?.(error);
+      }
+      if (failed) {
+        failures += 1;
+        const backoff = Math.min(
+          maxBackoff,
+          (interval || 1e3) * 2 ** (failures - 1)
+        );
+        await sleep2(backoff, signal);
+      } else {
+        failures = 0;
+        if (!more) await sleep2(interval, signal);
+      }
+    }
+  }
+  const channelRead = (options = {}) => ({
+    agent_id: options.agentId ?? cfg.agentId
+  });
+  return {
+    ...createAgentsGovernance(request, cfg.agentId),
+    agentId: cfg.agentId,
+    send(input) {
+      if (!input || typeof input.channel !== "string" || !input.channel) {
+        return Promise.reject(
+          new ValidationError("send needs a channel id", "channel")
+        );
+      }
+      return request("POST", "/v1/agents/messages", {
+        body: {
+          agent_id: input.agentId ?? cfg.agentId,
+          channel_id: input.channel,
+          type: input.type,
+          text: input.text,
+          thread_id: input.threadId,
+          mentions: input.mentions,
+          data: input.data,
+          tokens: input.tokens,
+          cost: input.cost,
+          task_id: input.taskId,
+          task_status: input.taskStatus
+        }
+      });
+    },
+    inbox,
+    ack,
+    poll,
+    async list(options = {}) {
+      const r = await request("GET", "/v1/agents", {
+        query: { include_retired: options.includeRetired || void 0 }
+      });
+      return r.agents ?? [];
+    },
+    get(agentId) {
+      return request("GET", `/v1/agents/${enc2(agentId)}`);
+    },
+    channels: {
+      async list(options = {}) {
+        const r = await request(
+          "GET",
+          "/v1/agents/channels",
+          { query: { include_archived: options.includeArchived || void 0 } }
+        );
+        return r.channels ?? [];
+      },
+      get(channelId, options) {
+        return request("GET", `/v1/agents/channels/${enc2(channelId)}`, {
+          query: channelRead(options)
+        });
+      },
+      async members(channelId, options) {
+        const r = await request(
+          "GET",
+          `/v1/agents/channels/${enc2(channelId)}/members`,
+          { query: channelRead(options) }
+        );
+        return r.members ?? [];
+      },
+      async messages(channelId, options = {}) {
+        const r = await request("GET", `/v1/agents/channels/${enc2(channelId)}/messages`, {
+          query: {
+            ...channelRead(options),
+            cursor: options.cursor,
+            after: options.after,
+            limit: options.limit,
+            sender_agent_id: options.senderAgentId,
+            type: options.type,
+            thread_id: options.threadId
+          }
+        });
+        return {
+          channel: r.channel,
+          messages: r.messages ?? [],
+          nextCursor: r.next_cursor ?? null,
+          latestCursor: r.latest_cursor ?? null,
+          hasMore: Boolean(r.has_more)
+        };
+      }
+    }
+  };
+}
+var NODE_CRYPTO = "node:crypto";
+async function getSubtle() {
+  const subtle = globalThis.crypto?.subtle;
+  if (subtle) return subtle;
+  try {
+    const mod = await import(
+      /* webpackIgnore: true */
+      /* @vite-ignore */
+      NODE_CRYPTO
+    );
+    if (mod.webcrypto?.subtle) return mod.webcrypto.subtle;
+  } catch {
+  }
+  throw new ChannlizeError(
+    "verifyAgentWebhook needs the Web Crypto API (globalThis.crypto.subtle, or node:crypto webcrypto on Node.js 18)"
+  );
+}
+function hexToBytes(hex) {
+  if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-f]/i.test(hex)) {
+    return null;
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+function toBytes(body) {
+  if (typeof body === "string") return new TextEncoder().encode(body);
+  const copy = new Uint8Array(body.byteLength);
+  copy.set(body);
+  return copy;
+}
+async function verifyAgentWebhook(rawBody, signatureHeader, secret) {
+  if (!secret)
+    throw new ValidationError("The agent secret is required", "secret");
+  const header = Array.isArray(signatureHeader) ? signatureHeader[0] : signatureHeader;
+  const m = /^sha256=([0-9a-f]+)$/i.exec(header?.trim() ?? "");
+  const expected = m ? hexToBytes(m[1]) : null;
+  if (!expected || expected.length !== 32) return false;
+  const subtle = await getSubtle();
+  const key = await subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  );
+  return subtle.verify("HMAC", key, expected, toBytes(rawBody));
+}
+async function parseAgentWebhook(rawBody, signatureHeader, secret) {
+  return await parseAgentWebhookEvent(
+    rawBody,
+    signatureHeader,
+    secret
+  );
+}
+async function parseAgentWebhookEvent(rawBody, signatureHeader, secret) {
+  if (!await verifyAgentWebhook(rawBody, signatureHeader, secret)) {
+    throw new ChannlizeError(
+      "Invalid agent webhook signature",
+      401,
+      "INVALID_SIGNATURE"
+    );
+  }
+  const text = typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody);
+  return JSON.parse(text);
+}
+
 // src/client.ts
 var ChannlizeClient = class {
   config;
@@ -216,8 +1229,8 @@ var ChannlizeClient = class {
     this.config = {
       ...config,
       // After the spread: an explicit `undefined` must not drop the defaults.
-      baseUrl: config.baseUrl || "https://api.channlize.com",
-      timeout: config.timeout ?? 1e4
+      baseUrl: config.baseUrl || DEFAULT_BASE_URL,
+      timeout: config.timeout ?? DEFAULT_TIMEOUT
     };
     this.validateConfig();
   }
@@ -226,6 +1239,26 @@ var ChannlizeClient = class {
       throw new ValidationError("Widget key is required");
     }
   }
+  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() {
+    if (!this.config.serverApiKey) {
+      throw new ValidationError(
+        "serverApiKey (an agent or multi-agent key) is required for agents",
+        "serverApiKey"
+      );
+    }
+    this.agentsClient ??= createAgentsClient({
+      apiKey: this.config.serverApiKey,
+      baseUrl: this.config.baseUrl,
+      timeout: this.config.timeout
+    });
+    return this.agentsClient;
+  }
   makeRequest(endpoint, options = {}) {
     return requestJson(this.config, endpoint, options);
   }
@@ -343,6 +1376,9 @@ var ChannlizeClient = class {
    * `POST /public/events`). Shown under Log tracking in the dashboard.
    */
   async trackEvent(name, options) {
+    return this.nonFatalTracking(() => this.sendBrowserEvent(name, options));
+  }
+  async sendBrowserEvent(name, options) {
     const res = await this.makeRequest(
       "/public/events",
       {
@@ -371,6 +1407,28 @@ var ChannlizeClient = class {
         "serverApiKey is required for trackServerEvent"
       );
     }
+    return this.nonFatalTracking(() => this.sendServerEvent(name, options));
+  }
+  /**
+   * 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.
+   */
+  async nonFatalTracking(send) {
+    try {
+      return await send();
+    } catch (error) {
+      if (!(error instanceof RateLimitError)) throw error;
+      const dropped = error.code === "PLAN_LIMIT_REACHED" ? "plan_limit" : "rate_limit";
+      if (!this.warnedDropped && typeof console !== "undefined") {
+        this.warnedDropped = true;
+        console.warn(`[channlize] log event dropped: ${error.message}`);
+      }
+      return { success: false, id: "", dropped };
+    }
+  }
+  warnedDropped = false;
+  async sendServerEvent(name, options) {
     const res = await this.makeRequest(
       "/v1/events",
       {
@@ -415,13 +1473,75 @@ var ChannlizeClient = class {
     );
   }
 };
+
+// src/agents-types.ts
+var AGENT_STATUSES = ["active", "paused", "retired"];
+var AGENT_DELIVERY_MODES = ["webhook", "inbox", "a2a"];
+var AGENT_MESSAGE_TYPES = [
+  "message",
+  "task",
+  "question",
+  "escalation",
+  "status"
+];
+var SENDABLE_AGENT_MESSAGE_TYPES = [
+  "message",
+  "task",
+  "status"
+];
+var AGENT_TASK_STATUSES = [
+  "open",
+  "working",
+  "input_required",
+  "completed",
+  "failed",
+  "canceled",
+  "rejected"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  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,
-  createNotifier
+  createAgentsClient,
+  createNotifier,
+  isAgentMessageWebhook,
+  isQuestionEscalatedWebhook,
+  isQuestionOutcomeMessage,
+  isQuestionOutcomeWebhook,
+  isRetryable,
+  isTaskHandoffMessage,
+  isValidEventKey,
+  keyKind,
+  parseAgentWebhook,
+  parseAgentWebhookEvent,
+  parseApiError,
+  readChannlizeEnv,
+  retryAfter,
+  verifyAgentWebhook
 });
 //# sourceMappingURL=index.js.map