typeclaw 0.36.8 → 0.37.0

package/src/init/checkpoint.ts

@@ -0,0 +1,201 @@
+import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import {
+  KNOWN_PROVIDERS,
+  listKnownModelRefs,
+  listKnownProviderVendorIds,
+  providerIdsForVendor,
+  type KnownProviderId,
+  type KnownProviderVendorId,
+  type ModelRef,
+} from '@/config/providers'
+
+// In-folder scratch for an in-progress `typeclaw init`, co-located with the
+// agent it describes. Lives under the agent's `.typeclaw/` (the same gitignored
+// local-scratch dir as the persistent-$HOME overlay), so it self-cleans when
+// the half-init folder is deleted, survives a folder rename mid-init, and is
+// inspectable right next to the thing being resumed. Gitignored via
+// `TRULY_IGNORED_PATTERNS`; never committed.
+export const INIT_CHECKPOINT_PATH = join('.typeclaw', 'init-progress.json')
+
+export const WIZARD_CHECKPOINT_VERSION = 1
+
+export type WizardChannelChoice = 'slack' | 'discord' | 'telegram' | 'kakaotalk' | 'github' | 'none'
+
+export type AuthMethod = 'api-key' | 'oauth'
+
+// Only stable selection IDs — never `llmAuth`, tokens, OAuth data, channel
+// secrets, the volatile models.dev catalog, or full `ModelOption` objects. The
+// projection in `checkpointFromSelections` is the single seam that enforces
+// this, so a secret can never leak into host state by accident.
+export interface WizardAnswerCheckpointV1 {
+  version: typeof WIZARD_CHECKPOINT_VERSION
+  cwd: string
+  updatedAt: string
+  vendorId?: KnownProviderVendorId
+  providerId?: KnownProviderId
+  modelRef?: ModelRef | string
+  authMethod?: AuthMethod
+  visionVendorId?: KnownProviderVendorId
+  visionProviderId?: KnownProviderId
+  visionModelRef?: ModelRef | string
+  visionAuthMethod?: AuthMethod
+  channelChoice?: WizardChannelChoice
+}
+
+export interface WizardCheckpointStore {
+  load(cwd: string): Promise<WizardAnswerCheckpointV1 | undefined>
+  save(cwd: string, checkpoint: WizardAnswerCheckpointV1): Promise<void>
+  clear(cwd: string): Promise<void>
+}
+
+// Selections the wizard already holds, projected to the persisted shape. Keep
+// this the ONLY place that reads `WizardState` so secret fields are physically
+// unable to reach the checkpoint file.
+export interface WizardCheckpointSelections {
+  cwd: string
+  vendorId?: KnownProviderVendorId
+  providerId?: KnownProviderId
+  modelRef?: ModelRef | string
+  authMethod?: AuthMethod
+  visionVendorId?: KnownProviderVendorId
+  visionProviderId?: KnownProviderId
+  visionModelRef?: ModelRef | string
+  visionAuthMethod?: AuthMethod
+  channelChoice?: WizardChannelChoice
+}
+
+export function checkpointFromSelections(selections: WizardCheckpointSelections): WizardAnswerCheckpointV1 {
+  return {
+    version: WIZARD_CHECKPOINT_VERSION,
+    cwd: selections.cwd,
+    updatedAt: new Date().toISOString(),
+    ...(selections.vendorId !== undefined ? { vendorId: selections.vendorId } : {}),
+    ...(selections.providerId !== undefined ? { providerId: selections.providerId } : {}),
+    ...(selections.modelRef !== undefined ? { modelRef: selections.modelRef } : {}),
+    ...(selections.authMethod !== undefined ? { authMethod: selections.authMethod } : {}),
+    ...(selections.visionVendorId !== undefined ? { visionVendorId: selections.visionVendorId } : {}),
+    ...(selections.visionProviderId !== undefined ? { visionProviderId: selections.visionProviderId } : {}),
+    ...(selections.visionModelRef !== undefined ? { visionModelRef: selections.visionModelRef } : {}),
+    ...(selections.visionAuthMethod !== undefined ? { visionAuthMethod: selections.visionAuthMethod } : {}),
+    ...(selections.channelChoice !== undefined ? { channelChoice: selections.channelChoice } : {}),
+  }
+}
+
+// Drop any saved field that no longer references a real vendor/provider/model.
+// Stale values cascade downward: an unknown provider invalidates its model and
+// auth-method too, since those were chosen for a provider that no longer
+// exists. Returns a sanitized copy; never throws on drift.
+export function sanitizeCheckpointAgainstCatalog(
+  checkpoint: WizardAnswerCheckpointV1,
+  validModelRefs: ReadonlySet<string> = new Set(listKnownModelRefs()),
+): WizardAnswerCheckpointV1 {
+  const sanitized: WizardAnswerCheckpointV1 = {
+    version: WIZARD_CHECKPOINT_VERSION,
+    cwd: checkpoint.cwd,
+    updatedAt: checkpoint.updatedAt,
+  }
+
+  const vendor = pruneVendor(checkpoint.vendorId)
+  const provider = pruneProvider(vendor, checkpoint.providerId)
+  if (vendor !== undefined) sanitized.vendorId = vendor
+  if (provider !== undefined) {
+    sanitized.providerId = provider
+    if (checkpoint.modelRef !== undefined && validModelRefs.has(checkpoint.modelRef)) {
+      sanitized.modelRef = checkpoint.modelRef
+    }
+    if (checkpoint.authMethod !== undefined) sanitized.authMethod = checkpoint.authMethod
+  }
+
+  const visionVendor = pruneVendor(checkpoint.visionVendorId)
+  const visionProvider = pruneProvider(visionVendor, checkpoint.visionProviderId)
+  if (visionVendor !== undefined) sanitized.visionVendorId = visionVendor
+  if (visionProvider !== undefined) {
+    sanitized.visionProviderId = visionProvider
+    if (checkpoint.visionModelRef !== undefined && validModelRefs.has(checkpoint.visionModelRef)) {
+      sanitized.visionModelRef = checkpoint.visionModelRef
+    }
+    if (checkpoint.visionAuthMethod !== undefined) sanitized.visionAuthMethod = checkpoint.visionAuthMethod
+  }
+
+  if (checkpoint.channelChoice !== undefined) sanitized.channelChoice = checkpoint.channelChoice
+
+  return sanitized
+}
+
+function pruneVendor(vendorId: KnownProviderVendorId | undefined): KnownProviderVendorId | undefined {
+  if (vendorId === undefined) return undefined
+  return listKnownProviderVendorIds().includes(vendorId) ? vendorId : undefined
+}
+
+function pruneProvider(
+  vendorId: KnownProviderVendorId | undefined,
+  providerId: KnownProviderId | undefined,
+): KnownProviderId | undefined {
+  if (vendorId === undefined || providerId === undefined) return undefined
+  if (!(providerId in KNOWN_PROVIDERS)) return undefined
+  return providerIdsForVendor(vendorId).includes(providerId) ? providerId : undefined
+}
+
+function checkpointFilePath(cwd: string): string {
+  return join(cwd, INIT_CHECKPOINT_PATH)
+}
+
+export function createLocalWizardCheckpointStore(): WizardCheckpointStore {
+  return {
+    async load(cwd) {
+      const path = checkpointFilePath(cwd)
+      let parsed: unknown
+      try {
+        parsed = JSON.parse(await readFile(path, 'utf8'))
+      } catch {
+        return undefined
+      }
+      if (!isValidCheckpoint(parsed)) return undefined
+      return parsed
+    },
+
+    // Atomic write: temp + rename within the agent's .typeclaw/ so a crash
+    // mid-write never leaves a half-written file that `load` would misparse and
+    // discard.
+    async save(cwd, checkpoint) {
+      const final = checkpointFilePath(cwd)
+      const tmp = `${final}.${process.pid}.tmp`
+      await mkdir(dirname(final), { recursive: true })
+      await writeFile(tmp, JSON.stringify(checkpoint), { mode: 0o600 })
+      await rename(tmp, final)
+    },
+
+    async clear(cwd) {
+      try {
+        await unlink(checkpointFilePath(cwd))
+      } catch {}
+    },
+  }
+}
+
+function isValidCheckpoint(value: unknown): value is WizardAnswerCheckpointV1 {
+  if (typeof value !== 'object' || value === null) return false
+  const v = value as Record<string, unknown>
+  if (v.version !== WIZARD_CHECKPOINT_VERSION) return false
+  if (typeof v.cwd !== 'string') return false
+  if (typeof v.updatedAt !== 'string') return false
+  // Every optional selection field must be a string when present. Membership
+  // (is this a real provider/model?) is the sanitizer's job, but a non-string
+  // here is structurally corrupt and would later index KNOWN_PROVIDERS or join
+  // into prompt text with a wrong shape — reject it at load.
+  return OPTIONAL_STRING_FIELDS.every((field) => v[field] === undefined || typeof v[field] === 'string')
+}
+
+const OPTIONAL_STRING_FIELDS = [
+  'vendorId',
+  'providerId',
+  'modelRef',
+  'authMethod',
+  'visionVendorId',
+  'visionProviderId',
+  'visionModelRef',
+  'visionAuthMethod',
+  'channelChoice',
+] as const satisfies ReadonlyArray<keyof WizardAnswerCheckpointV1>

