typeclaw 0.36.8 → 0.37.1

package/src/cli/provider.ts

@@ -1,4 +1,4 @@
-import { cancel, intro, isCancel, log, password, select } from '@clack/prompts'
+import { autocomplete, cancel, intro, isCancel, log, password, select } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import {
@@ -282,8 +282,9 @@ async function resolveProviderForAdd(input: string | undefined): Promise<KnownPr
 
 async function pickVendorToAdd(): Promise<KnownProviderVendorId> {
   const vendorIds = listKnownProviderVendorIds()
-  const choice = await select<KnownProviderVendorId>({
+  const choice = await autocomplete<KnownProviderVendorId>({
     message: 'Pick a provider to add',
+    placeholder: 'Type to search…',
     options: vendorIds.map((id) => ({
       value: id,
       label: KNOWN_PROVIDER_VENDORS[id].name,
@@ -301,8 +302,9 @@ async function pickVendorToAdd(): Promise<KnownProviderVendorId> {
 async function pickVariantToAdd(vendorId: KnownProviderVendorId): Promise<KnownProviderId> {
   const variants = providerIdsForVendor(vendorId)
   if (variants.length === 1) return variants[0]!
-  const choice = await select<KnownProviderId>({
+  const choice = await autocomplete<KnownProviderId>({
     message: `Pick a ${KNOWN_PROVIDER_VENDORS[vendorId].name} option`,
+    placeholder: 'Type to search…',
     options: variants.map((id) => {
       const hint = variantHint(vendorId, id)
       return hint !== undefined

package/src/cli/restart.ts

@@ -1,9 +1,11 @@
+import { confirm, isCancel } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import { config, validateConfig } from '@/config'
 import { start, stop } from '@/container'
 import { findAgentDir, isInitialized } from '@/init'
 
+import { guardIncompleteInit } from './incomplete-init'
 import { c, errorLine, renderStartSuccess, spinner } from './ui'
 
 export const restartCommand = defineCommand({
@@ -27,6 +29,28 @@ export const restartCommand = defineCommand({
   async run({ args }) {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
 
+    // Runs before BOTH isInitialized and stop. A wizard abort persists a
+    // checkpoint before scaffold writes typeclaw.json, so a checkpoint-but-no-
+    // config dir is an incomplete init that should get resume guidance, not the
+    // generic config-missing error — and a half-init agent usually has no
+    // container to stop. A `continue` falls through to isInitialized, which
+    // still catches a truly uninitialized dir.
+    const guard = await guardIncompleteInit({
+      cwd,
+      interactive: Boolean(process.stdout.isTTY),
+      confirmContinue: async () => {
+        const proceed = await confirm({ message: 'Try restarting anyway?', initialValue: false })
+        return !isCancel(proceed) && proceed === true
+      },
+    })
+    if (guard.action === 'block') {
+      console.error(errorLine(guard.message))
+      process.exit(1)
+    }
+    if (guard.action === 'abort') {
+      process.exit(0)
+    }
+
     if (!isInitialized(cwd)) {
       console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first.'))
       process.exit(1)

package/src/cli/start.ts

@@ -1,9 +1,11 @@
+import { confirm, isCancel } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import { config, validateConfig } from '@/config'
 import { start } from '@/container'
 import { findAgentDir, isInitialized } from '@/init'
 
+import { guardIncompleteInit } from './incomplete-init'
 import { errorLine, renderStartSuccess, spinner } from './ui'
 
 export const startCommand = defineCommand({
@@ -27,6 +29,28 @@ export const startCommand = defineCommand({
   async run({ args }) {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
 
+    // Runs BEFORE the isInitialized check: a wizard abort persists a checkpoint
+    // before scaffold writes typeclaw.json, so a checkpoint-but-no-config dir is
+    // an incomplete init, not a "never initialized" one. Guarding first means
+    // that case gets the resume guidance instead of the generic config-missing
+    // error. A `continue` (no incomplete checkpoint, or "try anyway") falls
+    // through to isInitialized, which still catches a truly uninitialized dir.
+    const guard = await guardIncompleteInit({
+      cwd,
+      interactive: Boolean(process.stdout.isTTY),
+      confirmContinue: async () => {
+        const proceed = await confirm({ message: 'Try starting anyway?', initialValue: false })
+        return !isCancel(proceed) && proceed === true
+      },
+    })
+    if (guard.action === 'block') {
+      console.error(errorLine(guard.message))
+      process.exit(1)
+    }
+    if (guard.action === 'abort') {
+      process.exit(0)
+    }
+
     if (!isInitialized(cwd)) {
       console.error(errorLine('TypeClaw config file not found. Run `typeclaw init` first.'))
       process.exit(1)

package/src/cli/tunnel.ts

@@ -5,7 +5,7 @@ import { select, text, password, isCancel, cancel, log } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
 import { loadConfigSync, validateConfig } from '@/config'
-import { resolveHostPort, resolveTuiToken } from '@/container'
+import { CONTAINER_PORT, resolveHostPort, resolveTuiToken } from '@/container'
 import { appendOrReplaceEnvKey, findAgentDir, hasEnvKey, isInitialized } from '@/init'
 import type { ClientMessage, ServerMessage, TunnelLogsServerMessage, TunnelSnapshot } from '@/shared'
 import type { TunnelConfig, TunnelFor, TunnelProvider } from '@/tunnels'
@@ -921,13 +921,32 @@ async function withTuiSocket<T>(
   }
 }
 
-async function resolveWsUrl(cwd: string, input?: string, pathname = '/'): Promise<LiveResult<string>> {
+async function resolveWsUrl(
+  cwd: string,
+  input?: string,
+  pathname = '/',
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<LiveResult<string>> {
   try {
-    const url = input === undefined ? new URL(`ws://127.0.0.1:${await resolveHostPort({ cwd })}`) : new URL(input)
-    if (input === undefined) {
-      const token = await resolveTuiToken({ cwd })
-      if (token !== null) url.searchParams.set('token', token)
+    if (input !== undefined) {
+      const url = new URL(input)
+      url.pathname = pathname
+      return { ok: true, value: url.toString() }
     }
+    // In-container short-circuit: when the agent runs `typeclaw tunnel …` from
+    // inside its own container (the only way it CAN run it), `docker` is not on
+    // $PATH, so the host-side discovery below (resolveHostPort/resolveTuiToken,
+    // which both shell out to `docker`) fails and the websocket connect aborts
+    // with the opaque `[object ErrorEvent]`. typeclaw's `docker run` sets
+    // TYPECLAW_CONTAINER_NAME (always) and TYPECLAW_TUI_TOKEN (when configured),
+    // and the agent's WS server listens on CONTAINER_PORT on the container
+    // loopback — so we can dial directly without docker. Mirrors the same
+    // short-circuit in src/cron/bridge.ts (resolveInContainerUrl).
+    const inContainer = resolveInContainerWsUrl(env, pathname)
+    if (inContainer !== null) return { ok: true, value: inContainer }
+    const url = new URL(`ws://127.0.0.1:${await resolveHostPort({ cwd })}`)
+    const token = await resolveTuiToken({ cwd })
+    if (token !== null) url.searchParams.set('token', token)
     url.pathname = pathname
     return { ok: true, value: url.toString() }
   } catch (err) {
@@ -935,6 +954,17 @@ async function resolveWsUrl(cwd: string, input?: string, pathname = '/'): Promis
   }
 }
 
+// Returns null on the host stage (TYPECLAW_CONTAINER_NAME unset), where the
+// docker-based discovery in resolveWsUrl is the right path.
+export function resolveInContainerWsUrl(env: NodeJS.ProcessEnv, pathname = '/'): string | null {
+  if (env.TYPECLAW_CONTAINER_NAME === undefined) return null
+  const url = new URL(`ws://127.0.0.1:${CONTAINER_PORT}`)
+  const token = env.TYPECLAW_TUI_TOKEN
+  if (token !== undefined && token !== '') url.searchParams.set('token', token)
+  url.pathname = pathname
+  return url.toString()
+}
+
 function waitForOpen(ws: WebSocket, timeoutMs: number): Promise<void> {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => reject(new Error('timed out connecting to agent websocket')), timeoutMs)
@@ -948,15 +978,30 @@ function waitForOpen(ws: WebSocket, timeoutMs: number): Promise<void> {
     )
     ws.addEventListener(
       'error',
-      (err) => {
+      (event) => {
         clearTimeout(timer)
-        reject(err)
+        reject(new Error(describeWsErrorEvent(event)))
       },
       { once: true },
     )
   })
 }
 
+// A WebSocket 'error' listener fires with an ErrorEvent, NOT an Error. Passing
+// it straight to a catch site that does `String(err)` yields the useless
+// `[object ErrorEvent]`. Pull the real message out (`.message`, or the nested
+// `.error`) so failures read like `Expected 101 status code` / connection
+// refused instead.
+function describeWsErrorEvent(event: unknown): string {
+  if (event instanceof Error) return event.message
+  if (typeof event === 'object' && event !== null) {
+    const { message, error } = event as { message?: unknown; error?: unknown }
+    if (typeof message === 'string' && message !== '') return message
+    if (error instanceof Error && error.message !== '') return error.message
+  }
+  return 'websocket connection failed'
+}
+
 function waitForServerMessage(
   ws: WebSocket,
   timeoutMs: number,

package/src/config/config.ts

@@ -2,7 +2,7 @@ import { accessSync, constants as fsConstants, readFileSync, statSync, writeFile
 import { homedir } from 'node:os'
 import { isAbsolute, join, posix, resolve } from 'node:path'
 
-import type { Model } from '@mariozechner/pi-ai'
+import type { KnownApi, Model } from '@mariozechner/pi-ai'
 import { z } from 'zod'
 
 import { channelsSchema, SEEDED_GITHUB_EVENT_ALLOWLISTS } from '@/channels/schema'
@@ -13,9 +13,12 @@ import { secretFieldSchema } from '@/secrets/resolve'
 import {
   DEFAULT_MODEL_REF,
   KNOWN_PROVIDERS,
+  isKnownModelRef,
+  isModelRef,
   listKnownModelRefs,
   type KnownModelRef,
-  type KnownProviderId,
+  type ModelRef,
+  providerForModelRef,
 } from './providers'
 
 const CONFIG_FILE = 'typeclaw.json'
@@ -574,16 +577,55 @@ const tunnelsArraySchema = z
     }
   })
 
-// `models` maps a profile name to one or more curated model refs. The
+const customModelCostSchema = z
+  .object({
+    input: z.number().optional(),
+    output: z.number().optional(),
+    cacheRead: z.number().optional(),
+    cacheWrite: z.number().optional(),
+  })
+  .catchall(z.unknown())
+
+export const customModelMetaSchema = z
+  .object({
+    name: z.string().min(1).optional(),
+    reasoning: z.boolean().optional(),
+    input: z.array(z.string().min(1)).optional(),
+    contextWindow: z.number().optional(),
+    maxTokens: z.number().optional(),
+    cost: customModelCostSchema.optional(),
+  })
+  .catchall(z.unknown())
+
+export type CustomModelMeta = z.infer<typeof customModelMetaSchema>
+
+export const customModelsSchema = z.record(z.string().min(1), customModelMetaSchema).default({})
+
+export type CustomModels = z.infer<typeof customModelsSchema>
+
+const customModelRefSchema = z.string().refine((ref) => isModelRef(ref), {
+  message: 'model ref must be "<known-provider>/<model-id>" with a known provider',
+})
+
+const singleModelRef = z.union([z.enum(knownModelRefs), customModelRefSchema])
+
+function asModelRef(value: string): ModelRef {
+  if (isModelRef(value)) return value
+  throw new Error(`Invalid model ref: ${value}`)
+}
+
+// `models` maps a profile name to one or more model refs. Curated refs keep
+// editor autocomplete through the enum branch, while custom refs are allowed
+// when they target a known provider.
 // `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
+// Each value is either a single model ref 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[]`.
+// non-empty array so downstream consumers read a uniform `ModelRef[]`.
 //
 // Profile names are open strings; the runtime recognizes a handful of
 // well-known names by convention (`default`, `fast`, `deep`, `vision`) but
@@ -596,9 +638,9 @@ const tunnelsArraySchema = z
 // `persistMigratedConfig`), so every downstream consumer sees the new shape.
 const modelRefOrChainSchema = z
   .union([
-    z.enum(knownModelRefs),
+    singleModelRef,
     z
-      .array(z.enum(knownModelRefs))
+      .array(singleModelRef)
       .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
@@ -609,7 +651,7 @@ const modelRefOrChainSchema = z
         message: 'models chain must not contain duplicate refs',
       }),
   ])
-  .transform((value) => (Array.isArray(value) ? value : [value]))
+  .transform((value) => (Array.isArray(value) ? value : [value]).map((ref) => asModelRef(ref)))
 export const modelsSchema = z
   .record(z.string().min(1), modelRefOrChainSchema)
   .refine((m) => 'default' in m, { message: 'models.default is required' })
@@ -617,7 +659,7 @@ export const modelsSchema = z
 // 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 type Models = Record<string, ModelRef[]> & { default: ModelRef[] }
 
 export const configSchema = z
   .object({
@@ -626,9 +668,10 @@ export const configSchema = z
     // `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. The default value is
-    // shaped to match the post-transform output (always `KnownModelRef[]`),
+    // shaped to match the post-transform output (always `ModelRef[]`),
     // not the user-facing input shape.
-    models: modelsSchema.default(() => ({ default: [DEFAULT_MODEL_REF] })) as unknown as z.ZodType<Models>,
+    models: modelsSchema.default(() => ({ default: [asModelRef(DEFAULT_MODEL_REF)] })) as unknown as z.ZodType<Models>,
+    customModels: customModelsSchema,
     // 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.
@@ -656,12 +699,58 @@ export const configSchema = z
 
 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]
+export function resolveModel(ref: KnownModelRef | ModelRef | string): Model<KnownApi> {
+  const providerId = providerForModelRef(ref)
+  const modelId = ref.slice(providerId.length + 1)
+  const provider = KNOWN_PROVIDERS[providerId]
+  if (isKnownModelRef(ref)) {
+    const model = (provider.models as Record<string, Model<KnownApi>>)[modelId]
+    if (model !== undefined) return model
+  }
+
+  if (!isModelRef(ref)) {
+    throw new Error(`Invalid model ref "${ref}". Expected "<known-provider>/<model-id>".`)
+  }
+
+  const templateModelId = Object.keys(provider.models)[0]
+  if (templateModelId === undefined) {
+    throw new Error(`Provider ${providerId} has no curated models to use as a transport template`)
+  }
+  const template = (provider.models as Record<string, Model<KnownApi>>)[templateModelId]
+  if (template === undefined) {
+    throw new Error(`Provider ${providerId} has no curated models to use as a transport template`)
+  }
+
+  const meta = getConfig().customModels[ref]
+  return {
+    id: modelId,
+    provider: providerId,
+    baseUrl: provider.baseUrl ?? template.baseUrl,
+    api: template.api,
+    name: meta?.name ?? modelId,
+    reasoning: meta?.reasoning ?? false,
+    input: resolveCustomModelInput(meta?.input),
+    contextWindow: meta?.contextWindow ?? template.contextWindow,
+    maxTokens: meta?.maxTokens ?? template.maxTokens,
+    cost: resolveCustomModelCost(meta?.cost),
+  }
+}
+
+function resolveCustomModelInput(input: readonly string[] | undefined): Model<KnownApi>['input'] {
+  if (input === undefined) return ['text']
+  const supported = input.filter(
+    (value): value is Model<KnownApi>['input'][number] => value === 'text' || value === 'image',
+  )
+  return supported.length > 0 ? supported : ['text']
+}
+
+function resolveCustomModelCost(cost: CustomModelMeta['cost']): Model<KnownApi>['cost'] {
+  return {
+    input: cost?.input ?? 0,
+    output: cost?.output ?? 0,
+    cacheRead: cost?.cacheRead ?? 0,
+    cacheWrite: cost?.cacheWrite ?? 0,
+  }
 }
 
 // Resolves a profile name (e.g. `fast`, `deep`, `vision`) to its fallback
@@ -672,8 +761,8 @@ export function resolveModel(ref: KnownModelRef): Model<'openai-completions'> |
 // 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[]
+  ref: ModelRef
+  refs: ModelRef[]
   profile: string
   fellBackToDefault: boolean
 }
@@ -790,6 +879,7 @@ export type FieldEffect = 'applied' | 'restart-required' | 'ignored'
 export const FIELD_EFFECTS: Record<string, FieldEffect> = {
   $schema: 'ignored',
   models: 'applied',
+  customModels: 'applied',
   port: 'restart-required',
   mounts: 'restart-required',
   mcpServers: 'restart-required',
@@ -885,6 +975,7 @@ export function extractPluginConfigs(raw: unknown): Record<string, unknown> {
     '$schema',
     'port',
     'models',
+    'customModels',
     'mounts',
     'plugins',
     'alias',

package/src/config/index.ts

@@ -2,6 +2,8 @@ export {
   buildConfigMigrationCommitMessage,
   config,
   configSchema,
+  customModelMetaSchema,
+  customModelsSchema,
   DEFAULT_PLUGINS,
   dockerSchema,
   dockerfileSchema,
@@ -29,6 +31,8 @@ export {
   type Config,
   type ConfigChange,
   type ConfigReloadDiff,
+  type CustomModelMeta,
+  type CustomModels,
   type DockerConfig,
   type DockerfileConfig,
   type GitConfig,
@@ -43,5 +47,5 @@ export {
   type ResolvedProfile,
   type ValidateConfigResult,
 } from './config'
-export { type KnownModelRef, type KnownProviderId } from './providers'
+export { type KnownModelRef, type KnownProviderId, type ModelRef } from './providers'
 export { createConfigReloadable, type CreateConfigReloadableOptions } from './reloadable'

package/src/config/models-mutation.ts

@@ -3,13 +3,16 @@ import { join } from 'node:path'
 
 import { commitSystemFileSync } from '@/git/system-commit'
 
-import { configSchema, loadConfigSyncOrDefaults, validateConfig } from './config'
+import { configSchema, loadConfigSyncOrDefaults, validateConfig, type CustomModelMeta } from './config'
 import {
   KNOWN_PROVIDERS,
+  isKnownModelRef,
+  isModelRef,
   listKnownModelRefs,
   providerForModelRef,
   type KnownModelRef,
   type KnownProviderId,
+  type ModelRef,
 } from './providers'
 import { isProviderConfigured, listConfiguredProviders } from './providers-mutation'
 
@@ -20,8 +23,8 @@ export type ModelProfileEntry = {
   // 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[]
+  ref: ModelRef
+  refs: ModelRef[]
   providerId: KnownProviderId
   // Credential status for every provider referenced by the chain. The chain's
   // overall status is `available` only when every entry resolves; otherwise
@@ -67,7 +70,7 @@ export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.
   return out
 }
 
-function uniqueProviders(refs: ReadonlyArray<KnownModelRef>): KnownProviderId[] {
+function uniqueProviders(refs: ReadonlyArray<ModelRef>): KnownProviderId[] {
   const seen = new Set<KnownProviderId>()
   const out: KnownProviderId[] = []
   for (const r of refs) {
@@ -103,9 +106,7 @@ export function listRegisteredModelRefs(cwd: string, env: NodeJS.ProcessEnv = pr
   return listKnownModelRefs().filter((ref) => registered.has(providerForModelRef(ref)))
 }
 
-export function isKnownModelRef(value: string): value is KnownModelRef {
-  return (listKnownModelRefs() as ReadonlyArray<string>).includes(value)
-}
+export { isKnownModelRef }
 
 // `set` is the canonical mutation for both creating a new profile and updating
 // an existing one (mirrors how `models.<profile>` works in the schema).
@@ -115,6 +116,7 @@ export function isKnownModelRef(value: string): value is KnownModelRef {
 export type SetProfileOptions = {
   force?: boolean
   env?: NodeJS.ProcessEnv
+  meta?: CustomModelMeta
 }
 
 export function setProfile(
@@ -127,7 +129,7 @@ export function setProfile(
   if (trimmed.length === 0) {
     return { ok: false, reason: 'Profile name cannot be empty.' }
   }
-  if (!isKnownModelRef(ref)) {
+  if (!isModelRef(ref)) {
     return {
       ok: false,
       reason: `Unknown model "${ref}". Run \`typeclaw model list --available\` to see valid options.`,
@@ -143,7 +145,8 @@ export function setProfile(
 
   const existingBefore = readModelsRaw(cwd)
   const verb = existingBefore !== null && trimmed in existingBefore ? 'set' : 'add'
-  return writeProfile(cwd, trimmed, ref, `model: ${verb} ${trimmed} → ${ref}`)
+  const customModel = !isKnownModelRef(ref) && options.meta !== undefined ? { ref, meta: options.meta } : undefined
+  return writeProfile(cwd, trimmed, ref, `model: ${verb} ${trimmed} → ${ref}`, customModel)
 }
 
 // `add` is just `set` with a uniqueness guard; users who want "update" should
@@ -189,19 +192,26 @@ export function removeProfile(cwd: string, profile: string): ModelMutationResult
   return writeModels(cwd, next, `model: remove ${profile}`)
 }
 
-function writeProfile(cwd: string, profile: string, ref: KnownModelRef, message: string): ModelMutationResult {
+function writeProfile(
+  cwd: string,
+  profile: string,
+  ref: ModelRef,
+  message: string,
+  customModel?: { ref: ModelRef; meta: CustomModelMeta },
+): ModelMutationResult {
   const existing = readModelsRaw(cwd)
   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)
+  return writeModels(cwd, next, message, customModel)
 }
 
 function writeModels(
   cwd: string,
   models: Record<string, string | string[]>,
   commitMessage: string,
+  customModel?: { ref: ModelRef; meta: CustomModelMeta },
 ): ModelMutationResult {
   const path = join(cwd, CONFIG_FILE)
   let parsed: Record<string, unknown>
@@ -215,6 +225,10 @@ function writeModels(
     return { ok: false, reason: `Failed to read ${CONFIG_FILE}: ${(error as Error).message}` }
   }
   parsed.models = models
+  if (customModel !== undefined) {
+    const existingCustomModels = isObjectRecord(parsed.customModels) ? parsed.customModels : {}
+    parsed.customModels = { ...existingCustomModels, [customModel.ref]: customModel.meta }
+  }
   const check = configSchema.safeParse(parsed)
   if (!check.success) {
     return {
@@ -244,6 +258,10 @@ function writeModels(
   return { ok: true }
 }
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
 // 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

package/src/config/providers-mutation.ts

@@ -5,7 +5,7 @@ import { providerKeyDefaultEnv } from '@/secrets/defaults'
 import type { ProviderCredential, Providers } from '@/secrets/schema'
 
 import { type Models, loadConfigSync } from './config'
-import { KNOWN_PROVIDERS, type KnownModelRef, type KnownProviderId, providerForModelRef } from './providers'
+import { KNOWN_PROVIDERS, type KnownProviderId, type ModelRef, providerForModelRef } from './providers'
 
 // Where a configured credential resolves from at runtime. Reported by
 // `typeclaw provider list` so users can tell whether their key is coming from
@@ -230,7 +230,7 @@ function refTargetsProvider(ref: string, providerId: string): boolean {
   return ref.startsWith(`${providerId}/`)
 }
 
-function safeProviderForRef(ref: KnownModelRef): KnownProviderId | null {
+function safeProviderForRef(ref: ModelRef): KnownProviderId | null {
   try {
     return providerForModelRef(ref)
   } catch {