@anvia/cli 1.2.0 → 1.3.0

package/dist/index.js

@@ -1,21 +1,39 @@
 import {
   addRegistryItem,
+  bundledSkillsDirectory,
   closestRegistryItemName,
+  collectSkillFiles,
   createRegistryItem,
+  initSkills,
   initializeProject,
   inspectInstalledItems,
+  inspectInstalledSkills,
   isRegistryItemName,
+  isSkillsTarget,
   registryItemNames,
-  updateInstalledItems
-} from "./chunk-IH4ZNWHB.js";
+  skillNames,
+  skillsTargetDirectory,
+  skillsTargetNames,
+  updateInstalledItems,
+  updateSkills
+} from "./chunk-ERCP4EIZ.js";
 export {
   addRegistryItem,
+  bundledSkillsDirectory,
   closestRegistryItemName,
+  collectSkillFiles,
   createRegistryItem,
+  initSkills,
   initializeProject,
   inspectInstalledItems,
+  inspectInstalledSkills,
   isRegistryItemName,
+  isSkillsTarget,
   registryItemNames,
-  updateInstalledItems
+  skillNames,
+  skillsTargetDirectory,
+  skillsTargetNames,
+  updateInstalledItems,
+  updateSkills
 };
 //# sourceMappingURL=index.js.map

package/dist/skills/anvia-agent/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: anvia-agent
+description: Build Anvia agents and tools — Agent options, tool definitions, approvals, memory, streaming, multi-agent teams, and provider wiring.
+---
+
+# Anvia Agent Skill
+
+Use this skill when the user wants to build or change an Anvia agent: defining
+tools, configuring the `Agent`, handling approvals and streaming, adding memory,
+composing specialists, or wiring a provider model.
+
+## Process
+
+1. Define tools first (`references/tools.md`) — zod schemas, approvals.
+2. Create the `Agent` (`references/agent-options.md`) — smallest option set that works.
+3. Wire the provider model (`references/providers.md`) — keep vendor SDKs in provider packages.
+4. Compose specialists when needed (`references/teams.md`) — subagents as tools, or `AgentTeam`.
+5. Run `scripts/check-agent.sh` from the app root before claiming done.
+
+## Minimal slice
+
+```ts
+import { Agent } from "@anvia/core/agent";
+import { createTool } from "@anvia/core/tool";
+import { OpenAIClient } from "@anvia/openai";
+import { z } from "zod";
+
+const addTool = createTool({
+  name: "add",
+  description: "Add two numbers together.",
+  inputSchema: z.object({
+    x: z.number().describe("The first number."),
+    y: z.number().describe("The second number."),
+  }),
+  outputSchema: z.number(),
+  execute: (args) => args.x + args.y,
+});
+
+const client = new OpenAIClient({
+  baseUrl: process.env.OPENAI_BASEURL,
+  apiKey: process.env.OPENAI_API_KEY ?? "",
+});
+const agent = new Agent({
+  id: "agent",
+  model: client.completionModel({ modelId: "gpt-6-astra", api: "responses" }),
+  instructions: "You are a concise assistant. Use tools when useful.",
+  maxTurns: 2,
+  tools: [addTool],
+});
+
+const response = await agent.generate({ prompt: "What is 12 + 30? Use the add tool." });
+if (response.type !== "response") throw new Error("Unexpected tool approval request.");
+console.log(response.output);
+```
+
+## Output
+
+Prefer one agent, few tools, explicit zod schemas. Point to the relevant
+reference file instead of pasting its contents into chat.

package/dist/skills/anvia-agent/references/agent-options.md

