typeclaw 0.4.0 → 0.5.1

package/src/config/config.ts

@@ -103,6 +103,19 @@ const dockerfileObjectSchema = z.object({
   // edit. Opt-out with `cloudflared: false` to skip the ~35MB binary on
   // agents that don't use tunnels.
   cloudflared: z.boolean().default(true),
+  // Install xvfb so the entrypoint shim can spawn an Xvfb virtual X
+  // server and export DISPLAY, giving headed Chrome (agent-browser
+  // --headed, Playwright headful) a real X11 display to connect to.
+  // Default `true` because modern bot detection (Akamai/Cloudflare Bot
+  // Manager) fingerprints `--headless` and `--headless=new` regardless
+  // of UA spoof, and headed-via-Xvfb is the cheapest path to a passing
+  // fingerprint from a container. Opt-out with `xvfb: false` to save
+  // ~5MB image + ~10MB RAM/idle on agents that never touch a browser.
+  // The shim self-heals — when Xvfb isn't on PATH it execs the agent
+  // directly, no other Dockerfile or shim change needed. Boolean-only
+  // because the package has no API-stable versioning that matters
+  // here; xvfb tracks the upstream X server release.
+  xvfb: z.boolean().default(true),
   append: z.array(dockerfileLineSchema).default([]),
 })
 
@@ -278,32 +291,50 @@ const tunnelsArraySchema = z
     }
   })
 
-// `models` is a map from profile name to a single curated model ref. The
+// `models` maps a profile name to one or more curated model refs. The
 // `default` profile is mandatory; every other profile is optional and falls
 // back to `default` at resolution time (see `resolveProfile`).
 //
+// Each value is either a single `KnownModelRef` or a non-empty array of refs
+// forming a fallback chain: when a turn against the first ref fails (hard
+// throw or a soft provider error), the runtime disposes the failed session
+// and replays the same prompt against the next ref. Schema accepts both
+// shapes for ergonomics; the parsed value is always normalised to a
+// non-empty array so downstream consumers read a uniform `KnownModelRef[]`.
+//
 // Profile names are open strings; the runtime recognizes a handful of
 // well-known names by convention (`default`, `fast`, `deep`, `vision`) but
-// any string is valid. Subagents may declare a static profile preference;
-// callers may override per-spawn. Unknown profile names resolve to `default`
-// with a one-time warning at session construction.
+// any string is valid. Unknown profile names resolve to `default` with a
+// one-time warning at session construction.
 //
 // The pre-multi-model schema had a single `model: KnownModelRef` at the top
 // level. `migrateLegacyConfigShape` rewrites that to `models: { default: ... }`
 // on first load (and writes the result back to disk + commits via
 // `persistMigratedConfig`), so every downstream consumer sees the new shape.
+const modelRefOrChainSchema = z
+  .union([
+    z.enum(knownModelRefs),
+    z
+      .array(z.enum(knownModelRefs))
+      .min(1)
+      // Reject exact duplicates in a chain — retrying the same ref after the
+      // same class of failure is almost certainly a config typo, and silently
+      // deduping would mask user intent. Different models from the same
+      // provider (e.g. `["openai/gpt-5.4-nano", "openai/gpt-5.4-mini"]`) are
+      // still valid because they hit distinct upstream endpoints.
+      .refine((arr) => new Set(arr).size === arr.length, {
+        message: 'models chain must not contain duplicate refs',
+      }),
+  ])
+  .transform((value) => (Array.isArray(value) ? value : [value]))
 export const modelsSchema = z
-  .record(z.string().min(1), z.enum(knownModelRefs))
+  .record(z.string().min(1), modelRefOrChainSchema)
   .refine((m) => 'default' in m, { message: 'models.default is required' })
 
-// Zod's `z.record(..., refine)` doesn't refine the inferred type — the inferred
-// shape is `Record<string, KnownModelRef>` where every access is `T | undefined`.
-// The runtime guarantee (the `refine` above) is that `default` is present, so
-// we narrow the type here. Every consumer (auth.ts, agent/index.ts,
-// resolveProfile) reads `models.default` on the hot path; without this
-// narrowing they all have to assert or `?? throw`, which is noise around an
-// invariant the schema already enforces.
-export type Models = Record<string, KnownModelRef> & { default: KnownModelRef }
+// Zod's `z.record(..., refine)` doesn't refine the inferred type. The
+// `default` key is schema-enforced, so we narrow it here to spare every
+// consumer the `T | undefined` assertion noise.
+export type Models = Record<string, KnownModelRef[]> & { default: KnownModelRef[] }
 
 export const configSchema = z
   .object({
@@ -311,8 +342,10 @@ export const configSchema = z
     port: z.number().int().min(1).max(65535).default(DEFAULT_PORT),
     // `default(() => ...)` ensures every parsed config has at least
     // `models.default`. Direct `.default({ default: ... })` would short-circuit
-    // the refinement, so we lean on the lazy thunk form.
-    models: modelsSchema.default(() => ({ default: DEFAULT_MODEL_REF })) as unknown as z.ZodType<Models>,
+    // the refinement, so we lean on the lazy thunk form. The default value is
+    // shaped to match the post-transform output (always `KnownModelRef[]`),
+    // not the user-facing input shape.
+    models: modelsSchema.default(() => ({ default: [DEFAULT_MODEL_REF] })) as unknown as z.ZodType<Models>,
     // Defaults to `[]` so the field can be omitted from `typeclaw.json` (no
     // host paths exposed) without failing the whole config load. `typeclaw
     // init` omits this field so users don't see noise for the empty case.
@@ -345,26 +378,28 @@ export function resolveModel(ref: KnownModelRef): Model<'openai-completions'> |
   return KNOWN_PROVIDERS[providerId].models[modelId as never]
 }
 
-// Resolves a profile name (e.g. `fast`, `deep`, `vision`) to a concrete model
-// ref. Unknown profiles fall back to `default` so callers can pass through
+// Resolves a profile name (e.g. `fast`, `deep`, `vision`) to its fallback
+// chain. Unknown profiles fall back to `default` so callers can pass through
 // arbitrary subagent-declared or user-overridden strings without crashing.
-// Returns the resolved ref plus whether it came from the requested profile or
-// from the `default` fallback, so the caller can warn once per session
-// instead of every prompt.
+// `refs` is non-empty (the schema guarantees `default` exists and every value
+// is at least one ref). `ref` is the head of the chain — the model the
+// session is created with first. Callers that don't implement fallback can
+// keep reading `ref`; fallback-aware callers iterate `refs`.
 export type ResolvedProfile = {
   ref: KnownModelRef
+  refs: KnownModelRef[]
   profile: string
   fellBackToDefault: boolean
 }
 
 export function resolveProfile(models: Models, name: string | undefined): ResolvedProfile {
   const requested = name ?? 'default'
-  const ref = models[requested]
-  if (ref !== undefined) {
-    return { ref, profile: requested, fellBackToDefault: false }
+  const refs = models[requested]
+  if (refs !== undefined) {
+    return { ref: refs[0]!, refs, profile: requested, fellBackToDefault: false }
   }
   const fallback = models.default
-  return { ref: fallback, profile: 'default', fellBackToDefault: true }
+  return { ref: fallback[0]!, refs: fallback, profile: 'default', fellBackToDefault: true }
 }
 
 // Resolves a mount's `path` field to an absolute host path, mirroring shell

package/src/config/models-mutation.ts

@@ -17,8 +17,16 @@ const CONFIG_FILE = 'typeclaw.json'
 
 export type ModelProfileEntry = {
   profile: string
+  // Head of the fallback chain. Kept under the legacy `ref` name so callers
+  // that only care about the active model (the common case) don't need to
+  // dereference `refs[0]`. The chain itself is exposed as `refs`.
   ref: KnownModelRef
+  refs: KnownModelRef[]
   providerId: KnownProviderId
+  // Credential status for every provider referenced by the chain. The chain's
+  // overall status is `available` only when every entry resolves; otherwise
+  // it is `missing-credentials`, and `missingProviders` names which.
+  missingProviders: KnownProviderId[]
   isDefault: boolean
   credentialStatus: 'available' | 'missing-credentials'
 }
@@ -28,14 +36,18 @@ export type ModelMutationResult = { ok: true } | { ok: false; reason: string }
 export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.env): ModelProfileEntry[] {
   const models = loadConfigSync(cwd).models
   const out: ModelProfileEntry[] = []
-  for (const [profile, ref] of Object.entries(models)) {
-    const providerId = providerForModelRef(ref)
+  for (const [profile, refs] of Object.entries(models)) {
+    const headRef = refs[0]!
+    const providerId = providerForModelRef(headRef)
+    const missingProviders = uniqueProviders(refs).filter((p) => !hasUsableCredential(cwd, p, env))
     out.push({
       profile,
-      ref,
+      ref: headRef,
+      refs,
       providerId,
+      missingProviders,
       isDefault: profile === 'default',
-      credentialStatus: hasUsableCredential(cwd, providerId, env) ? 'available' : 'missing-credentials',
+      credentialStatus: missingProviders.length === 0 ? 'available' : 'missing-credentials',
     })
   }
   // `default` always first; remaining profiles alphabetical so output is stable.
@@ -47,6 +59,19 @@ export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.
   return out
 }
 
+function uniqueProviders(refs: ReadonlyArray<KnownModelRef>): KnownProviderId[] {
+  const seen = new Set<KnownProviderId>()
+  const out: KnownProviderId[] = []
+  for (const r of refs) {
+    const p = providerForModelRef(r)
+    if (!seen.has(p)) {
+      seen.add(p)
+      out.push(p)
+    }
+  }
+  return out
+}
+
 export function listAvailableModelRefs(): KnownModelRef[] {
   return listKnownModelRefs()
 }
@@ -158,14 +183,18 @@ export function removeProfile(cwd: string, profile: string): ModelMutationResult
 
 function writeProfile(cwd: string, profile: string, ref: KnownModelRef, message: string): ModelMutationResult {
   const existing = readModelsRaw(cwd)
-  const next = existing === null ? { default: ref } : { ...existing, [profile]: ref }
+  const next: Record<string, string | string[]> = existing === null ? { default: ref } : { ...existing, [profile]: ref }
   if (existing === null && profile !== 'default') {
     next.default = ref
   }
   return writeModels(cwd, next, message)
 }
 
-function writeModels(cwd: string, models: Record<string, string>, commitMessage: string): ModelMutationResult {
+function writeModels(
+  cwd: string,
+  models: Record<string, string | string[]>,
+  commitMessage: string,
+): ModelMutationResult {
   const path = join(cwd, CONFIG_FILE)
   let parsed: Record<string, unknown>
   try {
@@ -207,10 +236,15 @@ function writeModels(cwd: string, models: Record<string, string>, commitMessage:
   return { ok: true }
 }
 
-function readModelsRaw(cwd: string): Record<string, string> | null {
+// Returns the raw `models` block from disk in its on-disk shape: each value
+// is `string | string[]` (the user-facing schema). Writers preserve whichever
+// shape was already present for profiles they don't touch — converting a
+// hand-authored fallback chain back to a single string would silently drop
+// the fallback.
+function readModelsRaw(cwd: string): Record<string, string | string[]> | null {
   try {
     const raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
-    const parsed = JSON.parse(raw) as { models?: Record<string, string> }
+    const parsed = JSON.parse(raw) as { models?: Record<string, string | string[]> }
     return parsed.models ?? null
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null

package/src/config/providers-mutation.ts

@@ -136,8 +136,8 @@ export function findModelsReferencingProvider(cwd: string, providerId: string):
   const models = readModelsOrNull(cwd)
   if (models === null) return []
   const out: string[] = []
-  for (const [profile, ref] of Object.entries(models)) {
-    if (refTargetsProvider(ref, providerId)) out.push(profile)
+  for (const [profile, refs] of Object.entries(models)) {
+    if (refs.some((r) => refTargetsProvider(r, providerId))) out.push(profile)
   }
   return out
 }
@@ -212,12 +212,16 @@ function readEnvKey(env: NodeJS.ProcessEnv, key: string): string | undefined {
 function buildProviderReferenceMap(models: Models | null): Map<string, string[]> {
   const out = new Map<string, string[]>()
   if (models === null) return out
-  for (const [profile, ref] of Object.entries(models)) {
-    const providerId = safeProviderForRef(ref)
-    if (providerId === null) continue
-    const existing = out.get(providerId) ?? []
-    existing.push(profile)
-    out.set(providerId, existing)
+  for (const [profile, refs] of Object.entries(models)) {
+    for (const ref of refs) {
+      const providerId = safeProviderForRef(ref)
+      if (providerId === null) continue
+      const existing = out.get(providerId) ?? []
+      if (!existing.includes(profile)) {
+        existing.push(profile)
+        out.set(providerId, existing)
+      }
+    }
   }
   return out
 }

package/src/container/start.ts

@@ -455,7 +455,24 @@ export async function planStart({
   // the start() preflight force-removes any lingering corpse before the next
   // launch — so the only state Docker ever sees in `docker ps -a` is either
   // a running container or one the user has not started again yet.
-  const runArgs = ['run', '-d', '--name', containerName, '-p', `${publishHost}:${hostPort}:${CONTAINER_PORT}`]
+  //
+  // `--shm-size=2g` is mandatory for the bundled Chrome (agent-browser) to
+  // survive heavy pages. Docker's default /dev/shm is 64MB; Chrome uses
+  // shared memory for the renderer process and silently crashes mid-load
+  // on any site with a large DOM or non-trivial WebGL. The crash surfaces
+  // as a blank page or "target closed" with no clear cause — easy to
+  // misattribute to bot detection. 2g matches the Playwright/Puppeteer
+  // canonical recommendation and is a memory cap, not an allocation (only
+  // used pages count against the host).
+  const runArgs = [
+    'run',
+    '-d',
+    '--name',
+    containerName,
+    '--shm-size=2g',
+    '-p',
+    `${publishHost}:${hostPort}:${CONTAINER_PORT}`,
+  ]
 
   // Network egress filter: when `typeclaw.json#network.blockInternal` is true,
   // grant the container CAP_NET_ADMIN at boot so the entrypoint shim can

package/src/cron/consumer.ts

@@ -1,6 +1,8 @@
 import type { AgentSession } from '@/agent'
-import { subscribeProviderErrors } from '@/agent/provider-error'
+import { promptWithFallback, resolveFallbackChain } from '@/agent/model-fallback'
 import type { SessionOrigin } from '@/agent/session-origin'
+import { getConfig } from '@/config'
+import type { KnownModelRef } from '@/config/providers'
 import type { HookBus } from '@/plugin'
 import type { Stream, Unsubscribe } from '@/stream'
 
@@ -41,7 +43,12 @@ export type CronConsumerLogger = {
 export type CreateCronConsumerOptions = {
   stream: Stream
   cwd: string
-  createSessionForCron: (job: PromptJob) => Promise<CronSession>
+  // The optional `refOverride` argument is consumed by the fallback loop: the
+  // consumer calls this factory once per ref in the profile's chain, pinning
+  // each attempt to the specified model. Factories that don't honor the
+  // override silently lose fallback semantics, so production wiring threads
+  // it through to `createSession({ refOverride })`.
+  createSessionForCron: (job: PromptJob, refOverride?: KnownModelRef) => Promise<CronSession>
   // Builds the `CronHandlerContext` for the job and awaits its `handler`.
   // Wired by `src/run/index.ts` to reuse `runPromptForCommand` /
   // `runExecForCommand` from the command runner so plugin cron handlers and
@@ -121,7 +128,7 @@ export function createCronConsumer({
 
 async function runPrompt(
   job: PromptJob,
-  createSessionForCron: (job: PromptJob) => Promise<CronSession>,
+  createSessionForCron: (job: PromptJob, refOverride?: KnownModelRef) => Promise<CronSession>,
   stream: Stream,
   logger: CronConsumerLogger,
 ): Promise<void> {
@@ -148,52 +155,131 @@ async function runPrompt(
     })
     return
   }
-  const session = await createSessionForCron(job)
-  const unsubProviderErrors =
-    session.session !== undefined
-      ? subscribeProviderErrors(session.session, (err) => {
-          logger.error(`[cron] ${job.id}: LLM call failed: ${err.message}`)
+  // Resolve the model fallback chain for the cron profile (cron jobs run
+  // under the `default` profile today). Single-ref configs produce a length-1
+  // chain; multi-ref configs (e.g. `"default": ["openai/...", "fireworks/..."]`)
+  // drive the retry-on-failure loop inside `runPromptOnce`.
+  const refs = resolveFallbackChain(getConfig().models, undefined)
+  await runPromptOnce(job, refs, createSessionForCron, logger)
+}
+
+async function runPromptOnce(
+  job: PromptJob,
+  refs: KnownModelRef[],
+  createSessionForCron: (job: PromptJob, refOverride?: KnownModelRef) => Promise<CronSession>,
+  logger: CronConsumerLogger,
+): Promise<void> {
+  // Per-attempt lifecycle: every session we create gets full
+  // turn-start → turn-end → session-end → dispose bracketing, regardless of
+  // whether the helper chose it as the final session or disposed it as a
+  // failed earlier attempt. Without per-attempt session.end, plugin state
+  // keyed by sessionId (security plugin's remote-taint map, memory plugin's
+  // debounce timer) would orphan for every failed attempt. We track the
+  // last session separately so we can fire session.idle exactly once on
+  // success (matching pre-fallback cron behavior — see the pre-fallback
+  // try/finally structure: idle inside the prompt try-block, end in the
+  // outer finally).
+  let lastSession: CronSession | null = null
+  const result = await promptWithFallback({
+    refs,
+    text: job.prompt,
+    createSessionForRef: async (ref) => {
+      const created = await createSessionForCron(job, ref)
+      lastSession = created
+      const turnEvent =
+        created.hooks && created.sessionId !== undefined && created.agentDir !== undefined
+          ? {
+              sessionId: created.sessionId,
+              agentDir: created.agentDir,
+              ...(created.origin !== undefined ? { origin: created.origin } : {}),
+            }
+          : undefined
+      if (created.hooks && turnEvent !== undefined) {
+        await created.hooks.runSessionTurnStart(turnEvent)
+      }
+      // Bridge the CronSession wrapper into the AgentSession surface the
+      // fallback helper expects:
+      //   prompt    → CronSession.prompt (wrapper that calls AgentSession.prompt
+      //               in production, or a hand-rolled test fake)
+      //   subscribe → CronSession.session.subscribe when an underlying agent
+      //               session is supplied, else a no-op (soft-error detection
+      //               degrades to "off" in that mode; only hard throws drive
+      //               fallback). Test fakes that omit `.session` lose
+      //               soft-error fallback — production code always provides it.
+      // .bind(created.session) is load-bearing: AgentSession.subscribe is a
+      // regular method that reads `this._eventListeners`. Destructuring drops
+      // the receiver.
+      const sessionForHelper: AgentSession = {
+        prompt: (text: string) => created.prompt(text),
+        subscribe: created.session?.subscribe.bind(created.session) ?? (() => () => {}),
+      } as unknown as AgentSession
+      return {
+        session: sessionForHelper,
+        // Per-attempt teardown. Fires turn.end and session.end for every
+        // session created (success or failure), then disposes the underlying
+        // resources. Hooks that throw are logged but don't prevent disposal.
+        dispose: async () => {
+          if (created.hooks && turnEvent !== undefined) {
+            try {
+              await created.hooks.runSessionTurnEnd(turnEvent)
+            } catch (e) {
+              logger.warn(`[cron] ${job.id}: turn-end hook threw: ${describe(e)}`)
+            }
+          }
+          if (created.hooks && created.sessionId !== undefined) {
+            try {
+              await created.hooks.runSessionEnd({
+                sessionId: created.sessionId,
+                ...(created.origin !== undefined ? { origin: created.origin } : {}),
+              })
+            } catch (e) {
+              logger.warn(`[cron] ${job.id}: session-end hook threw: ${describe(e)}`)
+            }
+          }
+          created.dispose?.()
+        },
+      }
+    },
+    onAttemptFailed: (attempt) => {
+      logger.warn(
+        `[cron] ${job.id}: ${attempt.outcome} failure on ${attempt.ref}: ${attempt.errorMessage ?? 'unknown'}; falling back`,
+      )
+    },
+  })
+
+  if (!result.success) {
+    logger.error(
+      `[cron] ${job.id}: all ${result.attempts.length} model(s) failed; last error: ${result.lastError?.message ?? 'unknown'}`,
+    )
+  }
+
+  // session.idle fires once, only on success, and only against the session
+  // that handled the turn. Then dispose the successful session (the helper
+  // returns the session+dispose so we can run post-prompt hooks against a
+  // live session before tearing it down). Failed-chain disposal is already
+  // handled by the helper's per-attempt dispose calls.
+  if (result.success && lastSession !== null) {
+    const finalSession: CronSession = lastSession
+    if (finalSession.hooks && finalSession.sessionId !== undefined) {
+      try {
+        await finalSession.hooks.runSessionIdle({
+          sessionId: finalSession.sessionId,
+          parentTranscriptPath: finalSession.getTranscriptPath?.(),
+          idleMs: 0,
+          ...(finalSession.origin !== undefined ? { origin: finalSession.origin } : {}),
         })
-      : null
-  const turnEvent =
-    session.hooks && session.sessionId !== undefined && session.agentDir !== undefined
-      ? {
-          sessionId: session.sessionId,
-          agentDir: session.agentDir,
-          ...(session.origin !== undefined ? { origin: session.origin } : {}),
-        }
-      : undefined
-  try {
-    if (session.hooks && turnEvent !== undefined) {
-      await session.hooks.runSessionTurnStart(turnEvent)
-    }
-    try {
-      await session.prompt(job.prompt)
-    } finally {
-      if (session.hooks && turnEvent !== undefined) {
-        await session.hooks.runSessionTurnEnd(turnEvent)
+      } catch (e) {
+        logger.warn(`[cron] ${job.id}: session-idle hook threw: ${describe(e)}`)
       }
     }
-    if (session.hooks && session.sessionId !== undefined) {
-      await session.hooks.runSessionIdle({
-        sessionId: session.sessionId,
-        parentTranscriptPath: session.getTranscriptPath?.(),
-        idleMs: 0,
-        ...(session.origin !== undefined ? { origin: session.origin } : {}),
-      })
-    }
-  } finally {
-    unsubProviderErrors?.()
-    if (session.hooks && session.sessionId !== undefined) {
-      await session.hooks.runSessionEnd({
-        sessionId: session.sessionId,
-        ...(session.origin !== undefined ? { origin: session.origin } : {}),
-      })
-    }
-    session.dispose?.()
+    await result.dispose()
   }
 }
 
+function describe(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
 async function runExec(job: ExecJob, cwd: string): Promise<void> {
   const [cmd, ...args] = job.command
   if (!cmd) throw new Error(`exec job ${job.id}: empty command`)