typeclaw 0.1.5 → 0.2.0

package/src/cli/init.ts

@@ -11,6 +11,7 @@ import {
 import type { DockerAvailability } from '@/container'
 import {
   findAgentDir,
+  hasExistingChannelSecrets,
   isDirectoryNonEmpty,
   isHatched,
   readExistingProviderApiKey,
@@ -26,6 +27,20 @@ import { makeOAuthLoginRunner } from '@/init/oauth-login'
 
 import { c, done, errorLine } from './ui'
 
+// ESC and Ctrl+C both produce clack's cancel symbol (the keypress layer
+// aliases both to the same "cancel" action — there's no way to tell them
+// apart through @clack/prompts). The wizard treats every cancel as "go
+// back to the previous step": each step that runs an interactive prompt
+// either advances with a value or rewinds. There is no "go back" target
+// on the very first step (pick-provider), so a `back` there is a no-op
+// that re-displays the same prompt rather than aborting. Users who want
+// to bail out of the wizard kill the process from outside (close the
+// terminal, send SIGTERM); inside an active clack prompt Ctrl+C is also
+// aliased to cancel, so there is no in-wizard abort hotkey.
+export type StepResult<T> = { kind: 'value'; value: T } | { kind: 'back' }
+const back = <T>(): StepResult<T> => ({ kind: 'back' })
+const value = <T>(v: T): StepResult<T> => ({ kind: 'value', value: v })
+
 export const init = defineCommand({
   meta: {
     name: 'init',
@@ -61,238 +76,58 @@ export const init = defineCommand({
     }
 
     intro('Initializing TypeClaw...')
+    log.info('Press ESC at any prompt to go back to the previous step.')
 
-    const selectedModel = await pickModel()
-    const provider = KNOWN_PROVIDERS[selectedModel.providerId]
-
-    const existingApiKey = await readExistingProviderApiKey(cwd, selectedModel.providerId)
-    const llmAuth = await collectLLMAuth(provider, existingApiKey)
-
-    const channelChoice = await select({
-      message: 'Pick a channel to wire (you can add more later by editing typeclaw.json + secrets.json)',
-      options: [
-        { value: 'slack', label: 'Slack' },
-        { value: 'discord', label: 'Discord' },
-        { value: 'telegram', label: 'Telegram' },
-        { value: 'kakaotalk', label: 'KakaoTalk' },
-        { value: 'none', label: 'Skip — no channel right now' },
-      ],
-      initialValue: 'slack' as const,
-    })
-    if (isCancel(channelChoice)) {
-      cancel('Aborted.')
-      process.exit(0)
-    }
-
-    let discordBotToken: string | undefined
-    let slackBotToken: string | undefined
-    let slackAppToken: string | undefined
-    let telegramBotToken: string | undefined
-    let kakaotalkEmail: string | undefined
-    let kakaotalkPassword: string | undefined
-
-    if (channelChoice === 'discord') {
-      note(
-        [
-          'https://discord.com/developers/applications',
-          'New Application → Bot tab → Reset Token.',
-          'Enable the MESSAGE CONTENT intent.',
-        ].join('\n'),
-        'Get a Discord bot token',
-      )
-      const token = await password({
-        message: 'Discord bot token',
-        validate: (value) => (value && value.length > 0 ? undefined : 'Token is required'),
-      })
-      if (isCancel(token)) {
-        cancel('Aborted.')
-        process.exit(0)
-      }
-      discordBotToken = token
-    }
-
-    if (channelChoice === 'kakaotalk') {
-      note(
-        [
-          'KakaoTalk authentication uses a personal account, registered as a',
-          'tablet sub-device. Messages will be sent and received under this',
-          'account. Use a non-primary account if possible.',
-          '',
-          'After you submit the password, KakaoTalk may ask you to confirm a',
-          'passcode on your phone. Watch the screen for the code.',
-        ].join('\n'),
-        'About to log in to KakaoTalk',
-      )
-      const email = await text({
-        message: 'KakaoTalk email',
-        validate: (value) => (value && value.length > 0 ? undefined : 'Email is required'),
-      })
-      if (isCancel(email)) {
-        cancel('Aborted.')
-        process.exit(0)
-      }
-      const pwd = await password({
-        message: 'KakaoTalk password',
-        validate: (value) => (value && value.length > 0 ? undefined : 'Password is required'),
-      })
-      if (isCancel(pwd)) {
-        cancel('Aborted.')
-        process.exit(0)
-      }
-      kakaotalkEmail = email
-      kakaotalkPassword = pwd
-    }
-
-    if (channelChoice === 'slack') {
-      note(
-        [
-          '1. https://api.slack.com/apps → Create New App → From a manifest.',
-          '   Pick your workspace, then paste this JSON manifest:',
-          '',
-          '   {',
-          '     "display_information": { "name": "TypeClaw" },',
-          '     "features": {',
-          '       "bot_user": { "display_name": "TypeClaw", "always_online": true }',
-          '     },',
-          '     "oauth_config": {',
-          '       "scopes": {',
-          '         "bot": [',
-          '           "app_mentions:read", "chat:write", "users:read", "files:read",',
-          '           "channels:history", "channels:read",',
-          '           "groups:history",   "groups:read",',
-          '           "im:history",       "im:read",',
-          '           "mpim:history",     "mpim:read"',
-          '         ]',
-          '       }',
-          '     },',
-          '     "settings": {',
-          '       "event_subscriptions": {',
-          '         "bot_events": [',
-          '           "app_mention",',
-          '           "message.channels", "message.groups",',
-          '           "message.im",       "message.mpim"',
-          '         ]',
-          '       },',
-          '       "socket_mode_enabled": true',
-          '     }',
-          '   }',
-          '',
-          '2. Install to Workspace, then OAuth & Permissions →',
-          '   copy the Bot User OAuth Token (xoxb-...).',
-          '3. Basic Information → App-Level Tokens → Generate Token and',
-          '   Scopes, add the connections:write scope, and copy the',
-          '   token (xapp-...). Socket Mode needs this; the manifest',
-          '   cannot grant it.',
-          '4. Invite the bot to any private channel or DM you want it in:',
-          '   /invite @TypeClaw',
-        ].join('\n'),
-        'Get a Slack bot',
-      )
-      const botToken = await password({
-        message: 'Slack bot token (xoxb-...)',
-        validate: (value) =>
-          value && value.length > 0
-            ? value.startsWith('xoxb-')
-              ? undefined
-              : 'Bot token must start with "xoxb-"'
-            : 'Token is required',
-      })
-      if (isCancel(botToken)) {
-        cancel('Aborted.')
-        process.exit(0)
-      }
-      slackBotToken = botToken
-      note(
-        [
-          'Slack does not accept connections:write inside the manifest, so',
-          'this token has to be generated by hand:',
-          '',
-          '1. Basic Information → App-Level Tokens → Generate Token and Scopes.',
-          '2. Token Name: anything (e.g. "socket-mode").',
-          '3. Add Scope → connections:write → Generate.',
-          '4. Copy the xapp-... token shown once on screen.',
-          '   (You cannot retrieve it later — only revoke and regenerate.)',
-        ].join('\n'),
-        'Generate the Slack app-level token',
-      )
-      const appToken = await password({
-        message: 'Slack app-level token (xapp-...) — Socket Mode requires this',
-        validate: (value) =>
-          value && value.length > 0
-            ? value.startsWith('xapp-')
-              ? undefined
-              : 'App-level token must start with "xapp-"'
-            : 'Token is required',
-      })
-      if (isCancel(appToken)) {
-        cancel('Aborted.')
-        process.exit(0)
-      }
-      slackAppToken = appToken
-    }
-
-    if (channelChoice === 'telegram') {
-      note(
-        [
-          'Open Telegram and message @BotFather.',
-          '/newbot → pick a name and username, copy the HTTP API token',
-          '  (looks like 1234567890:ABCdef...).',
-          'In @BotFather: /setprivacy → Disable, so the bot can see group messages.',
-        ].join('\n'),
-        'Get a Telegram bot token',
-      )
-      const token = await password({
-        message: 'Telegram bot token',
-        validate: (value) =>
-          value && value.length > 0
-            ? /^\d+:/.test(value)
-              ? undefined
-              : 'Bot token must look like "<digits>:<secret>" (from @BotFather)'
-            : 'Token is required',
-      })
-      if (isCancel(token)) {
-        cancel('Aborted.')
-        process.exit(0)
-      }
-      telegramBotToken = token
-      note(
-        [
-          'Open https://t.me/<your_bot_username> (the username you picked in /newbot, ends in "bot").',
-          'Tap Start in the chat — the agent will reply once it hatches.',
-          'For groups: add the bot to the group, then @mention it or reply to its messages.',
-        ].join('\n'),
-        'Send your first message',
-      )
-    }
+    const collected = await collectWizardInputs(cwd, defaultWizardPrompts)
+    const { model, llmAuth, vision, channelChoice, reuseExistingChannel, channelSecrets } = collected
+    const { discordBotToken, slackBotToken, slackAppToken, telegramBotToken, kakaotalkEmail, kakaotalkPassword } =
+      channelSecrets
 
     // TODO: add remaining wizard steps from TypeClaw.md once their runtime lands:
     //   - git backup (url + PAT) — Phase 10
     //   - cron.json scaffolding — Phase 9
     //   - compose.yml registration in $HOME/.typeclaw — Phase 12
-    const wantsKakaotalk = kakaotalkEmail !== undefined && kakaotalkPassword !== undefined
+
+    // Reuse means: wire the adapter in typeclaw.json but skip the prompt for
+    // fresh tokens / fresh kakaotalk login. `with<Adapter>` flags carry that
+    // intent down to scaffold(); writeSecrets / runKakaotalkAuth see no new
+    // input and leave the existing secrets.json slot untouched.
+    const reuseDiscord = reuseExistingChannel && channelChoice === 'discord'
+    const reuseSlack = reuseExistingChannel && channelChoice === 'slack'
+    const reuseTelegram = reuseExistingChannel && channelChoice === 'telegram'
+    const reuseKakaotalk = reuseExistingChannel && channelChoice === 'kakaotalk'
+    const wantsKakaotalk = (kakaotalkEmail !== undefined && kakaotalkPassword !== undefined) || reuseKakaotalk
     let hatchingOk = false
     let preflightFailure: Extract<DockerAvailability, { ok: false }> | null = null
     try {
       await runInit({
         cwd,
         llmAuth,
-        model: selectedModel.ref,
+        model: model.ref,
+        ...(vision !== undefined ? { visionModel: vision.model.ref, visionAuth: vision.llmAuth } : {}),
         cliEntry: process.argv[1],
         ...(discordBotToken !== undefined ? { discordBotToken } : {}),
         ...(slackBotToken !== undefined ? { slackBotToken, slackAppToken } : {}),
         ...(telegramBotToken !== undefined ? { telegramBotToken } : {}),
+        ...(reuseDiscord ? { withDiscord: true } : {}),
+        ...(reuseSlack ? { withSlack: true } : {}),
+        ...(reuseTelegram ? { withTelegram: true } : {}),
         ...(wantsKakaotalk
           ? {
               withKakaotalk: true,
-              runKakaotalkAuth: ({ cwd: agentDir }) =>
-                runKakaotalkBootstrap({
-                  email: kakaotalkEmail!,
-                  password: kakaotalkPassword!,
-                  agentDir,
-                  callbacks: {
-                    onPasscode: (code) => log.info(`Confirm this passcode on your phone: ${code}`),
-                  },
-                }),
+              ...(reuseKakaotalk
+                ? {}
+                : {
+                    runKakaotalkAuth: ({ cwd: agentDir }) =>
+                      runKakaotalkBootstrap({
+                        email: kakaotalkEmail!,
+                        password: kakaotalkPassword!,
+                        agentDir,
+                        callbacks: {
+                          onPasscode: (code) => log.info(`Confirm this passcode on your phone: ${code}`),
+                        },
+                      }),
+                  }),
             }
           : {}),
         onProgress: reportProgress(
@@ -327,6 +162,756 @@ export const init = defineCommand({
   },
 })
 
+interface WizardState {
+  catalog?: { options: ModelOption[]; source: 'models.dev' | 'curated'; warning?: string }
+  providerId?: KnownProviderId
+  model?: ModelOption
+  reuseExisting?: boolean
+  authMethod?: 'api-key' | 'oauth'
+  llmAuth?: LLMAuth
+  visionProviderId?: KnownProviderId
+  visionModel?: ModelOption
+  visionReuseExisting?: boolean
+  visionAuthMethod?: 'api-key' | 'oauth'
+  visionLlmAuth?: LLMAuth
+  channelChoice?: ChannelChoice
+  channelReuseOffered?: boolean
+  channelReuseExisting?: boolean
+}
+
+type ChannelChoice = 'slack' | 'discord' | 'telegram' | 'kakaotalk' | 'none'
+
+interface CollectedInputs {
+  model: ModelOption
+  llmAuth: LLMAuth
+  // Set only when the default model is text-only and the user picked a
+  // vision-capable model for the `vision` profile. `llmAuth` is reused from
+  // the default provider's credentials when the vision provider matches, so
+  // tests can still mint a single auth object and have it cover both.
+  vision?: {
+    model: ModelOption
+    llmAuth: LLMAuth
+  }
+  channelChoice: ChannelChoice
+  reuseExistingChannel: boolean
+  channelSecrets: {
+    discordBotToken?: string
+    slackBotToken?: string
+    slackAppToken?: string
+    telegramBotToken?: string
+    kakaotalkEmail?: string
+    kakaotalkPassword?: string
+  }
+}
+
+type StepId =
+  | 'pick-provider'
+  | 'pick-model'
+  | 'reuse-existing-key'
+  | 'pick-auth-method'
+  | 'enter-api-key'
+  | 'pick-vision-provider'
+  | 'pick-vision-model'
+  | 'pick-vision-auth-method'
+  | 'enter-vision-api-key'
+  | 'pick-channel'
+  | 'reuse-existing-channel'
+  | 'channel-flow'
+
+export interface WizardPrompts {
+  loadCatalog: () => Promise<NonNullable<WizardState['catalog']>>
+  readExistingApiKey: (cwd: string, providerId: KnownProviderId) => Promise<string | null>
+  pickProvider: (options: ModelOption[], initial: KnownProviderId | undefined) => Promise<StepResult<KnownProviderId>>
+  pickModel: (
+    options: ModelOption[],
+    providerId: KnownProviderId,
+    initial: KnownModelRef | undefined,
+  ) => Promise<StepResult<ModelOption>>
+  askReuseExistingKey: (
+    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+    existingApiKey: string | null,
+    initial: boolean | undefined,
+  ) => Promise<StepResult<'reuse' | 'prompt'>>
+  pickAuthMethod: (
+    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+    initial: 'api-key' | 'oauth' | undefined,
+  ) => Promise<StepResult<'api-key' | 'oauth'>>
+  askApiKey: (provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]) => Promise<StepResult<string>>
+  pickVisionProvider: (
+    options: ModelOption[],
+    initial: KnownProviderId | undefined,
+  ) => Promise<StepResult<KnownProviderId | 'skip'>>
+  pickVisionModel: (
+    options: ModelOption[],
+    providerId: KnownProviderId,
+    initial: KnownModelRef | undefined,
+  ) => Promise<StepResult<ModelOption>>
+  pickChannel: (initial: ChannelChoice | undefined) => Promise<StepResult<ChannelChoice>>
+  hasExistingChannelSecrets: (cwd: string, channel: Exclude<ChannelChoice, 'none'>) => Promise<boolean>
+  askReuseExistingChannel: (channel: Exclude<ChannelChoice, 'none'>) => Promise<StepResult<'reuse' | 'prompt'>>
+  runChannelFlow: (choice: ChannelChoice) => Promise<StepResult<CollectedInputs['channelSecrets']>>
+  buildOAuthAuth: (provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]) => LLMAuth
+}
+
+export const defaultWizardPrompts: WizardPrompts = {
+  loadCatalog,
+  readExistingApiKey: readExistingProviderApiKey,
+  pickProvider,
+  pickModel: pickModelForProvider,
+  askReuseExistingKey,
+  pickAuthMethod,
+  askApiKey,
+  pickVisionProvider,
+  pickVisionModel,
+  pickChannel,
+  hasExistingChannelSecrets,
+  askReuseExistingChannel,
+  runChannelFlow,
+  buildOAuthAuth: (provider) => ({
+    kind: 'oauth',
+    runLogin: makeOAuthLoginRunner(buildOAuthCallbacks(provider.name)),
+  }),
+}
+
+export async function collectWizardInputs(cwd: string, prompts: WizardPrompts): Promise<CollectedInputs> {
+  const catalog = await prompts.loadCatalog()
+  const state: WizardState = { catalog }
+  let step: StepId = 'pick-provider'
+
+  while (true) {
+    switch (step) {
+      case 'pick-provider': {
+        const result = await prompts.pickProvider(catalog.options, state.providerId)
+        if (result.kind === 'back') {
+          break
+        }
+        if (state.providerId !== result.value) {
+          state.model = undefined
+          state.reuseExisting = undefined
+          state.authMethod = undefined
+          state.llmAuth = undefined
+        }
+        state.providerId = result.value
+        step = 'pick-model'
+        break
+      }
+
+      case 'pick-model': {
+        const result = await prompts.pickModel(catalog.options, state.providerId!, state.model?.ref)
+        if (result.kind === 'back') {
+          step = 'pick-provider'
+          break
+        }
+        state.model = result.value
+        step = 'reuse-existing-key'
+        break
+      }
+
+      case 'reuse-existing-key': {
+        const provider = KNOWN_PROVIDERS[state.providerId!]
+        const existingApiKey = await prompts.readExistingApiKey(cwd, state.providerId!)
+        const decision = await prompts.askReuseExistingKey(provider, existingApiKey, state.reuseExisting)
+        if (decision.kind === 'back') {
+          step = 'pick-model'
+          break
+        }
+        if (decision.value === 'reuse' && existingApiKey !== null) {
+          log.info(`Using existing ${provider.name} API key from secrets.json.`)
+          state.llmAuth = { kind: 'api-key', apiKey: existingApiKey }
+          state.reuseExisting = true
+          step = stepAfterDefaultAuth(state)
+          break
+        }
+        state.reuseExisting = false
+        state.llmAuth = undefined
+        step = 'pick-auth-method'
+        break
+      }
+
+      case 'pick-auth-method': {
+        const provider = KNOWN_PROVIDERS[state.providerId!]
+        const result = await prompts.pickAuthMethod(provider, state.authMethod)
+        if (result.kind === 'back') {
+          step = 'reuse-existing-key'
+          break
+        }
+        state.authMethod = result.value
+        if (result.value === 'oauth') {
+          state.llmAuth = prompts.buildOAuthAuth(provider)
+          step = stepAfterDefaultAuth(state)
+        } else {
+          step = 'enter-api-key'
+        }
+        break
+      }
+
+      case 'enter-api-key': {
+        const provider = KNOWN_PROVIDERS[state.providerId!]
+        const result = await prompts.askApiKey(provider)
+        if (result.kind === 'back') {
+          step = 'pick-auth-method'
+          break
+        }
+        state.llmAuth = { kind: 'api-key', apiKey: result.value }
+        step = stepAfterDefaultAuth(state)
+        break
+      }
+
+      case 'pick-vision-provider': {
+        const visionOptions = catalog.options.filter((o) => o.supportsVision)
+        const result = await prompts.pickVisionProvider(visionOptions, state.visionProviderId)
+        if (result.kind === 'back') {
+          step = stepBeforeVision(state)
+          break
+        }
+        if (result.value === 'skip') {
+          state.visionProviderId = undefined
+          state.visionModel = undefined
+          state.visionLlmAuth = undefined
+          state.visionReuseExisting = undefined
+          state.visionAuthMethod = undefined
+          step = 'pick-channel'
+          break
+        }
+        if (state.visionProviderId !== result.value) {
+          state.visionModel = undefined
+          state.visionReuseExisting = undefined
+          state.visionAuthMethod = undefined
+          state.visionLlmAuth = undefined
+        }
+        state.visionProviderId = result.value
+        step = 'pick-vision-model'
+        break
+      }
+
+      case 'pick-vision-model': {
+        const visionOptions = catalog.options.filter((o) => o.supportsVision)
+        const result = await prompts.pickVisionModel(visionOptions, state.visionProviderId!, state.visionModel?.ref)
+        if (result.kind === 'back') {
+          step = 'pick-vision-provider'
+          break
+        }
+        state.visionModel = result.value
+        if (state.visionProviderId === state.providerId) {
+          log.info(`Using ${KNOWN_PROVIDERS[state.providerId!].name} credentials for the vision profile.`)
+          state.visionLlmAuth = state.llmAuth
+          state.visionReuseExisting = true
+          step = 'pick-channel'
+          break
+        }
+        const existingVisionKey = await prompts.readExistingApiKey(cwd, state.visionProviderId!)
+        if (existingVisionKey !== null) {
+          log.info(`Using existing ${KNOWN_PROVIDERS[state.visionProviderId!].name} API key from secrets.json.`)
+          state.visionLlmAuth = { kind: 'api-key', apiKey: existingVisionKey }
+          state.visionReuseExisting = true
+          step = 'pick-channel'
+          break
+        }
+        state.visionReuseExisting = false
+        state.visionLlmAuth = undefined
+        step = 'pick-vision-auth-method'
+        break
+      }
+
+      case 'pick-vision-auth-method': {
+        const provider = KNOWN_PROVIDERS[state.visionProviderId!]
+        const result = await prompts.pickAuthMethod(provider, state.visionAuthMethod)
+        if (result.kind === 'back') {
+          step = 'pick-vision-model'
+          break
+        }
+        state.visionAuthMethod = result.value
+        if (result.value === 'oauth') {
+          state.visionLlmAuth = prompts.buildOAuthAuth(provider)
+          step = 'pick-channel'
+        } else {
+          step = 'enter-vision-api-key'
+        }
+        break
+      }
+
+      case 'enter-vision-api-key': {
+        const provider = KNOWN_PROVIDERS[state.visionProviderId!]
+        const result = await prompts.askApiKey(provider)
+        if (result.kind === 'back') {
+          step = 'pick-vision-auth-method'
+          break
+        }
+        state.visionLlmAuth = { kind: 'api-key', apiKey: result.value }
+        step = 'pick-channel'
+        break
+      }
+
+      case 'pick-channel': {
+        const result = await prompts.pickChannel(state.channelChoice)
+        if (result.kind === 'back') {
+          step = stepBeforePickChannel(state)
+          break
+        }
+        if (state.channelChoice !== result.value) {
+          state.channelReuseOffered = undefined
+          state.channelReuseExisting = undefined
+        }
+        state.channelChoice = result.value
+        step = result.value === 'none' ? 'channel-flow' : 'reuse-existing-channel'
+        break
+      }
+
+      case 'reuse-existing-channel': {
+        const choice = state.channelChoice as Exclude<ChannelChoice, 'none'>
+        const present = await prompts.hasExistingChannelSecrets(cwd, choice)
+        if (!present) {
+          state.channelReuseOffered = false
+          state.channelReuseExisting = false
+          step = 'channel-flow'
+          break
+        }
+        state.channelReuseOffered = true
+        const decision = await prompts.askReuseExistingChannel(choice)
+        if (decision.kind === 'back') {
+          step = 'pick-channel'
+          break
+        }
+        if (decision.value === 'reuse') {
+          log.info(`Using existing ${channelDisplayName(choice)} credentials from secrets.json.`)
+          state.channelReuseExisting = true
+          return finalize(state, {})
+        }
+        state.channelReuseExisting = false
+        step = 'channel-flow'
+        break
+      }
+
+      case 'channel-flow': {
+        const result = await prompts.runChannelFlow(state.channelChoice!)
+        if (result.kind === 'back') {
+          step = state.channelReuseOffered === true ? 'reuse-existing-channel' : 'pick-channel'
+          break
+        }
+        return finalize(state, result.value)
+      }
+    }
+  }
+}
+
+function finalize(state: WizardState, channelSecrets: CollectedInputs['channelSecrets']): CollectedInputs {
+  return {
+    model: state.model!,
+    llmAuth: state.llmAuth!,
+    ...(state.visionModel !== undefined && state.visionLlmAuth !== undefined
+      ? { vision: { model: state.visionModel, llmAuth: state.visionLlmAuth } }
+      : {}),
+    channelChoice: state.channelChoice ?? 'none',
+    reuseExistingChannel: state.channelReuseExisting === true,
+    channelSecrets,
+  }
+}
+
+function channelDisplayName(choice: Exclude<ChannelChoice, 'none'>): string {
+  switch (choice) {
+    case 'slack':
+      return 'Slack'
+    case 'discord':
+      return 'Discord'
+    case 'telegram':
+      return 'Telegram'
+    case 'kakaotalk':
+      return 'KakaoTalk'
+  }
+}
+
+function stepAfterDefaultAuth(state: WizardState): StepId {
+  return state.model?.supportsVision === false ? 'pick-vision-provider' : 'pick-channel'
+}
+
+function stepBeforeVision(state: WizardState): StepId {
+  if (state.reuseExisting === true) return 'reuse-existing-key'
+  if (state.authMethod === 'api-key') return 'enter-api-key'
+  return 'pick-auth-method'
+}
+
+function stepBeforePickChannel(state: WizardState): StepId {
+  if (state.visionModel !== undefined) {
+    if (state.visionProviderId === state.providerId) return 'pick-vision-model'
+    if (state.visionReuseExisting === true) return 'pick-vision-model'
+    if (state.visionAuthMethod === 'api-key') return 'enter-vision-api-key'
+    if (state.visionAuthMethod === 'oauth') return 'pick-vision-auth-method'
+    return 'pick-vision-model'
+  }
+  if (state.model?.supportsVision === false) return 'pick-vision-provider'
+  return stepBeforeVision(state)
+}
+
+async function loadCatalog(): Promise<NonNullable<WizardState['catalog']>> {
+  const s = spinner()
+  s.start('Loading model catalog from models.dev...')
+  const { options, source, warning } = await fetchModelOptions()
+  if (source === 'curated') {
+    s.stop(`Using built-in catalog (models.dev unavailable: ${warning ?? 'unknown'})`)
+  } else {
+    s.stop('Loaded model catalog.')
+  }
+  return warning !== undefined ? { options, source, warning } : { options, source }
+}
+
+async function pickProvider(
+  options: ModelOption[],
+  initial: KnownProviderId | undefined,
+): Promise<StepResult<KnownProviderId>> {
+  const providers = uniqueProviders(options)
+  const choice = await select({
+    message: 'Pick an LLM provider',
+    options: providers.map((id) => ({ value: id, label: KNOWN_PROVIDERS[id].name, hint: providerAuthHint(id) })),
+    initialValue: initial ?? providers[0],
+  })
+  if (isCancel(choice)) return back()
+  return value(choice)
+}
+
+async function pickModelForProvider(
+  options: ModelOption[],
+  providerId: KnownProviderId,
+  initial: KnownModelRef | undefined,
+): Promise<StepResult<ModelOption>> {
+  const candidates = 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,
+      hint: formatModelHint(o),
+    })),
+    initialValue: initial ?? candidates[0]?.ref,
+  })
+  if (isCancel(choice)) return back()
+  const picked = candidates.find((o) => o.ref === choice)
+  if (!picked) throw new Error(`Internal error: picked model ${choice} not in candidates`)
+  return value(picked)
+}
+
+async function askReuseExistingKey(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  existingApiKey: string | null,
+  initial: boolean | undefined,
+): Promise<StepResult<'reuse' | 'prompt'>> {
+  if (!providerSupportsApiKey(provider) || existingApiKey === null) return value('prompt')
+  const reuse = await confirm({
+    message: `Reuse existing ${provider.name} API key from secrets.json?`,
+    initialValue: initial ?? true,
+  })
+  if (isCancel(reuse)) return back()
+  return value(reuse === true ? 'reuse' : 'prompt')
+}
+
+async function askReuseExistingChannel(
+  channel: Exclude<ChannelChoice, 'none'>,
+): Promise<StepResult<'reuse' | 'prompt'>> {
+  const reuse = await confirm({
+    message: `Reuse existing ${channelDisplayName(channel)} credentials from secrets.json?`,
+    initialValue: true,
+  })
+  if (isCancel(reuse)) return back()
+  return value(reuse === true ? 'reuse' : 'prompt')
+}
+
+async function pickAuthMethod(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  initial: 'api-key' | 'oauth' | undefined,
+): Promise<StepResult<'api-key' | 'oauth'>> {
+  const supportsApiKey = providerSupportsApiKey(provider)
+  const supportsOAuth = providerSupportsOAuth(provider)
+  if (supportsApiKey && supportsOAuth) {
+    const choice = await select<'api-key' | 'oauth'>({
+      message: `How do you want to authenticate to ${provider.name}?`,
+      options: [
+        { value: 'api-key', label: 'API key', hint: 'saved to secrets.json' },
+        { value: 'oauth', label: 'OAuth (browser login)', hint: 'saved to secrets.json' },
+      ],
+      initialValue: initial ?? 'api-key',
+    })
+    if (isCancel(choice)) return back()
+    return value(choice)
+  }
+  // Single-method providers: no prompt to back out of, so always advance.
+  return value(supportsOAuth ? 'oauth' : 'api-key')
+}
+
+async function pickVisionProvider(
+  options: ModelOption[],
+  initial: KnownProviderId | undefined,
+): Promise<StepResult<KnownProviderId | 'skip'>> {
+  const providers = uniqueProviders(options)
+  if (providers.length === 0) {
+    log.warn('No vision-capable models available; skipping vision profile.')
+    return value('skip')
+  }
+  const choice = await select<KnownProviderId | 'skip'>({
+    message: 'Your model is text-only. Pick a provider for the `vision` profile (used for image input)',
+    options: [
+      ...providers.map((id) => ({
+        value: id as KnownProviderId | 'skip',
+        label: KNOWN_PROVIDERS[id].name,
+        hint: providerAuthHint(id),
+      })),
+      { value: 'skip', label: 'Skip — no vision support', hint: 'add later with `typeclaw model set vision <ref>`' },
+    ],
+    initialValue: initial ?? providers[0],
+  })
+  if (isCancel(choice)) return back()
+  return value(choice)
+}
+
+async function pickVisionModel(
+  options: ModelOption[],
+  providerId: KnownProviderId,
+  initial: KnownModelRef | undefined,
+): Promise<StepResult<ModelOption>> {
+  const candidates = 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,
+      hint: formatModelHint(o),
+    })),
+    initialValue: initial ?? candidates[0]?.ref,
+  })
+  if (isCancel(choice)) return back()
+  const picked = candidates.find((o) => o.ref === choice)
+  if (!picked) throw new Error(`Internal error: picked vision model ${choice} not in candidates`)
+  return value(picked)
+}
+
+async function askApiKey(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]): Promise<StepResult<string>> {
+  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'),
+  })
+  if (isCancel(apiKey)) return back()
+  return value(apiKey)
+}
+
+async function pickChannel(initial: ChannelChoice | undefined): Promise<StepResult<ChannelChoice>> {
+  const choice = await select<ChannelChoice>({
+    message: 'Pick a channel to wire (you can add more later by editing typeclaw.json + secrets.json)',
+    options: [
+      { value: 'slack', label: 'Slack' },
+      { value: 'discord', label: 'Discord' },
+      { value: 'telegram', label: 'Telegram' },
+      { value: 'kakaotalk', label: 'KakaoTalk' },
+      { value: 'none', label: 'Skip — no channel right now' },
+    ],
+    initialValue: initial ?? 'slack',
+  })
+  if (isCancel(choice)) return back()
+  return value(choice)
+}
+
+async function runChannelFlow(choice: ChannelChoice): Promise<StepResult<CollectedInputs['channelSecrets']>> {
+  switch (choice) {
+    case 'none':
+      return value({})
+    case 'discord':
+      return runDiscordFlow()
+    case 'kakaotalk':
+      return runKakaotalkFlow()
+    case 'slack':
+      return runSlackFlow()
+    case 'telegram':
+      return runTelegramFlow()
+  }
+}
+
+async function runDiscordFlow(): Promise<StepResult<CollectedInputs['channelSecrets']>> {
+  note(
+    [
+      'https://discord.com/developers/applications',
+      'New Application → Bot tab → Reset Token.',
+      'Enable the MESSAGE CONTENT intent.',
+    ].join('\n'),
+    'Get a Discord bot token',
+  )
+  const token = await password({
+    message: 'Discord bot token',
+    validate: (v) => (v && v.length > 0 ? undefined : 'Token is required'),
+  })
+  if (isCancel(token)) return back()
+  return value({ discordBotToken: token })
+}
+
+async function runKakaotalkFlow(): Promise<StepResult<CollectedInputs['channelSecrets']>> {
+  // Sub-flow with its own back-aware loop: ESC on the password prompt
+  // returns to the email prompt; ESC on the email prompt unwinds to the
+  // channel picker.
+  type SubStep = 'email' | 'password'
+  let sub: SubStep = 'email'
+  let email: string | undefined
+  let pwd: string | undefined
+
+  note(
+    [
+      'KakaoTalk authentication uses a personal account, registered as a',
+      'tablet sub-device. Messages will be sent and received under this',
+      'account. Use a non-primary account if possible.',
+      '',
+      'After you submit the password, KakaoTalk may ask you to confirm a',
+      'passcode on your phone. Watch the screen for the code.',
+    ].join('\n'),
+    'About to log in to KakaoTalk',
+  )
+
+  while (true) {
+    if (sub === 'email') {
+      const input = await text({
+        message: 'KakaoTalk email',
+        ...(email !== undefined ? { initialValue: email } : {}),
+        validate: (v) => (v && v.length > 0 ? undefined : 'Email is required'),
+      })
+      if (isCancel(input)) return back()
+      email = input
+      sub = 'password'
+      continue
+    }
+    const input = await password({
+      message: 'KakaoTalk password',
+      validate: (v) => (v && v.length > 0 ? undefined : 'Password is required'),
+    })
+    if (isCancel(input)) {
+      sub = 'email'
+      continue
+    }
+    pwd = input
+    return value({ kakaotalkEmail: email, kakaotalkPassword: pwd })
+  }
+}
+
+async function runSlackFlow(): Promise<StepResult<CollectedInputs['channelSecrets']>> {
+  type SubStep = 'bot' | 'app'
+  let sub: SubStep = 'bot'
+  let botToken: string | undefined
+
+  note(
+    [
+      '1. https://api.slack.com/apps → Create New App → From a manifest.',
+      '   Pick your workspace, then paste this JSON manifest:',
+      '',
+      '   {',
+      '     "display_information": { "name": "TypeClaw" },',
+      '     "features": {',
+      '       "bot_user": { "display_name": "TypeClaw", "always_online": true }',
+      '     },',
+      '     "oauth_config": {',
+      '       "scopes": {',
+      '         "bot": [',
+      '           "app_mentions:read", "chat:write", "users:read", "files:read",',
+      '           "channels:history", "channels:read",',
+      '           "groups:history",   "groups:read",',
+      '           "im:history",       "im:read",',
+      '           "mpim:history",     "mpim:read"',
+      '         ]',
+      '       }',
+      '     },',
+      '     "settings": {',
+      '       "event_subscriptions": {',
+      '         "bot_events": [',
+      '           "app_mention",',
+      '           "message.channels", "message.groups",',
+      '           "message.im",       "message.mpim"',
+      '         ]',
+      '       },',
+      '       "socket_mode_enabled": true',
+      '     }',
+      '   }',
+      '',
+      '2. Install to Workspace, then OAuth & Permissions →',
+      '   copy the Bot User OAuth Token (xoxb-...).',
+      '3. Basic Information → App-Level Tokens → Generate Token and',
+      '   Scopes, add the connections:write scope, and copy the',
+      '   token (xapp-...). Socket Mode needs this; the manifest',
+      '   cannot grant it.',
+      '4. Invite the bot to any private channel or DM you want it in:',
+      '   /invite @TypeClaw',
+    ].join('\n'),
+    'Get a Slack bot',
+  )
+
+  while (true) {
+    if (sub === 'bot') {
+      const input = await password({
+        message: 'Slack bot token (xoxb-...)',
+        validate: (v) =>
+          v && v.length > 0
+            ? v.startsWith('xoxb-')
+              ? undefined
+              : 'Bot token must start with "xoxb-"'
+            : 'Token is required',
+      })
+      if (isCancel(input)) return back()
+      botToken = input
+      note(
+        [
+          'Slack does not accept connections:write inside the manifest, so',
+          'this token has to be generated by hand:',
+          '',
+          '1. Basic Information → App-Level Tokens → Generate Token and Scopes.',
+          '2. Token Name: anything (e.g. "socket-mode").',
+          '3. Add Scope → connections:write → Generate.',
+          '4. Copy the xapp-... token shown once on screen.',
+          '   (You cannot retrieve it later — only revoke and regenerate.)',
+        ].join('\n'),
+        'Generate the Slack app-level token',
+      )
+      sub = 'app'
+      continue
+    }
+    const input = await password({
+      message: 'Slack app-level token (xapp-...) — Socket Mode requires this',
+      validate: (v) =>
+        v && v.length > 0
+          ? v.startsWith('xapp-')
+            ? undefined
+            : 'App-level token must start with "xapp-"'
+          : 'Token is required',
+    })
+    if (isCancel(input)) {
+      sub = 'bot'
+      continue
+    }
+    return value({ slackBotToken: botToken!, slackAppToken: input })
+  }
+}
+
+async function runTelegramFlow(): Promise<StepResult<CollectedInputs['channelSecrets']>> {
+  note(
+    [
+      'Open Telegram and message @BotFather.',
+      '/newbot → pick a name and username, copy the HTTP API token',
+      '  (looks like 1234567890:ABCdef...).',
+      'In @BotFather: /setprivacy → Disable, so the bot can see group messages.',
+    ].join('\n'),
+    'Get a Telegram bot token',
+  )
+  const token = await password({
+    message: 'Telegram bot token',
+    validate: (v) =>
+      v && v.length > 0
+        ? /^\d+:/.test(v)
+          ? undefined
+          : 'Bot token must look like "<digits>:<secret>" (from @BotFather)'
+        : 'Token is required',
+  })
+  if (isCancel(token)) return back()
+  note(
+    [
+      'Open https://t.me/<your_bot_username> (the username you picked in /newbot, ends in "bot").',
+      'Tap Start in the chat — the agent will reply once it hatches.',
+      'For groups: add the bot to the group, then @mention it or reply to its messages.',
+    ].join('\n'),
+    'Send your first message',
+  )
+  return value({ telegramBotToken: token })
+}
+
 function reportProgress(
   onHatchingDone: (ok: boolean) => void,
   onPreflightFail: (result: Extract<DockerAvailability, { ok: false }>) => void,
@@ -432,69 +1017,8 @@ function reportHatching(event: Extract<InitStepEvent, { step: 'hatching' }>): vo
   if (event.result.ok) {
     console.log('Hatched. 🐣')
   } else {
-    console.error(`Hatching failed: ${event.result.reason}`)
-  }
-}
-
-// Resolves how the user wants to authenticate to the chosen provider:
-// - api-key only (e.g. Fireworks): prompt for the key, write to secrets.json.
-// - oauth only (e.g. openai-codex): run the browser flow inline, write
-//   secrets.json. No API key prompt at all.
-// - both supported (no providers ship this today, but Anthropic will when
-//   wired): ask "API key or OAuth?" first, then dispatch to the chosen path.
-async function collectLLMAuth(
-  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
-  existingApiKey: string | null,
-): Promise<LLMAuth> {
-  const supportsApiKey = providerSupportsApiKey(provider)
-  const supportsOAuth = providerSupportsOAuth(provider)
-
-  const existingKeyDecision = await decideExistingApiKeyReuse(provider, existingApiKey, (message) =>
-    confirm({ message, initialValue: true }),
-  )
-  if (existingKeyDecision === 'cancel') {
-    cancel('Aborted.')
-    process.exit(0)
-  }
-  if (existingKeyDecision === 'reuse' && existingApiKey !== null) {
-    log.info(`Using existing ${provider.name} API key from secrets.json.`)
-    return { kind: 'api-key', apiKey: existingApiKey }
-  }
-
-  let method: 'api-key' | 'oauth'
-  if (supportsApiKey && supportsOAuth) {
-    const choice = await select<'api-key' | 'oauth'>({
-      message: `How do you want to authenticate to ${provider.name}?`,
-      options: [
-        { value: 'api-key', label: 'API key', hint: 'saved to secrets.json' },
-        { value: 'oauth', label: 'OAuth (browser login)', hint: 'saved to secrets.json' },
-      ],
-      initialValue: 'api-key',
-    })
-    if (isCancel(choice)) {
-      cancel('Aborted.')
-      process.exit(0)
-    }
-    method = choice
-  } else if (supportsOAuth) {
-    method = 'oauth'
-  } else {
-    method = 'api-key'
-  }
-
-  if (method === 'api-key') {
-    const apiKey = await password({
-      message: `Put your ${provider.name} API key (will be saved to secrets.json)`,
-      validate: (value) => (value && value.length > 0 ? undefined : 'API key is required'),
-    })
-    if (isCancel(apiKey)) {
-      cancel('Aborted.')
-      process.exit(0)
-    }
-    return { kind: 'api-key', apiKey }
+    console.error(errorLine(`Hatching failed: ${event.result.reason}`))
   }
-
-  return { kind: 'oauth', runLogin: makeOAuthLoginRunner(buildOAuthCallbacks(provider.name)) }
 }
 
 export async function decideExistingApiKeyReuse(
@@ -540,50 +1064,6 @@ function buildOAuthCallbacks(providerName: string) {
   }
 }
 
