typeclaw 0.7.0 → 0.9.0

package/src/cli/init.ts

@@ -6,6 +6,7 @@ import { defineCommand } from 'citty'
 
 import {
   KNOWN_PROVIDERS,
+  providerForModelRef,
   supportsApiKey as providerSupportsApiKey,
   supportsOAuth as providerSupportsOAuth,
   type KnownModelRef,
@@ -30,6 +31,7 @@ import {
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
 import { fetchModelOptions, type ModelOption } from '@/init/models-dev'
 import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
+import { API_KEY_DASHBOARD_URL, validateApiKey, type KeyValidationResult } from '@/init/validate-api-key'
 
 import { buildOAuthCallbacks } from './oauth-callbacks'
 import { c, done, errorLine, printSlackAppManifestSetup } from './ui'
@@ -237,14 +239,29 @@ export const init = defineCommand({
     }
 
     if (hatchingOk) {
-      done({
-        title: c.green('Hatched. Your agent is ready.'),
-        hints: [
-          { label: 'Attach TUI:', command: 'typeclaw tui' },
-          { label: 'Follow logs:', command: 'typeclaw logs -f' },
-          { label: 'Stop:', command: 'typeclaw stop' },
-        ],
-      })
+      const claimableChannel =
+        channelChoice !== 'none' && channelChoice !== 'github' ? channelDisplayName(channelChoice) : null
+      const hints: Array<{ label: string; command: string }> = []
+      if (claimableChannel !== null) {
+        hints.push({ label: 'Claim your agent:', command: 'typeclaw role claim' })
+      }
+      hints.push(
+        { label: 'Attach TUI:', command: 'typeclaw tui' },
+        { label: 'Follow logs:', command: 'typeclaw logs -f' },
+        { label: 'Stop:', command: 'typeclaw stop' },
+        { label: 'Diagnose issues:', command: 'typeclaw doctor' },
+      )
+      if (claimableChannel !== null) {
+        note(
+          [
+            `Your agent will not respond on ${claimableChannel} until you claim ownership.`,
+            `This prevents strangers from talking to it.`,
+            `Run \`typeclaw role claim\` to finish setup.`,
+          ].join('\n'),
+          'Claim ownership before chatting',
+        )
+      }
+      done({ title: c.green('Hatched. Your agent is ready.'), hints })
     }
   },
 })
@@ -329,6 +346,7 @@ export interface WizardPrompts {
     initial: 'api-key' | 'oauth' | undefined,
   ) => Promise<StepResult<'api-key' | 'oauth'>>
   askApiKey: (provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]) => Promise<StepResult<string>>