@@ -0,0 +1,83 @@
+# Agent Options
+
+```ts
+const agent = new Agent({
+  id: "agent", // required, stable across restarts
+  model, // required CompletionModel from a provider package
+  instructions: "...", // system guidance; keep it task-specific
+  tools: [...], // AnyTool | ProviderTool | ToolIndex
+  mcpServers: [...], // MCP servers (the only path for MCP tools)
+  skills: skillSet, // SkillSet from loadSkills() — Agent merges its tools
+  context: [...], // static Document or VectorContext entries
+  memory: { store }, // MemoryStore for session continuity
+  outputSchema: schema, // zod schema for structured final output
+  toolChoice, // constrain or force tool use
+  maxTurns, // bound runaway loops (e.g. 2-4 for demos)
+  middlewares: [...], // AgentMiddleware for cross-cutting tool behavior
+  guardrails, // policy input for safety constraints
+  temperature, // maxTokens, retries, controls, providerOptions as needed
+});
+```
+
+## generate vs stream
+
+- `agent.generate({ prompt, session? })` — one shot. Returns `{ type: "response" }`,
+  `{ type: "interaction" }` (approval/question), or `{ type: "blocked" }` (guardrail
+  stop); never throws for those.
+- `agent.stream({ prompt, toolConcurrency? })` — events: `tool_call`,
+  `tool_result`, `text_delta`, `response`. Use `toolConcurrency` when parallel
+  specialist calls are safe. Requires a streaming-capable model — it throws
+  otherwise, so fall back to `generate` for chat-only models.
+
+## Memory
+
+`memory: { store }` with a `MemoryStore` (`load` / `append` / `clear` over
+`Message[]`), plus a `session` (`{ sessionId, userId }`) per call:
+
+```ts
+const agent = new Agent({ id: "agent", model, instructions: "...", memory: { store } });
+await agent.generate({ prompt: "Remember my project is named Anvia.", session });
+await agent.generate({ prompt: "What is my project named?", session });
+```
+
+Compaction (`afterTokens` / `recentTokens` + token counter + compactor) is opt-in
+for long sessions — add it when context growth is the problem, not upfront.
+`agent.compactMemory({ session })` forces that compaction on demand.
+
+## Multi-agent
+
+Specialists route by their `name` + `description` text — both optional on
+`Agent`, but give them explicitly (`asTool` falls back to a generic description
+when omitted). `asTool` itself requires a tool `name` and an explicit
+`suspension` policy:
+
+```ts
+const coordinator = new Agent({
+  id: "coordinator",
+  model,
+  instructions: "Coordinate specialist agents through tools. ...",
+  maxTurns: 4,
+  tools: [supportAgent.asTool({ name: "ask_support_agent", suspension: "reject" })],
+});
+```
+
+Keep the coordinator's instructions to routing + synthesis. Give each specialist
+a short task built only from user facts. Prefer `stream` with `toolConcurrency`
+for parallel delegation. When members must talk, wait, and spawn each other,
+use `AgentTeam` (`references/teams.md`); for static teams/pipelines, check the
+cookbook (`07_multi_agent`, `05_pipelines`) before inventing a new pattern.
+
+## Skills wiring
+
+```ts
+import { loadSkills, skill } from "@anvia/core/skills";
+
+const skills = await loadSkills(skill.local("./skills"));
+const agent = new Agent({ id: "agent", model, instructions: "...", skills });
+```
+
+`skill.local(path)` treats the path as one skill when it holds `SKILL.md`,
+otherwise as a folder of skills. `loadSkills` builds the system instructions
+(name + description + reference/script listing) and the four lazy
+`get_skill_*` / `run_skill_script` tools — the Agent only pulls full
+instructions, references, or scripts when relevant.

package/dist/skills/anvia-agent/references/providers.md

@@ -0,0 +1,22 @@
+# Providers
+
+Provider behavior lives in provider packages, never in `@anvia/core`:
+
+- `@anvia/openai`, `@anvia/anthropic`, `@anvia/gemini`, `@anvia/mistral`,
+  `@anvia/grok` — check the owning package README for client names and model options.
+- Typical shape: `new OpenAIClient({ baseUrl, apiKey })`, then
+  `client.completionModel({ modelId, api: "responses" })` for the Agent model.
+- Embedding, transcription, and image/audio generation follow the same split:
+  core contracts, provider adapters in `packages/provider-*`, local embeddings
+  in `packages/embedding-transformers`.
+
+## Rules
+
+- Never import a vendor SDK in `@anvia/core` (or in app code that claims to be
+  provider-agnostic) — add a provider adapter instead.
+- Read credentials from the environment at the boundary
+  (`process.env.OPENAI_API_KEY ?? ""`); never commit keys or trace payloads.
+- Tests must mock or fake provider SDKs. Ordinary package tests must not need
+  network access or real API keys.
+- Match the package's import style: some packages use extensionless local
+  imports, many adapters use `.js` suffixes in source imports.

