typeclaw 0.2.0 → 0.3.1

package/src/cli/model.ts

@@ -1,7 +1,13 @@
-import { cancel, intro, isCancel, select } from '@clack/prompts'
+import { cancel, intro, isCancel, log, select } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
-import { addProfile, listModelProfiles, removeProfile, setProfile } from '@/config/models-mutation'
+import {
+  addProfile,
+  listModelProfiles,
+  listRegisteredModelRefs,
+  removeProfile,
+  setProfile,
+} from '@/config/models-mutation'
 import {
   KNOWN_PROVIDERS,
   listKnownModelRefs,
@@ -11,8 +17,11 @@ import {
 } from '@/config/providers'
 import { findAgentDir, isInitialized } from '@/init'
 
+import { runProviderAddFlow } from './provider'
 import { c, done, errorLine } from './ui'
 
+const ADD_PROVIDER_SENTINEL = '__add-provider__'
+
 const setSub = defineCommand({
   meta: {
     name: 'set',
@@ -38,7 +47,7 @@ const setSub = defineCommand({
   async run({ args }) {
     const cwd = ensureAgentDir()
     const profile = args.profile ?? (await pickProfileName())
-    const ref = args.ref ?? (await pickModelRef())
+    const ref = args.ref ?? (await pickModelRef(cwd))
 
     intro(`Setting model profile: ${profile} → ${ref}`)
 
@@ -78,7 +87,7 @@ const addSub = defineCommand({
   },
   async run({ args }) {
     const cwd = ensureAgentDir()
-    const ref = args.ref ?? (await pickModelRef())
+    const ref = args.ref ?? (await pickModelRef(cwd))
 
     intro(`Adding model profile: ${args.profile} → ${ref}`)
 
@@ -198,22 +207,45 @@ async function pickProfileName(): Promise<string> {
   return choice
 }
 
-async function pickModelRef(): Promise<string> {
-  const refs = listKnownModelRefs()
-  const choice = await select<KnownModelRef>({
-    message: 'Pick a model',
-    options: refs.map((ref) => ({
-      value: ref,
-      label: describeRef(ref),
-      hint: ref,
-    })),
-    initialValue: refs[0],
-  })
-  if (isCancel(choice)) {
-    cancel('Aborted.')
-    process.exit(0)
+async function pickModelRef(cwd: string): Promise<string> {
+  while (true) {
+    const refs = listRegisteredModelRefs(cwd)
+    if (refs.length === 0) {
+      log.info("No provider credentials found. Let's add one first.")
+      const added = await runProviderAddFlow(cwd, {})
+      if (!added.ok) {
+        console.error(errorLine(added.reason))
+        process.exit(1)
+      }
+      continue
+    }
+    const choice = await select<KnownModelRef | typeof ADD_PROVIDER_SENTINEL>({
+      message: 'Pick a model',
+      options: [
+        ...refs.map((ref) => ({
+          value: ref,
+          label: describeRef(ref),
+          hint: ref,
+        })),
+        {
+          value: ADD_PROVIDER_SENTINEL,
+          label: c.cyan('+ add provider'),
+          hint: 'configure a new provider',
+        },
+      ],
+      initialValue: refs[0],
+    })
+    if (isCancel(choice)) {
+      cancel('Aborted.')
+      process.exit(0)
+    }
+    if (choice !== ADD_PROVIDER_SENTINEL) return choice
+    const added = await runProviderAddFlow(cwd, {})
+    if (!added.ok) {
+      console.error(errorLine(added.reason))
+      process.exit(1)
+    }
   }
-  return choice
 }
 
 function describeRef(ref: KnownModelRef): string {

package/src/cli/provider.ts

@@ -48,37 +48,51 @@ const addSub = defineCommand({
   },
   async run({ args }) {
     const cwd = ensureAgentDir()
-    const providerId = await resolveProviderForAdd(args.provider)
-    const provider = KNOWN_PROVIDERS[providerId]
-
-    intro(`Adding provider: ${provider.name}`)
-
-    const method = await resolveAuthMethod(provider, args)
-    if (method === 'oauth') {
-      const result = await runOAuthLogin(cwd, providerId)
-      if (!result.ok) {
-        console.error(errorLine(`OAuth login failed: ${result.reason}`))
-        process.exit(1)
-      }
-      done({
-        title: c.green(`Logged in to ${provider.name}.`),
-        hints: nextStepHints({ credentialChanged: true }),
-      })
-      return
-    }
-
-    const credential = await resolveApiKeyInputs(provider, args)
-    const result = addProvider(cwd, providerId, credential)
+    const result = await runProviderAddFlow(cwd, args)
     if (!result.ok) {
       console.error(errorLine(result.reason))
       process.exit(1)
     }
+  },
+})
+
+export type ProviderAddFlowArgs = {
+  provider?: string | undefined
+  key?: string | undefined
+  env?: string | undefined
+  oauth?: boolean | undefined
+}
+
+export type ProviderAddFlowResult =
+  | { ok: true; providerId: KnownProviderId; method: 'api-key' | 'oauth' }
+  | { ok: false; reason: string }
+
+export async function runProviderAddFlow(cwd: string, args: ProviderAddFlowArgs): Promise<ProviderAddFlowResult> {
+  const providerId = await resolveProviderForAdd(args.provider)
+  const provider = KNOWN_PROVIDERS[providerId]
+
+  intro(`Adding provider: ${provider.name}`)
+
+  const method = await resolveAuthMethod(provider, args)
+  if (method === 'oauth') {
+    const result = await runOAuthLogin(cwd, providerId)
+    if (!result.ok) return { ok: false, reason: `OAuth login failed: ${result.reason}` }
     done({
-      title: c.green(`Added ${provider.name} credentials to secrets.json.`),
+      title: c.green(`Logged in to ${provider.name}.`),
       hints: nextStepHints({ credentialChanged: true }),
     })
-  },
-})
+    return { ok: true, providerId, method: 'oauth' }
+  }
+
+  const credential = await resolveApiKeyInputs(provider, args)
+  const result = addProvider(cwd, providerId, credential)
+  if (!result.ok) return { ok: false, reason: result.reason }
+  done({
+    title: c.green(`Added ${provider.name} credentials to secrets.json.`),
+    hints: nextStepHints({ credentialChanged: true }),
+  })
+  return { ok: true, providerId, method: 'api-key' }
+}
 
 const setSub = defineCommand({
   meta: {

package/src/cli/usage.ts

@@ -6,7 +6,7 @@ import { formatJson, formatReport } from '@/usage/report'
 
 import { parseSince, parseUntil, USAGE_COMMON_ARGS } from './usage-args'
 
-const SUBCOMMANDS = ['daily', 'session', 'models'] as const
+const SUBCOMMANDS = ['daily', 'session', 'models', 'origin'] as const
 type Subcommand = (typeof SUBCOMMANDS)[number]
 type View = 'summary' | Subcommand
 
@@ -18,6 +18,13 @@ const COMMON_ARGS = {
   },
 }
 
+// Captured by the parent's `setup` hook (which citty runs BEFORE the matched
+// subcommand's `run`, with the full parent-level argv parsed). Subcommands
+// read this in their own `run` to recover global options like `--since` that
+// appeared before the subcommand name. Single-instance CLI processes only —
+// no concurrency.
+let parentRunArgs: Record<string, unknown> | undefined
+
 const subcommand = (view: View, description: string) =>
   defineCommand({
     meta: { name: view, description },
@@ -26,7 +33,7 @@ const subcommand = (view: View, description: string) =>
       ...(view === 'session' ? { limit: { type: 'string' as const, description: 'max sessions (default 20)' } } : {}),
     },
     async run({ args }) {
-      await emit(view, args)
+      await emit(view, mergeParentArgs(args))
     },
   })
 
@@ -36,10 +43,14 @@ export const usageCommand = defineCommand({
     description: 'report LLM token usage and cost for this agent folder',
   },
   args: COMMON_ARGS,
+  setup({ args }) {
+    parentRunArgs = args as unknown as Record<string, unknown>
+  },
   subCommands: {
     daily: subcommand('daily', 'one row per calendar day'),
     session: subcommand('session', 'top sessions by cost'),
     models: subcommand('models', 'one row per provider/model'),
+    origin: subcommand('origin', 'one row per session origin (tui/cron/channel/subagent)'),
   },
   async run({ args }) {
     // citty invokes both the matched subcommand's `run` and the parent's
@@ -50,6 +61,23 @@ export const usageCommand = defineCommand({
   },
 })
 
+// citty's subcommand `run` only sees args that came AFTER the subcommand
+// name (the child's rawArgs is pre-sliced), so `usage --since=X origin` would
+// silently drop `--since` despite the help text advertising it as a global
+// option. The parent's `setup` runs first with the full parent-level parse
+// (which includes everything: global options + subcommand options merged),
+// so we capture it there and merge it as a fallback under any explicitly-set
+// child arg. Child-wins so `usage --since=A origin --since=B` still honours B.
+function mergeParentArgs(childArgs: Record<string, unknown>): Record<string, unknown> {
+  if (parentRunArgs === undefined) return childArgs
+  const merged: Record<string, unknown> = { ...parentRunArgs }
+  for (const key of Object.keys(childArgs)) {
+    const v = childArgs[key]
+    if (v !== undefined && v !== '' && v !== false) merged[key] = v
+  }
+  return merged
+}
+
 async function emit(view: View, args: Record<string, unknown>): Promise<void> {
   const cwdArg = typeof args.cwd === 'string' && args.cwd.length > 0 ? args.cwd : process.cwd()
   const agentDir = findAgentDir(cwdArg) ?? cwdArg

package/src/config/config.ts

@@ -881,7 +881,16 @@ export type ValidateConfigResult = { ok: true } | { ok: false; reason: string }
 // 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 {
+export type ValidateConfigOptions = {
+  // Skip the mount-path accessibility check. Host-side callers leave this
+  // false (the default) so missing mount directories surface as a precise
+  // pre-`docker run` error. Container-side callers (the reload registry)
+  // set it true because mount paths in typeclaw.json are host paths and
+  // don't resolve inside the container's filesystem.
+  skipMounts?: boolean
+}
+
+export function validateConfig(cwd: string, options: ValidateConfigOptions = {}): ValidateConfigResult {
   let raw: string
   try {
     raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
@@ -907,9 +916,11 @@ export function validateConfig(cwd: string): ValidateConfigResult {
     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
+  if (!options.skipMounts) {
+    for (const mount of result.data.mounts) {
+      const check = validateMount(mount, cwd)
+      if (!check.ok) return check
+    }
   }
 
   return { ok: true }

package/src/config/models-mutation.ts

@@ -11,7 +11,7 @@ import {
   type KnownModelRef,
   type KnownProviderId,
 } from './providers'
-import { isProviderConfigured } from './providers-mutation'
+import { isProviderConfigured, listConfiguredProviders } from './providers-mutation'
 
 const CONFIG_FILE = 'typeclaw.json'
 
@@ -51,6 +51,25 @@ export function listAvailableModelRefs(): KnownModelRef[] {
   return listKnownModelRefs()
 }
 
+// Subset of `listAvailableModelRefs()` filtered to providers with a usable
+// credential in this agent folder — either a `secrets.json#providers.<id>`
+// entry (api-key OR oauth) or a credential resolvable from the process env
+// via the provider's canonical env-var name. Used by `typeclaw model set`'s
+// interactive picker so users only see models they can actually run; the
+// CLI surfaces an explicit "add provider" sentinel when the result is empty
+// or when the user wants to wire a new one.
+//
+// Ordering preserves `listKnownModelRefs()` (provider-table declaration
+// order, then per-provider model order) so the picker reads stably across
+// invocations.
+export function listRegisteredModelRefs(cwd: string, env: NodeJS.ProcessEnv = process.env): KnownModelRef[] {
+  const registered = new Set<KnownProviderId>()
+  for (const entry of listConfiguredProviders(cwd, env)) {
+    if (entry.known) registered.add(entry.id as KnownProviderId)
+  }
+  return listKnownModelRefs().filter((ref) => registered.has(providerForModelRef(ref)))
+}
+
 export function isKnownModelRef(value: string): value is KnownModelRef {
   return (listKnownModelRefs() as ReadonlyArray<string>).includes(value)
 }

package/src/config/reloadable.ts

@@ -11,24 +11,42 @@ export type CreateConfigReloadableOptions = {
   // hand-edits) take effect without a container restart. `roles.<name>.permissions`
   // changes still require a restart — see FIELD_EFFECTS in config.ts.
   permissions?: PermissionService
+  // Skip the mount-path accessibility check inside validateConfig. Mount paths
+  // in typeclaw.json are host paths — they don't resolve inside the container,
+  // so the check would always fail on any agent that declares mounts. `mounts`
+  // is `restart-required` anyway, so reload never applies mount changes. Set
+  // this when wiring the reloadable from a container-stage context.
+  skipMountValidation?: boolean
 }
 
-export function createConfigReloadable({ cwd, permissions }: CreateConfigReloadableOptions): Reloadable {
+export function createConfigReloadable({
+  cwd,
+  permissions,
+  skipMountValidation = false,
+}: CreateConfigReloadableOptions): Reloadable {
   return {
     scope: 'config',
     description: 'typeclaw.json runtime config',
-    reload: async () => doReload(cwd, permissions),
+    reload: async () => doReload(cwd, permissions, skipMountValidation),
   }
 }
 
-async function doReload(cwd: string, permissions: PermissionService | undefined): Promise<ReloadResult> {
+async function doReload(
+  cwd: string,
+  permissions: PermissionService | undefined,
+  skipMountValidation: boolean,
+): Promise<ReloadResult> {
   // Mount accessibility belongs to the validation surface, not loadConfigSync —
   // validateConfig is the single gate that every host-side caller goes through.
   // Run it before swapping the live config pointer so a mount that vanished
   // between starts surfaces as a reload failure (`mounts` is restart-required
   // anyway, so the user has to restart to pick up changes; better to flag the
   // problem now than to let restart fail later).
-  const validated = validateConfig(cwd)
+  //
+  // Container-side reload skips mount validation: mounts are host paths and
+  // statSync against them inside the container always fails. The host-side
+  // `start` / `restart` / doctor paths still gate on the full validateConfig.
+  const validated = validateConfig(cwd, { skipMounts: skipMountValidation })
   if (!validated.ok) {
     return { scope: 'config', ok: false, reason: validated.reason }
   }

package/src/cron/consumer.ts

@@ -1,3 +1,5 @@
+import type { AgentSession } from '@/agent'
+import { subscribeProviderErrors } from '@/agent/provider-error'
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { HookBus } from '@/plugin'
 import type { Stream, Unsubscribe } from '@/stream'
@@ -20,6 +22,12 @@ export type CronSession = {
   agentDir?: string
   getTranscriptPath?: () => string | undefined
   origin?: SessionOrigin
+  // Underlying agent session, exposed so the consumer can subscribe to
+  // `message_end` events and surface soft provider errors (billing, rate
+  // limit, network — pi-coding-agent encodes these in the assistant message
+  // instead of throwing, so the outer try/catch never sees them). Optional
+  // so existing test fakes that only need `prompt` keep working.
+  session?: AgentSession
 }
 
 export type CronConsumerLogger = {
@@ -72,7 +80,7 @@ export function createCronConsumer({
         inFlight.add(job.id)
         try {
           if (job.kind === 'prompt') {
-            await runPrompt(job, createSessionForCron, stream)
+            await runPrompt(job, createSessionForCron, stream, logger)
           } else {
             await runExec(job, cwd)
           }
@@ -98,6 +106,7 @@ async function runPrompt(
   job: PromptJob,
   createSessionForCron: (job: PromptJob) => Promise<CronSession>,
   stream: Stream,
+  logger: CronConsumerLogger,
 ): Promise<void> {
   if (job.subagent !== undefined) {
     // Propagate the cron job's role and origin into the spawned subagent.
@@ -123,6 +132,12 @@ 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}`)
+        })
+      : null
   const turnEvent =
     session.hooks && session.sessionId !== undefined && session.agentDir !== undefined
       ? {
@@ -151,6 +166,7 @@ async function runPrompt(
       })
     }
   } finally {
+    unsubProviderErrors?.()
     if (session.hooks && session.sessionId !== undefined) {
       await session.hooks.runSessionEnd({
         sessionId: session.sessionId,

package/src/run/channel-session-factory.ts

@@ -33,6 +33,7 @@ export type BuildChannelSessionFactoryDeps = {
   // their inbound messages came from.
   getChannelRouter: () => ChannelRouter
   containerName?: string
+  runtimeVersion?: string
   // When set, rehydrating a session JSONL caps oversized tool results in the
   // file before pi-coding-agent reads it. `null` disables the load-time pass
   // (tool-result-cap.enabled=false in config, or no plugin block at all).
@@ -105,6 +106,7 @@ export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps)
           }
         : {}),
       ...(deps.containerName !== undefined ? { containerName: deps.containerName } : {}),
+      ...(deps.runtimeVersion !== undefined ? { runtimeVersion: deps.runtimeVersion } : {}),
       ...(deps.permissions !== undefined ? { permissions: deps.permissions } : {}),
     })
 

package/src/run/index.ts

@@ -24,6 +24,7 @@ import {
   loadCron as loadCronDefault,
   type Scheduler,
 } from '@/cron'
+import { CLI_VERSION } from '@/init/cli-version'
 import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
 import { ReloadRegistry } from '@/reload'
@@ -90,6 +91,7 @@ export async function startAgent({
   // which is what we want, since there is no host daemon to honor it anyway.
   const containerName = process.env.TYPECLAW_CONTAINER_NAME
   const containerNameOpt = containerName !== undefined ? { containerName } : {}
+  const runtimeVersionOpt = { runtimeVersion: CLI_VERSION }
   const tuiToken = process.env.TYPECLAW_TUI_TOKEN
   const tuiTokenOpt = tuiToken !== undefined && tuiToken !== '' ? { tuiToken } : {}
 
@@ -103,7 +105,13 @@ export async function startAgent({
     ...(cwdConfig.roles !== undefined ? { roles: cwdConfig.roles } : {}),
   })
 
-  reloadRegistry.register(createConfigReloadable({ cwd, permissions: pluginsLoaded.permissions }))
+  reloadRegistry.register(
+    createConfigReloadable({
+      cwd,
+      permissions: pluginsLoaded.permissions,
+      skipMountValidation: containerName !== undefined,
+    }),
+  )
   const pluginRegistry = pluginsLoaded.registry
   const pluginHooks = pluginsLoaded.hooks
 
@@ -155,6 +163,7 @@ export async function startAgent({
       rehydrateCapOptions: resolveCapOptionsFromConfig(pluginConfigsByName['tool-result-cap']),
       permissions: pluginsLoaded.permissions,
       ...containerNameOpt,
+      ...runtimeVersionOpt,
     }),
     permissions: pluginsLoaded.permissions,
     claimHandler: claimController.claimHandler,
@@ -198,6 +207,7 @@ export async function startAgent({
         ...(entry.pluginSubagent.toolResultBudget !== undefined
           ? { toolResultBudget: entry.pluginSubagent.toolResultBudget }
           : {}),
+        ...runtimeVersionOpt,
       })
       return {
         ...created,
@@ -267,6 +277,7 @@ export async function startAgent({
             }
           : {}),
         ...containerNameOpt,
+        ...runtimeVersionOpt,
       })
       return {
         prompt: (text) => session.prompt(text),
@@ -274,6 +285,7 @@ export async function startAgent({
         sessionId,
         agentDir: cwd,
         origin: cronOrigin,
+        session,
         ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
         getTranscriptPath: () => sessionManager.getSessionFile(),
       }
@@ -316,6 +328,7 @@ export async function startAgent({
       agentDir: cwd,
       userPrompt: '',
       payload,
+      onProviderError: (message) => console.error(`[subagent] ${name}: LLM call failed: ${message}`),
       ...(options?.parentSessionId !== undefined ? { parentSessionId: options.parentSessionId } : {}),
       ...(spawnedByRole !== undefined ? { spawnedByRole } : {}),
       ...(options?.spawnedByOrigin !== undefined ? { spawnedByOrigin: options.spawnedByOrigin } : {}),
@@ -363,6 +376,7 @@ export async function startAgent({
     pluginRuntime,
     claimController,
     ...containerNameOpt,
+    ...runtimeVersionOpt,
     ...tuiTokenOpt,
     ...containerBrokerOpt,
   }).start()

package/src/server/index.ts

@@ -7,6 +7,7 @@ import {
   type CreateSessionResult,
 } from '@/agent'
 import { runPluginDoctorChecks, runPluginDoctorFix } from '@/agent/doctor'
+import { detectProviderError } from '@/agent/provider-error'
 import type { SessionOrigin } from '@/agent/session-origin'
 import type { ChannelRouter } from '@/channels/router'
 import type { HookBus } from '@/plugin'
@@ -38,6 +39,7 @@ export type ServerOptions = {
   agentDir?: string
   pluginRuntime?: PluginRuntime
   containerName?: string
+  runtimeVersion?: string
   tuiToken?: string
   // Optional in-process portbroker handler. When provided, requests to the
   // /portbroker WS path are routed to it instead of being treated as TUI
@@ -108,6 +110,7 @@ export function createServer({
   agentDir,
   pluginRuntime,
   containerName,
+  runtimeVersion,
   tuiToken,
   containerBroker,
   logger = consoleLogger,
@@ -167,6 +170,7 @@ export function createServer({
               ...(channelRouter ? { channelRouter } : {}),
               ...(pluginsWiring ? { plugins: pluginsWiring } : {}),
               ...(containerName !== undefined ? { containerName } : {}),
+              ...(runtimeVersion !== undefined ? { runtimeVersion } : {}),
             })
             const session = 'session' in result ? result.session : result
             const dispose = 'session' in result && result.dispose ? result.dispose : async () => {}
@@ -455,16 +459,10 @@ function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogge
 }
 
 function forwardAssistantError(ws: Ws, message: unknown, logger: ServerLogger, sessionFileId: string): void {
-  if (typeof message !== 'object' || message === null) return
-  const m = message as { role?: string; stopReason?: string; errorMessage?: string }
-  if (m.role !== 'assistant') return
-  if (m.stopReason !== 'error' && m.stopReason !== 'aborted') return
-  // 'aborted' is fired when the user hits Escape — don't surface it as an
-  // error message because the TUI already shows abort feedback elsewhere.
-  if (m.stopReason === 'aborted') return
-  const text = typeof m.errorMessage === 'string' && m.errorMessage.length > 0 ? m.errorMessage : 'LLM call failed'
-  logger.error(`[server] ${sessionFileId}: LLM call failed: ${text}`)
-  send(ws, { type: 'error', message: text })
+  const detected = detectProviderError(message)
+  if (detected === null) return
+  logger.error(`[server] ${sessionFileId}: LLM call failed: ${detected.message}`)
+  send(ws, { type: 'error', message: detected.message })
 }
 
 function enqueuePrompt(