typeclaw 0.1.0

package/src/config/config.ts

@@ -0,0 +1,424 @@
+import { accessSync, constants as fsConstants, readFileSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { isAbsolute, join, resolve } from 'node:path'
+
+import type { Model } from '@mariozechner/pi-ai'
+import { z } from 'zod'
+
+import { channelsSchema } from '@/channels/schema'
+
+import {
+  DEFAULT_MODEL_REF,
+  KNOWN_PROVIDERS,
+  listKnownModelRefs,
+  type KnownModelRef,
+  type KnownProviderId,
+} from './providers'
+
+const CONFIG_FILE = 'typeclaw.json'
+
+const knownModelRefs = listKnownModelRefs() as [KnownModelRef, ...KnownModelRef[]]
+
+// T9 keypad: T=8, Y=9, P=7, E=3
+const DEFAULT_PORT = 8973
+
+// Mount names land on disk as `mounts/<name>` inside the agent folder, so they
+// share a namespace with regular filenames. Restricting to lowercase
+// alphanumerics + `-`/`_` keeps them shell-safe and avoids accidental shadowing
+// of files like `mounts/.git` or `mounts/Hello`.
+const MOUNT_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]*$/
+
+export const mountSchema = z.object({
+  name: z.string().regex(MOUNT_NAME_PATTERN, 'mount name must be lowercase alphanumeric with - or _'),
+  path: z.string().min(1),
+  readOnly: z.boolean().default(false),
+  description: z.string().optional(),
+})
+
+export type Mount = z.infer<typeof mountSchema>
+
+const portNumber = z.number().int().min(1).max(65535)
+
+// `allow` is the discriminator between "forward everything" ('*') and a fixed
+// allowlist (number[]). `deny` is only meaningful when allow === '*'; combining
+// it with a number[] allow is rejected at parse time so a typo doesn't silently
+// drop the deny rule. An empty allowlist (`allow: []`) is the off switch.
+export const portForwardSchema = z
+  .object({
+    allow: z.union([z.literal('*'), z.array(portNumber)]),
+    deny: z.array(portNumber).optional(),
+  })
+  .refine((v) => !(Array.isArray(v.allow) && v.deny !== undefined && v.deny.length > 0), {
+    message: 'portForward.deny is only meaningful when allow is "*"; remove deny or set allow to "*"',
+    path: ['deny'],
+  })
+  .default({ allow: '*' })
+
+export type PortForward = z.infer<typeof portForwardSchema>
+
+const dockerfileLineSchema = z.string().refine((line) => !/[\r\n]/.test(line), {
+  message: 'dockerfile.append entries must be single Dockerfile lines; split multiline instructions into array entries',
+})
+
+// A feature toggle is either a boolean (install latest / don't install) or a
+// version string that becomes an apt pin (`pkg=<version>`). The string form
+// rejects whitespace and `=` so the `pkg=<version>` invocation we pass to
+// apt-get cannot be smuggled into a separate package or option flag.
+const dockerfileFeatureSchema = z.union([
+  z.boolean(),
+  z
+    .string()
+    .min(1)
+    .refine((v) => !/[\s=]/.test(v), {
+      message: 'dockerfile feature version strings must not contain whitespace or "="',
+    }),
+])
+
+// `default(() => ({}))` paired with field-level defaults is the idiom that
+// makes both `dockerfile: {}` and an omitted `dockerfile` key resolve to the
+// SAME fully-populated object. A plain `.default({})` would short-circuit the
+// inner field defaults when the key is omitted, leaving downstream code with
+// `{ append: undefined, tmux: undefined, ... }` and a `lines.length` crash.
+const dockerfileObjectSchema = z.object({
+  ffmpeg: dockerfileFeatureSchema.default(false),
+  gh: dockerfileFeatureSchema.default(true),
+  python: z.boolean().default(true),
+  tmux: dockerfileFeatureSchema.default(true),
+  append: z.array(dockerfileLineSchema).default([]),
+})
+
+export const dockerfileSchema = dockerfileObjectSchema.default(() => dockerfileObjectSchema.parse({}))
+
+export type DockerfileConfig = z.infer<typeof dockerfileSchema>
+export type DockerfileFeatureToggle = z.infer<typeof dockerfileFeatureSchema>
+
+const gitignoreLineSchema = z.string().refine((line) => !/[\r\n]/.test(line), {
+  message: 'gitignore.append entries must be single gitignore lines; split multiline patterns into array entries',
+})
+
+export const gitignoreSchema = z
+  .object({
+    append: z.array(gitignoreLineSchema).default([]),
+  })
+  .default({ append: [] })
+
+export type GitignoreConfig = z.infer<typeof gitignoreSchema>
+
+export const configSchema = z
+  .object({
+    $schema: z.string().optional(),
+    port: z.number().int().min(1).max(65535).default(DEFAULT_PORT),
+    model: z.enum(knownModelRefs).default(DEFAULT_MODEL_REF),
+    // 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.
+    mounts: z.array(mountSchema).default([]),
+    plugins: z.array(z.string().min(1)).default([]),
+    // Additional names the agent answers to in channel engagement, on top
+    // of `basename(agentDir)` which is always implicit. Each entry is a
+    // plain string matched case-insensitively as a substring of the
+    // inbound text. Empty/whitespace-only entries are rejected at parse
+    // time. Defaults to `[]`. Hatching appends the agent's chosen name
+    // here, so a freshly-hatched bot already has its identity wired up.
+    alias: z.array(z.string().trim().min(1)).default([]),
+    channels: channelsSchema,
+    portForward: portForwardSchema,
+    dockerfile: dockerfileSchema,
+    gitignore: gitignoreSchema,
+  })
+  .catchall(z.unknown())
+
+export type Config = z.infer<typeof configSchema>
+
+export function resolveModel(ref: KnownModelRef): Model<'openai-completions'> | Model<'openai-responses'> {
+  // Model IDs can contain '/', so split only on the first separator.
+  const slash = ref.indexOf('/')
+  const providerId = ref.slice(0, slash) as KnownProviderId
+  const modelId = ref.slice(slash + 1)
+  return KNOWN_PROVIDERS[providerId].models[modelId as never]
+}
+
+// Resolves a mount's `path` field to an absolute host path, mirroring shell
+// expansion rules: `~`/`~/...` → home dir, relative → resolved against `cwd`,
+// absolute → unchanged. Single source of truth so validation and Docker arg
+// building agree on the resolved path.
+export function expandMountPath(input: string, cwd: string): string {
+  if (input === '~' || input.startsWith('~/')) {
+    return join(homedir(), input.slice(1))
+  }
+  return isAbsolute(input) ? input : resolve(cwd, input)
+}
+
+// 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.
+//
+// `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())
+
+let current: Config = config
+
+export function getConfig(): Config {
+  return current
+}
+
+// Test-only: restore the live pointer to the module-import-time snapshot. Lets
+// reload-aware tests run without leaking a swapped pointer into other test
+// files that still mutate the eager `config` export directly.
+export function __resetConfigForTesting(): void {
+  current = config
+}
+
+export type ConfigChange = {
+  path: string
+  before: unknown
+  after: unknown
+}
+
+export type ConfigReloadDiff = {
+  applied: ConfigChange[]
+  restartRequired: ConfigChange[]
+  ignored: ConfigChange[]
+}
+
+// Reloads typeclaw.json from disk and atomically swaps the live config pointer
+// on success. Throws (and leaves `current` untouched) when the file is
+// malformed or schema-invalid — callers translate that into a `Reloadable`
+// failure result.
+export function reloadConfig(cwd: string): ConfigReloadDiff {
+  const next = loadConfigSync(cwd)
+  const diff = diffConfig(current, next)
+  current = next
+  return diff
+}
+
+// Field classification. The fence is intentional: only fields that are read
+// fresh on each session/subagent/cron-reload land in `applied`. Boot-only
+// fields (port, mounts, container/server bind) are reported as
+// `restartRequired` so the user knows the reload landed but the change won't
+// take effect until restart.
+export type FieldEffect = 'applied' | 'restart-required' | 'ignored'
+
+export const FIELD_EFFECTS: Record<string, FieldEffect> = {
+  $schema: 'ignored',
+  model: 'applied',
+  port: 'restart-required',
+  mounts: 'restart-required',
+  plugins: 'restart-required',
+  alias: 'applied',
+  channels: 'applied',
+  portForward: 'restart-required',
+  dockerfile: 'restart-required',
+  gitignore: 'restart-required',
+}
+
+// Stable JSON for value comparison. Fields are small JSON-shaped objects, so
+// JSON.stringify with sorted keys is sufficient and avoids a deep-equal dep.
+function stableStringify(value: unknown): string {
+  if (value === undefined) return 'undefined'
+  return JSON.stringify(value, (_key, v: unknown) => {
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      const sorted: Record<string, unknown> = {}
+      for (const k of Object.keys(v as Record<string, unknown>).sort()) {
+        sorted[k] = (v as Record<string, unknown>)[k]
+      }
+      return sorted
+    }
+    return v
+  })
+}
+
+function diffConfig(before: Config, after: Config): ConfigReloadDiff {
+  const diff: ConfigReloadDiff = { applied: [], restartRequired: [], ignored: [] }
+  const keys = new Set<string>(Object.keys(FIELD_EFFECTS))
+
+  for (const path of keys) {
+    const b = readPath(before, path)
+    const a = readPath(after, path)
+    if (stableStringify(b) === stableStringify(a)) continue
+
+    const change: ConfigChange = { path, before: b, after: a }
+    const effect = FIELD_EFFECTS[path] ?? 'applied'
+    if (effect === 'applied') diff.applied.push(change)
+    else if (effect === 'restart-required') diff.restartRequired.push(change)
+    else diff.ignored.push(change)
+  }
+
+  return diff
+}
+
+function readPath(obj: unknown, path: string): unknown {
+  let cur: unknown = obj
+  for (const part of path.split('.')) {
+    if (cur === null || cur === undefined) return undefined
+    cur = (cur as Record<string, unknown>)[part]
+  }
+  return cur
+}
+
+// Plugin configs live at the top level of typeclaw.json keyed by plugin name
+// (e.g. "standup-log": { ... }). They are preserved by configSchema.catchall(z.unknown())
+// because the schema does not predeclare these keys. This helper returns the
+// raw map of unknown values keyed by plugin name; the plugin loader re-validates
+// each block against its plugin's `configSchema`.
+export function extractPluginConfigs(raw: unknown): Record<string, unknown> {
+  if (typeof raw !== 'object' || raw === null) return {}
+  const known = new Set([
+    '$schema',
+    'port',
+    'model',
+    'mounts',
+    'plugins',
+    'channels',
+    'portForward',
+    'dockerfile',
+    'gitignore',
+  ])
+  const result: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(raw as Record<string, unknown>)) {
+    if (!known.has(key)) result[key] = value
+  }
+  return result
+}
+
+export function loadPluginConfigsSync(cwd: string): Record<string, unknown> {
+  let raw: string
+  try {
+    raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
+  } catch {
+    return {}
+  }
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch {
+    return {}
+  }
+  return extractPluginConfigs(json)
+}
+
+export function loadConfigSync(cwd: string): Config {
+  let raw: string
+  try {
+    raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
+  } catch {
+    return configSchema.parse({})
+  }
+
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    throw new Error(`${CONFIG_FILE} is not valid JSON: ${detail}`)
+  }
+
+  const result = configSchema.safeParse(json)
+  if (!result.success) {
+    throw new Error(`${CONFIG_FILE} is invalid: ${formatZodError(result.error)}`)
+  }
+  return result.data
+}
+
+export type ValidateConfigResult = { ok: true } | { ok: false; reason: string }
+
+// Missing file → ok (matches `loadMounts` in src/container/up.ts; `isInitialized`
+// is the dedicated check for "not initialized"). Present but invalid → fail, so
+// `restart` doesn't stop the container before discovering the config is broken.
+//
+// Mount accessibility is checked here (after schema parse succeeds) so every
+// caller — `typeclaw start`, `restart`, `reload`, hostd's restart RPC — fails
+// fast with a clear, mount-named error instead of letting Docker surface a
+// confusing path-sharing error (or, on some Linux setups, silently bind-mount
+// an empty auto-created directory). First-failure reporting matches the
+// schema-error path's shape; users fix one and re-run.
+export function validateConfig(cwd: string): ValidateConfigResult {
+  let raw: string
+  try {
+    raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
+  } catch {
+    return { ok: true }
+  }
+
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error)
+    return { ok: false, reason: `${CONFIG_FILE} is not valid JSON: ${detail}` }
+  }
+
+  const result = configSchema.safeParse(json)
+  if (!result.success) {
+    return { ok: false, reason: `${CONFIG_FILE} is invalid: ${formatZodError(result.error)}` }
+  }
+
+  for (const mount of result.data.mounts) {
+    const check = validateMount(mount, cwd)
+    if (!check.ok) return check
+  }
+
+  return { ok: true }
+}
+
+// Verifies a mount's host path: exists, is a directory, is readable, and is
+// writable when not declared `readOnly`. Symlinks are followed (statSync's
+// default) so a broken symlink reads as "does not exist". Permission checks
+// are skipped when running as root (uid 0) — euidaccess returns success
+// regardless, so the test would be vacuous and inconsistent with non-root.
+export function validateMount(mount: Mount, cwd: string): ValidateConfigResult {
+  const resolved = expandMountPath(mount.path, cwd)
+  const label = `mount "${mount.name}"`
+
+  let stats: ReturnType<typeof statSync>
+  try {
+    stats = statSync(resolved)
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code
+    if (code === 'ENOENT') {
+      return { ok: false, reason: `${label}: path ${resolved} does not exist` }
+    }
+    const detail = error instanceof Error ? error.message : String(error)
+    return { ok: false, reason: `${label}: cannot stat ${resolved}: ${detail}` }
+  }
+
+  if (!stats.isDirectory()) {
+    return { ok: false, reason: `${label}: path ${resolved} is not a directory` }
+  }
+
+  const isRoot = typeof process.getuid === 'function' && process.getuid() === 0
+  if (isRoot) return { ok: true }
+
+  try {
+    accessSync(resolved, fsConstants.R_OK)
+  } catch {
+    return { ok: false, reason: `${label}: path ${resolved} is not readable` }
+  }
+
+  if (!mount.readOnly) {
+    try {
+      accessSync(resolved, fsConstants.W_OK)
+    } catch {
+      return {
+        ok: false,
+        reason: `${label}: path ${resolved} is not writable (declare readOnly: true if read-only access is intended)`,
+      }
+    }
+  }
+
+  return { ok: true }
+}
+
+function formatZodError(error: z.ZodError): string {
+  return error.issues
+    .map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '<root>'
+      return `${path}: ${issue.message}`
+    })
+    .join('; ')
+}