package/dist/skills/anvia-agent/references/teams.md

@@ -0,0 +1,84 @@
+# Subagents and Teams
+
+Two composition shapes, chosen by who decides the control flow: when you can
+name the delegation graph, wire agents together yourself; when the model must
+decide who to call, give it subagent tools; when instances must talk, wait, and
+spawn each other, use `AgentTeam`.
+
+## Subagents as tools (you decide)
+
+`agent.asTool({ name, suspension })` wraps an Agent as a callable tool of
+another (see `references/agent-options.md` for the coordinator example).
+Prefer this when the delegation graph is static and shallow — one coordinator
+calling named specialists, optionally fanned out in parallel via
+`toolConcurrency`. Each call is independent; subagents share nothing but the
+model.
+
+## AgentTeam (the model decides)
+
+`AgentTeam` from `@anvia/core/agent` runs a coordinator plus member agents as
+one supervised runtime:
+
+```ts
+import { Agent, AgentTeam } from "@anvia/core/agent";
+
+const researcher = new Agent({ id: "researcher", model, instructions: "Find facts only." });
+const writer = new Agent({ id: "writer", model, instructions: "Draft from findings only." });
+
+const team = new AgentTeam({
+  id: "research-team", // coordinator options (id, model, instructions, tools, memory...)
+  model,
+  instructions: "Coordinate research and drafting through your member tools.",
+  members: [researcher, writer], // required; Agent instances, unique ids
+  communication: { siblings: true }, // default false
+  limits: { maxConcurrentAgents: 4 },
+});
+
+const outcome = await team.generate({ prompt: "Brief the team and produce a memo." });
+console.log(
+  outcome.output,
+  outcome.usage,
+  outcome.members.map((m) => `${m.name}:${m.status}`),
+);
+```
+
+Constructor options are coordinator `AgentOptions` plus:
+
+- `members` — required array of `Agent` instances. Member ids must be unique
+  and match `^[a-zA-Z0-9_-]{1,58}$` because they become spawn tool names.
+- `spawning: [{ from, to }]` — additional spawn permissions between members;
+  the coordinator can always spawn every member.
+- `communication: { siblings: true }` — allow messaging and waiting between
+  instances with the same parent (default false).
+- `limits` — `maxDepth` (3), `maxConcurrentAgents` (4), `maxAgentInstances`
+  (12), `maxTotalTurns` (100), `maxBufferedEvents` (1024). Breaching a limit
+  raises `AgentTeamLimitError`; unread stream-event overflow cancels the run.
+
+The runtime injects reserved tools — `spawn_<memberId>`, `send_message`,
+`wait_for_agent`, `list_agents`, `cancel_agent`. A member tool with one of
+those names throws at construction.
+
+## Running teams
+
+- `generate({ prompt })` or `{ messages }` — exactly one. Returns the
+  coordinator outcome (`response` or `blocked`) plus `teamRunId`, aggregate
+  `usage`, and per-instance `members` summaries (status, usage, outcome).
+- `stream()` — async events: `agent_queued` / `agent_started` /
+  `agent_waiting` / `agent_idle` / `agent_failed` / `agent_cancelled`,
+  `message_queued` / `message_delivered`, `interaction`, and nested
+  `agent_event`s (each tagged with the emitting instance). Also exposes
+  `textStream`, `text`, `result`, `steer(input)`, and `cancel(reason?)`.
+- Interactions from any member (tool approvals, questions) must be resolved at
+  the team level: pass `resolveInteraction(request) => response` on the run.
+  Without it, an interaction fails the run with `AgentTeamInteractionError`.
+
+## Rules
+
+- Keep members narrow: one task each, explicit `name` + `description`, facts
+  in, facts out — the coordinator routes by that text.
+- One coordinator; do not nest teams inside teams. Escalating depth is what
+  `limits.maxDepth` is there to stop.
+- A fixed sequence of agent steps is a pipeline (`.agent()` stage — see the
+  `anvia-pipeline` skill), not a team.
+- Studio renders team runs with steer, cancel, and interaction cards — see the
+  `anvia-studio` skill.

