typeclaw 0.8.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/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: