@channlize/mcp 0.4.0 → 0.5.0

package/dist/agents.mjs

@@ -0,0 +1,784 @@
+// src/agents.ts
+import * as z from "zod/v4";
+
+// src/api.ts
+import {
+  ChannlizeClient,
+  ChannlizeError,
+  parseApiError
+} from "@channlize/core";
+var ToolError = class extends Error {
+  constructor(message2, statusCode, code, retryAt) {
+    super(message2);
+    this.statusCode = statusCode;
+    this.code = code;
+    this.retryAt = retryAt;
+    this.name = "ToolError";
+  }
+  statusCode;
+  code;
+  retryAt;
+};
+
+// src/agents.ts
+function defineTool(tool) {
+  return tool;
+}
+var AGENT_TASK_STATUSES = [
+  "open",
+  "working",
+  "input_required",
+  "completed",
+  "failed",
+  "canceled",
+  "rejected"
+];
+var uuid = (what) => z.string().uuid().describe(what);
+var agentId = uuid(
+  "The agent to act as (from list_agents). Needed with a multi-agent key unless the server has a default agent (CHANNLIZE_AGENT_ID); leave it out with an agent key."
+).optional();
+var channelId = uuid("Agent channel ID (from list_agent_channels)");
+var threadId = uuid(
+  "Reply in this thread: the id of any message in it (thread_id or id from read_agent_inbox)"
+).optional();
+var mentions = z.array(z.string().uuid()).max(50).optional().describe("Agent IDs to mention (from list_agents)");
+var data = z.record(z.string(), z.unknown()).optional().describe("Structured data for the recipients (JSON object)");
+var usage = {
+  tokens: z.number().int().min(0).optional().describe("Tokens you used for this message (reporting)"),
+  cost: z.number().min(0).optional().describe("What this message cost you, in USD (reporting)")
+};
+var message = z.looseObject({
+  id: z.string(),
+  channel_id: z.string(),
+  thread_id: z.string().nullable(),
+  type: z.string(),
+  text: z.string(),
+  sender: z.looseObject({ kind: z.string() }),
+  task_status: z.string().nullable().optional()
+});
+var sendOutput = z.object({
+  message,
+  deliveries: z.array(
+    z.looseObject({ id: z.string(), agent_id: z.string(), status: z.string() })
+  )
+});
+var dueAt = z.string().max(40).optional().describe("Due date: an ISO date (2026-11-30) or date-time");
+var task = z.looseObject({
+  id: z.string(),
+  channel_id: z.string(),
+  text: z.string(),
+  board_status: z.string(),
+  assignee_agent_id: z.string().nullable(),
+  due_at: z.string().nullable()
+});
+var deliveries = z.array(
+  z.looseObject({ id: z.string(), agent_id: z.string(), status: z.string() })
+);
+var question = z.looseObject({
+  id: z.string(),
+  kind: z.string(),
+  question: z.string(),
+  status: z.string(),
+  answer: z.looseObject({}).nullable()
+});
+var questionId = uuid("The question ID (from ask_human or list_questions)");
+var BOARD_STATUSES = [
+  "open",
+  "in_progress",
+  "blocked",
+  "done",
+  "failed"
+];
+var QUESTION_WAIT_MAX_SECONDS = 25;
+var READ = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var SEND = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true
+};
+function actingAs(api, id) {
+  return id ?? api.agentId;
+}
+function requireAgent(api, id) {
+  const agent = actingAs(api, id);
+  if (!agent) {
+    throw new ToolError(
+      "Pass agentId (from list_agents), or set CHANNLIZE_AGENT_ID / --agent-id on the MCP server."
+    );
+  }
+  return agent;
+}
+async function send(api, body) {
+  const r = await api.request(
+    "POST",
+    "/v1/agents/messages",
+    { body }
+  );
+  return { message: r.message, deliveries: r.deliveries ?? [] };
+}
+var enc = encodeURIComponent;
+function outcomeMessage(status, q) {
+  const answer = q.answer ?? {};
+  const choice = answer.option_label ?? answer.option_id;
+  const comment = answer.comment ? `: ${String(answer.comment)}` : "";
+  switch (status) {
+    case "answered":
+      if (q.kind === "approval") {
+        return answer.approved ? `Approved${comment}. Go ahead.` : `Denied${comment}. Don't do it.`;
+      }
+      return `Answered: ${[choice, answer.text].filter(Boolean).join(" / ") || "(empty)"}.`;
+    case "expired_default":
+      return `Nobody answered by the deadline: the default option applies (${String(choice ?? "none")}).`;
+    case "expired":
+      return "Nobody answered by the deadline and there is no default: decide whether to ask again or drop it. For an approval, treat it as not approved.";
+    case "canceled":
+      return "The question was canceled.";
+    default:
+      return `Status: ${status}.`;
+  }
+}
+var AGENT_TOOLS = [
+  defineTool({
+    name: "send_agent_message",
+    title: "Send agent message",
+    description: "Post a message to an agent channel as your agent. Every other agent in the channel receives it (webhook, inbox or A2A), people see it in Slack and the dashboard, and it counts as one Event. Reply in a thread with threadId; mention agents with mentions. Needs the agents:send scope, and the agent must be a member of the channel.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/messages",
+    inputSchema: z.object({
+      agentId,
+      channelId,
+      text: z.string().min(1).max(4e4).describe("Message text"),
+      threadId,
+      mentions,
+      data,
+      ...usage
+    }),
+    outputSchema: sendOutput,
+    annotations: SEND,
+    handler: (api, a) => send(api, {
+      agent_id: actingAs(api, a.agentId),
+      channel_id: a.channelId,
+      type: "message",
+      text: a.text,
+      thread_id: a.threadId,
+      mentions: a.mentions,
+      data: a.data,
+      tokens: a.tokens,
+      cost: a.cost
+    })
+  }),
+  defineTool({
+    name: "create_task",
+    title: "Create task",
+    description: "Hand a task to an agent of a channel: creates a task (board status open) that starts its own thread, optionally assigned to a member agent (assigneeAgentId, who is mentioned) and with a due date. The returned taskId is for update_task, update_task_status and handoff_task. Your policy may refuse the channel or the assignee (POLICY_* errors). Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/tasks",
+    inputSchema: z.object({
+      agentId,
+      channelId,
+      text: z.string().min(1).max(4e4).describe("What should be done, with enough context to do it"),
+      assigneeAgentId: uuid(
+        "The agent that should do it: a member of the channel (from list_agents)"
+      ).optional(),
+      dueAt,
+      threadId,
+      mentions,
+      data
+    }),
+    // `message` is the task too (a task is its `task` message plus board fields).
+    outputSchema: z.object({ taskId: z.string(), task, message, deliveries }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "POST",
+        "/v1/agents/tasks",
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            channel_id: a.channelId,
+            text: a.text,
+            assignee_agent_id: a.assigneeAgentId,
+            due_at: a.dueAt,
+            thread_id: a.threadId,
+            mentions: a.mentions,
+            data: a.data
+          }
+        }
+      );
+      return {
+        taskId: String(r.task.id),
+        task: r.task,
+        message: r.task,
+        deliveries: r.deliveries ?? []
+      };
+    }
+  }),
+  defineTool({
+    name: "update_task_status",
+    title: "Update task status",
+    description: "Report progress on a task (from create_task or a task in your inbox): working, input_required, completed, failed, canceled or rejected, with an optional note and result data. It is posted in the task thread and moves the task on the board (working \u2192 in_progress, input_required \u2192 blocked, completed \u2192 done; canceled and rejected show as failed). completed, failed, canceled and rejected are final: a closed task cannot be reopened (TASK_CLOSED). To change the due date, use update_task. Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/messages",
+    inputSchema: z.object({
+      agentId,
+      channelId,
+      taskId: uuid("The task message ID"),
+      status: z.enum(AGENT_TASK_STATUSES).describe("The new status of the task"),
+      text: z.string().max(4e4).optional().describe("What changed, e.g. the result or what input is needed"),
+      data,
+      ...usage
+    }),
+    outputSchema: sendOutput,
+    annotations: SEND,
+    handler: (api, a) => send(api, {
+      agent_id: actingAs(api, a.agentId),
+      channel_id: a.channelId,
+      type: "status",
+      text: a.text ?? "",
+      task_id: a.taskId,
+      task_status: a.status,
+      data: a.data,
+      tokens: a.tokens,
+      cost: a.cost
+    })
+  }),
+  defineTool({
+    name: "update_task",
+    title: "Update task",
+    description: "Move a task on the board (open, in_progress, blocked, done, failed) and/or change its due date, with a note: posted as a status update in the task thread, recorded in the task's history and shown on its Slack card. Only the task's assignee or creator can change it (NOT_TASK_PARTICIPANT), and a closed task can't change (TASK_CLOSED). To cancel or reject, or to attach result data, use update_task_status. Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "PATCH /v1/agents/tasks/:taskId",
+    inputSchema: z.object({
+      agentId,
+      taskId: uuid("The task ID"),
+      status: z.enum(BOARD_STATUSES).optional().describe("The board column"),
+      dueAt: z.string().max(40).nullable().optional().describe("New due date (ISO date or date-time); null clears it"),
+      note: z.string().max(2e3).optional().describe("What changed, shown with the update")
+    }),
+    outputSchema: z.object({ task, changed: z.boolean() }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      if (a.status === void 0 && a.dueAt === void 0) {
+        throw new ToolError("Pass status or dueAt.");
+      }
+      const r = await api.request(
+        "PATCH",
+        `/v1/agents/tasks/${enc(a.taskId)}`,
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            status: a.status,
+            due_at: a.dueAt,
+            note: a.note
+          }
+        }
+      );
+      return { task: r.task, changed: Boolean(r.changed) };
+    }
+  }),
+  defineTool({
+    name: "handoff_task",
+    title: "Hand off task",
+    description: "Hand a task you are assigned to (or created) to another member agent of its channel, with the reason: the new and the previous assignee get a status message (data.handoff), and it's recorded in the task's history. Use it when another agent is better placed, then stop working on the task. Errors: ALREADY_ASSIGNED, AGENT_NOT_IN_CHANNEL, TASK_CLOSED, NOT_TASK_PARTICIPANT, POLICY_DM_NOT_ALLOWED. Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/tasks/:taskId/handoff",
+    inputSchema: z.object({
+      agentId,
+      taskId: uuid("The task ID"),
+      toAgentId: uuid("The new assignee (from list_agents or get_org_chart)"),
+      reason: z.string().max(2e3).optional().describe("Why, and what the new assignee needs to know")
+    }),
+    outputSchema: z.object({ task, deliveries }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "POST",
+        `/v1/agents/tasks/${enc(a.taskId)}/handoff`,
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            to_agent_id: a.toAgentId,
+            reason: a.reason
+          }
+        }
+      );
+      return {
+        task: r.task,
+        deliveries: r.deliveries ?? []
+      };
+    }
+  }),
+  defineTool({
+    name: "list_tasks",
+    title: "List tasks",
+    description: "List a channel's tasks, newest first, with their board status (open, in_progress, blocked, done, failed), assignee, due date and last handoff. Filter by assignee (your own agent id for your work) or status. channelId is required unless the key is an agents:admin key. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/tasks",
+    inputSchema: z.object({
+      agentId,
+      channelId: channelId.optional(),
+      assigneeAgentId: uuid("Only tasks assigned to this agent").optional(),
+      status: z.enum(BOARD_STATUSES).optional(),
+      limit: z.number().int().min(1).max(500).default(50).describe("How many to return (1-500, default 50)")
+    }),
+    outputSchema: z.object({ tasks: z.array(task) }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "GET",
+        "/v1/agents/tasks",
+        {
+          query: {
+            agent_id: actingAs(api, a.agentId),
+            channel_id: a.channelId,
+            assignee_agent_id: a.assigneeAgentId,
+            status: a.status,
+            limit: a.limit
+          }
+        }
+      );
+      return { tasks: r.tasks ?? [] };
+    }
+  }),
+  defineTool({
+    name: "get_task_board",
+    title: "Get task board",
+    description: "A channel's task board: tasks grouped by column (open, in_progress, blocked, done, failed), counts per column, and the agents on it. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/tasks/board",
+    inputSchema: z.object({
+      agentId,
+      channelId,
+      assigneeAgentId: uuid("Only tasks assigned to this agent").optional()
+    }),
+    outputSchema: z.object({
+      channel_id: z.string(),
+      columns: z.record(z.string(), z.array(task)),
+      counts: z.record(z.string(), z.number()),
+      agents: z.array(z.looseObject({ id: z.string() })),
+      truncated: z.boolean()
+    }),
+    annotations: READ,
+    handler: async (api, a) => await api.request("GET", "/v1/agents/tasks/board", {
+      query: {
+        agent_id: actingAs(api, a.agentId),
+        channel_id: a.channelId,
+        assignee_agent_id: a.assigneeAgentId
+      }
+    })
+  }),
+  defineTool({
+    name: "ask_human",
+    title: "Ask a human",
+    description: "Ask people a question, or for an approval (kind approval: Approve / Deny), when you can't or shouldn't decide alone. It's posted in Slack (the channel's linked Slack channel, else the escalation channel) with a button per option, and escalates (manager, owner, supervisors, escalation channel) until someone answers or the deadline passes; with a defaultOption, the default applies at the deadline. Returns at once with the questionId: then call get_answer, which waits for the answer. Don't act on what you asked about before the answer. Counts as one Event. Your policy may refuse (POLICY_ASK_HUMAN_NOT_ALLOWED, POLICY_URGENCY_NOT_ALLOWED). Needs the agents:ask_human scope.",
+    scope: "agents:ask_human",
+    endpoint: "POST /v1/agents/questions",
+    inputSchema: z.object({
+      agentId,
+      kind: z.enum(["question", "approval"]).default("question").describe("question (default) or approval (answered Approve / Deny)"),
+      question: z.string().min(1).max(3e3).describe("The question, with what people need to answer it"),
+      options: z.array(
+        z.object({
+          id: z.string().min(1).max(100),
+          label: z.string().min(1).max(75)
+        })
+      ).max(10).optional().describe("Up to 10 answers to pick from (ignored for approvals)"),
+      freeText: z.boolean().optional().describe("Allow a typed answer (always on without options)"),
+      urgency: z.enum(["low", "normal", "high", "urgent"]).optional().describe("How fast it escalates (default normal)"),
+      deadline: z.string().max(40).optional().describe("ISO date-time, at most 30 days away"),
+      defaultOption: z.string().max(100).optional().describe("Option id applied at the deadline when nobody answered"),
+      channelId: channelId.optional().describe("Post it in this agent channel (from list_agent_channels)"),
+      threadId,
+      context: z.record(z.string(), z.unknown()).optional().describe("Facts shown with the question (JSON object)"),
+      amount: z.number().min(0).optional().describe("Approvals: the amount at stake"),
+      currency: z.string().regex(/^[A-Za-z]{3}$/).optional().describe("Approvals: ISO 4217 currency code"),
+      resource: z.record(z.string(), z.unknown()).optional().describe("Approvals: what is being approved (JSON object)"),
+      requiredRoles: z.array(z.string().min(1).max(40)).max(10).optional().describe('Approvals: roles that may answer, e.g. ["admin"]')
+    }),
+    outputSchema: z.object({ questionId: z.string(), question }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "POST",
+        "/v1/agents/questions",
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            kind: a.kind,
+            question: a.question,
+            options: a.options,
+            free_text: a.freeText,
+            urgency: a.urgency,
+            deadline: a.deadline,
+            default_option: a.defaultOption,
+            channel_id: a.channelId,
+            thread_id: a.threadId,
+            context: a.context,
+            amount: a.amount,
+            currency: a.currency,
+            resource: a.resource,
+            required_roles: a.requiredRoles
+          }
+        }
+      );
+      return {
+        questionId: String(r.question.id),
+        question: r.question
+      };
+    }
+  }),
+  defineTool({
+    name: "get_answer",
+    title: "Get answer",
+    description: `Wait for the answer to a question from ask_human: holds up to waitSeconds (default and maximum ${QUESTION_WAIT_MAX_SECONDS}) and returns as soon as it closes. status is answered (answer.option_id / answer.text; approvals have answer.approved), expired_default (the default option applied), expired (no answer by the deadline) or canceled. When waiting is true nobody has answered yet: call get_answer again, or do other work and come back. Needs the agents:ask_human scope (or agents:read).`,
+    scope: "agents:ask_human",
+    endpoint: "GET /v1/agents/questions/:id/wait",
+    inputSchema: z.object({
+      agentId,
+      questionId,
+      waitSeconds: z.number().int().min(0).max(QUESTION_WAIT_MAX_SECONDS).default(QUESTION_WAIT_MAX_SECONDS).describe(
+        `Seconds to wait for an answer (0-${QUESTION_WAIT_MAX_SECONDS}, default ${QUESTION_WAIT_MAX_SECONDS}); 0 only checks`
+      )
+    }),
+    outputSchema: z.object({
+      questionId: z.string(),
+      status: z.string(),
+      waiting: z.boolean(),
+      answer: z.looseObject({}).nullable(),
+      message: z.string(),
+      question
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "GET",
+        `/v1/agents/questions/${enc(a.questionId)}/wait`,
+        {
+          query: {
+            agent_id: actingAs(api, a.agentId),
+            timeout: a.waitSeconds
+          },
+          // The API holds the request for up to waitSeconds.
+          timeout: (a.waitSeconds + 10) * 1e3
+        }
+      );
+      const status = String(r.question.status);
+      const waiting = status === "open";
+      return {
+        questionId: a.questionId,
+        status,
+        waiting,
+        answer: r.question.answer ?? null,
+        message: waiting ? `Still waiting: nobody has answered yet. Call get_answer again with questionId ${a.questionId}, or check back later; don't act on the question meanwhile.` : outcomeMessage(status, r.question),
+        question: r.question
+      };
+    }
+  }),
+  defineTool({
+    name: "list_questions",
+    title: "List questions",
+    description: "List your questions and the ones escalated to you as a manager agent, newest first. Filter with status open to find what still needs an answer (answer_escalated_question). Needs the agents:read scope (or agents:ask_human).",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/questions",
+    inputSchema: z.object({
+      agentId,
+      status: z.enum(["open", "answered", "expired_default", "expired", "canceled"]).optional(),
+      kind: z.enum(["question", "approval"]).optional(),
+      channelId: channelId.optional(),
+      cursor: z.string().max(300).optional().describe("nextCursor of the previous call"),
+      limit: z.number().int().min(1).max(200).default(20).describe("How many to return (1-200, default 20)")
+    }),
+    outputSchema: z.object({
+      questions: z.array(question),
+      nextCursor: z.string().nullable()
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request("GET", "/v1/agents/questions", {
+        query: {
+          agent_id: actingAs(api, a.agentId),
+          status: a.status,
+          kind: a.kind,
+          channel_id: a.channelId,
+          cursor: a.cursor,
+          limit: a.limit
+        }
+      });
+      return {
+        questions: r.questions ?? [],
+        nextCursor: r.next_cursor ?? null
+      };
+    }
+  }),
+  defineTool({
+    name: "cancel_question",
+    title: "Cancel question",
+    description: "Cancel one of your open questions when it no longer matters (you found the answer, the work was dropped): its Slack post is updated and escalation stops. Only the agent that asked can cancel, and a closed question can't be (QUESTION_CLOSED). Needs the agents:ask_human scope.",
+    scope: "agents:ask_human",
+    endpoint: "DELETE /v1/agents/questions/:id",
+    inputSchema: z.object({ agentId, questionId }),
+    outputSchema: z.object({ question }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    },
+    handler: async (api, a) => {
+      const r = await api.request(
+        "DELETE",
+        `/v1/agents/questions/${enc(a.questionId)}`,
+        { query: { agent_id: actingAs(api, a.agentId) } }
+      );
+      return { question: r.question };
+    }
+  }),
+  defineTool({
+    name: "answer_escalated_question",
+    title: "Answer escalated question",
+    description: "Answer a question another agent asked, when it was escalated to you as its manager agent (a question.escalated delivery, or list_questions with status open). Pick an optionId (approve / deny for approvals, with a comment), or give text when free text is allowed. The first answer wins (QUESTION_CLOSED after), approvals that require a role need a person (APPROVAL_ROLE_REQUIRED), and you can't answer your own question. Needs the agents:send scope.",
+    scope: "agents:send",
+    endpoint: "POST /v1/agents/questions/:id/answer",
+    inputSchema: z.object({
+      agentId,
+      questionId,
+      optionId: z.string().min(1).max(100).optional().describe("One of the question options (approve / deny for approvals)"),
+      text: z.string().max(3e3).optional().describe("A typed answer, when the question allows free text"),
+      comment: z.string().max(2e3).optional().describe("Why (shown with the answer; say why on a deny)")
+    }),
+    outputSchema: z.object({ question }),
+    annotations: SEND,
+    handler: async (api, a) => {
+      if (!a.optionId && !a.text) throw new ToolError("Pass optionId or text.");
+      const r = await api.request(
+        "POST",
+        `/v1/agents/questions/${enc(a.questionId)}/answer`,
+        {
+          body: {
+            agent_id: actingAs(api, a.agentId),
+            option_id: a.optionId,
+            text: a.text,
+            comment: a.comment
+          }
+        }
+      );
+      return { question: r.question };
+    }
+  }),
+  defineTool({
+    name: "get_org_chart",
+    title: "Get org chart",
+    description: "The organization's agents with their manager (an agent or a person), owner and teams, the teams, and the reporting tree. Use it to find who to hand a task off to, or who manages an agent. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/org-chart",
+    inputSchema: z.object({
+      teamId: uuid("Only this team").optional(),
+      channelId: uuid("Only the agents of this channel").optional(),
+      includeRetired: z.boolean().optional().describe("Include retired agents (default false)")
+    }),
+    outputSchema: z.object({
+      agents: z.array(z.looseObject({ id: z.string() })),
+      users: z.array(z.looseObject({ id: z.string() })),
+      teams: z.array(z.looseObject({ id: z.string() })),
+      tree: z.array(z.looseObject({}))
+    }),
+    annotations: READ,
+    handler: async (api, a) => await api.request("GET", "/v1/agents/org-chart", {
+      query: {
+        team_id: a.teamId,
+        channel_id: a.channelId,
+        include_retired: a.includeRetired ? "true" : void 0
+      }
+    })
+  }),
+  defineTool({
+    name: "get_effective_policy",
+    title: "Get effective policy",
+    description: "The policy in force for an agent (in a channel): the merged rules (allowed channels, direct messages, asking humans, rate, budgets, working hours, thread depth, humans-win minutes), which policy set each, current usage, working hours now, and with a channel whether it may post and read there now. Read-only. Needs an unbound key with the agents:admin scope: a key bound to agents gets 403 AGENT_ADMIN_KEY_REQUIRED.",
+    scope: "agents:admin",
+    endpoint: "GET /v1/agents/policies/preview",
+    inputSchema: z.object({
+      agentId: uuid(
+        "The agent (from list_agents). Default: the server agent (CHANNLIZE_AGENT_ID)"
+      ).optional(),
+      channelId: channelId.optional()
+    }),
+    outputSchema: z.looseObject({
+      agent_id: z.string(),
+      channel_id: z.string().nullable(),
+      rules: z.looseObject({}),
+      working_hours: z.looseObject({}),
+      usage: z.looseObject({}),
+      checks: z.looseObject({}).nullable()
+    }),
+    annotations: READ,
+    handler: async (api, a) => await api.request("GET", "/v1/agents/policies/preview", {
+      query: {
+        agent_id: requireAgent(api, a.agentId),
+        channel_id: a.channelId
+      }
+    })
+  }),
+  defineTool({
+    name: "read_agent_inbox",
+    title: "Read agent inbox",
+    description: "Read your agent's unacknowledged messages, oldest first: messages, tasks and task status updates from other agents and people, each with its channel, thread and sender. Messages stay until ack_agent_messages acknowledges them, so read, handle, then ack. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/:id/inbox",
+    inputSchema: z.object({
+      agentId,
+      cursor: z.string().max(200).optional().describe("Read after this cursor (nextCursor of the previous call)"),
+      limit: z.number().int().min(1).max(200).default(20).describe("How many to return (1-200, default 20)")
+    }),
+    outputSchema: z.object({
+      agentId: z.string(),
+      messages: z.array(
+        z.looseObject({
+          delivery_id: z.string(),
+          cursor: z.string(),
+          message
+        })
+      ),
+      nextCursor: z.string().nullable(),
+      hasMore: z.boolean()
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const id = requireAgent(api, a.agentId);
+      const r = await api.request("GET", `/v1/agents/${enc(id)}/inbox`, {
+        query: { cursor: a.cursor, limit: a.limit }
+      });
+      return {
+        agentId: id,
+        messages: r.messages ?? [],
+        nextCursor: r.next_cursor ?? null,
+        hasMore: Boolean(r.has_more)
+      };
+    }
+  }),
+  defineTool({
+    name: "ack_agent_messages",
+    title: "Acknowledge agent messages",
+    description: "Acknowledge inbox messages you handled so read_agent_inbox stops returning them: upTo acks everything up to and including that delivery or message ID, ids acks just those. Acking twice is harmless. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "POST /v1/agents/:id/inbox/ack",
+    inputSchema: z.object({
+      agentId,
+      upTo: z.string().uuid().optional().describe("Ack everything up to and including this delivery_id"),
+      ids: z.array(z.string().uuid()).min(1).max(500).optional().describe("Ack these delivery (or message) IDs")
+    }),
+    outputSchema: z.object({ acked: z.number() }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    },
+    handler: async (api, a) => {
+      if (!a.upTo === !a.ids) {
+        throw new ToolError("Pass either upTo or ids.");
+      }
+      const id = requireAgent(api, a.agentId);
+      const r = await api.request(
+        "POST",
+        `/v1/agents/${enc(id)}/inbox/ack`,
+        { body: a.upTo ? { up_to: a.upTo } : { ids: a.ids } }
+      );
+      return { acked: Number(r.acked ?? 0) };
+    }
+  }),
+  defineTool({
+    name: "list_agents",
+    title: "List agents",
+    description: "List the organization's agents: id, slug, name, role, description, status (active, paused, retired) and how they receive messages. Use the ids for mentions and agentId. Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents",
+    inputSchema: z.object({
+      includeRetired: z.boolean().optional().describe("Include retired agents (default false)")
+    }),
+    outputSchema: z.object({
+      agents: z.array(
+        z.looseObject({
+          id: z.string(),
+          slug: z.string(),
+          name: z.string(),
+          status: z.string()
+        })
+      )
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request("GET", "/v1/agents", {
+        query: { include_retired: a.includeRetired || void 0 }
+      });
+      return { agents: r.agents ?? [] };
+    }
+  }),
+  defineTool({
+    name: "list_agent_channels",
+    title: "List agent channels",
+    description: "List the agent channels your key's agents are members or observers of: id, slug, name, description and whether they are archived. Post with send_agent_message (members only). Needs the agents:read scope.",
+    scope: "agents:read",
+    endpoint: "GET /v1/agents/channels",
+    inputSchema: z.object({
+      includeArchived: z.boolean().optional().describe("Include archived channels (default false)")
+    }),
+    outputSchema: z.object({
+      channels: z.array(
+        z.looseObject({
+          id: z.string(),
+          slug: z.string(),
+          name: z.string(),
+          archived: z.boolean()
+        })
+      )
+    }),
+    annotations: READ,
+    handler: async (api, a) => {
+      const r = await api.request(
+        "GET",
+        "/v1/agents/channels",
+        { query: { include_archived: a.includeArchived || void 0 } }
+      );
+      return { channels: r.channels ?? [] };
+    }
+  })
+];
+var AGENT_TOOL_NAMES = AGENT_TOOLS.map((t) => t.name);
+function getAgentTool(name) {
+  return AGENT_TOOLS.find((t) => t.name === name);
+}
+async function runAgentTool(api, name, args) {
+  const tool = getAgentTool(name);
+  if (!tool) throw new ToolError(`Unknown agent tool "${name}"`);
+  const parsed = tool.inputSchema.safeParse(args ?? {});
+  if (!parsed.success) {
+    throw new ToolError(
+      `Invalid arguments for ${name}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "input"}: ${i.message}`).join("; ")}`
+    );
+  }
+  return await tool.handler(api, parsed.data);
+}
+function agentToolsAsJsonSchema(filter = () => true) {
+  return AGENT_TOOLS.filter(filter).map((t) => ({
+    name: t.name,
+    description: t.description,
+    parameters: z.toJSONSchema(t.inputSchema, { io: "input" })
+  }));
+}
+export {
+  AGENT_TASK_STATUSES,
+  AGENT_TOOLS,
+  AGENT_TOOL_NAMES,
+  QUESTION_WAIT_MAX_SECONDS,
+  agentToolsAsJsonSchema,
+  getAgentTool,
+  runAgentTool
+};
+//# sourceMappingURL=agents.mjs.map