typeclaw 0.6.0 → 0.7.0

package/README.md

@@ -2,51 +2,48 @@
 
 > A TypeScript-native, Bun-powered, Docker-friendly general-purpose agent runtime.
 
-## Why?
-
-There are great agents out there. None of them were quite the shape I wanted:
+Full docs: **[typeclaw.dev](https://typeclaw.dev)**.
 
-- **OpenClaw** — feature-rich, but heavy
-- **NanoClaw** — simple, but no plugin system
-- **PicoClaw** — fast, but Go (so plugins live outside the runtime)
-- **ZeroClaw** — light, but Rust (same problem, different ecosystem)
-- **Hermes Agent** — awesome, but Python
+## Why?
 
-None of that matters to most people. It matters to me. If you're like me, TypeClaw is the right choice.
+There are great agents out there. None of them were quite the shape I wanted — most are written in Go, Rust, or Python, which means plugins live outside the runtime (IPC, FFI, or a separate process). The ones in TypeScript are either too heavy or too bare.
 
 TypeClaw is the agent I wanted to use:
 
 - **TypeScript end to end** — agent core, plugins, channel adapters, CLI, TUI all in one language
 - **Bun-native plugins** — plugins are just TS modules; no IPC, no FFI, hot-reloadable config
 - **Docker-friendly by default** — every agent runs in its own container; the host CLI is purely a launcher
-- **Multi-channel out of the box** — Slack, Discord, TUI, websocket — all routed through one in-process stream
 - **Self-improving** — the agent observes its own work, distills it into long-term memory and reusable skills, and gets sharper over time without you writing prompts for it
 
-## Features
+If you're like me, TypeClaw is the right choice. If not, that's fine too.
 
-- 🐳 **Sandboxed by default** — every agent runs in its own Docker container, with an `.env` and bind-mounted host folders
-- 🔌 **Plugin system** — plain TypeScript modules contribute tools, skills, subagents, channels, and typed config
-- 💬 **Multi-channel** — Slack, Discord, and a websocket TUI out of the box; one agent, many inboxes
-- 👥 **Group chat awareness** — knows who's in the room, distinguishes humans from bots, and stays engaged after a reply without re-mentioning
+## What you'd expect
+
+- 🐳 **Sandboxed by default** — every agent runs in its own Docker container with `.env` injection and bind-mounted host folders
+- 🔌 **Plugin system** — plain TypeScript modules contribute tools, skills, subagents, channels, commands, and typed config
+- 💬 **Multi-channel** — Slack, Discord, Telegram, KakaoTalk, GitHub webhooks, and a websocket TUI; one agent, many inboxes
 - ⏰ **Cron** — schedule prompts or shell commands; per-job coalescing so slow jobs don't pile up
 - 📚 **Skills on demand** — markdown procedures the agent loads only when relevant; zero token cost until used
-- 🌱 **Self-improving** — bundled memory plugin observes the agent's work and consolidates it into long-term memory (see below)
-- 🧠 **Muscle memory** — repeated procedures get distilled into reusable skills that the agent writes for itself
-- 🔄 **Hot reload** — change `typeclaw.json`, `typeclaw reload` — no restart for most fields
-- 🔁 **Self-restart** — the agent can bounce its own container when it updates itself
-- 🌐 **Auto port-forward** — dev servers inside the container appear on `localhost`, even loopback-only ones
-- 🌍 **Public tunnels** — Cloudflare Quick (zero signup) or bring-your-own external URL; the agent self-registers GitHub webhooks at the resulting public URL
-- 🎼 **Compose** — orchestrate multiple agents across multiple folders
-
-### 🌱 Self-improving, in detail
+- 🔎 **Web research** — bundled `scout` subagent plus first-class `websearch` and `webfetch` tools (DuckDuckGo via curl-impersonate, Wikipedia)
+- 🛡 **Security guards** — bundled `tool.before` policies catch secret exfil, SSRF, prompt injection, and tainted git remotes before they fire
+- 📊 **Usage and doctor** — `typeclaw usage` reports token/$ spend per session, model, or day; `typeclaw doctor` diagnoses host, agent folder, and plugin state
 
-The bundled `memory` plugin turns lived experience into reusable knowledge. No manual prompt engineering. No curated example library.
+## Where it goes further
 
-1. **Observe.** After every idle turn, a `memory-logger` subagent reads the transcript and appends notable fragments to `memory/yyyy-MM-dd.md`. Cheap, frequent, lossy by design.
-2. **Dream.** On a cron schedule (default 4am), a `dreaming` subagent consolidates daily streams into `MEMORY.md`, and — when it spots a procedure worth remembering — writes it as **muscle memory**: a new skill at `memory/skills/<name>/SKILL.md`.
-3. **Apply.** Tomorrow's prompt sees the updated `MEMORY.md`. Muscle-memory skills sit alongside bundled and user-installed ones, loaded on demand. Every dream is committed with a one-line summary — e.g. `dream: 3 fragments + new skill 'pr-review' 🔮` — so growth is auditable.
+- 🌱 **Self-improving** — bundled `memory` plugin distills sessions into long-term `MEMORY.md` without you writing prompts for it
+- 🧠 **Muscle memory** — repeated procedures get distilled into reusable skills the agent writes for itself and loads on later runs
+- 💾 **Auto-backup** — the bundled `backup` plugin commits session logs and memory on every idle window with an LLM-generated commit subject
+- 🪄 **Subagents** — first-class child sessions with their own system prompt, payload schema, and per-payload coalescing; cron and the main agent fire them through one in-process Stream
+- 🪪 **Roles and permissions** — `owner` / `trusted` / `member` / `guest` with first-message match rules per channel; gates `channel.respond`, cron scheduling, and security bypasses, so a Slack stranger can't tell the agent to push to main
+- 👥 **Group chat awareness** — knows who's in the room, distinguishes humans from bots, and stays engaged after a reply without re-mentioning
+- 🧱 **Managed-file guards** — `typeclaw.json`, `cron.json`, `MEMORY.md`, and bundled skills are protected from accidental rewrites; invalid config writes are rejected at the tool boundary
+- 🌐 **Headed browser inside the container** — bundled `agent-browser` plugin ships Chrome under Xvfb so the agent can drive real web pages past bot fingerprinting
+- 🌍 **Tunnels and auto port-forward** — dev servers inside the container appear on `localhost` (even loopback-only ones); public URLs via Cloudflare Quick (zero signup) or your own external URL, with GitHub webhooks self-registered at the resulting URL
+- 🔄 **Hot reload** — change `typeclaw.json`, run `typeclaw reload` — no restart for most fields
+- 🔁 **Self-restart** — the agent can bounce its own container when it updates itself
+- 🎼 **Compose** — orchestrate multiple agents across multiple folders
 
-See [`src/bundled-plugins/memory/README.md`](./src/bundled-plugins/memory/README.md) for the full contract.
+Memory loop and subagent architecture are covered in detail in [AGENTS.md](./AGENTS.md) and [`src/bundled-plugins/memory/README.md`](./src/bundled-plugins/memory/README.md).
 
 ## Install
 
@@ -67,59 +64,7 @@ typeclaw tui         # attach a terminal UI to the running agent
 
 That's it. The agent is now alive, listening on a websocket, ready to receive prompts from the TUI or any wired channel.
 
-## CLI
-
-| Command                             | Purpose                                                                             |
-| ----------------------------------- | ----------------------------------------------------------------------------------- |
-| `typeclaw init`                     | Scaffold a new agent folder                                                         |
-| `typeclaw start`                    | Build and run the container                                                         |
-| `typeclaw stop`                     | Stop the container                                                                  |
-| `typeclaw restart`                  | `stop` then `start`                                                                 |
-| `typeclaw status`                   | Show container + daemon registration state                                          |
-| `typeclaw logs`                     | Stream container stdout/stderr with local timestamps; `-f` to follow                |
-| `typeclaw tui`                      | Attach a terminal UI over the agent's websocket                                     |
-| `typeclaw shell`                    | Open a shell inside the running container                                           |
-| `typeclaw reload`                   | Push a live config reload to the running agent                                      |
-| `typeclaw compose`                  | Orchestrate multiple agents                                                         |
-| `typeclaw cron list`                | List every cron job registered in the running agent (user `cron.json` + plugins)    |
-| `typeclaw channel add <kind>`       | Wire a new channel adapter (Slack, Discord, Telegram, KakaoTalk, GitHub)            |
-| `typeclaw channel set <kind>`       | Rotate the credentials of an already-configured channel (bot/app tokens, PAT, etc.) |
-| `typeclaw channel reauth kakaotalk` | Re-authenticate KakaoTalk after a stale-token 401 or to rotate the stored password  |
-| `typeclaw tunnel ...`               | Add/list/status/remove public tunnels and inspect tunnel logs                       |
-
-## Configuration
-
-Agent folder layout after `init`:
-
-```
-my-agent/
-├── typeclaw.json     # main config (schema-validated)
-├── cron.json         # scheduled jobs (optional)
-├── .env              # secrets, injected via --env-file
-├── Dockerfile        # auto-managed by typeclaw, refreshed every `start`
-├── package.json      # `typeclaw` as a dependency
-├── .gitignore        # auto-managed
-├── workspace/        # agent's free-write zone (gitignored)
-├── sessions/         # JSONL session logs (gitignored, force-committed by auto-backup)
-└── memory/           # MEMORY.md + muscle-memory skills (gitignored, force-committed by dreaming)
-```
-
-`typeclaw.json` is JSON Schema–validated (see `typeclaw.schema.json`). Highlights:
-
-- `port` — preferred host port (CLI falls back to ephemeral on conflict)
-- `mounts` — host directories to expose inside the container
-- `plugins` — list of plugin module specifiers
-- `channels` — `slack-bot` / `discord-bot` config
-- `portForward` — allow/deny list for auto port forwarding (default: `*`)
-- `tunnels` — declare public URLs for inbound webhooks and ad-hoc exposure (`cloudflare-quick` or `external`)
-- `dockerfile` — toggles for `gh`, `python`, `tmux`, `ffmpeg`, `cjkFonts`, plus `append` lines
-- `memory` — idle window and dreaming schedule for the memory plugin
-
-`Dockerfile` and `.gitignore` are owned by TypeClaw and rewritten on every `start` — edit `src/init/dockerfile.ts` and re-run `start --build` to ship template changes.
-
-### Secrets
-
-Credentials live in two gitignored files: `.env` (plain `KEY=value` lines, injected into the container via `--env-file`) and `secrets.json` (a structured store managed by TypeClaw). **Env-wins**: when a credential's canonical env var (e.g. `FIREWORKS_API_KEY`, `SLACK_BOT_TOKEN`) is set, that value is used at runtime — `secrets.json` is never auto-mutated to capture it. Every secret-bearing field in `secrets.json` is a `Secret` (`string | { value?, env? }`), so the file can rebind a credential to a custom env-var name on demand. See [AGENTS.md § Secrets](./AGENTS.md#secrets) for the full contract.
+See `typeclaw --help` for the full command surface, or [typeclaw.dev](https://typeclaw.dev) for guides and configuration reference.
 
 ## Development
 
@@ -130,7 +75,7 @@ bun install
 bun test
 ```
 
-Pre-commit checks (must all pass — no exceptions):
+Pre-commit checks (all must pass — no exceptions):
 
 ```sh
 bun run typecheck
@@ -138,11 +83,12 @@ bun run lint
 bun run format
 ```
 
-See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy.
+See [AGENTS.md](./AGENTS.md) for the long-form architecture notes — stages, hostd internals, message stream, plugin contracts, and the testing philosophy. The docs site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/).
 
-## Website
+## Acknowledgments
 
-The landing page and documentation site at [typeclaw.dev](https://typeclaw.dev) lives in [`docs/`](./docs/). It's a Next.js + Fumadocs app — see [`docs/README.md`](./docs/README.md) for layout and the contributor workflow.
+- **Multi-channel** is powered by [agent-messenger](https://github.com/agent-messenger/agent-messenger) — every non-GitHub adapter (`slack-bot`, `discord-bot`, `telegram-bot`, `kakaotalk`) is built on its SDK. Thanks to the maintainers for the credential extraction, listener protocols, and platform coverage that made multi-channel a feature instead of a year-long project.
+- **Subagent architecture** is inspired by [oh-my-openagent](https://github.com/code-yeongyu/oh-my-openagent) by [@code-yeongyu](https://github.com/code-yeongyu). Thanks for the shape that made this clean.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/agent/system-prompt.ts

@@ -68,7 +68,9 @@ The bundled \`scout\` subagent is its external counterpart — web research only
 
 When the user hands you a task that will take minutes (a multi-step browser session, a long build, a complex external operation), acknowledge in plain language ("Alright, running that in the background — I'll let you know when it's done"), spawn one subagent with \`run_in_background: true\`, then KEEP TALKING. Stay available for follow-ups, related questions, parallel small tasks. When the completion reminder lands, weave the result into your next reply naturally. If the conversation has gone idle, proactively message the user with the result rather than waiting.
 
-The bundled \`operator\` subagent is the right tool for this mode. It is write-capable (read, write, edit, bash with side effects) and runs on the default model. Use it for: browser sessions, multi-file refactors, deploys, anything that involves taking action on behalf of the user over multiple steps. The operator returns a structured final report (outcome, what changed, what was observed); surface it naturally rather than copy-pasting. Operator is gated by a separate permission (\`subagent.spawn.operator\`) so write-capable spawns are restricted to owner-tier and trusted-tier callers — if the gate denies, fall back to doing the work in your own session rather than reporting failure to the user.
+Before you start an inline operation you expect to take more than ~30 seconds — a chain of \`webfetch\` calls, a \`websearch\` round you'll iterate on, a \`bash\` command that hits a slow API or scrapes a site, an \`agent-browser\` session, any "fetch N things in a loop" — pause and ask whether a subagent should run it instead. Inline long calls block the user from talking to you and pollute your context window with intermediate output; \`scout\` (for research) or \`operator\` (for actions with side effects) keeps the conversation responsive and returns a clean summary. The exception is a single quick call (one \`webfetch\` of a known URL, one \`websearch\` query you already know the shape of) — do those inline.
+
+The bundled \`operator\` subagent is the right tool for this mode. It is write-capable (read, write, edit, bash with side effects) and runs on the default model. Use it for: browser sessions, multi-file refactors, deploys, batch API calls, anything that involves taking action on behalf of the user over multiple steps. The operator returns a structured final report (outcome, what changed, what was observed); surface it naturally rather than copy-pasting. Operator is gated by a separate permission (\`subagent.spawn.operator\`) so write-capable spawns are restricted to owner-tier and trusted-tier callers — if the gate denies, fall back to doing the work in your own session rather than reporting failure to the user.
 
 **Status queries**
 

package/src/cli/init.ts

@@ -374,7 +374,14 @@ export const defaultWizardPrompts: WizardPrompts = {
   hasExistingChannelSecrets,
   askReuseExistingChannel,
   runChannelFlow,
-  runOAuthLogin: (provider, cwd, model) => makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))({ cwd, model }),
+  runOAuthLogin: async (provider, cwd, model) => {
+    const { callbacks, dispose } = buildOAuthCallbacks(provider.name)
+    try {
+      return await makeOAuthLoginRunner(callbacks)({ cwd, model })
+    } finally {
+      dispose()
+    }
+  },
   askOAuthFailureRecovery,
 }
 

package/src/cli/oauth-callbacks.ts

@@ -9,41 +9,71 @@ import type { OAuthCallbacks } from '@/init/oauth-login'
 // concurrent `onManualCodeInput` prompt for users whose browser is on a
 // different host than the CLI. See src/init/oauth-login.ts for the contract
 // on each callback and why onManualCodeInput is required for cross-device.
-export function buildOAuthCallbacks(providerName: string): OAuthCallbacks {
+//
+// Returns `{ callbacks, dispose }` rather than bare callbacks because of a
+// pi-ai contract gap: pi-ai races `onManualCodeInput()` against the local
+// callback server (packages/ai/src/utils/oauth/anthropic.ts:210-253). When
+// the browser wins the race, pi-ai sets `result.code` and falls through to
+// token exchange WITHOUT calling `server.cancelWait()` on the manual side —
+// the manual `text()` prompt is left dangling in clack's render pipeline,
+// re-appearing after every subsequent log line. Without the dispose hook,
+// the user sees "Logged in to {Provider}" immediately followed by the stale
+// "paste the redirect URL here" prompt that's now meaningless. Each call
+// site (init/provider) MUST call `dispose()` in a finally after the OAuth
+// runner returns so the orphaned prompt aborts cleanly; clack honors the
+// signal by resolving the prompt with cancel state, the cancel branch
+// throws inside our callback, and pi-ai's outer `.catch()` swallows it
+// (since it stops awaiting the manual promise on the winning-browser path).
+export type OAuthCallbackHandle = {
+  callbacks: OAuthCallbacks
+  dispose: () => void
+}
+
+export function buildOAuthCallbacks(providerName: string): OAuthCallbackHandle {
+  const controller = new AbortController()
+  const { signal } = controller
   return {
-    onAuth: (url, instructions) => {
-      // Don't put the URL inside note(): clack wraps long lines with the box
-      // border `│` on each wrapped segment, which corrupts the URL when the
-      // user copy-pastes it. Keep instructional text in the box, but print
-      // the URL itself as a bare console.log line that any terminal will
-      // hyperlink intact.
-      const preamble = [
-        `Open this URL in your browser to sign in to ${providerName}.`,
-        '',
-        'If your browser shows "this site can\'t be reached" after you sign in,',
-        'copy the full address from the top of the browser and paste it below.',
-      ]
-      if (instructions) preamble.push('', instructions)
-      note(preamble.join('\n'), 'Browser login')
-      console.log(url)
-      console.log('')
-    },
-    onProgress: (message) => {
-      log.info(message)
-    },
-    onPrompt: async (message, placeholder) => {
-      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
-      if (isCancel(value)) return null
-      return value
-    },
-    onManualCodeInput: async () => {
-      const value = await text({
-        message:
-          'If your browser shows "this site can\'t be reached" after you sign in, copy the full address from the top of the browser and paste it here:',
-        placeholder: 'http://localhost:1455/auth/callback?code=...&state=...',
-      })
-      if (isCancel(value)) throw new Error('Login cancelled by user')
-      return value
+    dispose: () => controller.abort(),
+    callbacks: {
+      onAuth: (url, instructions) => {
+        // Don't put the URL inside note(): clack wraps long lines with the box
+        // border `│` on each wrapped segment, which corrupts the URL when the
+        // user copy-pastes it. Keep instructional text in the box, but print
+        // the URL itself as a bare console.log line that any terminal will
+        // hyperlink intact.
+        const preamble = [
+          `Open this URL in your browser to sign in to ${providerName}.`,
+          '',
+          'If your browser shows "this site can\'t be reached" after you sign in,',
+          'copy the full address from the top of the browser and paste it below.',
+        ]
+        if (instructions) preamble.push('', instructions)
+        note(preamble.join('\n'), 'Browser login')
+        console.log(url)
+        console.log('')
+      },
+      onProgress: (message) => {
+        log.info(message)
+      },
+      onPrompt: async (message, placeholder) => {
+        const value = await text({
+          message,
+          signal,
+          ...(placeholder !== undefined ? { placeholder } : {}),
+        })
+        if (isCancel(value)) return null
+        return value
+      },
+      onManualCodeInput: async () => {
+        const value = await text({
+          message:
+            'If your browser shows "this site can\'t be reached" after you sign in, copy the full address from the top of the browser and paste it here:',
+          placeholder: 'http://localhost:1455/auth/callback?code=...&state=...',
+          signal,
+        })
+        if (isCancel(value)) throw new Error('Login cancelled by user')
+        return value
+      },
     },
   }
 }

package/src/cli/provider.ts

@@ -367,10 +367,15 @@ async function runOAuthLogin(cwd: string, providerId: KnownProviderId): Promise<
   }
   const modelRef = `${providerId}/${ref}` as const
 
-  const runner = makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))
-  const result = await runner({ cwd, model: modelRef as Parameters<typeof runner>[0]['model'] })
-  if (!result.ok) return { ok: false, reason: result.reason }
-  return { ok: true }
+  const { callbacks, dispose } = buildOAuthCallbacks(provider.name)
+  try {
+    const runner = makeOAuthLoginRunner(callbacks)
+    const result = await runner({ cwd, model: modelRef as Parameters<typeof runner>[0]['model'] })
+    if (!result.ok) return { ok: false, reason: result.reason }
+    return { ok: true }
+  } finally {
+    dispose()
+  }
 }
 
 function authHint(id: KnownProviderId): string {

package/src/config/config.ts

@@ -420,15 +420,39 @@ export function expandMountPath(input: string, cwd: string): string {
 
 // Loaded eagerly from process.cwd()/typeclaw.json at module-import time so
 // citty arg defaults (e.g. config.port in src/cli/*.ts) see real values, not
-// hardcoded fallbacks. Missing file → schema defaults; malformed file → throw,
-// which surfaces during CLI startup instead of silently reverting to defaults
-// and confusing the user.
+// hardcoded fallbacks. Missing file → schema defaults; malformed file → ALSO
+// schema defaults plus a stderr warning.
+//
+// Why soft-fail and not throw: every CLI command — including diagnostic ones
+// (`typeclaw status`, `typeclaw doctor`, `typeclaw logs`, `typeclaw stop`,
+// `typeclaw usage`, `typeclaw tui`) — pays this eager-load cost through its
+// import graph, regardless of whether the command actually reads config. A
+// hard throw here turns every read-only diagnostic into a crash exactly when
+// the user needs the diagnostic to figure out what's wrong with their config.
+// `validateConfig` (called by `start`/`restart`/`reload`/host-side mutations)
+// is the strict gate for destructive paths; that's where malformed-config
+// errors should surface, not at module-import time.
 //
 // `config` is a module-import-time snapshot. Container-stage code that must
 // observe `typeclaw run` reloads should call `getConfig()` instead, which
 // returns the current swapped-in value. Host-stage CLI processes are
 // short-lived, so they keep using `config` directly.
-export const config: Config = loadConfigSync(process.cwd())
+export const config: Config = loadConfigSyncOrDefaults(process.cwd())
+
+export function loadConfigSyncOrDefaults(cwd: string, options: { warn?: (message: string) => void } = {}): Config {
+  try {
+    return loadConfigSync(cwd)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    const warn = options.warn ?? ((message: string) => process.stderr.write(message))
+    warn(
+      `warning: ${detail}\n` +
+        `warning: continuing with default config so diagnostic commands still work; ` +
+        `run \`typeclaw doctor\` or fix ${CONFIG_FILE} before \`typeclaw start\`/\`restart\`/\`reload\`.\n`,
+    )
+    return configSchema.parse({})
+  }
+}
 
 let current: Config = config
 