package/src/init/dockerfile.ts

@@ -18,6 +18,10 @@ export type BuildDockerfileOptions = {
   // host signal — e.g. a bare `buildDockerfile()` in tests — stays small and
   // deterministic.
   cjkFontsAuto?: boolean
+  // Emit a BuildKit Dockerfile (default) or strip BuildKit-only directives for
+  // hosts without buildx. `start` sets this to false when buildx is absent so
+  // the legacy `docker build` can still build the agent image.
+  buildKit?: boolean
 }
 
 // Apt packages that EVERY image must have — git for the agent runtime,
@@ -75,6 +79,7 @@ const BASELINE_APT_PACKAGES = [
   'util-linux',
   'bubblewrap',
   'jq',
+  'libgomp1',
 ] as const
 
 // curl-impersonate is the only currently-working way to query DuckDuckGo from
@@ -573,6 +578,72 @@ RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
  && chmod +x ${TYPECLAW_ENTRYPOINT_PATH}`
 }
 
+// Layer 7: install @huggingface/transformers with its linux-native binaries.
+//
+// The host node_modules is bind-mounted over /agent at runtime carrying
+// whatever binaries the host (typically macOS) resolved, so this layer seeds
+// LINUX binaries into an image path that survives the bind mount and still
+// wins Node/Bun resolution. Two native-dep mechanisms, fixed differently:
+//
+//   1. onnxruntime-node ships its addon via a POSTINSTALL that materializes the
+//      binary inside the package dir, so a plain `bun add` covers it.
+//   2. sharp resolves its native code from SEPARATE `@img/sharp-*` optional
+//      PACKAGES, not a postinstall addon. sharp is a MANDATORY dep of
+//      transformers, loaded eagerly because the package main chains
+//      transformers.js -> utils/image.js (top-level `import sharp`) even though
+//      typeclaw only does text feature-extraction. `bun add
+//      @huggingface/transformers` alone does NOT pull the linux `@img/*` when
+//      the bind-mounted host tree already satisfies sharp with the macOS ones —
+//      so `sharp.js` throws at import ("Could not load the sharp module using
+//      the linux-<arch> runtime") and the container exits at startup. We
+//      install the arch-matched linux platform packages EXPLICITLY to fix it.
+//
+// CRITICAL — install location. `typeclaw start` bind-mounts the host agent
+// folder over /agent at runtime (`-v <cwd>:/agent`), so anything written under
+// /agent/node_modules at BUILD time is MASKED at runtime and can never win.
+// The prior fix ran this `bun add` under `WORKDIR /agent`, populating
+// /agent/node_modules — invisible behind the bind mount, so the sharp crash
+// persisted. We install from `WORKDIR /` instead: the linux packages land in
+// the IMAGE's /node_modules, which is NOT masked by the /agent mount. Node/Bun
+// resolution for `require('@img/sharp-linux-<arch>')` ascends from
+// /agent/node_modules/sharp up the directory chain and finds /node_modules,
+// so the linux binary resolves. WORKDIR is restored to /agent afterwards so
+// later layers and the runtime CWD are unchanged.
+//
+// EXACT transformers version this image installs. Must stay in lockstep with
+// `@huggingface/transformers` in the repo package.json (a guard test in
+// dockerfile.test.ts asserts the two agree). The pin is EXACT — not a caret —
+// because this layer's `bun add` runs at `WORKDIR /` with NO project lockfile,
+// so the repo `bun.lock` does NOT constrain it. A bare `@huggingface/
+// transformers` (no version) would resolve npm `latest` at BUILD time: the day
+// a newer transformers ships, the container would install it while the
+// sharp/libvips pins below stay fixed, and the mismatched sharp platform
+// packages crash at container import ("Could not load the sharp module using
+// the linux-<arch> runtime"). Pinning the version closes that drift.
+export const TRANSFORMERS_VERSION = '4.2.0'
+
+// sharp + libvips versions are pinned to what @huggingface/transformers@4.2.0
+// resolves. A future transformers bump that moves sharp must bump
+// TRANSFORMERS_VERSION, `sharp@`, `@img/sharp-linux-*`, and
+// `@img/sharp-libvips-linux-*` together — mismatched sharp/libvips platform
+// packages are a known failure mode. `$TARGETARCH` is `arm64` or `amd64`; an
+// empty value (bare `docker build` without buildx) falls back to x64 for
+// determinism.
+const LAYER_TRANSFORMERS_INSTALL = `# Layer 7: install @huggingface/transformers with its linux-native binaries.
+# Installs the linux onnxruntime-node addon AND sharp's linux platform packages
+# (@img/sharp-linux-*) into the image's /node_modules so they survive the
+# runtime /agent bind mount and still win Node/Bun resolution from
+# /agent/node_modules/sharp. The transformers version is pinned EXACT (this
+# bun add has no lockfile) — see src/init/dockerfile.ts for the rationale.
+WORKDIR /
+RUN SHARP_ARCH="$(if [ "\${TARGETARCH:-amd64}" = "arm64" ]; then echo arm64; else echo x64; fi)" \\
+ && bun add \\
+      @huggingface/transformers@${TRANSFORMERS_VERSION} \\
+      sharp@0.34.5 \\
+      "@img/sharp-linux-\${SHARP_ARCH}@0.34.5" \\
+      "@img/sharp-libvips-linux-\${SHARP_ARCH}@1.2.4"
+WORKDIR /agent`
+
 // Claude Code's official installer is `curl | bash`, not apt — can't live
 // in APT_FEATURES. Layer placed after the toggle apt install (so curl + ca-
 // certificates from the baseline are guaranteed present) and before the
@@ -1059,7 +1130,7 @@ const TYPECLAW_CX_GLOBAL_HOOKS = JSON.stringify({
   },
 })
 
-function renderCodexCliInstallLayer(enabled: boolean): string {
+function renderCodexCliInstallLayer(enabled: boolean, buildKit: boolean): string {
   if (!enabled) return ''
   return `# Layer 5.7 (toggle): install OpenAI's Codex CLI. Opt-in via
 # typeclaw.json#docker.file.codexCli. The skill \`typeclaw-codex-cli\`
@@ -1069,8 +1140,7 @@ function renderCodexCliInstallLayer(enabled: boolean): string {
 # are pre-written at build time so the operator subagent never has to
 # construct that JSON itself — same load-bearing reason as the Claude
 # Code layer above.
-RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
-    bun install -g @openai/codex \\
+RUN ${bunCacheMount(buildKit)}bun install -g @openai/codex \\
  && codex --version > /dev/null \\
  && cat > ${TYPECLAW_CX_SESSION_START_HOOK_PATH} <<'TYPECLAW_CX_SESSION_START_HOOK_EOF'
 ${TYPECLAW_CX_SESSION_START_HOOK_SCRIPT}TYPECLAW_CX_SESSION_START_HOOK_EOF
@@ -1155,15 +1225,19 @@ export function buildDockerfile(
   config: DockerfileConfig = defaultConfig(),
   options: BuildDockerfileOptions = {},
 ): string {
+  // buildKit is the default; `start` passes false on hosts without buildx so the
+  // generated Dockerfile omits the `# syntax=` pragma and every cache mount —
+  // the legacy builder accepts the result as-is, no text post-processing needed.
+  const buildKit = options.buildKit !== false
   const cjkFonts = resolveCjkFonts(config.cjkFonts, options.cjkFontsAuto ?? false)
   const toggleAptArgs = collectToggleAptArgs(config, cjkFonts)
-  const ghKeyringLayer = renderGhKeyringLayer(config.gh)
+  const ghKeyringLayer = renderGhKeyringLayer(config.gh, buildKit)
   const cloudflaredLayer = renderCloudflaredLayer(config.cloudflared)
   const customLines = renderCustomDockerfileLines(config.append)
   const baseImageVersion = options.baseImageVersion ?? null
 
   const claudeCodeLayer = renderClaudeCodeInstallLayer(config.claudeCode)
-  const codexCliLayer = renderCodexCliInstallLayer(config.codexCli)
+  const codexCliLayer = renderCodexCliInstallLayer(config.codexCli, buildKit)
   const fromAndHeavyLayers =
     baseImageVersion !== null
       ? renderVersionedHead(
@@ -1173,11 +1247,12 @@ export function buildDockerfile(
           cloudflaredLayer,
           claudeCodeLayer,
           codexCliLayer,
+          buildKit,
         )
-      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer, codexCliLayer)
+      : renderInlineHead(ghKeyringLayer, toggleAptArgs, cloudflaredLayer, claudeCodeLayer, codexCliLayer, buildKit)
 
-  return `${BUILDKIT_HEADER}
-# AUTOGENERATED by typeclaw — do not edit.
+  const header = buildKit ? `${BUILDKIT_HEADER}\n` : ''
+  return `${header}# AUTOGENERATED by typeclaw — do not edit.
 # This file is rewritten on every \`typeclaw start\` from src/init/dockerfile.ts
 # in the typeclaw repo. Local edits will be overwritten (and committed away if
 # the working tree is dirty). To change the template, edit dockerfile.ts there.
@@ -1223,8 +1298,9 @@ function renderVersionedHead(
   cloudflaredLayer: string,
   claudeCodeLayer: string,
   codexCliLayer: string,
+  buildKit: boolean,
 ): string {
-  const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs)}\n\n`
+  const toggleAptLayer = toggleAptArgs.length === 0 ? '' : `${renderToggleAptInstallLayer(toggleAptArgs, buildKit)}\n\n`
   const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
   const claudeCodeBlock = claudeCodeLayer === '' ? '' : `${claudeCodeLayer}\n\n`
   const codexCliBlock = codexCliLayer === '' ? '' : `${codexCliLayer}\n\n`
@@ -1236,6 +1312,8 @@ ARG TARGETARCH
 
 ${ghKeyringLayer}${toggleAptLayer}${cloudflaredBlock}${claudeCodeBlock}${codexCliBlock}${renderEntrypointShimLayer()}
 
+${LAYER_TRANSFORMERS_INSTALL}
+
 `
 }
 
@@ -1249,6 +1327,7 @@ function renderInlineHead(
   cloudflaredLayer: string,
   claudeCodeLayer: string,
   codexCliLayer: string,
+  buildKit: boolean,
 ): string {
   const baselineAndToggleArgs = [...BASELINE_APT_PACKAGES, ...toggleAptArgs]
   const cloudflaredBlock = cloudflaredLayer === '' ? '' : `${cloudflaredLayer}\n\n`
@@ -1274,9 +1353,7 @@ ${ghKeyringLayer}# Layer 2 (changes when the package list changes): the actual a
 #
 # No \`rm -rf /var/lib/apt/lists/*\` because the lists live on a cache mount
 # that is excluded from the image layer by definition.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    apt-get update \\
+RUN ${aptCacheMount(buildKit)}apt-get update \\
  && apt-get install -y --no-install-recommends \\
       ${baselineAndToggleArgs.join(' ')} \\
  && if [ "$TARGETARCH" = "arm64" ]; then \\
@@ -1290,14 +1367,16 @@ ${LAYER_2_5_CURL_IMPERSONATE}
 
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
-${LAYER_4_AGENT_BROWSER_INSTALL}
+${renderAgentBrowserInstallLayer(buildKit)}
 
 ${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
 
-${LAYER_5_CHROME_FOR_TESTING}
+${renderChromeForTestingLayer(buildKit)}
 
 ${cloudflaredBlock}${claudeCodeBlock}${codexCliBlock}${renderEntrypointShimLayer()}
 
+${LAYER_TRANSFORMERS_INSTALL}
+
 `
 }
 
@@ -1317,13 +1396,11 @@ RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64
 `
 }
 
-function renderToggleAptInstallLayer(toggleAptArgs: string[]): string {
+function renderToggleAptInstallLayer(toggleAptArgs: string[], buildKit: boolean): string {
   return `# Layer 1 (toggle apt install): packages requested via typeclaw.json
 # #docker.file toggles. Baseline + Chrome runtime libs are already in the
 # base image; this layer only adds gh/tmux/python/ffmpeg/cjkFonts if enabled.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    apt-get update \\
+RUN ${aptCacheMount(buildKit)}apt-get update \\
  && apt-get install -y --no-install-recommends \\
       ${toggleAptArgs.join(' ')}`
 }
@@ -1353,9 +1430,7 @@ ${LAYER_0_APT_KEEP_CACHE}
 # packages (gh/python/tmux/ffmpeg) are intentionally NOT installed here —
 # they layer onto the base in the per-agent Dockerfile so users can opt in/
 # out via typeclaw.json without forcing a base-image rebuild.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    apt-get update \\
+RUN ${aptCacheMount(true)}apt-get update \\
  && apt-get install -y --no-install-recommends \\
       ${BASELINE_APT_PACKAGES.join(' ')} \\
  && if [ "$TARGETARCH" = "arm64" ]; then \\
@@ -1369,13 +1444,15 @@ ${LAYER_2_5_CURL_IMPERSONATE}
 
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
-${LAYER_4_AGENT_BROWSER_INSTALL}
+${renderAgentBrowserInstallLayer(true)}
 
 ${LAYER_4_5_AGENT_BROWSER_HEADED_WRAPPER}
 
-${LAYER_5_CHROME_FOR_TESTING}
+${renderChromeForTestingLayer(true)}
 
 ${renderEntrypointShimLayer()}
+
+${LAYER_TRANSFORMERS_INSTALL}
 `
 }
 
@@ -1386,6 +1463,19 @@ ${renderEntrypointShimLayer()}
 
 const BUILDKIT_HEADER = `# syntax=docker/dockerfile:1.7`
 
+// Cache-mount prefixes spliced between `RUN ` and the command. BuildKit honors
+// `--mount=type=cache` (apt .debs / bun packages reused across builds); the
+// legacy builder (hosts without buildx) has no equivalent, so legacy mode emits
+// an empty prefix — same image, just no cross-build cache. Generating the two
+// modes structurally is why typeclaw needs no Dockerfile text post-processing.
+const APT_CACHE_MOUNT =
+  '--mount=type=cache,target=/var/cache/apt,sharing=locked \\\n' +
+  '    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\\n    '
+const BUN_CACHE_MOUNT = '--mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\\n    '
+
+const aptCacheMount = (buildKit: boolean): string => (buildKit ? APT_CACHE_MOUNT : '')
+const bunCacheMount = (buildKit: boolean): string => (buildKit ? BUN_CACHE_MOUNT : '')
+
 const FROM_AND_WORKDIR = `FROM oven/bun:1-slim
 
 WORKDIR /agent
@@ -1429,10 +1519,10 @@ RUN if [ "$TARGETARCH" = "arm64" ]; then \\
    && printf '%s\\n' '{"executablePath":"/usr/bin/chromium"}' > /root/.agent-browser/config.json; \\
     fi`
 
-const LAYER_4_AGENT_BROWSER_INSTALL = `# Layer 4 (volatile): install agent-browser globally so it survives the
+const renderAgentBrowserInstallLayer = (buildKit: boolean): string =>
+  `# Layer 4 (volatile): install agent-browser globally so it survives the
 # runtime bind-mount over /agent/node_modules.
-RUN --mount=type=cache,target=/root/.bun/install/cache,sharing=locked \\
-    bun install -g agent-browser`
+RUN ${bunCacheMount(buildKit)}bun install -g agent-browser@^0.27.0`
 
 // Layer 4.5: shim the agent-browser binary with a wrapper that calls
 // \`agent-browser close\` before \`open\`/\`goto\`/\`navigate\` when headed
@@ -1548,10 +1638,9 @@ TYPECLAW_AGENT_BROWSER_WRAPPER_EOF`
 // already installed in Layer 2; --with-deps is a defense-in-depth backstop
 // so a future agent-browser bump that adds new deps installs them
 // automatically (near-no-op when Layer 2 already covers them).
-const LAYER_5_CHROME_FOR_TESTING = `# Layer 5 (heavy, amd64 only): Chrome for Testing download.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    if [ "$TARGETARCH" != "arm64" ]; then \\
+const renderChromeForTestingLayer = (buildKit: boolean): string =>
+  `# Layer 5 (heavy, amd64 only): Chrome for Testing download.
+RUN ${aptCacheMount(buildKit)}if [ "$TARGETARCH" != "arm64" ]; then \\
       agent-browser install --with-deps; \\
     fi`
 
@@ -1590,16 +1679,14 @@ function singlePackageArgs(name: string, toggle: DockerfileFeatureToggle): strin
 // (the most frequent change) does not re-fetch the GPG key over the network.
 // When `gh` is disabled, omit the layer entirely — both to skip the network
 // roundtrip on cold builds and to keep the package source registry clean.
-function renderGhKeyringLayer(toggle: DockerfileFeatureToggle): string {
+function renderGhKeyringLayer(toggle: DockerfileFeatureToggle, buildKit: boolean): string {
   if (toggle === false) return ''
   return `# Layer 1 (rarely changes): register the GitHub CLI apt repository and trust
 # its keyring. Split from the package install below so editing the package
 # list (the most frequent change to this Dockerfile) does NOT re-fetch the
 # GPG key over the network. The cache mount on /var/cache/apt covers the
 # tiny gnupg/curl install we need to bootstrap the key fetch.
-RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
-    --mount=type=cache,target=/var/lib/apt/lists,sharing=locked \\
-    apt-get update \\
+RUN ${aptCacheMount(buildKit)}apt-get update \\
  && apt-get install -y --no-install-recommends curl ca-certificates gnupg \\
  && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \\
       | gpg --dearmor -o /etc/apt/keyrings/githubcli-archive-keyring.gpg \\

package/src/init/gitignore.ts

@@ -9,7 +9,7 @@ export const TRULY_IGNORED_PATTERNS = [
   '.env.local',
   'secrets.json',
   'auth.json',
-  '.typeclaw/home/',
+  '.typeclaw/',
   'node_modules/',
   'packages/*/node_modules/',
   'workspace/',
@@ -40,12 +40,12 @@ export function buildGitignore(config: GitignoreConfig = { append: [] }): string
 # as a safety net so an agent folder cloned from a pre-rename machine never
 # stages credentials by accident.
 #
-# .typeclaw/home/ is the persistent-$HOME overlay populated by the
-# entrypoint shim's \`link_persistent_home_files\` (see
-# src/init/dockerfile.ts). It mirrors selected files from the container's
-# $HOME (e.g. ~/.codex/auth.json) into the bind-mounted agent folder so
-# tool credentials survive container restarts. Always credentials; never
-# commit.
+# .typeclaw/ is the agent's local-scratch dir. It holds the persistent-$HOME
+# overlay (.typeclaw/home/, populated by the entrypoint shim's
+# \`link_persistent_home_files\` — see src/init/dockerfile.ts, mirrors container
+# $HOME files like ~/.codex/auth.json so tool credentials survive restarts) and
+# the in-progress init checkpoint (.typeclaw/init-progress.json, non-secret
+# wizard selections for resume). Local-only; never commit.
 ${TRULY_IGNORED_PATTERNS.join('\n')}
 
 # System-managed: gitignored by default so the agent never stages them by hand,

package/src/init/index.ts

@@ -10,13 +10,15 @@ import {
   GWS_MULTI_ACCOUNT_PLUGIN_VERSION,
   migrateLegacyConfigShape,
   type Config,
+  type CustomModelMeta,
 } from '@/config'
 import {
   DEFAULT_MODEL_REF,
   KNOWN_PROVIDERS,
+  isKnownModelRef,
   providerForModelRef,
-  type KnownModelRef,
   type KnownProviderId,
+  type ModelRef,
 } from '@/config/providers'
 import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
 import { commitSystemFile } from '@/git/system-commit'
@@ -171,7 +173,8 @@ export type InitOptions = {
   cwd: string
   // Selected `provider/model` ref written into typeclaw.json. Defaults to
   // DEFAULT_MODEL_REF when callers (or older test fixtures) omit it.
-  model?: KnownModelRef
+  model?: ModelRef | string
+  modelMeta?: CustomModelMeta
   // How the agent will authenticate to the LLM provider. When omitted,
   // defaults to the api-key path with `apiKey` (legacy field, still
   // supported for backwards compat with the old `runInit` signature).
@@ -181,7 +184,8 @@ export type InitOptions = {
   // when both refer to the same provider; the wizard enforces this
   // pairing rule, so by the time we get here `visionAuth` is either
   // (a) absent, or (b) the right auth for `visionModel`'s provider.
-  visionModel?: KnownModelRef
+  visionModel?: ModelRef | string
+  visionModelMeta?: CustomModelMeta
   visionAuth?: LLMAuth
   apiKey?: string
   discordBotToken?: string
@@ -224,7 +228,9 @@ export async function runInit({
   apiKey,
   llmAuth,
   model = DEFAULT_MODEL_REF,
+  modelMeta,
   visionModel,
+  visionModelMeta,
   visionAuth,
   discordBotToken,
   slackBotToken,
@@ -304,7 +310,9 @@ export async function runInit({
   emit({ step: 'scaffold', phase: 'start' })
   await scaffold(cwd, {
     model,
+    ...(modelMeta !== undefined ? { modelMeta } : {}),
     ...(visionModel !== undefined ? { visionModel } : {}),
+    ...(visionModelMeta !== undefined ? { visionModelMeta } : {}),
     withDiscord: wantsDiscord,
     withSlack: wantsSlack,
     withTelegram: wantsTelegram,
@@ -520,8 +528,10 @@ export async function isHatched(dir: string): Promise<boolean> {
 }
 
 export type ScaffoldOptions = {
-  model?: KnownModelRef
-  visionModel?: KnownModelRef
+  model?: ModelRef | string
+  modelMeta?: CustomModelMeta
+  visionModel?: ModelRef | string
+  visionModelMeta?: CustomModelMeta
   withDiscord?: boolean
   withSlack?: boolean
   withTelegram?: boolean
@@ -545,12 +555,14 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   // `memory.*`) is omitted to keep the scaffold minimal — duplicating defaults
   // here would mean every schema change has to be mirrored in two places, and
   // users would feel obligated to maintain values they never set.
-  const models: Record<string, KnownModelRef> = { default: options.model ?? DEFAULT_MODEL_REF }
+  const models: Record<string, string> = { default: options.model ?? DEFAULT_MODEL_REF }
   if (options.visionModel !== undefined) models.vision = options.visionModel
   const config: Record<string, unknown> = {
     $schema: './node_modules/typeclaw/typeclaw.schema.json',
     models,
   }
+  const customModels = collectCustomModels(options)
+  if (Object.keys(customModels).length > 0) config.customModels = customModels
   const channels: Record<string, Record<string, never>> = {}
   if (options.withDiscord) channels['discord-bot'] = {}
   if (options.withSlack) channels['slack-bot'] = {}
@@ -578,12 +590,32 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   await writeFile(join(root, GITIGNORE_FILE), buildGitignore(), { flag: 'wx' }).catch(ignoreExists)
 }
 
+function collectCustomModels(options: ScaffoldOptions): Record<string, CustomModelMeta> {
+  const customModels: Record<string, CustomModelMeta> = {}
+  addCustomModel(customModels, options.model ?? DEFAULT_MODEL_REF, options.modelMeta)
+  if (options.visionModel !== undefined) addCustomModel(customModels, options.visionModel, options.visionModelMeta)
+  return customModels
+}
+
+function addCustomModel(
+  customModels: Record<string, CustomModelMeta>,
+  ref: string,
+  meta: CustomModelMeta | undefined,
+): void {
+  if (isKnownModelRef(ref)) return
+  customModels[ref] = meta ?? {}
+}
+
 // agent-browser ships in every agent: the bundled SKILL.md (src/skills/
 // agent-browser/SKILL.md) is a discovery stub that calls `agent-browser
 // skills get core` at runtime, so the CLI must be installed for the skill
 // to function. The Dockerfile pre-downloads Chromium too, so the agent
 // can drive a browser without any first-run setup.
-const AGENT_BROWSER_VERSION = '^0.26.0'
+//
+// Must match the Dockerfile Layer 4 global install (dockerfile.ts); they are
+// two installs of the same CLI and a skew is silent. Enforced by a guard test
+// in packagejson.test.ts.
+export const AGENT_BROWSER_VERSION = '^0.27.0'
 function buildPackageJson(root: string, name: string): Record<string, unknown> {
   return {
     name,
@@ -738,10 +770,10 @@ export async function writeSecrets(
     slackAppToken,
     telegramBotToken,
   }: {
-    model?: KnownModelRef
+    model?: ModelRef | string
     // Omitted on the OAuth path — credentials live in secrets.json via the OAuth runner.
     apiKey?: string
-    visionModel?: KnownModelRef
+    visionModel?: ModelRef | string
     visionApiKey?: string
     discordBotToken?: string
     slackBotToken?: string