@channlize/core 0.4.0 → 0.6.0

package/dist/index.mjs

@@ -23,7 +23,8 @@ function readChannlizeEnv(env = typeof process !== "undefined" ? process.env : v
     apiKey: clean(env?.CHANNLIZE_API_KEY),
     projectId: clean(env?.CHANNLIZE_PROJECT_ID),
     baseUrl: clean(env?.CHANNLIZE_BASE_URL),
-    timeout: clean(env?.CHANNLIZE_TIMEOUT)
+    timeout: clean(env?.CHANNLIZE_TIMEOUT),
+    agentId: clean(env?.CHANNLIZE_AGENT_ID)
   };
 }
 function parseApiError(status, body, statusText = "") {
@@ -59,6 +60,12 @@ var ChannlizeError = class extends Error {
    * `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) {
@@ -81,11 +88,121 @@ var RateLimitError = class extends ChannlizeError {
   }
 };
 
+// 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 = {}) {
+  return send(
+    http,
+    endpoint,
+    options,
+    async (res) => await res.json()
+  );
+}
+async function requestText(http, endpoint, options = {}) {
+  return send(http, endpoint, options, async (res) => ({
+    body: await res.text(),
+    status: res.status,
+    headers: res.headers
+  }));
+}
+async function send(http, endpoint, options, read) {
   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",
@@ -103,21 +220,33 @@ async function requestJson(http, endpoint, options = {}) {
     if (!response.ok) {
       await handleErrorResponse(response);
     }
-    const data = await response.json();
-    return data;
+    return await read(response);
   } catch (error) {
     clearTimeout(timeoutId);
     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) {
   let body = {};
   if (response.headers.get("content-type")?.includes("application/json")) {
@@ -126,11 +255,27 @@ async function handleErrorResponse(response) {
     } catch {
     }
   }
-  throw errorFromApi(parseApiError(response.status, body, response.statusText));
+  throw errorFromApi(
+    parseApiError(response.status, body, response.statusText),
+    retryAfterHeader(response.headers.get("retry-after"))
+  );
 }
-function errorFromApi(info) {
+function errorFromApi(info, retryAfter2) {
   const { status, message, code } = info;
-  let error;
+  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:
       error = new AuthenticationError(message);
@@ -152,6 +297,7 @@ function errorFromApi(info) {
   }
   error.requestId = info.requestId;
   error.details = info.body;
+  error.retryAt = retryAt;
   return error;
 }
 
@@ -225,6 +371,1091 @@ 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-observability.ts
+var enc2 = encodeURIComponent;
+function day(v) {
+  return v instanceof Date ? v.toISOString().slice(0, 10) : v;
+}
+function iso2(v) {
+  return v instanceof Date ? v.toISOString() : v;
+}
+function list(v) {
+  return Array.isArray(v) ? v.join(",") : v;
+}
+function need2(value, what, field) {
+  if (typeof value !== "string" || !value) {
+    throw new ValidationError(`${what} is required`, field);
+  }
+}
+function exportFilterFields(f = {}) {
+  return {
+    from: iso2(f.from),
+    to: iso2(f.to),
+    agent_id: f.agentId,
+    channel_id: f.channelId,
+    thread_id: f.threadId,
+    type: f.type,
+    status: list(f.status),
+    action: f.action,
+    actor_type: f.actorType,
+    actor_id: f.actorId,
+    target_type: f.targetType,
+    target_id: f.targetId
+  };
+}
+function defined(o) {
+  return Object.fromEntries(
+    Object.entries(o).filter(([, v]) => v !== void 0)
+  );
+}
+function filenameOf(disposition) {
+  const m = disposition ? /filename="?([^";]+)"?/i.exec(disposition) : null;
+  return m ? m[1] : null;
+}
+async function* paginate(page, max) {
+  const limit = max ?? Infinity;
+  if (limit <= 0) return;
+  let cursor;
+  let seen = 0;
+  for (; ; ) {
+    const r = await page(cursor);
+    for (const item of r.items) {
+      yield item;
+      if (++seen >= limit) return;
+    }
+    if (!r.nextCursor || r.nextCursor === cursor) return;
+    cursor = r.nextCursor;
+  }
+}
+function createAgentsObservability(request, requestText2) {
+  const safely = (fn) => {
+    try {
+      return fn();
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  };
+  const rangeQuery = (f = {}) => ({
+    from: day(f.from),
+    to: day(f.to),
+    channel_id: f.channelId,
+    agent_id: f.agentId
+  });
+  function edge(source, target, options = {}) {
+    return safely(async () => {
+      need2(source, "The source node id", "source");
+      need2(target, "The target node id", "target");
+      const r = await request("GET", "/v1/agents/insights/graph/edge", {
+        query: {
+          source,
+          target,
+          from: day(options.from),
+          to: day(options.to),
+          channel_id: options.channelId,
+          cursor: options.cursor,
+          limit: options.limit
+        }
+      });
+      return {
+        range: r.range,
+        source: r.source,
+        target: r.target,
+        threads: r.threads ?? [],
+        nextCursor: r.next_cursor ?? null
+      };
+    });
+  }
+  function search(options) {
+    return safely(async () => {
+      if (!options || typeof options.q !== "string" || options.q.trim().length < 2) {
+        throw new ValidationError("search needs q, at least 2 characters", "q");
+      }
+      const r = await request("GET", "/v1/agents/search", {
+        query: {
+          q: options.q,
+          agent_id: options.agentId,
+          channel_id: options.channelId,
+          type: options.type,
+          include: list(options.include),
+          from: iso2(options.from),
+          to: iso2(options.to),
+          cursor: options.cursor,
+          limit: options.limit
+        }
+      });
+      return {
+        results: r.results ?? [],
+        nextCursor: r.next_cursor ?? null,
+        window: r.window
+      };
+    });
+  }
+  return {
+    insights: {
+      graph(filters = {}) {
+        return request("GET", "/v1/agents/insights/graph", {
+          query: {
+            ...rangeQuery(filters),
+            team_id: filters.teamId,
+            limit: filters.limit,
+            edge_limit: filters.edgeLimit
+          }
+        });
+      },
+      edge,
+      edgeAll(source, target, options = {}) {
+        const { max, ...rest } = options;
+        return paginate(async (cursor) => {
+          const page = await edge(source, target, { ...rest, cursor });
+          return { items: page.threads, nextCursor: page.nextCursor };
+        }, max);
+      },
+      cost(options = {}) {
+        return request("GET", "/v1/agents/insights/cost", {
+          query: {
+            ...rangeQuery(options),
+            group_by: options.groupBy,
+            team_id: options.teamId,
+            limit: options.limit
+          }
+        });
+      },
+      metrics(filters = {}) {
+        return request("GET", "/v1/agents/insights/metrics", {
+          query: rangeQuery(filters)
+        });
+      }
+    },
+    search,
+    searchAll(options) {
+      const { max, ...rest } = options ?? {};
+      return paginate(async (cursor) => {
+        const page = await search({ ...rest, cursor });
+        return { items: page.results, nextCursor: page.nextCursor };
+      }, max);
+    },
+    exports: {
+      download(kind, format = "csv", filters = {}) {
+        return safely(async () => {
+          need2(kind, "The export kind", "kind");
+          const res = await requestText2("/v1/agents/export", {
+            query: { kind, format, ...exportFilterFields(filters) }
+          });
+          return {
+            body: res.body,
+            rows: Number(res.headers.get("x-export-rows") ?? 0) || 0,
+            truncated: res.headers.get("x-export-truncated") === "true",
+            contentType: res.headers.get("content-type") ?? "",
+            filename: filenameOf(res.headers.get("content-disposition"))
+          };
+        });
+      },
+      start(input) {
+        return safely(async () => {
+          need2(input?.kind, "The export kind", "kind");
+          const r = await request("POST", "/v1/agents/export", {
+            body: {
+              kind: input.kind,
+              format: input.format,
+              filters: defined(exportFilterFields(input.filters))
+            }
+          });
+          return { exportId: r.export_id, status: r.status, export: r.export };
+        });
+      },
+      get(exportId) {
+        return safely(async () => {
+          need2(exportId, "The export id", "exportId");
+          const r = await request(
+            "GET",
+            `/v1/agents/export/${enc2(exportId)}`
+          );
+          return r.export;
+        });
+      },
+      async list(options = {}) {
+        const r = await request(
+          "GET",
+          "/v1/agents/export",
+          { query: { limit: options.limit } }
+        );
+        return r.exports ?? [];
+      }
+    },
+    telemetry: {
+      async getOtel() {
+        return (await request("GET", "/v1/agents/telemetry/otel")).otel;
+      },
+      async setOtel(input) {
+        const r = await request(
+          "PUT",
+          "/v1/agents/telemetry/otel",
+          {
+            body: {
+              enabled: input?.enabled,
+              endpoint_url: input?.endpointUrl,
+              headers: input?.headers
+            }
+          }
+        );
+        return r.otel;
+      },
+      testOtel() {
+        return request(
+          "POST",
+          "/v1/agents/telemetry/otel/test"
+        );
+      },
+      async getWebhook() {
+        return (await request(
+          "GET",
+          "/v1/agents/telemetry/webhook"
+        )).webhook;
+      },
+      setWebhook(input) {
+        return request(
+          "PUT",
+          "/v1/agents/telemetry/webhook",
+          {
+            body: {
+              enabled: input?.enabled,
+              url: input?.url,
+              rotate_secret: input?.rotateSecret
+            }
+          }
+        );
+      },
+      testWebhook() {
+        return request(
+          "POST",
+          "/v1/agents/telemetry/webhook/test"
+        );
+      }
+    }
+  };
+}
+
+// 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 enc3 = 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;
+  };
+  const fetchText = (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();
+    return requestText(cfg, `${path}${qs ? `?${qs}` : ""}`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${cfg.apiKey}` }
+    });
+  };
+  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/${enc3(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/${enc3(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),
+    ...createAgentsObservability(request, fetchText),
+    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/${enc3(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/${enc3(channelId)}`, {
+          query: channelRead(options)
+        });
+      },
+      async members(channelId, options) {
+        const r = await request(
+          "GET",
+          `/v1/agents/channels/${enc3(channelId)}/members`,
+          { query: channelRead(options) }
+        );
+        return r.members ?? [];
+      },
+      async messages(channelId, options = {}) {
+        const r = await request("GET", `/v1/agents/channels/${enc3(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(
+    "Webhook signature checks need 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");
+  return verifyHmacSha256(rawBody, signatureHeader, secret);
+}
+async function verifyHmacSha256(rawBody, signatureHeader, 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);
+}
+async function verifyTelemetryWebhook(rawBody, signatureHeader, secret) {
+  if (!secret) {
+    throw new ValidationError(
+      "The telemetry webhook secret is required",
+      "secret"
+    );
+  }
+  return verifyHmacSha256(rawBody, signatureHeader, secret);
+}
+async function parseTelemetryWebhook(rawBody, signatureHeader, secret) {
+  if (!await verifyTelemetryWebhook(rawBody, signatureHeader, secret)) {
+    throw new ChannlizeError(
+      "Invalid telemetry 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;
@@ -242,6 +1473,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);
   }
@@ -397,9 +1648,9 @@ var ChannlizeClient = class {
    * 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) {
+  async nonFatalTracking(send2) {
     try {
-      return await send();
+      return await send2();
     } catch (error) {
       if (!(error instanceof RateLimitError)) throw error;
       const dropped = error.code === "PLAN_LIMIT_REACHED" ? "plan_limit" : "rate_limit";
@@ -456,21 +1707,98 @@ 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"
+];
+
+// src/agents-observability-types.ts
+var COST_GROUPINGS = [
+  "agent",
+  "channel",
+  "team",
+  "task",
+  "day"
+];
+var AGENT_EXPORT_KINDS = [
+  "messages",
+  "tasks",
+  "questions",
+  "audit"
+];
+var AGENT_EXPORT_FORMATS = ["csv", "json"];
+var AGENT_EXPORT_SYNC_MAX_ROWS = 1e4;
 export {
+  AGENT_DELIVERY_MODES,
+  AGENT_EXPORT_FORMATS,
+  AGENT_EXPORT_KINDS,
+  AGENT_EXPORT_SYNC_MAX_ROWS,
+  AGENT_MESSAGE_TYPES,
+  AGENT_POLICY_CODES,
+  AGENT_STATUSES,
+  AGENT_TASK_ERROR_CODES,
+  AGENT_TASK_STATUSES,
+  AgentPolicyError,
+  AgentTaskError,
+  AgentThreadPausedError,
   AuthenticationError,
+  COST_GROUPINGS,
   ChannlizeClient,
   ChannlizeError,
   DEFAULT_BASE_URL,
   DEFAULT_TIMEOUT,
   EVENT_KEY_PATTERN,
   EVENT_SEVERITIES,
+  HumanTakeoverError,
+  POLICY_SCOPES,
+  QUESTION_KINDS,
+  QUESTION_STATUSES,
+  QUESTION_URGENCIES,
+  QUESTION_WAIT_MAX_SECONDS,
+  QuestionClosedError,
   RateLimitError,
+  SENDABLE_AGENT_MESSAGE_TYPES,
+  TASK_BOARD_STATUSES,
   ValidationError,
+  createAgentsClient,
   createNotifier,
   ChannlizeClient as default,
+  isAgentMessageWebhook,
+  isQuestionEscalatedWebhook,
+  isQuestionOutcomeMessage,
+  isQuestionOutcomeWebhook,
+  isRetryable,
+  isTaskHandoffMessage,
   isValidEventKey,
   keyKind,
+  parseAgentWebhook,
+  parseAgentWebhookEvent,
   parseApiError,
-  readChannlizeEnv
+  parseTelemetryWebhook,
+  readChannlizeEnv,
+  retryAfter,
+  verifyAgentWebhook,
+  verifyTelemetryWebhook
 };
 //# sourceMappingURL=index.mjs.map