talon-agent 1.10.1 → 1.12.0

package/README.md

@@ -2,25 +2,26 @@
 
 [![Node.js](https://img.shields.io/badge/node-%3E%3D22-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-6.0-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![Claude](https://img.shields.io/badge/Claude_Agent_SDK-Anthropic-D97706)](https://github.com/anthropics/claude-agent-sdk-typescript)
+[![Backends](https://img.shields.io/badge/backends-Claude_%7C_Kilo_%7C_OpenCode_%7C_Codex-D97706)](#backends)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![CI](https://github.com/dylanneve1/talon/actions/workflows/ci.yml/badge.svg)](https://github.com/dylanneve1/talon/actions/workflows/ci.yml)
 
-Multi-platform agentic AI harness powered by Claude. Runs on **Telegram**, **Teams**, and **Terminal** with full tool access through MCP.
+Multi-platform agentic AI harness. Runs on **Telegram**, **Discord**, **Microsoft Teams**, and the **Terminal**, with a pluggable backend (**Claude Agent SDK**, **Kilo**, **OpenCode**, or **Codex**) and full tool access through MCP.
 
 ---
 
 ## Features
 
-|                       |                                                                                                         |
-| --------------------- | ------------------------------------------------------------------------------------------------------- |
-| **Multi-frontend**    | Telegram (Grammy + GramJS userbot), Microsoft Teams (Bot Framework), Terminal with live tool visibility |
-| **Claude Agent SDK**  | Streaming responses, extended thinking, adaptive effort, 1M token context, dynamic model discovery      |
-| **MCP tools**         | Messaging, media, history, search, web fetch, cron jobs, stickers, file system, admin controls          |
-| **Plugins**           | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search                     |
-| **Background agents** | Heartbeat (periodic maintenance) and Dream (memory consolidation + diary)                               |
-| **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard                              |
-| **Model registry**    | Models discovered from the SDK at startup --- new models appear in all pickers automatically            |
+|                       |                                                                                                                                       |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| **Multi-frontend**    | Telegram (Grammy + GramJS userbot), Discord (discord.js), Microsoft Teams (Bot Framework), Terminal with live tool visibility         |
+| **Pluggable backend** | Claude Agent SDK, Kilo, OpenCode, Codex — selectable per-process via `backend` config. Streaming, model fallback, context-overflow recovery. |
+| **MCP tools**         | Messaging, media, history, search, web fetch, cron jobs, triggers, stickers, file system, admin controls                              |
+| **Plugins**           | Hot-reloadable plugin system. Built-in: GitHub, MemPalace, Playwright, Brave Search                                                   |
+| **Background agents** | Heartbeat (periodic maintenance) and Dream (memory consolidation + diary) — backend-agnostic                                          |
+| **Triggers**          | Self-authored watcher scripts (bash/python/node) that wake the bot when conditions are met                                            |
+| **Per-chat settings** | Model, effort level, and pulse toggle per conversation via inline keyboard                                                            |
+| **Model registry**    | Models discovered from the active backend at startup — new models appear in all pickers automatically                                 |
 
 ---
 
@@ -41,7 +42,11 @@ npx talon chat        # terminal chat mode
 **Prerequisites:**
 
 - [Node.js 22+](https://nodejs.org/)
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` CLI on PATH)
+- Backend-specific:
+  - `claude` backend: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` CLI on PATH).
+  - `kilo` backend: nothing extra — `@kilocode/sdk` spawns a local server. Free models are accessible without auth; routed models use Kilo's own credentials.
+  - `opencode` backend: nothing extra — `@opencode-ai/sdk` spawns a local server.
+  - `codex` backend: install the `codex` CLI (`npm i -g @openai/codex`) and authenticate with `codex login` (ChatGPT auth or `OPENAI_API_KEY`).
 - Talon runs from a normal source or package install; standalone compiled binaries are not supported.
 
 ---
@@ -52,7 +57,7 @@ npx talon chat        # terminal chat mode
 index.ts                    Composition root
   |
   +-- core/                 Platform-agnostic engine
-  |   +-- models.ts         Model registry (dynamic SDK discovery)
+  |   +-- models.ts         Model registry (dynamic backend discovery)
   |   +-- gateway.ts        HTTP bridge for MCP tool calls
   |   +-- dispatcher.ts     Per-chat serial, cross-chat parallel execution
   |   +-- plugin.ts         Plugin loader, registry, hot-reload
@@ -60,15 +65,23 @@ index.ts                    Composition root
   |   +-- dream.ts          Memory consolidation agent
   |   +-- pulse.ts          Conversation-aware group engagement
   |   +-- cron.ts           Persistent scheduled jobs
-  |   +-- tools/            MCP tool definitions (13 files)
+  |   +-- triggers.ts       Self-authored watcher scripts
+  |   +-- tools/            MCP tool definitions
   |
   +-- backend/
-  |   +-- claude-sdk/       Claude Agent SDK (modular: handler, stream,
-  |   |                     options, state, warm, models, constants)
-  |   +-- opencode/         OpenCode SDK alternative backend
+  |   +-- registry.ts       Bootstrap-decoupled backend lookup
+  |   +-- shared/           Cross-backend helpers (stream state, flow violation,
+  |   |                     prompt format, model retry, system prompt, usage)
+  |   +-- remote-server/    Shared infrastructure for agent-server backends
+  |   |                     (MCP registration, sessions, providers, lifecycle)
+  |   +-- claude-sdk/       Claude Agent SDK (in-process MCP, hooks)
+  |   +-- kilo/             Kilo HTTP server backend (streaming via SSE)
+  |   +-- opencode/         OpenCode HTTP server backend
+  |   +-- codex/            Codex CLI backend (`@openai/codex-sdk`)
   |
   +-- frontend/
-  |   +-- telegram/         Grammy bot + GramJS userbot (10 files)
+  |   +-- telegram/         Grammy bot + GramJS userbot
+  |   +-- discord/          discord.js v14
   |   +-- teams/            Bot Framework + Graph API
   |   +-- terminal/         Readline CLI with tool call visibility
   |
@@ -77,7 +90,22 @@ index.ts                    Composition root
   +-- util/                 Config, logging, workspace, paths, time
 ```
 
-**Dependency rule:** `core/` imports nothing from `frontend/` or `backend/`. Frontends and backends depend on core types, never on each other.
+**Dependency rule:** `core/` imports nothing from `frontend/` or `backend/`. Frontends and backends depend on core types, never on each other. All four backends (Claude SDK, Kilo, OpenCode, Codex) implement the same `QueryBackend` interface in `core/types.ts`. Kilo and OpenCode additionally share the `remote-server/` infrastructure because they wrap forks of the same upstream HTTP agent server.
+
+---
+
+## Backends
+
+Select via the `backend` field in `~/.talon/config.json`. All backends implement the same `QueryBackend` interface — heartbeat, dream, and chat handlers are backend-agnostic.
+
+| Backend    | `backend` value | Transport                                              | Notes                                                                   |
+| ---------- | --------------- | ------------------------------------------------------ | ----------------------------------------------------------------------- |
+| Claude SDK | `"claude"`      | In-process via `@anthropic-ai/claude-agent-sdk`        | Requires the `claude` CLI on `PATH`. Hook-based turn termination.       |
+| Kilo       | `"kilo"`        | Local HTTP server via `@kilocode/sdk`                  | SSE-streamed turns. Routes to many model providers via Kilo's auth.     |
+| OpenCode   | `"opencode"`    | Local HTTP server via `@opencode-ai/sdk`               | SSE-streamed turns; same MCP and session shape as Kilo (upstream fork). |
+| Codex      | `"codex"`       | Per-turn subprocess via `@openai/codex-sdk`            | Requires the `codex` CLI from `@openai/codex` and an OpenAI API key (or ChatGPT auth). MCP servers configured via TOML overrides at thread start. |
+
+The Kilo and OpenCode backends share infrastructure (`backend/remote-server/`) since the upstream HTTP API is the same; each backend supplies its own SDK client, port, and delivery suffix. Codex is its own integration on top of the Codex CLI's JSONL event stream.
 
 ---
 
@@ -216,25 +244,25 @@ talon doctor    Validate environment and dependencies
 
 Config file: `~/.talon/config.json`
 
-| Field                      | Default      | Description                                                         |
-| -------------------------- | ------------ | ------------------------------------------------------------------- |
-| `frontend`                 | `"telegram"` | `"telegram"`, `"terminal"`, `"teams"`, or an array                  |
-| `backend`                  | `"claude"`   | `"claude"` or `"opencode"`                                          |
-| `botToken`                 | ---          | Telegram bot token                                                  |
-| `model`                    | `"default"`  | Default Claude model. Legacy `claude-*` aliases are still accepted. |
-| `concurrency`              | `1`          | Max concurrent AI queries (1--20)                                   |
-| `pulse`                    | `true`       | Periodic group engagement                                           |
-| `heartbeat`                | `false`      | Background maintenance agent                                        |
-| `heartbeatIntervalMinutes` | `60`         | Heartbeat interval                                                  |
-| `braveApiKey`              | ---          | Brave Search API key                                                |
-| `timezone`                 | ---          | IANA timezone (e.g. `"Europe/London"`)                              |
-| `plugins`                  | `[]`         | External plugin packages                                            |
-| `adminUserId`              | ---          | Telegram user ID for `/admin` commands                              |
-| `allowedUsers`             | ---          | Whitelist of Telegram user IDs                                      |
-| `apiId` / `apiHash`        | ---          | Telegram API credentials for full message history                   |
-| `github`                   | ---          | GitHub plugin config (see above)                                    |
-| `mempalace`                | ---          | MemPalace plugin config (see above)                                 |
-| `playwright`               | ---          | Playwright plugin config (see above)                                |
+| Field                      | Default      | Description                                                     |
+| -------------------------- | ------------ | --------------------------------------------------------------- |
+| `frontend`                 | `"telegram"` | `"telegram"`, `"discord"`, `"teams"`, `"terminal"`, or an array |
+| `backend`                  | `"claude"`   | `"claude"`, `"kilo"`, `"opencode"`, or `"codex"`                |
+| `botToken`                 | ---          | Telegram bot token                                              |
+| `model`                    | `"default"`  | Default model. Interpretation depends on the active backend.    |
+| `concurrency`              | `1`          | Max concurrent AI queries (1--20)                               |
+| `pulse`                    | `true`       | Periodic group engagement                                       |
+| `heartbeat`                | `false`      | Background maintenance agent                                    |
+| `heartbeatIntervalMinutes` | `60`         | Heartbeat interval                                              |
+| `braveApiKey`              | ---          | Brave Search API key                                            |
+| `timezone`                 | ---          | IANA timezone (e.g. `"Europe/London"`)                          |
+| `plugins`                  | `[]`         | External plugin packages                                        |
+| `adminUserId`              | ---          | Telegram user ID for `/admin` commands                          |
+| `allowedUsers`             | ---          | Whitelist of Telegram user IDs                                  |
+| `apiId` / `apiHash`        | ---          | Telegram API credentials for full message history               |
+| `github`                   | ---          | GitHub plugin config (see above)                                |
+| `mempalace`                | ---          | MemPalace plugin config (see above)                             |
+| `playwright`               | ---          | Playwright plugin config (see above)                            |
 
 ---
 
@@ -258,7 +286,7 @@ Commands: `/model`, `/effort`, `/reset`, `/status`, `/help`
 docker compose up -d
 ```
 
-**Systemd:** `talon.service` included in the repository.
+**Systemd:** unit file at `packaging/systemd/talon.service` — copy to `/etc/systemd/system/`, set `User=` and `WorkingDirectory=`, then `systemctl enable --now talon`.
 
 **Health endpoint:** `GET http://localhost:19876/health` returns JSON with uptime, memory, queue depth, active sessions, and last activity timestamp.
 
@@ -272,10 +300,11 @@ docker compose up -d
 
 ```bash
 npm run dev              # watch mode
-npm test                 # 1300+ tests
+npm test                 # 2300+ tests across unit / SDK-stub / MCP-functional / integration tiers
 npm run test:coverage    # with coverage report
 npm run typecheck        # tsc --noEmit
 npm run lint             # oxlint
+npm run format           # prettier --write
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.10.1",
+  "version": "1.12.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -30,7 +30,16 @@
   },
   "files": [
     "bin/",
-    "src/",
+    "src/backend/",
+    "src/core/",
+    "src/frontend/",
+    "src/plugins/",
+    "src/storage/",
+    "src/util/",
+    "src/bootstrap.ts",
+    "src/cli.ts",
+    "src/index.ts",
+    "src/login.ts",
     "prompts/",
     "README.md",
     "tsconfig.json"
@@ -43,6 +52,13 @@
     "test": "vitest run",
     "test:ci": "vitest run --reporter=verbose --reporter=json --outputFile=test-results.json",
     "test:functional": "vitest run --reporter=verbose --reporter=json --outputFile=functional-results.json src/__tests__/package.functional.test.ts src/__tests__/tool-functional.test.ts src/__tests__/mcp-launcher.test.ts src/__tests__/mcp-launcher-functional.test.ts src/__tests__/integration/sdk-stub.test.ts src/__tests__/integration/talon-functional.test.ts",
+    "test:integration": "vitest run --reporter=verbose --reporter=json --outputFile=integration-results.json src/__tests__/integration/talon-mcp-functional.test.ts",
+    "test:integration:all": "vitest run --reporter=verbose src/__tests__/integration/",
+    "test:claude:backend": "vitest run --reporter=verbose --reporter=json --outputFile=claude-backend-results.json src/__tests__/integration/claude-live-discovery.test.ts",
+    "test:kilo:backend": "vitest run --reporter=verbose --reporter=json --outputFile=kilo-backend-results.json src/__tests__/integration/kilo-live-discovery.test.ts",
+    "test:opencode:backend": "vitest run --reporter=verbose --reporter=json --outputFile=opencode-backend-results.json src/__tests__/integration/opencode-live-discovery.test.ts",
+    "test:codex:backend": "vitest run --reporter=verbose --reporter=json --outputFile=codex-backend-results.json src/__tests__/integration/codex-live-discovery.test.ts",
+    "tarball:check": "node .github/scripts/tarball-check.mjs",
     "build:stub-sea": "node src/__tests__/integration/stub-claude/build-sea.mjs",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -60,12 +76,16 @@
     "@clack/prompts": "^1.2.0",
     "@grammyjs/auto-retry": "^2.0.2",
     "@grammyjs/transformer-throttler": "^1.2.1",
+    "@kilocode/sdk": "^7.2.22",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@openai/agents": "^0.11.4",
+    "@openai/codex-sdk": "^0.130.0",
     "@opencode-ai/sdk": "^1.4.0",
     "@playwright/mcp": "^0.0.75",
     "big-integer": "^1.6.52",
     "cheerio": "^1.2.0",
     "croner": "^10.0.1",
+    "discord.js": "^14.16.3",
     "grammy": "^1.42.0",
     "marked": "^18.0.0",
     "p-retry": "^8.0.0",
@@ -91,6 +111,7 @@
   },
   "overrides": {
     "@anthropic-ai/sdk": "^0.95.0",
-    "ip-address": "^10.1.1"
+    "ip-address": "^10.1.1",
+    "fast-uri": "^3.1.2"
   }
 }

package/prompts/base.md

@@ -1,13 +1,17 @@
 Be concise and direct. No filler. Answer directly.
 
-## Core tools
+## Tools
 
-- File system: Read, Write, Edit, Bash, Glob, Grep
-- Web: web_search(query), fetch_url(url)
-- Sub-agents: Agent (for complex multi-step tasks)
-- Any plugin tools registered are also available
+Only the tools the runtime registers for this turn are usable — the
+list is attached to this prompt by the backend. Do not invent or
+guess tool names from prior Talon configurations, other agents, or
+typical AI tooling vocabularies; if a name isn't in the registered
+list, calling it will fail the turn.
 
-## File handling
+When a tool that does what you need isn't present, fall back to
+plain conversation. Don't pretend to perform actions (reading a
+file, running a command, browsing the web) you have no tool for —
+say so plainly instead, and ask the user if you're unsure.
 
-- You have full file system access via Claude Code tools (Read, Write, Edit, Bash).
-- You CAN create files. Write them to the `~/.talon/workspace/` directory.
+Workspace artifacts, when persistable for this backend, live under
+`~/.talon/workspace/`.

package/prompts/discord.md

@@ -0,0 +1,84 @@
+## Discord Mode
+
+In servers (guilds), you'll see messages prefixed with [Name]: — use their name naturally. In DMs, just one user.
+
+### CRITICAL: Message delivery
+
+ALL messages to the user MUST be sent using the `send` tool. Your plain text output is **private** — the user never sees it, only you. Think of it as an internal scratchpad: jot a brief note to yourself if useful (a sentence or two — what you did, what you noticed, a reminder), but keep it short since nobody reads it. The only way to reach the user is the `send` tool.
+
+### The `send` tool
+
+One tool for everything. Set `type` to choose what to send:
+
+- `send(type="text", text="Hello!")` — send a message
+- `send(type="text", text="Hey", reply_to="123456789012345678")` — reply to a specific message (Discord IDs are strings)
+- `send(type="text", text="Pick", buttons=[[{"text":"A","callback_data":"a","style":"primary"}]])` — with buttons
+- `send(type="text", text="Reminder", delay_seconds=60)` — schedule for later
+- `send(type="photo", file_path="img.jpg", caption="Look!")` — send an image
+- `send(type="file", file_path="report.pdf")` — send a document
+- `send(type="video", file_path="clip.mp4")` — send a video
+- `send(type="voice", file_path="audio.ogg")` — send an audio attachment
+- `send(type="poll", question="Best?", options=["A","B","C"])` — create a poll
+- `send(type="dice")` — roll dice
+- `send(type="location", latitude=37.77, longitude=-122.42)` — share a Google Maps location link
+- `send(type="contact", phone_number="+1234", first_name="John")` — share a contact card
+
+ALL types support `reply_to` to reply to a specific message.
+
+### Discord-specific
+
+- **IDs are strings** — Discord uses snowflakes (17–20 digits). Treat them as opaque strings, not numbers.
+- **Buttons:** the `style` field accepts `"primary"`, `"secondary"`, `"success"`, `"danger"`. URL buttons use `url` instead of `callback_data`.
+- **Markdown is native:** `**bold**`, `*italic*`, `` `code` ``, ` ```fenced``` `, `# headings`, `> quotes`, `||spoilers||`, `[links](url)`. Discord renders these without translation.
+- **Mentions:** the bot is configured to suppress all mentions (`@everyone`, `@here`, role/user pings) so you can't accidentally ping anyone. Don't worry about escaping.
+- **Message limit:** 2000 chars per message. Long messages are auto-chunked at paragraph breaks.
+
+### Other tools
+
+- `react(message_id, emoji)` — react to a message (unicode emoji only on Discord; custom emojis need `<:name:id>` format)
+- `edit_message(message_id, text)` — edit a sent message (max 2000 chars)
+- `delete_message(message_id)` — delete a message
+- `pin_message(message_id)` / `unpin_message()` — pin/unpin
+- `read_chat_history(limit)` — read past messages from this channel
+- `search_chat_history(query)` — search recent messages by keyword
+- `list_chat_members()` — list members in this server (guild only)
+- `get_member_info(user_id)` — detailed user info
+- `online_count()` — approximate online member count
+
+### Message IDs
+
+The user's message ID is in the prompt as msg_id:N (Discord snowflake string). Use with `reply_to` and `react`.
+
+### Choosing not to respond
+
+You don't HAVE to respond to every message. If a message doesn't need a response:
+
+- React with an emoji using the `react` tool — preferred way to acknowledge without replying.
+- Or simply don't call `send` and skip it entirely.
+- In servers, prefer reactions over replies for simple acknowledgements.
+
+### Reactions
+
+Use naturally: 👍 ❤️ 🔥 😂 🎉 👀 💯. React AND reply when both feel right.
+
+### Buttons & Components
+
+When a user presses a button, you'll receive "[Button pressed]" with the custom_id. Buttons can also be a select menu — those come through with the chosen value in the same format.
+
+### File sending
+
+- Files users send are saved to `~/.talon/workspace/uploads/`.
+- To send files: write the file, then use `send(type="file", file_path="...")`.
+- File limit depends on the server's boost tier: 10 MB (default), 25 MB (tier 1), 50 MB (tier 2), 100 MB (tier 3). DMs use 10 MB. Larger files get rejected with a clear error — split or upload externally.
+- You CAN send files. NEVER say you can't.
+
+### Servers vs DMs
+
+- In servers, you only see messages where you're @mentioned or replied to (default), or any message in a configured channel (alt mode). Outside that, the conversation is happening without you.
+- In DMs, you see everything — but only allowed users can DM you in the first place.
+
+### Style
+
+- Concise. No filler.
+- Discord markdown renders natively — use it.
+- In servers, use names naturally.

package/prompts/identity.md

@@ -9,20 +9,20 @@
 
 ## Core
 
-- You're powered by Claude (Anthropic) via the Agent SDK
-- You have tools to interact with your current platform directly (send messages, react, etc.)
+- You're a Talon agent. The model and tools available to you depend on the active backend — only the tools listed below this prompt actually exist for this run.
+- You have tools to interact with your current platform directly (send messages, react, etc.) — those are always provided by the frontend.
 
 ## Identity Bootstrap
 
-Your identity is defined in `~/.talon/workspace/identity.md`. Read it to know who you are.
+Your identity is stored at `~/.talon/workspace/identity.md`. If a filesystem-capable tool is listed below, open that file to see who you are; if not, treat the identity content already inlined into this prompt (or absent) as authoritative and proceed.
 
-If the identity file is empty or only contains the template comments, you MUST ask the user during your first interaction:
+If the identity file is empty or only contains template comments, you MUST ask the user during your first interaction:
 
 - What should I be called?
 - Who are you / who created me?
 - What will I be used for?
 
-Write the answers to `~/.talon/workspace/identity.md` using the Write tool. Keep it concise — just key facts about who you are. Update it naturally if the user tells you to change something about yourself.
+When a filesystem-capable tool is available, persist the answers to `~/.talon/workspace/identity.md`. When it isn't, just remember the answers within the conversation and apply them. Keep identity content concise — key facts only.
 
 ## Guidelines
 
@@ -36,7 +36,7 @@ Write the answers to `~/.talon/workspace/identity.md` using the Write tool. Keep
 
 ## Memory Management
 
-When you learn important new information during a conversation, update your memory file (`~/.talon/workspace/memory/memory.md`) using the Write tool. Things worth remembering:
+When you learn important new information during a conversation, persist it to your memory file at `~/.talon/workspace/memory/memory.md` — only when a filesystem-capable tool is available for this backend. When no such tool is available, keep the information in working memory for the current conversation and don't pretend to save anything you can't actually save. Things worth remembering:
 
 - **User preferences**: communication style, interests, timezone, language, how they like to be addressed
 - **Important facts**: names, roles, relationships between users, projects they're working on

package/src/backend/claude-sdk/factory.ts

@@ -0,0 +1,79 @@
+/**
+ * Claude SDK backend factory — wires the Anthropic Claude Agent SDK
+ * into the registry.
+ *
+ * Unlike Kilo/OpenCode (which run a local HTTP server), the Claude SDK
+ * spawns a per-query subprocess. So this factory also wires the
+ * `refreshMcpServers` hot-swap path used by plugin reload + the
+ * `evictOrphanSubprocesses` cleanup helper.
+ */
+
+import { registerBackend } from "../registry.js";
+import type { BackendFactory } from "../registry.js";
+import type { QueryBackend } from "../../core/types.js";
+import { log } from "../../util/log.js";
+import { getPluginMcpServers } from "../../core/plugin.js";
+
+import {
+  initAgent as initClaudeAgent,
+  updateSystemPrompt as claudeUpdateSystemPrompt,
+  handleMessage as claudeHandleMessage,
+  warmSession as claudeWarmSession,
+  getActiveQuery,
+  buildMcpServers,
+  runOneShotAgent as claudeRunOneShotAgent,
+  evictOrphanSubprocesses as claudeEvictOrphanSubprocesses,
+} from "./index.js";
+
+import * as modelProvider from "./model-provider.js";
+
+// ── Factory ────────────────────────────────────────────────────────────────
+
+const claudeSdkFactory: BackendFactory = {
+  // The config schema uses `"claude"` for backward compatibility with
+  // talon.json files predating the registry. Matching the id here means
+  // no migration is needed.
+  id: "claude",
+  label: "Anthropic",
+
+  async init(config, ctx) {
+    await initClaudeAgent(config, ctx.getBridgePort);
+    log("bot", "Backend: Claude SDK (@anthropic-ai/claude-agent-sdk)");
+
+    const backend: QueryBackend = {
+      query: (params) => claudeHandleMessage(params),
+      warmSession: (chatId) => claudeWarmSession(chatId),
+      updateSystemPrompt: (prompt) => claudeUpdateSystemPrompt(prompt),
+      resolveModel: (q) => modelProvider.resolveModel(q),
+      getModelInfo: (id) => modelProvider.getModelInfo(id),
+      getSettingsPresentation: (m, options) =>
+        modelProvider.getSettingsPresentation(m, options),
+      getProviders: () => modelProvider.getProviders(),
+      getProviderModels: (p, pg, ps) =>
+        modelProvider.getProviderModels(p, pg, ps),
+      formatModelError: (q, r) => modelProvider.formatModelError(q, r),
+      listModels: (f) => modelProvider.listModels(f),
+      backendLabel: "Anthropic",
+      refreshMcpServers: async (chatId) => {
+        const qi = getActiveQuery(chatId);
+        if (!qi) return null;
+        // Two-phase teardown: remove all MCP servers first so each
+        // subprocess receives an OS-agnostic shutdown via stdio, then
+        // install the fresh set.
+        await qi.setMcpServers({});
+        const bridgeUrl = `http://127.0.0.1:${ctx.getBridgePort()}`;
+        const freshServers = {
+          ...buildMcpServers(chatId),
+          ...getPluginMcpServers(bridgeUrl, chatId),
+        };
+        return qi.setMcpServers(freshServers);
+      },
+      runOneShotAgent: (p) => claudeRunOneShotAgent(p),
+      evictOrphanSubprocesses: (label) => claudeEvictOrphanSubprocesses(label),
+    };
+
+    return { backend };
+  },
+};
+
+registerBackend(claudeSdkFactory);