package/src/config/providers.ts

@@ -108,6 +108,112 @@ export const KNOWN_PROVIDERS = {
       },
     },
   },
+  // Anthropic Claude — both the Anthropic Console API (ANTHROPIC_API_KEY)
+  // and Claude Pro/Max/Team/Enterprise subscriptions (OAuth) reach the same
+  // /v1/messages endpoint and share one provider id. Auth path determines
+  // which headers pi-ai's `anthropic-messages` transport injects: API key
+  // sends a plain `x-api-key`; OAuth sends Bearer + Claude Code identity
+  // (anthropic-beta: claude-code-20250219,oauth-2025-04-20 +
+  // user-agent: claude-cli/<version>), which is exactly the surface a
+  // subscriber's `claude setup-token` credential authorizes. The OAuth dance
+  // itself is authorization-code + PKCE against `claude.ai/oauth/authorize`
+  // with a localhost callback server (not device-code); the existing
+  // `typeclaw-claude-code` skill documents the user-side flow for getting
+  // a subscription credential onto the agent when the in-container browser
+  // callback can't reach the user's machine.
+  //
+  // anthropic is the FIRST provider in the registry where both auth modes
+  // coexist on one entry. The runtime in src/agent/auth.ts has a load-bearing
+  // resolution rule: when secrets.json#providers.anthropic carries an OAuth
+  // credential, `ANTHROPIC_API_KEY` in .env is IGNORED (OAuth-on-disk wins
+  // because env-wins only applies to api-key-shaped credentials). For
+  // api-key-only providers this is invisible; for anthropic it surfaces as
+  // "I added the env var but the agent still uses OAuth." The mitigation is
+  // to remove the OAuth credential explicitly (`typeclaw provider remove
+  // anthropic`) before relying on the env-var path. Same rule applies to any
+  // future dual-auth provider — keep the surprise in mind when expanding.
+  //
+  // Model lineup is the current GA tier as of 2026-04-16: Opus 4.7 (top,
+  // released Apr 16 2026), Sonnet 4.6 (mid, Feb 5 2026), Haiku 4.5 (fast,
+  // Oct 1 2025). Anthropic's own model overview lists these three as the
+  // current recommended set and flags earlier Opus/Sonnet variants with
+  // "Consider migrating to current models." Opus 4 / Sonnet 4 are deprecated
+  // (retirement: Jun 15 2026); the 4.5/4.6 alternates remain Active but are
+  // not the recommended path.
+  //
+  // ID semantics differ across the lineup and matter for forward-compat:
+  //   - `claude-haiku-4-5` is a 4.5-generation CONVENIENCE ALIAS that
+  //     resolves to the latest dated snapshot (currently `-20251001`). Per
+  //     Anthropic's model-id docs, pre-4.6 dateless ids are evergreen
+  //     pointers — Anthropic can ship a new dated snapshot under the same
+  //     alias and we pick it up automatically.
+  //   - `claude-sonnet-4-6` and `claude-opus-4-7` are 4.6+-generation PINNED
+  //     SNAPSHOTS, not aliases. Anthropic explicitly says "the dateless ID is
+  //     the canonical model ID for that release. It maps to a single, fixed
+  //     model snapshot." A future Sonnet 4.6.1 (if it ever exists) would ship
+  //     under a new id, NOT silently replace `claude-sonnet-4-6`.
+  // Consequence for refresh discipline: bumping Haiku is a no-op (alias
+  // catches the latest); bumping Sonnet/Opus to a future 4.7+ family is a
+  // real edit here. Don't assume `claude-opus-4-7` will silently advance.
+  //
+  // Opus 4.7 specifics that affect cost accounting:
+  //   - New tokenizer: same input maps to 1.0-1.3x more tokens than prior
+  //     generations depending on content type. Per-token price is unchanged
+  //     vs Opus 4.6, but total cost on identical workloads can rise meaningfully.
+  //   - 1M token context window (vs 200k on Haiku) and 128k max output (vs
+  //     64k on Sonnet/Haiku). 1M context is at standard pricing — no surcharge.
+  //   - New `xhigh` effort level between `high` and `max` (pi-ai 0.67.x may
+  //     not surface this knob yet; check before relying on it).
+  //
+  // Pricing mirrors Anthropic's official table as of 2026-05; cacheWrite is
+  // the 5m-TTL rate (1.25x input). 1h TTL is ~2x input (not modeled here —
+  // pi-ai's `cacheWrite` field captures the default 5m rate only).
+  anthropic: {
+    id: 'anthropic',
+    name: 'Anthropic',
+    baseUrl: 'https://api.anthropic.com',
+    auth: ['api-key', 'oauth'],
+    apiKeyEnv: 'ANTHROPIC_API_KEY',
+    oauthProviderId: 'anthropic',
+    models: {
+      'claude-haiku-4-5': {
+        id: 'claude-haiku-4-5',
+        name: 'Claude Haiku 4.5',
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        baseUrl: 'https://api.anthropic.com',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+        contextWindow: 200000,
+        maxTokens: 64000,
+      },
+      'claude-sonnet-4-6': {
+        id: 'claude-sonnet-4-6',
+        name: 'Claude Sonnet 4.6',
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        baseUrl: 'https://api.anthropic.com',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+        contextWindow: 1000000,
+        maxTokens: 64000,
+      },
+      'claude-opus-4-7': {
+        id: 'claude-opus-4-7',
+        name: 'Claude Opus 4.7',
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        baseUrl: 'https://api.anthropic.com',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+        contextWindow: 1000000,
+        maxTokens: 128000,
+      },
+    },
+  },
   // ChatGPT Plus/Pro subscription via the OAuth Codex backend. No API key
   // path here on purpose — the Codex backend is OAuth-only upstream.
   //

package/src/init/models-dev.ts

@@ -13,6 +13,7 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
   // (Codex is a backend, not a separate provider in their taxonomy). Curated
   // entries are surfaced regardless of upstream membership.
   'openai-codex': 'openai',
+  anthropic: 'anthropic',
   fireworks: 'fireworks-ai',
   zai: 'zai',
   // zai-coding (GLM Coding Plan) is a billing surface, not a separate model

package/typeclaw.schema.json

@@ -26,6 +26,9 @@
               "openai/gpt-5.4-mini",
               "openai/gpt-5.4",
               "openai/gpt-5.5",
+              "anthropic/claude-haiku-4-5",
+              "anthropic/claude-sonnet-4-6",
+              "anthropic/claude-opus-4-7",
               "openai-codex/gpt-5.4-mini",
               "openai-codex/gpt-5.4",
               "openai-codex/gpt-5.5",
@@ -50,6 +53,9 @@
                 "openai/gpt-5.4-mini",
                 "openai/gpt-5.4",
                 "openai/gpt-5.5",
+                "anthropic/claude-haiku-4-5",
+                "anthropic/claude-sonnet-4-6",
+                "anthropic/claude-opus-4-7",
                 "openai-codex/gpt-5.4-mini",
                 "openai-codex/gpt-5.4",
                 "openai-codex/gpt-5.5",