talon-agent 1.6.0 → 1.7.0

package/README.md

@@ -1,22 +1,28 @@
 # Talon
 
 [![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-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.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)
 [![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 powered by Claude. Runs on **Telegram**, **Teams**, and **Terminal** with full tool access through MCP.
+
+---
 
 ## Features
 
-- **Multi-frontend** — Telegram (Grammy), Teams (Bot Framework), Terminal (readline)
-- **Claude Agent SDK** — streaming responses, extended thinking, 1M context sessions
-- **31 MCP tools** — messaging, media, history, search, web, cron jobs, file system
-- **Plugin system** — extend with external tool packages (keeps core OSS-clean)
-- **Cron jobs** — persistent recurring tasks with full tool access
-- **Pulse** — periodic conversation-aware engagement in group chats
-- **Per-chat settings** — model, effort level, pulse toggle per conversation
+| | |
+|---|---|
+| **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 |
+
+---
 
 ## Quick Start
 
@@ -24,39 +30,134 @@ Multi-platform agentic AI harness powered by Claude. Runs on Telegram, Teams, an
 git clone https://github.com/dylanneve1/talon.git && cd talon
 npm install
 
-# Interactive setup (select frontend, configure tokens)
+# Interactive setup (select frontend, configure tokens, pick model)
 npx talon setup
 
 # Start
-npx talon start       # configured frontend (Telegram/Terminal)
+npx talon start       # configured frontend (daemon mode)
 npx talon chat        # terminal chat mode
 ```
 
-Requires [Node.js 22+](https://nodejs.org/) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated.
+**Prerequisites:**
+- [Node.js 22+](https://nodejs.org/)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (`claude` CLI on PATH)
+
+---
 
 ## Architecture
 
 ```
-index.ts (Composition Root)
-├── core/               Platform-agnostic core
-│   ├── gateway.ts      HTTP bridge for MCP tool calls
-│   ├── dispatcher.ts   Query queue + lifecycle
-│   ├── plugin.ts       Plugin loader + registry
-│   ├── pulse.ts        Periodic engagement
-│   └── cron.ts         Persistent scheduled jobs
-├── backend/
-│   ├── claude-sdk/     Claude Agent SDK + MCP subprocess
-│   └── opencode/       OpenCode SDK alternative
-├── frontend/
-│   ├── telegram/       Grammy + GramJS userbot
-│   ├── teams/          Bot Framework
-│   └── terminal/       Readline CLI with tool call visibility
-└── storage/            Sessions, history, settings, cron, media
+index.ts                    Composition root
+  |
+  +-- core/                 Platform-agnostic engine
+  |   +-- models.ts         Model registry (dynamic SDK 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
+  |   +-- heartbeat.ts      Periodic background agent
+  |   +-- dream.ts          Memory consolidation agent
+  |   +-- pulse.ts          Conversation-aware group engagement
+  |   +-- cron.ts           Persistent scheduled jobs
+  |   +-- tools/            MCP tool definitions (13 files)
+  |
+  +-- backend/
+  |   +-- claude-sdk/       Claude Agent SDK (modular: handler, stream,
+  |   |                     options, state, warm, models, constants)
+  |   +-- opencode/         OpenCode SDK alternative backend
+  |
+  +-- frontend/
+  |   +-- telegram/         Grammy bot + GramJS userbot (10 files)
+  |   +-- teams/            Bot Framework + Graph API
+  |   +-- terminal/         Readline CLI with tool call visibility
+  |
+  +-- storage/              Sessions, history, chat settings,
+  |                         cron jobs, media index, daily logs
+  +-- 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.
+
+---
+
+## Built-in Plugins
+
+### GitHub
+
+GitHub API access via the official GitHub MCP server. Gives the agent access to repositories, issues, PRs, code search, and more.
+
+**Requirements:** Docker installed and running.
+
+```json
+{
+  "github": {
+    "enabled": true,
+    "token": "ghp_..."
+  }
+}
+```
+
+The token is optional --- defaults to the output of `gh auth token` if the GitHub CLI is authenticated.
+
+### MemPalace
+
+Structured long-term memory with vector search. The agent can store, search, and retrieve memories semantically. Integrates with Dream mode for automatic memory consolidation and personal diary entries.
+
+**Requirements:** Python 3.10+ with the `mempalace` package.
+
+```bash
+# Set up a Python environment
+python -m venv ~/.talon/mempalace-venv
+~/.talon/mempalace-venv/bin/pip install mempalace    # Unix
+# or: ~/.talon/mempalace-venv/Scripts/pip install mempalace   # Windows
+```
+
+```json
+{
+  "mempalace": {
+    "enabled": true,
+    "palacePath": "~/.talon/workspace/palace",
+    "pythonPath": "~/.talon/mempalace-venv/bin/python"
+  }
+}
 ```
 
-## Plugin System
+Both paths are optional --- defaults to `~/.talon/workspace/palace/` and the venv Python respectively.
+
+### Playwright
 
-Plugins add MCP tools and gateway actions without modifying core code. SOLID interface — only `name` is required, everything else is optional.
+Headless browser automation via the Playwright MCP server. The agent can browse websites, take screenshots, generate PDFs, fill forms, and scrape content.
+
+**Requirements:** None --- `@playwright/mcp` is bundled with Talon.
+
+```json
+{
+  "playwright": {
+    "enabled": true,
+    "browser": "chromium",
+    "headless": true
+  }
+}
+```
+
+Supported browsers: `chromium` (default), `chrome`, `firefox`, `webkit`, `msedge`.
+
+### Brave Search
+
+Web search via the Brave Search MCP server. Replaces the built-in WebSearch/WebFetch tools with higher-quality search results.
+
+```json
+{
+  "braveApiKey": "BSA..."
+}
+```
+
+Get an API key at [brave.com/search/api](https://brave.com/search/api/).
+
+---
+
+## Custom Plugins
+
+Plugins add MCP tools and gateway actions without modifying core code. SOLID interface --- only `name` is required.
 
 ```json
 {
@@ -80,59 +181,92 @@ export default {
 };
 ```
 
+Plugins support hot-reload via the `reload_plugins` MCP tool --- no restart required.
+
+---
+
 ## CLI
 
 ```
-talon setup     Interactive setup wizard (multi-select frontends)
-talon start     Start the configured frontend
+talon setup     Interactive setup wizard
+talon start     Start as a background daemon
+talon stop      Stop the daemon
 talon chat      Terminal chat mode (always available)
-talon status    Health, sessions, and plugin status
-talon config    View/edit configuration
+talon status    Health, sessions, plugins, disk usage
+talon config    View or edit configuration
 talon logs      Tail structured log file
-talon doctor    Validate environment
+talon doctor    Validate environment and dependencies
 ```
 
+---
+
 ## Configuration
 
-`workspace/talon.json`:
+Config file: `~/.talon/config.json`
 
 | Field | Default | Description |
 |-------|---------|-------------|
-| `frontend` | `"telegram"` | `"telegram"`, `"terminal"`, or both |
-| `botToken` | — | Telegram bot token (required for Telegram) |
-| `model` | `"claude-sonnet-4-6"` | Default model |
-| `concurrency` | `1` | Max concurrent AI queries |
+| `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 |
-| `apiId` / `apiHash` | — | Telegram API for full history |
+| `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) |
+
+---
 
 ## Terminal Mode
 
 ```bash
-talon chat    # interactive terminal chat
+npx talon chat
 ```
 
-Tool calls shown in real-time with parameters. Streaming phase indicators (thinking/responding/using tools). Per-turn stats (duration, tokens, cache hit, tool count).
+Tool calls shown in real-time with parameters. Streaming phase indicators (thinking / responding / using tools). Per-turn stats: duration, tokens, cache hit rate, tool count.
+
+Commands: `/model`, `/effort`, `/reset`, `/status`, `/help`
+
+---
 
 ## Production
 
-- **Docker**: `docker compose up -d`
-- **Systemd**: `talon.service` included
-- **Health**: `GET http://localhost:19876/health` — JSON with uptime, memory, queue, sessions
-- **Logging**: Structured JSON via pino to `workspace/talon.log`
-- **Resilience**: Model fallback, session auto-retry, rate limiting, atomic writes, graceful shutdown
+**Docker:**
+```bash
+docker compose up -d
+```
+
+**Systemd:** `talon.service` included in the repository.
+
+**Health endpoint:** `GET http://localhost:19876/health` returns JSON with uptime, memory, queue depth, active sessions, and last activity timestamp.
+
+**Logging:** Structured JSON via pino to `~/.talon/talon.log`. Rotated on startup when the file exceeds 10MB.
+
+**Resilience:** Dynamic model fallback on overload, session auto-retry on expiry, rate limit handling with backoff, atomic file writes, graceful shutdown with 15-second drain timeout.
+
+---
 
 ## Development
 
 ```bash
 npm run dev              # watch mode
-npm test                 # 322 tests
-npm run test:coverage    # with coverage
+npm test                 # 1300+ tests
+npm run test:coverage    # with coverage report
 npm run typecheck        # tsc --noEmit
 npm run lint             # oxlint
 ```
 
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",
@@ -51,7 +51,7 @@
     "format:check": "prettier --check src/ prompts/"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.104",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.108",
     "@brave/brave-search-mcp-server": "^2.0.75",
     "@clack/prompts": "^1.2.0",
     "@grammyjs/auto-retry": "^2.0.2",

package/src/__tests__/chat-settings.test.ts

@@ -38,6 +38,12 @@ const { registerClaudeModelsStatic, CLAUDE_MODELS_STATIC } =
   await import("../backend/claude-sdk/models.js");
 registerClaudeModelsStatic(CLAUDE_MODELS_STATIC);
 
+const SDK_MODEL_IDS = {
+  sonnet: "default",
+  opus: "opus",
+  haiku: "haiku",
+} as const;
+
 describe("chat-settings", () => {
   describe("getChatSettings", () => {
     it("returns empty object for unknown chat", () => {
@@ -85,62 +91,67 @@ describe("chat-settings", () => {
   });
 
   describe("resolveModelName", () => {
-    it("resolves 'sonnet' to claude-sonnet-4-6", () => {
-      expect(resolveModelName("sonnet")).toBe("claude-sonnet-4-6");
+    it("resolves 'sonnet' to the SDK default model ID", () => {
+      expect(resolveModelName("sonnet")).toBe(SDK_MODEL_IDS.sonnet);
     });
 
-    it("resolves 'opus' to claude-opus-4-6", () => {
-      expect(resolveModelName("opus")).toBe("claude-opus-4-6");
+    it("resolves 'opus' to the SDK Opus model ID", () => {
+      expect(resolveModelName("opus")).toBe(SDK_MODEL_IDS.opus);
     });
 
-    it("resolves 'haiku' to claude-haiku-4-5", () => {
-      expect(resolveModelName("haiku")).toBe("claude-haiku-4-5");
+    it("resolves 'haiku' to the SDK Haiku model ID", () => {
+      expect(resolveModelName("haiku")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("resolves versioned aliases", () => {
-      expect(resolveModelName("sonnet-4.6")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("opus-4.6")).toBe("claude-opus-4-6");
-      expect(resolveModelName("haiku-4.5")).toBe("claude-haiku-4-5");
+      expect(resolveModelName("sonnet-4.6")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("opus-4.6")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("haiku-4.5")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("resolves dash-separated aliases", () => {
-      expect(resolveModelName("sonnet-4-6")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("opus-4-6")).toBe("claude-opus-4-6");
-      expect(resolveModelName("haiku-4-5")).toBe("claude-haiku-4-5");
+      expect(resolveModelName("sonnet-4-6")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("opus-4-6")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("haiku-4-5")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("is case-insensitive", () => {
-      expect(resolveModelName("Sonnet")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("OPUS")).toBe("claude-opus-4-6");
+      expect(resolveModelName("Sonnet")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("OPUS")).toBe(SDK_MODEL_IDS.opus);
     });
 
     it("trims whitespace", () => {
-      expect(resolveModelName("  sonnet  ")).toBe("claude-sonnet-4-6");
+      expect(resolveModelName("  sonnet  ")).toBe(SDK_MODEL_IDS.sonnet);
     });
 
     it("passes through unknown model names unchanged", () => {
       expect(resolveModelName("gpt-4")).toBe("gpt-4");
-      expect(resolveModelName("claude-sonnet-4-6")).toBe("claude-sonnet-4-6");
+    });
+
+    it("resolves legacy claude-* aliases to the current SDK IDs", () => {
+      expect(resolveModelName("claude-sonnet-4-6")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("claude-opus-4-6")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("claude-haiku-4-5")).toBe(SDK_MODEL_IDS.haiku);
     });
   });
 
   describe("resolveModelName — exhaustive alias coverage", () => {
     it("resolves all base aliases correctly", () => {
-      expect(resolveModelName("sonnet")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("opus")).toBe("claude-opus-4-6");
-      expect(resolveModelName("haiku")).toBe("claude-haiku-4-5");
+      expect(resolveModelName("sonnet")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("opus")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("haiku")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("resolves all dot-separated version aliases", () => {
-      expect(resolveModelName("sonnet-4.6")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("opus-4.6")).toBe("claude-opus-4-6");
-      expect(resolveModelName("haiku-4.5")).toBe("claude-haiku-4-5");
+      expect(resolveModelName("sonnet-4.6")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("opus-4.6")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("haiku-4.5")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("resolves all dash-separated version aliases", () => {
-      expect(resolveModelName("sonnet-4-6")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("opus-4-6")).toBe("claude-opus-4-6");
-      expect(resolveModelName("haiku-4-5")).toBe("claude-haiku-4-5");
+      expect(resolveModelName("sonnet-4-6")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("opus-4-6")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("haiku-4-5")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("passes through completely unknown model names unchanged", () => {
@@ -149,10 +160,10 @@ describe("chat-settings", () => {
       expect(resolveModelName("mistral-large")).toBe("mistral-large");
     });
 
-    it("passes through full claude model names unchanged (not aliases)", () => {
-      expect(resolveModelName("claude-sonnet-4-6")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("claude-opus-4-6")).toBe("claude-opus-4-6");
-      expect(resolveModelName("claude-haiku-4-5")).toBe("claude-haiku-4-5");
+    it("maps full claude compatibility aliases to the current SDK IDs", () => {
+      expect(resolveModelName("claude-sonnet-4-6")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("claude-opus-4-6")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("claude-haiku-4-5")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("preserves original casing for unknown models", () => {
@@ -171,16 +182,16 @@ describe("chat-settings", () => {
   });
 
   describe("model alias resolution (via registry)", () => {
-    it("resolves short aliases to full model IDs", () => {
-      expect(resolveModelName("sonnet")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("opus")).toBe("claude-opus-4-6");
-      expect(resolveModelName("haiku")).toBe("claude-haiku-4-5");
+    it("resolves short aliases to SDK model IDs", () => {
+      expect(resolveModelName("sonnet")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("opus")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("haiku")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("resolves versioned aliases", () => {
-      expect(resolveModelName("sonnet-4-6")).toBe("claude-sonnet-4-6");
-      expect(resolveModelName("opus-4.6")).toBe("claude-opus-4-6");
-      expect(resolveModelName("haiku-4.5")).toBe("claude-haiku-4-5");
+      expect(resolveModelName("sonnet-4-6")).toBe(SDK_MODEL_IDS.sonnet);
+      expect(resolveModelName("opus-4.6")).toBe(SDK_MODEL_IDS.opus);
+      expect(resolveModelName("haiku-4.5")).toBe(SDK_MODEL_IDS.haiku);
     });
 
     it("passes through unknown names unchanged", () => {

package/src/__tests__/claude-sdk-models.test.ts

@@ -0,0 +1,157 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mockSupportedModels = vi.fn();
+
+vi.mock("@anthropic-ai/claude-agent-sdk", () => ({
+  query: vi.fn(() => ({
+    supportedModels: mockSupportedModels,
+    [Symbol.asyncIterator]() {
+      return {
+        next: async () => ({ done: true, value: undefined }),
+      };
+    },
+  })),
+}));
+
+const sdkModels = [
+  {
+    value: "default",
+    displayName: "Default (recommended)",
+    description: "Sonnet 4.6 · Best for everyday tasks",
+  },
+  {
+    value: "sonnet[1m]",
+    displayName: "Sonnet (1M context)",
+    description:
+      "Sonnet 4.6 with 1M context · Billed as extra usage · $3/$15 per Mtok",
+  },
+  {
+    value: "opus",
+    displayName: "Opus",
+    description: "Opus 4.6 · Most capable for complex work",
+  },
+  {
+    value: "opus[1m]",
+    displayName: "Opus (1M context)",
+    description:
+      "Opus 4.6 with 1M context · Billed as extra usage · $5/$25 per Mtok",
+  },
+  {
+    value: "haiku",
+    displayName: "Haiku",
+    description: "Haiku 4.5 · Fastest for quick answers",
+  },
+  {
+    value: "claude-sonnet-4-6",
+    displayName: "Sonnet 4.6",
+    description: "claude-sonnet-4-6",
+  },
+];
+
+describe("registerClaudeModels", () => {
+  beforeEach(async () => {
+    vi.resetModules();
+    vi.clearAllMocks();
+    mockSupportedModels.mockResolvedValue(sdkModels);
+
+    const { clearModels } = await import("../core/models.js");
+    clearModels();
+  });
+
+  it("keeps SDK IDs/display names and maps 1M upgrades explicitly", async () => {
+    const { registerClaudeModels } =
+      await import("../backend/claude-sdk/models.js");
+    const {
+      get1mContextModelId,
+      getModels,
+      resolveModelId,
+      supports1mContext,
+    } = await import("../core/models.js");
+
+    await registerClaudeModels({ model: "default" });
+
+    const anthropicModels = getModels("anthropic");
+    expect(anthropicModels.map((model) => model.id)).toEqual([
+      "opus",
+      "opus[1m]",
+      "default",
+      "sonnet[1m]",
+      "haiku",
+    ]);
+
+    expect(
+      anthropicModels.find((model) => model.id === "default")?.displayName,
+    ).toBe("Default (recommended)");
+    expect(
+      anthropicModels.find((model) => model.id === "sonnet[1m]")?.displayName,
+    ).toBe("Sonnet (1M context)");
+    expect(
+      anthropicModels.some((model) => model.id === "claude-sonnet-4-6"),
+    ).toBe(false);
+
+    expect(resolveModelId("claude-sonnet-4-6")).toBe("default");
+    expect(resolveModelId("claude-sonnet-4-6[1m]")).toBe("sonnet[1m]");
+    expect(resolveModelId("claude-opus-4-6")).toBe("opus");
+
+    expect(get1mContextModelId("default")).toBe("sonnet[1m]");
+    expect(get1mContextModelId("claude-sonnet-4-6")).toBe("sonnet[1m]");
+    expect(get1mContextModelId("opus")).toBe("opus[1m]");
+    expect(get1mContextModelId("haiku")).toBeNull();
+
+    expect(supports1mContext("claude-sonnet-4-6")).toBe(true);
+    expect(supports1mContext("haiku")).toBe(false);
+  });
+
+  it("derives compatibility aliases from SDK metadata instead of hardcoded versions", async () => {
+    mockSupportedModels.mockResolvedValue([
+      {
+        value: "default",
+        displayName: "Default (recommended)",
+        description: "Sonnet 5.0 · Best for everyday tasks",
+      },
+      {
+        value: "sonnet[1m]",
+        displayName: "Sonnet (1M context)",
+        description:
+          "Sonnet 5.0 with 1M context · Billed as extra usage · $3/$15 per Mtok",
+      },
+      {
+        value: "opus",
+        displayName: "Opus",
+        description: "Opus 5.0 · Most capable for complex work",
+      },
+      {
+        value: "opus[1m]",
+        displayName: "Opus (1M context)",
+        description:
+          "Opus 5.0 with 1M context · Billed as extra usage · $5/$25 per Mtok",
+      },
+      {
+        value: "haiku",
+        displayName: "Haiku",
+        description: "Haiku 5.0 · Fastest for quick answers",
+      },
+      {
+        value: "claude-sonnet-5-0",
+        displayName: "Sonnet 5.0",
+        description: "claude-sonnet-5-0",
+      },
+    ]);
+
+    const { registerClaudeModels } =
+      await import("../backend/claude-sdk/models.js");
+    const { get1mContextModelId, resolveModelId } =
+      await import("../core/models.js");
+
+    await registerClaudeModels({ model: "default" });
+
+    expect(resolveModelId("claude-sonnet-5-0")).toBe("default");
+    expect(resolveModelId("claude-sonnet-4-6")).toBe("default");
+    expect(resolveModelId("claude-opus-5-0")).toBe("opus");
+    expect(resolveModelId("claude-opus-4-6")).toBe("opus");
+    expect(resolveModelId("claude-haiku-5-0")).toBe("haiku");
+    expect(resolveModelId("claude-haiku-4-5")).toBe("haiku");
+    expect(get1mContextModelId("claude-sonnet-4-6")).toBe("sonnet[1m]");
+    expect(get1mContextModelId("claude-sonnet-5-0")).toBe("sonnet[1m]");
+  });
+});