+  validateApiKey: (providerId: KnownProviderId, key: string) => Promise<KeyValidationResult>
   pickVisionProvider: (
     options: ModelOption[],
     initial: KnownProviderId | undefined,
@@ -368,6 +386,7 @@ export const defaultWizardPrompts: WizardPrompts = {
   askReuseExistingKey,
   pickAuthMethod,
   askApiKey,
+  validateApiKey,
   pickVisionProvider,
   pickVisionModel,
   pickChannel,
@@ -502,12 +521,18 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
       }
 
       case 'enter-api-key': {
-        const provider = KNOWN_PROVIDERS[state.providerId!]
+        const providerId = state.providerId!
+        const provider = KNOWN_PROVIDERS[providerId]
         const result = onResult(step, await prompts.askApiKey(provider))
         if (result.kind === 'back') {
           step = 'pick-auth-method'
           break
         }
+        const verdict = await runApiKeyValidation(prompts, providerId, result.value)
+        if (verdict === 'retry') {
+          step = 'enter-api-key'
+          break
+        }
         state.llmAuth = { kind: 'api-key', apiKey: result.value }
         step = stepAfterDefaultAuth(state)
         break
@@ -608,12 +633,18 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
       }
 
       case 'enter-vision-api-key': {
-        const provider = KNOWN_PROVIDERS[state.visionProviderId!]
+        const providerId = state.visionProviderId!
+        const provider = KNOWN_PROVIDERS[providerId]
         const result = onResult(step, await prompts.askApiKey(provider))
         if (result.kind === 'back') {
           step = 'pick-vision-auth-method'
           break
         }
+        const verdict = await runApiKeyValidation(prompts, providerId, result.value)
+        if (verdict === 'retry') {
+          step = 'enter-vision-api-key'
+          break
+        }
         state.visionLlmAuth = { kind: 'api-key', apiKey: result.value }
         step = 'pick-channel'
         break
@@ -771,12 +802,12 @@ async function pickModelForProvider(
   providerId: KnownProviderId,
   initial: KnownModelRef | undefined,
 ): Promise<StepResult<ModelOption>> {
-  const candidates = options.filter((o) => o.providerId === providerId)
+  const candidates = sortRecommendedFirst(options.filter((o) => o.providerId === providerId))
   const choice = await select<KnownModelRef>({
     message: `Pick a ${KNOWN_PROVIDERS[providerId].name} model`,
     options: candidates.map((o) => ({
       value: o.ref,
-      label: o.modelName,
+      label: formatModelLabel(o),
       hint: formatModelHint(o),
     })),
     initialValue: initial ?? candidates[0]?.ref,
@@ -863,12 +894,12 @@ async function pickVisionModel(
   providerId: KnownProviderId,
   initial: KnownModelRef | undefined,
 ): Promise<StepResult<ModelOption>> {
-  const candidates = options.filter((o) => o.providerId === providerId)
+  const candidates = sortRecommendedFirst(options.filter((o) => o.providerId === providerId))
   const choice = await select<KnownModelRef>({
     message: `Pick a vision-capable ${KNOWN_PROVIDERS[providerId].name} model`,
     options: candidates.map((o) => ({
       value: o.ref,
-      label: o.modelName,
+      label: formatModelLabel(o),
       hint: formatModelHint(o),
     })),
     initialValue: initial ?? candidates[0]?.ref,
@@ -879,7 +910,60 @@ async function pickVisionModel(
   return value(picked)
 }
 
+async function runApiKeyValidation(
+  prompts: WizardPrompts,
+  providerId: KnownProviderId,
+  key: string,
+): Promise<'accepted' | 'retry'> {
+  const provider = KNOWN_PROVIDERS[providerId]
+  const s = spinner()
+  s.start(`Checking your ${provider.name} key...`)
+  let result: KeyValidationResult
+  try {
+    result = await prompts.validateApiKey(providerId, key)
+  } catch {
+    s.stop(`Couldn't reach ${provider.name} to verify the key. Saving it anyway.`)
+    return 'accepted'
+  }
+  if (result.kind === 'ok') {
+    s.stop(`${provider.name} key looks good.`)
+    return 'accepted'
+  }
+  if (result.kind === 'skipped') {
+    s.stop(`Couldn't reach ${provider.name} to verify the key. Saving it anyway.`)
+    return 'accepted'
+  }
+  s.error(`${provider.name} rejected the key (HTTP ${result.status}).`)
+  const dashboardUrl = API_KEY_DASHBOARD_URL[providerId]
+  const lines = [
+    'The provider says this key is not valid.',
+    'Common causes: typo, expired key, wrong account, or pasting a project-scoped key.',
+  ]
+  if (dashboardUrl) {
+    lines.push('', `Get a fresh one at ${dashboardUrl}`)
+  }
+  note(lines.join('\n'), `${provider.name} key rejected`)
+  const choice = await select<'retry' | 'accept'>({
+    message: 'What do you want to do?',
+    options: [
+      { value: 'retry', label: 'Try a different key' },
+      { value: 'accept', label: 'Save this key anyway', hint: 'init continues, but the agent may fail to start' },
+    ],
+    initialValue: 'retry',
+  })
+  if (isCancel(choice) || choice === 'retry') return 'retry'
+  return 'accepted'
+}
+
 async function askApiKey(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]): Promise<StepResult<string>> {
+  const providerId = provider.id as KnownProviderId
+  const dashboardUrl = API_KEY_DASHBOARD_URL[providerId]
+  if (dashboardUrl) {
+    note(
+      [`Don't have a key yet?`, `Get one at ${dashboardUrl}`, `Then come back and paste it below.`].join('\n'),
+      `Get a ${provider.name} API key`,
+    )
+  }
   const apiKey = await password({
     message: `Put your ${provider.name} API key (will be saved to secrets.json)`,
     validate: (v) => (v && v.length > 0 ? undefined : 'API key is required'),
@@ -1371,6 +1455,30 @@ function uniqueProviders(options: ModelOption[]): KnownProviderId[] {
   return out
 }
 
+// Per-provider recommended model refs. Surfaces a "(Recommended)" suffix in
+// the picker label and floats the entry to the top of the list (which also
+// makes it the default `initialValue` when the caller has no prior choice).
+// Kept narrow on purpose: one recommendation per provider. gpt-5.4-mini is
+// listed under both `openai` and `openai-codex` because the same model is
+// the right default whether the user authenticates with an API key or with
+// a ChatGPT Plus/Pro subscription. claude-sonnet-4-6 follows Anthropic's
+// own current-tier guidance (see the model lineup notes in providers.ts).
+const RECOMMENDED_MODEL_REFS: ReadonlySet<KnownModelRef> = new Set<KnownModelRef>([
+  'openai/gpt-5.4-mini',
+  'openai-codex/gpt-5.4-mini',
+  'anthropic/claude-sonnet-4-6',
+])
+
+export function formatModelLabel(o: ModelOption): string {
+  return RECOMMENDED_MODEL_REFS.has(o.ref) ? `${o.modelName} (Recommended)` : o.modelName
+}
+
+export function sortRecommendedFirst(options: ModelOption[]): ModelOption[] {
+  const recommended = options.filter((o) => RECOMMENDED_MODEL_REFS.has(o.ref))
+  const rest = options.filter((o) => !RECOMMENDED_MODEL_REFS.has(o.ref))
+  return [...recommended, ...rest]
+}
+
 function formatModelHint(o: ModelOption): string {
   const parts: string[] = []
   if (o.contextWindow !== null) parts.push(`${(o.contextWindow / 1000).toFixed(0)}K ctx`)

package/src/cli/inspect.ts

@@ -0,0 +1,151 @@
+import { defineCommand } from 'citty'
+
+import { requireContainerRunning, resolveHostPort, resolveTuiToken } from '@/container'
+import { findAgentDir } from '@/init'
+import { runInspect, streamLive, type LiveSourceFactory, type SessionSummary } from '@/inspect'
+import { originLabel, shortSessionId } from '@/inspect/label'
+
+import { cancel, c, errorLine, isCancel } from './ui'
+
+export const inspectCommand = defineCommand({
+  meta: {
+    name: 'inspect',
+    description: 'replay a session transcript and tail live activity (host stage)',
+  },
+  args: {
+    session: {
+      type: 'positional',
+      description: 'session id or short prefix (omit to pick from a list)',
+      required: false,
+    },
+    filter: {
+      type: 'string',
+      description:
+        'category filter: comma-separated meta/user/assistant/tool/error/done/broadcast/cron-fire; prefix with ! to exclude',
+    },
+    since: {
+      type: 'string',
+      description: 'only events newer than this (forms: 30s, 5m, 1h, 7d)',
+    },
+    json: {
+      type: 'boolean',
+      description: 'emit one JSON event per line; requires an explicit session id',
+      default: false,
+    },
+    follow: {
+      type: 'boolean',
+      description:
+        'tail live activity after replay (default: true when the container is running); pass --no-follow to replay-then-exit',
+      default: true,
+    },
+  },
+  async run({ args }) {
+    const cwd = findAgentDir(process.cwd()) ?? process.cwd()
+    const color = useColor()
+    const sessionArg = typeof args.session === 'string' ? args.session : undefined
+    const filterArg = typeof args.filter === 'string' ? args.filter : undefined
+    const sinceArg = typeof args.since === 'string' ? args.since : undefined
+    const follow = args.follow !== false
+
+    const isJson = args.json === true
+    const liveSource = !follow || isJson ? undefined : await buildLiveSource(cwd)
+    const signal = installSigintAbort()
+
+    const result = await runInspect({
+      agentDir: cwd,
+      ...(sessionArg !== undefined ? { sessionIdOrPrefix: sessionArg } : {}),
+      ...(filterArg !== undefined ? { filter: filterArg } : {}),
+      ...(sinceArg !== undefined ? { since: sinceArg } : {}),
+      json: isJson,
+      color,
+      selectSession: clackSelect,
+      ...(liveSource !== undefined ? { liveSource } : {}),
+      signal,
+      stdout: (line) => process.stdout.write(`${line}\n`),
+      stderr: (line) => process.stderr.write(`${line}\n`),
+    })
+
+    if (!result.ok) {
+      process.stderr.write(`${errorLine(result.reason)}\n`)
+      process.exit(result.exitCode)
+    }
+    process.exit(result.exitCode)
+  },
+})
+
+async function buildLiveSource(cwd: string): Promise<LiveSourceFactory | undefined> {
+  const precheck = await requireContainerRunning({ cwd })
+  if (!precheck.ok) {
+    process.stderr.write(`${c.yellow('⚠')} ${precheck.reason}; tailing live events disabled\n`)
+    return undefined
+  }
+  const port = await resolveHostPort({ cwd })
+  const token = await resolveTuiToken({ cwd })
+  const baseUrl = new URL(`ws://127.0.0.1:${port}/inspect`)
+  if (token !== null) baseUrl.searchParams.set('token', token)
+  const url = baseUrl.toString()
+  return ({ sessionId, sinceMs, signal, onSubscribed }) =>
+    streamLive({
+      url,
+      sessionId,
+      ...(sinceMs !== undefined ? { sinceMs } : {}),
+      ...(signal !== undefined ? { signal } : {}),
+      ...(onSubscribed !== undefined ? { onSubscribed } : {}),
+    })
+}
+
+function installSigintAbort(): AbortSignal {
+  const ctrl = new AbortController()
+  const onSig = (): void => {
+    ctrl.abort()
+  }
+  process.once('SIGINT', onSig)
+  process.once('SIGTERM', onSig)
+  return ctrl.signal
+}
+
+function useColor(): boolean {
+  if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') return false
+  if (process.env.FORCE_COLOR === '0') return false
+  if (process.env.FORCE_COLOR) return true
+  return Boolean(process.stdout.isTTY)
+}
+
+async function clackSelect(sessions: SessionSummary[]): Promise<SessionSummary | null> {
+  const { select } = await import('@clack/prompts')
+  const picked = await select<string>({
+    message: `Pick a session to inspect (showing ${sessions.length})`,
+    options: sessions.map((s) => ({
+      value: s.sessionId,
+      label: formatRowLabel(s),
+      ...(s.firstPrompt !== null ? { hint: truncate(s.firstPrompt, 60) } : { hint: '(no prompt)' }),
+    })),
+    initialValue: sessions[0]?.sessionId,
+  })
+  if (isCancel(picked)) {
+    cancel('Cancelled.')
+    return null
+  }
+  return sessions.find((s) => s.sessionId === picked) ?? null
+}
+
+function formatRowLabel(s: SessionSummary): string {
+  const id = shortSessionId(s.sessionId)
+  const label = s.origin === null ? '(unknown origin)' : originLabel(s.origin)
+  const when = formatRelative(s.mtimeMs)
+  return `${c.cyan(id)}  ${label}  ${c.dim(when)}`
+}
+
+function formatRelative(ms: number): string {
+  const diff = Date.now() - ms
+  if (diff < 60_000) return 'just now'
+  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`
+  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`
+  return `${Math.floor(diff / 86_400_000)}d ago`
+}
+
+function truncate(text: string, max: number): string {
+  const oneline = text.replace(/\s+/g, ' ').trim()
+  if (oneline.length <= max) return oneline
+  return `${oneline.slice(0, max)}…`
+}

package/src/cli/role.ts

@@ -95,8 +95,13 @@ const listSub = defineCommand({
   },
   async run() {
     const cwd = findAgentDir(process.cwd()) ?? process.cwd()
-    const { loadConfigSync } = await import('@/config')
-    const config = loadConfigSync(cwd)
+    // Diagnostic command: route through `loadConfigSyncOrDefaults` (same
+    // soft-fail pattern as PR #288's `status`/`doctor` and the follow-up for
+    // `model list`) so a broken `typeclaw.json` doesn't crash the very
+    // command users reach for to see which roles the agent thinks it has.
+    // Defaults have no `roles` block, so the empty-state hint fires next.
+    const { loadConfigSyncOrDefaults } = await import('@/config')
+    const config = loadConfigSyncOrDefaults(cwd)
     if (!config.roles || Object.keys(config.roles).length === 0) {
       console.log(c.dim('No roles declared. Run `typeclaw role claim` to add one, or edit typeclaw.json by hand.'))
       return

package/src/cli/tunnel.ts

@@ -4,7 +4,7 @@ import { join } from 'node:path'
 import { select, text, isCancel, cancel, log } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
-import { loadConfigSync } from '@/config'
+import { loadConfigSync, validateConfig } from '@/config'
 import { resolveHostPort, resolveTuiToken } from '@/container'
 import { findAgentDir, isInitialized } from '@/init'
 import type { ClientMessage, ServerMessage, TunnelLogsServerMessage, TunnelSnapshot } from '@/shared'
@@ -168,6 +168,15 @@ export async function runTunnelAddFlow(
   args: AddArgs,
   prompts: TunnelPrompts = defaultPrompts,
 ): Promise<LiveResult<TunnelConfig>> {
+  // Strict gate before any read: a malformed or schema-invalid `typeclaw.json`
+  // would otherwise throw out of the subsequent `loadConfigSync` and surface
+  // as an uncaught exception instead of the clean exit-1-with-reason that
+  // every other LiveResult consumer expects. Same fence PR #288 documented
+  // for the `start`/`restart`/`reload` path: destructive paths route through
+  // `validateConfig` so the file's invariants are checked once, up front,
+  // and the rest of the flow can lean on them.
+  const validation = validateConfig(cwd)
+  if (!validation.ok) return { ok: false, reason: validation.reason }
   const config = loadConfigSync(cwd)
   if (config.tunnels.some((entry) => entry.name === args.name))
     return { ok: false, reason: `tunnel "${args.name}" already exists` }
@@ -206,6 +215,9 @@ export async function runTunnelAddFlow(
 }
 
 export function runTunnelRemoveFlow(cwd: string, args: RemoveArgs): LiveResult<{ removed: TunnelConfig }> {
+  // Same strict gate as `runTunnelAddFlow`. See the comment there for why.
+  const validation = validateConfig(cwd)
+  if (!validation.ok) return { ok: false, reason: validation.reason }
   const config = loadConfigSync(cwd)
   const tunnel = config.tunnels.find((entry) => entry.name === args.name)
   if (tunnel === undefined) return { ok: false, reason: `unknown tunnel: ${args.name}` }

package/src/cli/ui.ts

@@ -142,6 +142,27 @@ export const SLACK_APP_MANIFEST = {
       messages_tab_enabled: true,
       messages_tab_read_only_enabled: false,
     },
+    // Slash commands listed here appear in Slack's compose-box picker with
+    // their description as a tooltip. `url` is required by Slack's manifest
+    // schema even for Socket Mode bots, but is ignored at runtime when the
+    // app is in Socket Mode — Slack delivers `slash_commands` envelopes
+    // over the same WebSocket as message events. We point it at a
+    // deliberately-invalid placeholder (RFC 6761 reserved .invalid TLD)
+    // so a misconfigured (non-Socket-Mode) deployment fails fast rather
+    // than silently routing real slash invocations to a third-party URL.
+    slash_commands: [
+      {
+        command: '/stop',
+        description: 'Abort the current turn in this channel',
+        // usage_hint is intentionally omitted. Slack's manifest validator
+        // rejects an empty string ("Must be more than 0 characters") but
+        // the field is optional, so the cleanest answer is to leave it out
+        // rather than invent placeholder text for a command that takes no
+        // arguments.
+        url: 'https://example.invalid/typeclaw-uses-socket-mode',
+        should_escape: false,
+      },
+    ],
   },
   oauth_config: {
     scopes: {
@@ -150,13 +171,16 @@ export const SLACK_APP_MANIFEST = {
       // write scopes (chat, files, im/mpim/groups, pins, reactions) let the
       // agent post replies, upload attachments, open DMs, pin messages, and
       // react to messages. `channels:join` lets the bot self-join public
-      // channels it's invited to discuss in.
+      // channels it's invited to discuss in. `commands` is required for
+      // Slack to deliver `slash_commands` envelopes — without it, slash
+      // commands registered in `features` would silently fail to route.
       bot: [
         'app_mentions:read',
         'channels:history',
         'channels:join',
         'channels:read',
         'chat:write',
+        'commands',
         'emoji:read',
         'files:read',
         'files:write',

package/src/config/index.ts

@@ -10,6 +10,7 @@ export {
   gitSchema,
   gitignoreSchema,
   loadConfigSync,
+  loadConfigSyncOrDefaults,
   loadPluginConfigsSync,
   migrateLegacyConfigShape,
   modelsSchema,

package/src/config/models-mutation.ts

@@ -3,7 +3,7 @@ import { join } from 'node:path'
 
 import { commitSystemFileSync } from '@/git/system-commit'
 
-import { configSchema, loadConfigSync, validateConfig } from './config'
+import { configSchema, loadConfigSyncOrDefaults, validateConfig } from './config'
 import {
   KNOWN_PROVIDERS,
   listKnownModelRefs,
@@ -33,8 +33,16 @@ export type ModelProfileEntry = {
 
 export type ModelMutationResult = { ok: true } | { ok: false; reason: string }
 
+// `listModelProfiles` is the read-only path behind `typeclaw model list`, a
+// diagnostic command. It routes through `loadConfigSyncOrDefaults` (same
+// soft-fail pattern as `typeclaw status` / `doctor`, PR #288) so a broken
+// `typeclaw.json` doesn't crash the command users reach for to see what
+// model config the agent thinks it has. Mutation paths (`setProfile`,
+// `addProfile`, `removeProfile`) stay on the strict gate via `validateConfig`
+// in `writeModels`, because writing through a broken-on-disk file would
+// silently land schema-invalid bytes.
 export function listModelProfiles(cwd: string, env: NodeJS.ProcessEnv = process.env): ModelProfileEntry[] {
-  const models = loadConfigSync(cwd).models
+  const models = loadConfigSyncOrDefaults(cwd).models
   const out: ModelProfileEntry[] = []
   for (const [profile, refs] of Object.entries(models)) {
     const headRef = refs[0]!

package/src/cron/consumer.ts

@@ -195,7 +195,7 @@ async function runPromptOnce(
             }
           : undefined
       if (created.hooks && turnEvent !== undefined) {
-        await created.hooks.runSessionTurnStart(turnEvent)
+        await created.hooks.runSessionTurnStart({ ...turnEvent, userPrompt: job.prompt })
       }
       // Bridge the CronSession wrapper into the AgentSession surface the
       // fallback helper expects: