typeclaw 0.5.1 → 0.7.0

package/src/bundled-plugins/operator/operator.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod'
+
+import { bashTool, editTool, findTool, grepTool, lsTool, readTool, type Subagent, writeTool } from '@/plugin'
+
+export const OPERATOR_SYSTEM_PROMPT = `You are an operator subagent running inside TypeClaw. Your job: execute a multi-step task on behalf of the main agent and report what happened.
+
+## Your context
+
+- You were spawned by the main agent for one focused task.
+- The parent agent is still in conversation with the user; you are NOT.
+- The parent will receive a single \`<system-reminder>\` when you complete and will then call \`subagent_output\` to read your final assistant message.
+- Your final message is the WHOLE report. There is no follow-up channel. Make it complete, self-contained, and actionable.
+
+## What you can do
+
+You have a full tool set: read, write, edit, grep, find, ls, bash. You can:
+- Modify files (write/edit)
+- Run shell commands with side effects (bash without the read-only restriction)
+- Use any tool available to a normal operator session
+
+You CANNOT:
+- Spawn further subagents (you are at the end of the delegation chain).
+- Talk to the user directly (the parent owns the conversation).
+- Use channel_send, channel_reply, or any channel tool.
+
+## How to work
+
+1. **Plan briefly.** If the task has multiple steps, write a one-paragraph plan to yourself before acting. Don't over-plan — start doing.
+2. **Verify after each significant step.** A build command's exit code, a test run's pass/fail count, a file's actual contents after editing — these are the signals you act on.
+3. **Recover from failures.** If something fails (network blip, build error, test failure caused by an edit you made), fix it and continue. Only escalate to the parent if you genuinely cannot proceed.
+4. **Commit your changes** if the task involved file edits and the project's git history shows the agent commits its work. Read AGENTS.md if present to learn the project's commit conventions.
+
+## Final report
+
+Your final assistant message MUST contain:
+
+1. **Outcome.** One sentence: succeeded / partially succeeded / failed.
+2. **What you did.** Bullet list of the load-bearing actions taken (files edited, commands run, external services called). Skip trivial reads.
+3. **What changed.** If you edited files, list paths. If you committed, give the commit SHA. If you ran a deploy, give the deploy id.
+4. **What you observed.** Any noteworthy errors, warnings, unexpected state. The parent needs to know what to follow up on.
+5. **What's next.** Only if there are concrete open items. Don't pad with "let me know if you need more" — the parent will ask.
+
+Skip the report's section headers when the task was trivial (one file edit, ran one command) — a clean two-sentence summary is fine. Use the full structure for substantial work.
+
+## Rules
+
+- Stay on the task you were given. Do not expand scope.
+- Do NOT leave the workspace in a broken state. If a fix fails, revert your changes before reporting.
+- Do NOT commit secrets. \`.env\` and \`secrets.json\` are gitignored — read AGENTS.md for the full secret-handling contract before touching anything credential-shaped.
+- If the task seems wrong (asks you to delete production data, modify a file you cannot find, run a command that doesn't apply to this repo), report the issue rather than improvising.`
+
+export const operatorPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type OperatorPayload = z.infer<typeof operatorPayloadSchema>
+
+export function createOperatorSubagent(): Subagent<OperatorPayload> {
+  return {
+    systemPrompt: OPERATOR_SYSTEM_PROMPT,
+    profile: 'default',
+    tools: [readTool, grepTool, findTool, lsTool, bashTool, writeTool, editTool],
+    payloadSchema: operatorPayloadSchema,
+    visibility: 'public',
+    requiresSpecificPermission: true,
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      maxTotalBytes: 1_000_000,
+      toolNames: ['read', 'grep', 'find', 'ls', 'bash', 'write', 'edit'],
+    },
+  }
+}

package/src/bundled-plugins/scout/index.ts

@@ -0,0 +1,11 @@
+import { definePlugin } from '@/plugin'
+
+import { createScoutSubagent } from './scout'
+
+export default definePlugin({
+  plugin: async () => ({
+    subagents: {
+      scout: createScoutSubagent(),
+    },
+  }),
+})

package/src/bundled-plugins/scout/scout.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod'
+
+import { type Subagent, webfetchTool, websearchTool } from '@/plugin'
+
+export const SCOUT_SYSTEM_PROMPT = `You are a web-research specialist running inside TypeClaw. Your job: gather facts from the public internet and return a focused, citation-backed answer to the caller. For LOCAL questions (codebase, sessions, memory, config, git history, mounts), the caller should spawn \`explorer\` instead — you have no filesystem tools.
+
+=== READ-ONLY — NO SIDE EFFECTS ===
+You are STRICTLY PROHIBITED from:
+- Modifying local files or state of any kind
+- Spawning further subagents — you are at the end of the delegation chain
+- Posting to any channel, sending email, calling any write-side third-party API
+- Following URLs that look like authenticated callbacks, password resets, or one-time tokens
+
+Your role is EXCLUSIVELY to search and read public web sources.
+
+## Tools
+
+The runtime exposes these tools to you by these EXACT names — call them by name, do not paraphrase:
+
+- \`websearch\` — search the public web. Returns ranked \`{title, url, snippet}\` entries. Defaults to DuckDuckGo; pass \`source: "wikipedia"\` for encyclopedic lookups.
+- \`webfetch\` — fetch a single HTTP(S) URL and return the body, optionally compacted by a strategy:
+  - \`readability\` (default for HTML) — extract article content as markdown
+  - \`jq\` — query JSON APIs (pass \`query\`)
+  - \`selector\` — extract text from CSS-selected elements (pass \`selector\`)
+  - \`grep\` — filter response lines by regex (pass \`pattern\`, optional \`before\`/\`after\`/\`limit\`/\`offset\`)
+  - \`snapshot\` — indented semantic tree of the page (forms, headings, links)
+  - \`raw\` — no processing
+
+Launch multiple \`websearch\` queries in parallel for the same topic — different phrasings surface different sources. When a search result looks promising, \`webfetch\` it for the full content.
+
+## Process
+
+Before searching, analyze intent in an <analysis> block:
+
+<analysis>
+**Literal Request**: [what they literally asked]
+**Actual Need**: [what they're really trying to accomplish]
+**Success Looks Like**: [what result lets them proceed immediately]
+**Search Plan**: [the 2-3 queries you will try in parallel]
+</analysis>
+
+Then run searches, fetch the most relevant URLs, and synthesize.
+
+End every response with this exact structure:
+
+<results>
+<sources>
+- https://example.com/path — [what this source contributed]
+</sources>
+<answer>
+[Direct answer to the actual need, grounded in the cited sources. Quote short passages when precision matters. If sources disagree, say so and surface both.]
+</answer>
+<confidence>
+[high / medium / low — with one sentence on why. Low confidence is fine and useful; speculation dressed up as high confidence is not.]
+</confidence>
+<next_steps>
+[What the caller should do next, or "Ready to proceed."]
+</next_steps>
+</results>
+
+## Rules
+
+- Cite every claim with a URL from your <sources> list. **Never invent a URL.** If you didn't \`webfetch\` it, don't cite it.
+- If a fact appears only in your training data and you couldn't find a web source for it, say so explicitly rather than answering from memory.
+- Prefer primary sources (official docs, vendor changelogs, GitHub releases, paper PDFs) over aggregator blogs.
+- When dates matter (versions, deprecations, vulnerability disclosures), surface the date of the source.
+- If DuckDuckGo returns a CAPTCHA error, retry once with a different query phrasing; if it persists, report the failure to the caller — do not fall back to memory.
+- If the question requires LOCAL information (codebase, files in /agent/, git history, memory), say so explicitly and tell the caller to spawn \`explorer\` instead.
+- If you cannot find what was asked, say so explicitly with what queries you tried and what you DID find.`
+
+export const scoutPayloadSchema = z
+  .object({
+    requestId: z.string().optional(),
+    prompt: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough()
+
+export type ScoutPayload = z.infer<typeof scoutPayloadSchema>
+
+export function createScoutSubagent(): Subagent<ScoutPayload> {
+  return {
+    systemPrompt: SCOUT_SYSTEM_PROMPT,
+    profile: 'fast',
+    tools: [websearchTool, webfetchTool],
+    payloadSchema: scoutPayloadSchema,
+    visibility: 'public',
+    inFlightKey: (payload) => payload?.requestId ?? `anon-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+    toolResultBudget: {
+      maxTotalBytes: 512_000,
+      toolNames: ['websearch', 'webfetch'],
+    },
+  }
+}

package/src/channels/router.ts

@@ -1613,6 +1613,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       return
     }
 
+    if (isUpstreamEmptyResponseSentinel(assistantText)) {
+      logger.warn(
+        `[channels] ${live.keyId}: suppressed upstream_empty_response_sentinel text_len=${assistantText.length}`,
+      )
+      return
+    }
+
     logger.warn(
       `[channels] ${live.keyId}: recovering assistant_text_without_channel_tool text_len=${assistantText.length}`,
     )
@@ -2000,6 +2007,31 @@ export function isNoReplySignal(text: string): boolean {
   return false
 }
 
+// Detects the upstream "empty response" debug sentinel: when the LLM ends a
+// turn with only a `thinking` block, some provider SDK paths (observed
+// against claude-opus-4-5 via pi-ai) fabricate a single text block whose
+// body is a Python-repr dump of the raw API response — including the
+// model's thinking content and Anthropic's tamper-proof signature. The
+// recovery path in validateChannelTurn would otherwise post that sentinel
+// straight to the channel (production: signature leaked into a public
+// Slack channel on 2026-05-21).
+//
+// Kept separate from isNoReplySignal on purpose: that helper is the agent's
+// deliberate silent-turn protocol, this is upstream damage control. They
+// log under distinct subjects (`upstream_empty_response_sentinel` vs
+// `no_reply`) so an operator can tell a healthy quiet turn from a stream of
+// upstream empties that warrant investigation.
+//
+// Strict detection: leading `(Empty response:` AND a dict-encoded
+// `'stop_reason'` key. Catches the observed shape
+// `(Empty response: {'content': [...], 'stop_reason': 'end_turn', ...})`
+// while allowing legit prose like "Empty response from the cache layer".
+export function isUpstreamEmptyResponseSentinel(text: string): boolean {
+  const trimmed = text.trim()
+  if (!trimmed.startsWith('(Empty response:')) return false
+  return trimmed.includes("'stop_reason'")
+}
+
 function describe(err: unknown): string {
   return err instanceof Error ? err.message : String(err)
 }

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

@@ -116,6 +116,11 @@ const dockerfileObjectSchema = z.object({
   // because the package has no API-stable versioning that matters
   // here; xvfb tracks the upstream X server release.
   xvfb: z.boolean().default(true),
+  // `claudeCode` is boolean-only (not an apt feature toggle): the upstream
+  // installer is `curl | bash` and manages versions via env vars at install
+  // time, not via version pins like apt. Default `false`; the bundled
+  // `typeclaw-claude-code` skill prompts the user to opt in.
+  claudeCode: z.boolean().default(false),
   append: z.array(dockerfileLineSchema).default([]),
 })
 
@@ -415,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
 
@@ -1008,6 +1037,39 @@ export function validateConfig(cwd: string, options: ValidateConfigOptions = {})
     return { ok: true }
   }
 
+  const parsed = parseConfigJson(raw, { migrate: true, persistTarget: cwd })
+  if (!parsed.ok) return parsed
+
+  if (!options.skipMounts) {
+    for (const mount of parsed.config.mounts) {
+      const check = validateMount(mount, cwd)
+      if (!check.ok) return check
+    }
+  }
+
+  return { ok: true }
+}
+
+export type ParseConfigJsonResult = { ok: true; config: Config } | { ok: false; reason: string }
+
+export type ParseConfigJsonOptions = {
+  // Run `migrateLegacyConfigShape` before schema validation. Defaults to true
+  // so callers don't reject content the agent could have written through
+  // legacy keys; pass false to validate the exact bytes (used in tests).
+  migrate?: boolean
+  // When set, persist + commit the migrated shape to this agent dir if the
+  // migration ran. Only `validateConfig` uses this; the guard's in-memory
+  // validation never persists (the bytes aren't yet on disk).
+  persistTarget?: string
+}
+
+// Pure validator for an in-memory `typeclaw.json` string. Used by the
+// managed-config guard to reject `write`/`edit` calls that would land an
+// invalid file on disk. Does NOT check mount accessibility — that is the
+// runtime concern handled by `validateConfig` at `typeclaw start` time, and
+// the file the agent is producing may legitimately reference a mount path
+// that only exists on the host outside the container.
+export function parseConfigJson(raw: string, options: ParseConfigJsonOptions = {}): ParseConfigJsonResult {
   let json: unknown
   try {
     json = JSON.parse(raw)
@@ -1016,24 +1078,19 @@ export function validateConfig(cwd: string, options: ValidateConfigOptions = {})
     return { ok: false, reason: `${CONFIG_FILE} is not valid JSON: ${detail}` }
   }
 
-  const migrated = migrateLegacyConfigShape(json)
-  if (migrated.changed) {
-    persistMigratedConfig(cwd, migrated.json, migrated.applied)
+  const shouldMigrate = options.migrate ?? true
+  const migrated = shouldMigrate
+    ? migrateLegacyConfigShape(json)
+    : { json, changed: false, applied: [] as MigrationStep[] }
+  if (migrated.changed && options.persistTarget !== undefined) {
+    persistMigratedConfig(options.persistTarget, migrated.json, migrated.applied)
   }
 
   const result = configSchema.safeParse(migrated.json)
   if (!result.success) {
     return { ok: false, reason: `${CONFIG_FILE} is invalid: ${formatZodError(result.error)}` }
   }
-
-  if (!options.skipMounts) {
-    for (const mount of result.data.mounts) {
-      const check = validateMount(mount, cwd)
-      if (!check.ok) return check
-    }
-  }
-
-  return { ok: true }
+  return { ok: true, config: result.data }
 }
 
 // Verifies a mount's host path: exists, is a directory, is readable, and is

package/src/config/index.ts

@@ -14,6 +14,7 @@ export {
   migrateLegacyConfigShape,
   modelsSchema,
   mountSchema,
+  parseConfigJson,
   portForwardSchema,
   reloadConfig,
   resolveModel,
@@ -31,6 +32,8 @@ export {
   type MigrationStep,
   type Models,
   type Mount,
+  type ParseConfigJsonOptions,
+  type ParseConfigJsonResult,
   type PortForward,
   type ResolvedProfile,
   type ValidateConfigResult,

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/cron/index.ts

@@ -41,6 +41,9 @@ export {
   type ExecJob,
   type HandlerJob,
   migrateLegacyCronShape,
+  parseCronJson,
+  type ParseCronJsonOptions,
+  type ParseCronResult,
   type ParsedCronJob,
   type PromptJob,
 } from './schema'