-// Two-step provider+model picker. We split it because most users have a key
-// for exactly one provider — asking them to scroll through a flat list of
-// every (provider, model) pair would surface options they can't use.
-async function pickModel(): Promise<ModelOption> {
-  const s = spinner()
-  s.start('Loading model catalog from models.dev...')
-  const { options, source, warning } = await fetchModelOptions()
-  if (source === 'curated') {
-    s.stop(`Using built-in catalog (models.dev unavailable: ${warning ?? 'unknown'})`)
-  } else {
-    s.stop('Loaded model catalog.')
-  }
-
-  const providers = uniqueProviders(options)
-  const providerChoice = await select({
-    message: 'Pick an LLM provider',
-    options: providers.map((id) => ({ value: id, label: KNOWN_PROVIDERS[id].name, hint: providerAuthHint(id) })),
-    initialValue: providers[0],
-  })
-  if (isCancel(providerChoice)) {
-    cancel('Aborted.')
-    process.exit(0)
-  }
-
-  const candidates = options.filter((o) => o.providerId === providerChoice)
-  const modelChoice = await select<KnownModelRef>({
-    message: `Pick a ${KNOWN_PROVIDERS[providerChoice].name} model`,
-    options: candidates.map((o) => ({
-      value: o.ref,
-      label: o.modelName,
-      hint: formatModelHint(o),
-    })),
-    initialValue: candidates[0]?.ref,
-  })
-  if (isCancel(modelChoice)) {
-    cancel('Aborted.')
-    process.exit(0)
-  }
-
-  const picked = candidates.find((o) => o.ref === modelChoice)
-  if (!picked) throw new Error(`Internal error: picked model ${modelChoice} not in candidates`)
-  return picked
-}
-
 function uniqueProviders(options: ModelOption[]): KnownProviderId[] {
   const seen = new Set<KnownProviderId>()
   const out: KnownProviderId[] = []