package/src/config/index.ts

@@ -0,0 +1,25 @@
+export {
+  config,
+  configSchema,
+  expandMountPath,
+  extractPluginConfigs,
+  getConfig,
+  loadConfigSync,
+  loadPluginConfigsSync,
+  mountSchema,
+  dockerfileSchema,
+  portForwardSchema,
+  reloadConfig,
+  resolveModel,
+  validateConfig,
+  validateMount,
+  type Config,
+  type ConfigChange,
+  type ConfigReloadDiff,
+  type DockerfileConfig,
+  type Mount,
+  type PortForward,
+  type ValidateConfigResult,
+} from './config'
+export { type KnownModelRef, type KnownProviderId } from './providers'
+export { createConfigReloadable, type CreateConfigReloadableOptions } from './reloadable'

package/src/config/providers.ts

@@ -0,0 +1,234 @@
+import type { Api, Model } from '@mariozechner/pi-ai'
+
+// Authentication mechanism a provider supports. `api-key` reads a static key
+// from .env (the original path); `oauth` runs a browser flow at init time and
+// stores rotating credentials in secrets.json. The CLI picker uses this to ask
+// "API key or OAuth?" only when both are wired up.
+export type AuthMethod = 'api-key' | 'oauth'
+
+// `apiKeyEnv` and `oauthProviderId` are both always present on the literal
+// to keep `as const satisfies` narrowing easy on the consumer side; entries
+// that don't apply to a given provider are set to `null` rather than omitted.
+// Consumers check `auth.includes('api-key')` / `auth.includes('oauth')` to
+// decide which field to consult.
+type KnownProvider = {
+  id: string
+  name: string
+  baseUrl: string
+  auth: ReadonlyArray<AuthMethod>
+  apiKeyEnv: string | null
+  oauthProviderId: string | null
+  models: Record<string, Model<Api>>
+}
+
+// Curated allowlist of providers + models that are wired into the agent
+// runtime. The values here back the Zod enum on `configSchema.model`, so any
+// model the user can put in `typeclaw.json` MUST appear here verbatim. The
+// init-time picker may surface additional models from models.dev, but it
+// resolves them through this list before scaffolding (anything missing falls
+// back to a curated default).
+//
+// Adding a new model: append it to the matching provider's `models` map. Each
+// model object is the literal `Model<...>` that pi-ai consumes — keep it
+// faithful to https://github.com/mariozechner/pi-ai (the readme's "Custom
+// Models" section). `setRuntimeApiKey(provider, key)` keys off the `provider`
+// field, so it MUST match the outer provider id.
+//
+// Adding a new provider: add a top-level entry. Set `auth` to the supported
+// methods. For `api-key` providers, `apiKeyEnv` is the .env var typeclaw
+// writes at init and reads at boot (match the upstream provider's standard,
+// e.g. `OPENAI_API_KEY`). For `oauth` providers, `oauthProviderId` MUST match
+// a pi-ai OAuth provider id exactly, otherwise `authStorage.login()` will
+// throw "Unknown OAuth provider".
+export const KNOWN_PROVIDERS = {
+  openai: {
+    id: 'openai',
+    name: 'OpenAI',
+    // OpenAI's library auto-detects this from `provider: 'openai'`, but we
+    // store it explicitly so the init wizard can show users which endpoint
+    // their key will hit.
+    baseUrl: 'https://api.openai.com/v1',
+    auth: ['api-key'],
+    apiKeyEnv: 'OPENAI_API_KEY',
+    oauthProviderId: null,
+    // Costs and context windows mirror models.dev as of 2026-05-10. When
+    // refreshing, also rerun `scripts/generate-schema.ts` so typeclaw.schema.json
+    // picks up new enum values.
+    models: {
+      // Default. Cheapest tool-calling reasoning model in the family;
+      // available on every paid OpenAI account tier.
+      'gpt-5.4-nano': {
+        id: 'gpt-5.4-nano',
+        name: 'GPT-5.4 nano',
+        api: 'openai-responses',
+        provider: 'openai',
+        baseUrl: 'https://api.openai.com/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0.2, output: 1.25, cacheRead: 0.02, cacheWrite: 0 },
+        contextWindow: 400000,
+        maxTokens: 128000,
+      },
+      'gpt-5.4-mini': {
+        id: 'gpt-5.4-mini',
+        name: 'GPT-5.4 mini',
+        api: 'openai-responses',
+        provider: 'openai',
+        baseUrl: 'https://api.openai.com/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+        contextWindow: 400000,
+        maxTokens: 128000,
+      },
+      'gpt-5.4': {
+        id: 'gpt-5.4',
+        name: 'GPT-5.4',
+        api: 'openai-responses',
+        provider: 'openai',
+        baseUrl: 'https://api.openai.com/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+        contextWindow: 1050000,
+        maxTokens: 128000,
+      },
+      'gpt-5.5': {
+        id: 'gpt-5.5',
+        name: 'GPT-5.5',
+        api: 'openai-responses',
+        provider: 'openai',
+        baseUrl: 'https://api.openai.com/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+        contextWindow: 1050000,
+        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.
+  //
+  // pi-ai 0.73.1's `openai-codex` bucket carries gpt-5.5 (and 5.4) against
+  // chatgpt.com/backend-api. We pin pi-coding-agent ^0.67.3 today, which
+  // ships pi-ai 0.67.3 and lacks those entries — but we hand pi-ai a
+  // freshly-constructed `Model<>` literal via resolveModel(), bypassing its
+  // built-in catalog entirely (same trick we use for kimi-k2p6-turbo). So
+  // these ids work end-to-end as long as the Codex backend itself accepts
+  // them, which it does for ChatGPT Plus/Pro accounts as of 2026-05-10.
+  'openai-codex': {
+    id: 'openai-codex',
+    name: 'OpenAI Codex (ChatGPT Plus/Pro)',
+    baseUrl: 'https://chatgpt.com/backend-api',
+    auth: ['oauth'],
+    apiKeyEnv: null,
+    oauthProviderId: 'openai-codex',
+    models: {
+      'gpt-5.4-mini': {
+        id: 'gpt-5.4-mini',
+        name: 'GPT-5.4 mini',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0.75, output: 4.5, cacheRead: 0.075, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+      'gpt-5.4': {
+        id: 'gpt-5.4',
+        name: 'GPT-5.4',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 2.5, output: 15, cacheRead: 0.25, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+      'gpt-5.5': {
+        id: 'gpt-5.5',
+        name: 'GPT-5.5',
+        api: 'openai-codex-responses',
+        provider: 'openai-codex',
+        baseUrl: 'https://chatgpt.com/backend-api',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 5, output: 30, cacheRead: 0.5, cacheWrite: 0 },
+        contextWindow: 272000,
+        maxTokens: 128000,
+      },
+    },
+  },
+  fireworks: {
+    id: 'fireworks',
+    name: 'Fireworks',
+    baseUrl: 'https://api.fireworks.ai/inference/v1',
+    auth: ['api-key'],
+    apiKeyEnv: 'FIREWORKS_API_KEY',
+    oauthProviderId: null,
+    models: {
+      // Kept available even though models.dev hasn't indexed it yet —
+      // Fireworks ships this router as an alias to the latest k2.6 weights.
+      'accounts/fireworks/routers/kimi-k2p6-turbo': {
+        id: 'accounts/fireworks/routers/kimi-k2p6-turbo',
+        name: 'Kimi K2.6 Turbo',
+        api: 'openai-completions',
+        provider: 'fireworks',
+        baseUrl: 'https://api.fireworks.ai/inference/v1',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 256000,
+        maxTokens: 256000,
+      },
+    },
+  },
+} as const satisfies Record<string, KnownProvider>
+
+export type KnownProviderId = keyof typeof KNOWN_PROVIDERS
+
+export type KnownModelRef = {
+  [P in KnownProviderId]: `${P}/${Extract<keyof (typeof KNOWN_PROVIDERS)[P]['models'], string>}`
+}[KnownProviderId]
+
+export function listKnownModelRefs(): KnownModelRef[] {
+  const refs: string[] = []
+  for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
+    for (const modelId of Object.keys(KNOWN_PROVIDERS[providerId].models)) {
+      refs.push(`${providerId}/${modelId}`)
+    }
+  }
+  return refs as KnownModelRef[]
+}
+
+// The default we hand to scaffolded `typeclaw.json` and the schema's
+// `model.default`. Lives here (next to the provider table) so adding a model
+// can't drift from the field default — both come from the same module.
+export const DEFAULT_MODEL_REF: KnownModelRef = 'openai/gpt-5.4-nano'
+
+export function providerForModelRef(ref: KnownModelRef): KnownProviderId {
+  // KnownModelRef is `${provider}/${modelId}`, but provider IDs themselves can
+  // contain '-' and model IDs can contain '/' (Fireworks). We split on the
+  // first slash that follows a registered provider id.
+  for (const providerId of Object.keys(KNOWN_PROVIDERS) as KnownProviderId[]) {
+    if (ref.startsWith(`${providerId}/`)) return providerId
+  }
+  throw new Error(`Unknown provider in model ref: ${ref}`)
+}
+
+// `as const satisfies` narrows each entry's `auth` to a tuple of its specific
+// literal values, which makes `provider.auth.includes('oauth')` fail to
+// compile on api-key-only entries (because TS thinks the array can never
+// contain 'oauth'). These accessors widen the membership check back to
+// AuthMethod so consumers can branch without per-provider casts.
+export function supportsApiKey(provider: { auth: ReadonlyArray<AuthMethod> }): boolean {
+  return (provider.auth as ReadonlyArray<AuthMethod>).includes('api-key')
+}
+
+export function supportsOAuth(provider: { auth: ReadonlyArray<AuthMethod> }): boolean {
+  return (provider.auth as ReadonlyArray<AuthMethod>).includes('oauth')
+}