package/dist/skills/anvia-agent/references/tools.md

@@ -0,0 +1,71 @@
+# Tools
+
+Tools are created with `createTool` from `@anvia/core/tool`. Every tool needs a
+`name`, a routing `description`, a zod `inputSchema`, and an `execute`
+implementation. Input and output are validated at the boundary — describe every
+schema field so the model fills it correctly.
+
+```ts
+const tool = createTool({
+  name: "add",
+  description: "Add two numbers together.",
+  inputSchema: z.object({
+    x: z.number().describe("The first number."),
+    y: z.number().describe("The second number."),
+  }),
+  outputSchema: z.number(), // optional; when present, execute results are parsed against it
+  execute: (args) => args.x + args.y,
+});
+```
+
+## Approvals
+
+Side-effecting tools declare `requiresApproval` — a boolean, a static
+`{ reason }`, or a function of the args. Approval requests suspend the run;
+resume it explicitly:
+
+```ts
+const tool = createTool({
+  name: "delete_account",
+  description: "Delete a customer account permanently.",
+  inputSchema: z.object({ accountId: z.string() }),
+  outputSchema: z.string(),
+  requiresApproval: ({ accountId }) => ({ reason: `Permanently delete ${accountId}?` }),
+  execute: ({ accountId }) => `Deleted account ${accountId}`,
+});
+
+let result = await agent.generate({ prompt: "..." });
+while (result.type === "interaction") {
+  // result.interaction is e.g. { type: "tool-approval", toolName, reason }
+  result = await agent.resume(result.continuation, {
+    type: "tool-approval",
+    approved: false,
+    reason: "Reject sensitive operations in this demo.",
+  });
+}
+```
+
+Always handle the `interaction` result shape — `generate` does not throw for
+approvals. The same interaction loop applies to `createQuestionTool` prompts.
+
+## Built-in and dynamic tools
+
+- `createThinkTool()` — a scratchpad reasoning tool for agents that need visible
+  intermediate thought.
+- `createQuestionTool()` — ask the caller a question mid-run (resolves through
+  the interaction loop like approvals).
+- `ToolIndex` — expose a large or dynamic tool set behind one entry so the Agent
+  resolves tools at call time instead of listing them all in the prompt.
+- `createMiddleware()` — observe or map around requests, responses, and tool
+  input/output; prefer it over re-implementing retry or mapping inside
+  `execute`.
+- `createHook()` (from `@anvia/core/internal/agent`) — lifecycle actions
+  (continue, skip, terminate, approval). Per-run tool concurrency is the
+  `toolConcurrency` setting, not a middleware or hook concern.
+
+## MCP tools
+
+MCP tools must be registered through `Agent.mcpServers`, never smuggled in via
+`Agent.skills`. Skill tooling (`get_skill_instructions`, `get_skill_reference`,
+`get_skill_script`, `run_skill_script`) is created by `loadSkills` and merged by
+the Agent itself — pass the `SkillSet`, not its individual tools.

package/dist/skills/anvia-agent/scripts/check-agent.sh

@@ -0,0 +1,99 @@
+#!/bin/sh
+# Heuristic checks for Anvia agent/tool code in an app directory.
+# Usage: sh scripts/check-agent.sh [--dir <app-root>]
+# Fails with a list of violations; passes silently with "agent OK".
+
+DIR="."
+if [ "$1" = "--dir" ] && [ -n "$2" ]; then
+  DIR="$2"
+fi
+
+ROOTS_FOUND=0
+for root in "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server"; do
+  if [ -d "$root" ]; then
+    ROOTS_FOUND=1
+    break
+  fi
+done
+if [ "$ROOTS_FOUND" -eq 0 ]; then
+  echo "ERROR: no src/app/lib/server directory under '$DIR' — nothing was checked."
+  echo "Run from the app root or pass --dir <app-root>."
+  exit 1
+fi
+
+fail=0
+violation() {
+  echo "VIOLATION: $1"
+  fail=1
+}
+warning() {
+  echo "WARNING: $1"
+}
+
+scan() {
+  # $1 = include pattern; prints matching files under the usual roots.
+  grep -rln --include="$1" -e 'new Agent(' -e 'new AgentTeam(' -e 'createTool(' -e '.asTool(' \
+    "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server" 2>/dev/null
+}
+
+FILES=$( { scan '*.ts'; scan '*.tsx'; } | sort -u)
+
+if [ -z "$FILES" ]; then
+  echo "agent OK (no Agent/tool code found)"
+  exit 0
+fi
+
+# 1. createTool requires a zod inputSchema at the boundary.
+violations=$(echo "$FILES" | while IFS= read -r f; do
+  awk -v file="$f" '
+    /createTool\(/ { in_tool=1; buf=""; depth=0 }
+    in_tool { buf=buf "\n" $0; depth+=gsub(/\(/,"(")-gsub(/\)/,")") }
+    in_tool && depth<=0 && length(buf)>0 {
+      if (buf !~ /inputSchema/) print "VIOLATION: " file ": createTool without inputSchema (see references/tools.md)."
+      in_tool=0
+    }
+  ' "$f"
+done)
+if [ -n "$violations" ]; then
+  echo "$violations"
+  fail=1
+fi
+
+# 2. asTool requires an explicit suspension policy.
+if echo "$FILES" | xargs grep -h -A4 '.asTool(' 2>/dev/null | grep -q 'asTool('; then
+  echo "$FILES" | xargs grep -h -A4 '.asTool(' 2>/dev/null | grep -q 'suspension' || {
+    violation "agent.asTool without suspension policy (see references/agent-options.md)."
+  }
+fi
+
+# 3. new Agent requires id and model.
+if echo "$FILES" | xargs grep -h -B1 -A8 'new Agent(' 2>/dev/null | grep -q 'new Agent('; then
+  echo "$FILES" | xargs grep -h -B1 -A8 'new Agent(' 2>/dev/null | grep -q 'id:' || {
+    violation "new Agent without id (see references/agent-options.md)."
+  }
+  echo "$FILES" | xargs grep -h -B1 -A8 'new Agent(' 2>/dev/null | grep -q 'model' || {
+    violation "new Agent without model (see references/providers.md)."
+  }
+fi
+
+# 4. Sensitive tool names without requiresApproval (warning only).
+if echo "$FILES" | xargs grep -l -i -e 'name: *"[^"]*\(delete\|refund\|payment\|payroll\)' 2>/dev/null | grep -q .; then
+  hit=$(echo "$FILES" | xargs grep -l -i -e 'name: *"[^"]*\(delete\|refund\|payment\|payroll\)' 2>/dev/null)
+  echo "$hit" | xargs grep -L 'requiresApproval' 2>/dev/null | grep -q . && {
+    warning "sensitive tool without requiresApproval (see references/tools.md)."
+  }
+fi
+
+# 5. AgentTeam requires a members array.
+if echo "$FILES" | xargs grep -l 'new AgentTeam(' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A10 'new AgentTeam(' 2>/dev/null | grep -q 'members' || {
+    violation "new AgentTeam without members (see references/teams.md)."
+  }
+fi
+
+if [ "$fail" -eq 0 ]; then
+  echo "agent OK"
+  exit 0
+fi
+echo "See skills/anvia-agent/references/ for fixes."
+exit 1

package/dist/skills/anvia-channels/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: anvia-channels
+description: Connect Discord, Slack, and Telegram to Anvia agents — channel adapters, agent-backed bots, proactive delivery, sessions, streaming, and platform actions.
+---
+
+# Anvia Channels Skill
+
+Use this skill when the user wants an Anvia agent reachable from Discord, Slack,
+or Telegram, needs proactive delivery into a channel from a worker or monitor,
+or wants to handle raw platform events. The five libraries are private workspace
+packages — depend on them from the channels workspace (`workspace:*`), not npm.
+
+## Process
+
+1. Wire the platform adapter (`references/adapters.md`) — one factory call per
+   platform; credentials from the environment, never literals.
+2. Run an agent behind it (`references/channel-agent.md`) — sessions and memory,
+   streaming edits, acknowledgements, slash commands, paused approvals.
+3. Send or receive without an agent (`references/delivery.md`) —
+   `sendChannelMessage`, long-text splitting, validation, raw event handling.
+4. Run `scripts/check-channels.sh` from the app root before claiming done.
+
+## Minimal slice
+
+```ts
+import { createChannelAgent } from "@anvia/channel-agent";
+import { Agent } from "@anvia/core/agent";
+import { OpenAIClient } from "@anvia/openai";
+import { telegram } from "@anvia/telegram";
+
+const openai = new OpenAIClient({ apiKey: process.env.OPENAI_API_KEY ?? "" });
+const agent = new Agent({
+  id: "telegram-assistant",
+  model: openai.completionModel({ modelId: "gpt-6-astra", api: "responses" }),
+  instructions: "You are a concise assistant. Answer in the sender's language.",
+});
+
+const channel = telegram({
+  token: process.env.TELEGRAM_BOT_TOKEN ?? "",
+  onError: (error, context) => console.error(`[telegram:${context.operation}]`, error),
+});
+
+const service = createChannelAgent({
+  channel,
+  agent,
+  streaming: { placeholder: "Thinking…", editIntervalMs: 750 },
+  acknowledge: "👀",
+  onError: (error, context) => console.error(`[channel-agent:${context.stage}]`, error),
+});
+
+await service.start();
+process.once("SIGTERM", () => void service.stop());
+```
+
+## Output
+
+Prefer one adapter, one agent, environment-read credentials, and a shutdown path
+for every started service. Point to the relevant reference file instead of
+pasting its contents into chat.

package/dist/skills/anvia-channels/references/adapters.md

@@ -0,0 +1,53 @@
+# Channel adapters
+
+Three first-party adapters, each a single factory call. All factories read
+credentials from the environment at the call site — never a literal.
+
+| Platform | Factory                                             | Input transport         | Delivery |
+| -------- | --------------------------------------------------- | ----------------------- | -------- |
+| Telegram | `telegram({ token })` from `@anvia/telegram`        | Long polling or webhook | Bot API  |
+| Discord  | `discord({ token })` from `@anvia/discord`          | Gateway                 | REST     |
+| Slack    | `slack({ appToken, botToken })` from `@anvia/slack` | Socket Mode             | Web API  |
+
+## Option shapes
+
+Each factory accepts either live credentials or an injected low-level client for
+offline tests — the unions are exclusive (`token` and `api` are never both set):
+
+- `telegram({ token, baseUrl?, fetch?, maximumAttachmentBytes?, polling?, webhook?, onError? })`
+  or `telegram({ api })`. `onError(error, context)` receives
+  `context.operation`.
+- `discord({ token, messageContentIntent?, fetch?, maximumAttachmentBytes?, onError? })`
+  or `discord({ gateway })`. Set `messageContentIntent` when the bot needs
+  message content (privileged intent on Discord's side).
+- `slack({ appToken, botToken, fetch?, maximumAttachmentBytes? })` or
+  `slack({ transport })` — app-level + bot-level tokens are both required.
+
+Adapters also expose the classes directly (`TelegramChannel`, `DiscordChannel`,
+`SlackChannel`) if you need the type; prefer the factories.
+
+## Capabilities
+
+Adapters advertise what the platform supports through `channel.capabilities` —
+gate optional behavior on it instead of hard-coding per-platform branches.
+All three support message edits, deletion, and reactions; files and
+replies/threads everywhere; native actions differ (Discord buttons, Slack Block
+Kit buttons, Telegram inline keyboard); typing indicators exist on Discord and
+Telegram but not Slack.
+
+## Addresses and events
+
+Every conversation is a `ChannelAddress`: `{ platform, conversationId }`.
+`platform` is a plain string — custom adapters choose their own.
+
+Inbound payloads are validated at runtime and normalized into a `ChannelEvent`
+union: message, message-edited, message-deleted, reaction, action, or command
+events. You rarely touch raw platform payloads unless you write an adapter.
+
+## Custom adapters
+
+Implement `Channel<RawEvent>` from `@anvia/channel`: a `platform` string,
+optional `capabilities`, send/edit/delete/react operations, and an event
+subscription that normalizes raw payloads into `ChannelEvent` values at the
+boundary. Wrap any adapter with `createRateLimitedChannel(channel, options)`
+to throttle outbound delivery.

package/dist/skills/anvia-channels/references/channel-agent.md

@@ -0,0 +1,52 @@
+# Channel agent bridge
+
+`createChannelAgent({ channel, agent, ... })` from `@anvia/channel-agent` runs
+an Anvia `Agent` behind any adapter and returns a `ChannelAgentService` with
+`start()` / `stop()`. `serveChannelAgent(options)` is the shorthand that also
+starts it. The executor contract is structural — anything with `generate` /
+`stream` (plus optional `resume`), i.e. an `Agent` — so tests can pass a fake.
+
+## Options that matter
+
+- `shouldHandle(event)` — filter inbound messages; the default
+  (`defaultShouldHandleChannelEvent`) drops bot/self messages and non-text
+  noise. Override for allowlists or group-chat rules.
+- `createSession(event)` — return a `MemoryScope` to scope agent memory per
+  conversation or per user. Defaults to `defaultChannelAgentSession`
+  (per-conversation); use `channelConversationUserSession` when each sender
+  needs their own thread of memory, `channelConversationSession` /
+  `channelConversationKey` for custom keys.
+- `createPrompt({ event, context })` — reshape the prompt before the agent runs
+  (`channelMessagePrompt` is the default builder).
+- `renderOutcome({ outcome, event })` — turn the agent outcome into the reply
+  text or a full `ChannelMessage` (actions, attachments).
+- `streaming` — `{ enabled?, editIntervalMs?, placeholder? }`; the bridge edits
+  one message in place as the agent streams. `placeholder: false` disables the
+  "Thinking…" stub.
+- `acknowledge` — shorthand for a receipt reaction: `"👀"` or
+  `{ reaction, completeReaction?, ... }`; `false` disables.
+- `commands` — handle platform slash commands; `false` (default) ignores them.
+- `multimodal` — inbound attachments become prompt parts when enabled.
+- `errorMessage`, `emptyResponseMessage` — user-facing fallbacks.
+- `onError(error, context)` — always set it. `context.stage` is one of
+  `"filter" | "prepare" | "acknowledge" | "interaction" | "agent" | "delivery"`,
+  which tells you where a failure happened.
+
+## Approvals and questions
+
+Tool approvals and agent questions pause instead of failing: the bridge stores
+the pending interaction and renders platform actions (buttons/inline keyboards)
+so the conversation can resume when the user taps. `interactions` controls this
+— pass `false` to disable, or options with a store:
+
+- `MemoryChannelAgentInteractionStore` — in-memory, fine for dev.
+- `SqliteChannelAgentInteractionStore` — durable; pending interactions survive
+  restarts.
+- Helpers: `renderChannelAgentInteraction`, `parseChannelAgentActionResponse`,
+  `channelInteractionActions`, `channelInteractionKey`.
+
+## Lifecycle
+
+`start()` begins receiving; `stop()` drains and disconnects. Own the shutdown
+path: stop the service, then close memory/interaction-store clients. Guard
+against double-shutdown when both SIGINT and SIGTERM arrive.