typeclaw 0.3.1 → 0.5.0

package/src/cli/init.ts

@@ -1,3 +1,6 @@
+import { randomBytes } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+
 import { cancel, confirm, intro, isCancel, log, note, password, select, spinner, text } from '@clack/prompts'
 import { defineCommand } from 'citty'
 
@@ -8,14 +11,17 @@ import {
   type KnownModelRef,
   type KnownProviderId,
 } from '@/config/providers'
-import type { DockerAvailability } from '@/container'
+import { checkDockerAvailable, type DockerAvailability } from '@/container'
 import {
   findAgentDir,
+  formatEagerGithubWebhookInstallResult,
   hasExistingChannelSecrets,
   isDirectoryNonEmpty,
   isHatched,
   readExistingProviderApiKey,
   runInit,
+  type GithubInitCredentials,
+  type GithubTunnelProvider,
   type InitStep,
   type InitStepEvent,
   type KakaotalkAuthResult,
@@ -23,23 +29,48 @@ import {
 } from '@/init'
 import { runKakaotalkBootstrap } from '@/init/kakaotalk-auth'
 import { fetchModelOptions, type ModelOption } from '@/init/models-dev'
-import { makeOAuthLoginRunner } from '@/init/oauth-login'
+import { makeOAuthLoginRunner, type OAuthLoginResult } from '@/init/oauth-login'
 
+import { buildOAuthCallbacks } from './oauth-callbacks'
 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' }
+// either advances with a value or rewinds.
+//
+// Two cancel patterns must not trap the user:
+//   1. Single-prompt cancel-loop. On the first step (pick-provider) there
+//      is no previous step, so `back` re-displays the same prompt. Two
+//      consecutive cancels on that same prompt = the user wants out.
+//   2. Auto-advance round-trip. `back` from `enter-api-key` routes to
+//      `pick-auth-method`, which for single-method providers (e.g.
+//      Fireworks, api-key only) returns its value without prompting and
+//      sends the wizard straight back to `enter-api-key`. The user only
+//      ever sees the same api-key prompt and has no way to escape.
+//
+// Both patterns are detected in `collectWizardInputs` and surfaced as
+// `WizardAbortedError`, which the `init` command catches and turns into
+// a clean exit. Inside an active clack prompt Ctrl+C is still aliased to
+// cancel, so the abort hotkey is "cancel twice in a row".
+export class WizardAbortedError extends Error {
+  // When the wizard ran a successful eager OAuth login before aborting, the
+  // resulting credentials are already on disk at `<cwd>/secrets.json`. The
+  // CLI surfaces this on abort so the user knows to either re-run init in
+  // the same directory (the credentials will be reused) or delete the file.
+  readonly oauthCredentialsSaved: boolean
+  constructor(options: { oauthCredentialsSaved?: boolean } = {}) {
+    super('Wizard aborted by user')
+    this.name = 'WizardAbortedError'
+    this.oauthCredentialsSaved = options.oauthCredentialsSaved === true
+  }
+}
+
+export type StepResult<T> = { kind: 'value'; value: T; auto?: boolean } | { kind: 'back' }
 const back = <T>(): StepResult<T> => ({ kind: 'back' })
 const value = <T>(v: T): StepResult<T> => ({ kind: 'value', value: v })
+const autoValue = <T>(v: T): StepResult<T> => ({ kind: 'value', value: v, auto: true })
 
 export const init = defineCommand({
   meta: {
@@ -76,12 +107,54 @@ export const init = defineCommand({
     }
 
     intro('Initializing TypeClaw...')
-    log.info('Press ESC at any prompt to go back to the previous step.')
+    log.info('Press ESC at any prompt to go back. Press ESC twice in a row to abort.')
+
+    // Docker preflight runs BEFORE the wizard so an OAuth login (which the
+    // wizard fires the moment the user picks "OAuth (browser login)") doesn't
+    // burn a real browser flow on an agent folder we can't actually start.
+    // `runInit` re-runs the preflight as a defense-in-depth gate, but
+    // surfacing the failure here lets the user fix Docker without re-doing
+    // every wizard step.
+    const preflightSpinner = spinner()
+    preflightSpinner.start('Checking Docker...')
+    const preflight = await checkDockerAvailable()
+    if (!preflight.ok) {
+      preflightSpinner.error(preflightFailureSummary(preflight))
+      note(preflightFailureGuidance(preflight).join('\n'), 'Docker check failed')
+      process.exit(1)
+    }
+    preflightSpinner.stop('Docker is reachable.')
 
-    const collected = await collectWizardInputs(cwd, defaultWizardPrompts)
+    let collected: CollectedInputs
+    try {
+      collected = await collectWizardInputs(cwd, defaultWizardPrompts)
+    } catch (error) {
+      if (error instanceof WizardAbortedError) {
+        if (error.oauthCredentialsSaved) {
+          note(
+            [
+              'OAuth credentials were saved to `secrets.json` before you aborted.',
+              'Re-run `typeclaw init` here to pick up where you left off (the credentials',
+              'will be reused), or delete `secrets.json` if you want a clean restart.',
+            ].join('\n'),
+            'Saved OAuth credentials',
+          )
+        }
+        cancel('Aborted.')
+        process.exit(0)
+      }
+      throw error
+    }
     const { model, llmAuth, vision, channelChoice, reuseExistingChannel, channelSecrets } = collected
-    const { discordBotToken, slackBotToken, slackAppToken, telegramBotToken, kakaotalkEmail, kakaotalkPassword } =
-      channelSecrets
+    const {
+      discordBotToken,
+      slackBotToken,
+      slackAppToken,
+      telegramBotToken,
+      kakaotalkEmail,
+      kakaotalkPassword,
+      github: githubCredentials,
+    } = channelSecrets
 
     // TODO: add remaining wizard steps from TypeClaw.md once their runtime lands:
     //   - git backup (url + PAT) — Phase 10
@@ -96,7 +169,9 @@ export const init = defineCommand({
     const reuseSlack = reuseExistingChannel && channelChoice === 'slack'
     const reuseTelegram = reuseExistingChannel && channelChoice === 'telegram'
     const reuseKakaotalk = reuseExistingChannel && channelChoice === 'kakaotalk'
+    const reuseGithub = reuseExistingChannel && channelChoice === 'github'
     const wantsKakaotalk = (kakaotalkEmail !== undefined && kakaotalkPassword !== undefined) || reuseKakaotalk
+    const wantsGithub = githubCredentials !== undefined || reuseGithub
     let hatchingOk = false
     let preflightFailure: Extract<DockerAvailability, { ok: false }> | null = null
     try {
@@ -130,6 +205,12 @@ export const init = defineCommand({
                   }),
             }
           : {}),
+        ...(wantsGithub
+          ? {
+              withGithub: true,
+              ...(reuseGithub || githubCredentials === undefined ? {} : { githubCredentials }),
+            }
+          : {}),
         onProgress: reportProgress(
           (ok) => {
             hatchingOk = ok
@@ -149,6 +230,12 @@ export const init = defineCommand({
       process.exit(1)
     }
 
+    if (githubCredentials?.tunnelProvider === 'none') {
+      log.warn(
+        'Webhook delivery is disabled until you add a `tunnels[]` entry or set `channels.github.webhookUrl` manually.',
+      )
+    }
+
     if (hatchingOk) {
       done({
         title: c.green('Hatched. Your agent is ready.'),
@@ -179,7 +266,7 @@ interface WizardState {
   channelReuseExisting?: boolean
 }
 
-type ChannelChoice = 'slack' | 'discord' | 'telegram' | 'kakaotalk' | 'none'
+type ChannelChoice = 'slack' | 'discord' | 'telegram' | 'kakaotalk' | 'github' | 'none'
 
 interface CollectedInputs {
   model: ModelOption
@@ -201,6 +288,11 @@ interface CollectedInputs {
     telegramBotToken?: string
     kakaotalkEmail?: string
     kakaotalkPassword?: string
+    // Structured (auth union + webhook + repo allowlist) rather than flat
+    // tokens, so it rides as one sub-object instead of sibling fields.
+    // `runInit` delegates to `runAddChannel` for GitHub to keep the github
+    // config-writing in one place.
+    github?: GithubInitCredentials
   }
 }
 
@@ -250,9 +342,24 @@ export interface WizardPrompts {
   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
+  runOAuthLogin: (
+    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+    cwd: string,
+    model: KnownModelRef,
+  ) => Promise<OAuthLoginResult>
+  // Asked after a failed OAuth login. `apiKeyAvailable` is true when the
+  // provider also supports api-key auth (so the wizard can offer a fallback
+  // path); false for OAuth-only providers like openai-codex, where the only
+  // options are retry or abort.
+  askOAuthFailureRecovery: (
+    provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+    reason: string,
+    apiKeyAvailable: boolean,
+  ) => Promise<OAuthFailureRecovery>
 }
 
+export type OAuthFailureRecovery = 'retry' | 'api-key' | 'abort'
+
 export const defaultWizardPrompts: WizardPrompts = {
   loadCatalog,
   readExistingApiKey: readExistingProviderApiKey,
@@ -267,21 +374,35 @@ export const defaultWizardPrompts: WizardPrompts = {
   hasExistingChannelSecrets,
   askReuseExistingChannel,
   runChannelFlow,
-  buildOAuthAuth: (provider) => ({
-    kind: 'oauth',
-    runLogin: makeOAuthLoginRunner(buildOAuthCallbacks(provider.name)),
-  }),
+  runOAuthLogin: (provider, cwd, model) => makeOAuthLoginRunner(buildOAuthCallbacks(provider.name))({ cwd, model }),
+  askOAuthFailureRecovery,
 }
 
 export async function collectWizardInputs(cwd: string, prompts: WizardPrompts): Promise<CollectedInputs> {
   const catalog = await prompts.loadCatalog()
   const state: WizardState = { catalog }
   let step: StepId = 'pick-provider'
+  let pendingBackOrigin: StepId | null = null
+  let oauthCredentialsSaved = false
+
+  const abort = (): never => {
+    throw new WizardAbortedError({ oauthCredentialsSaved })
+  }
+
+  const onResult = <T>(currentStep: StepId, result: StepResult<T>): StepResult<T> => {
+    if (result.kind === 'back') {
+      if (pendingBackOrigin === currentStep) abort()
+      pendingBackOrigin = currentStep
+    } else if (!result.auto) {
+      pendingBackOrigin = null
+    }
+    return result
+  }
 
   while (true) {
     switch (step) {
       case 'pick-provider': {
-        const result = await prompts.pickProvider(catalog.options, state.providerId)
+        const result = onResult(step, await prompts.pickProvider(catalog.options, state.providerId))
         if (result.kind === 'back') {
           break
         }
@@ -297,7 +418,7 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
       }
 
       case 'pick-model': {
-        const result = await prompts.pickModel(catalog.options, state.providerId!, state.model?.ref)
+        const result = onResult(step, await prompts.pickModel(catalog.options, state.providerId!, state.model?.ref))
         if (result.kind === 'back') {
           step = 'pick-provider'
           break
@@ -310,7 +431,10 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
       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)
+        const decision = onResult(
+          step,
+          await prompts.askReuseExistingKey(provider, existingApiKey, state.reuseExisting),
+        )
         if (decision.kind === 'back') {
           step = 'pick-model'
           break
@@ -330,14 +454,39 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
 
       case 'pick-auth-method': {
         const provider = KNOWN_PROVIDERS[state.providerId!]
-        const result = await prompts.pickAuthMethod(provider, state.authMethod)
+        const result = onResult(step, 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)
+          // Run the browser login eagerly so the user sees the OAuth URL the
+          // moment they pick "OAuth (browser login)" — not at the end of the
+          // wizard. On failure we ask the user how to recover (retry / fall
+          // back to API key / abort) instead of dumping them back into the
+          // auth method picker with no guidance.
+          const login = await runOAuthLoginSafely(prompts, provider, cwd, state.model!.ref)
+          if (!login.ok) {
+            const recovery = await prompts.askOAuthFailureRecovery(
+              provider,
+              login.reason,
+              providerSupportsApiKey(provider),
+            )
+            // The recovery prompt is a fresh user decision, so it must clear
+            // any back-token left over from an earlier step. Without this, a
+            // sequence like `enter-api-key → back → autoValue('oauth') →
+            // OAuth fails → recovery=api-key → enter-api-key` would treat the
+            // user's NEXT back press as a double-back and abort the wizard.
+            pendingBackOrigin = null
+            if (recovery === 'abort') abort()
+            state.authMethod = recovery === 'api-key' ? 'api-key' : undefined
+            state.llmAuth = undefined
+            step = recovery === 'api-key' ? 'enter-api-key' : 'pick-auth-method'
+            break
+          }
+          oauthCredentialsSaved = true
+          state.llmAuth = { kind: 'oauth-completed' }
           step = stepAfterDefaultAuth(state)
         } else {
           step = 'enter-api-key'
@@ -347,7 +496,7 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
 
       case 'enter-api-key': {
         const provider = KNOWN_PROVIDERS[state.providerId!]
-        const result = await prompts.askApiKey(provider)
+        const result = onResult(step, await prompts.askApiKey(provider))
         if (result.kind === 'back') {
           step = 'pick-auth-method'
           break
@@ -359,7 +508,7 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
 
       case 'pick-vision-provider': {
         const visionOptions = catalog.options.filter((o) => o.supportsVision)
-        const result = await prompts.pickVisionProvider(visionOptions, state.visionProviderId)
+        const result = onResult(step, await prompts.pickVisionProvider(visionOptions, state.visionProviderId))
         if (result.kind === 'back') {
           step = stepBeforeVision(state)
           break
@@ -386,7 +535,10 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
 
       case 'pick-vision-model': {
         const visionOptions = catalog.options.filter((o) => o.supportsVision)
-        const result = await prompts.pickVisionModel(visionOptions, state.visionProviderId!, state.visionModel?.ref)
+        const result = onResult(
+          step,
+          await prompts.pickVisionModel(visionOptions, state.visionProviderId!, state.visionModel?.ref),
+        )
         if (result.kind === 'back') {
           step = 'pick-vision-provider'
           break
@@ -415,14 +567,32 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
 
       case 'pick-vision-auth-method': {
         const provider = KNOWN_PROVIDERS[state.visionProviderId!]
-        const result = await prompts.pickAuthMethod(provider, state.visionAuthMethod)
+        const result = onResult(step, 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)
+          // Same eager-login + recovery-prompt rationale as the default-provider branch above.
+          const login = await runOAuthLoginSafely(prompts, provider, cwd, state.visionModel!.ref)
+          if (!login.ok) {
+            const recovery = await prompts.askOAuthFailureRecovery(
+              provider,
+              login.reason,
+              providerSupportsApiKey(provider),
+            )
+            // See the matching pendingBackOrigin reset in the default-provider
+            // branch above — same reasoning applies to vision auth recovery.
+            pendingBackOrigin = null
+            if (recovery === 'abort') abort()
+            state.visionAuthMethod = recovery === 'api-key' ? 'api-key' : undefined
+            state.visionLlmAuth = undefined
+            step = recovery === 'api-key' ? 'enter-vision-api-key' : 'pick-vision-auth-method'
+            break
+          }
+          oauthCredentialsSaved = true
+          state.visionLlmAuth = { kind: 'oauth-completed' }
           step = 'pick-channel'
         } else {
           step = 'enter-vision-api-key'
@@ -432,7 +602,7 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
 
       case 'enter-vision-api-key': {
         const provider = KNOWN_PROVIDERS[state.visionProviderId!]
-        const result = await prompts.askApiKey(provider)
+        const result = onResult(step, await prompts.askApiKey(provider))
         if (result.kind === 'back') {
           step = 'pick-vision-auth-method'
           break
@@ -443,7 +613,7 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
       }
 
       case 'pick-channel': {
-        const result = await prompts.pickChannel(state.channelChoice)
+        const result: StepResult<ChannelChoice> = onResult(step, await prompts.pickChannel(state.channelChoice))
         if (result.kind === 'back') {
           step = stepBeforePickChannel(state)
           break
@@ -467,7 +637,7 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
           break
         }
         state.channelReuseOffered = true
-        const decision = await prompts.askReuseExistingChannel(choice)
+        const decision = onResult(step, await prompts.askReuseExistingChannel(choice))
         if (decision.kind === 'back') {
           step = 'pick-channel'
           break
@@ -483,7 +653,7 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
       }
 
       case 'channel-flow': {
-        const result = await prompts.runChannelFlow(state.channelChoice!)
+        const result = onResult(step, await prompts.runChannelFlow(state.channelChoice!))
         if (result.kind === 'back') {
           step = state.channelReuseOffered === true ? 'reuse-existing-channel' : 'pick-channel'
           break
@@ -494,6 +664,25 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
   }
 }
 
+// Belt-and-suspenders wrapper: `makeOAuthLoginRunner` already catches the
+// upstream pi-ai login flow and returns `{ ok: false, reason }`, but the
+// wizard cannot afford ANY uncaught throw from a custom runner (test seam,
+// future plugin-contributed runner) — it would bubble out of
+// `collectWizardInputs` and exit the whole init. Coerce unexpected throws to
+// the normal failure path so the recovery prompt always fires.
+async function runOAuthLoginSafely(
+  prompts: WizardPrompts,
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  cwd: string,
+  model: KnownModelRef,
+): Promise<OAuthLoginResult> {
+  try {
+    return await prompts.runOAuthLogin(provider, cwd, model)
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}
+
 function finalize(state: WizardState, channelSecrets: CollectedInputs['channelSecrets']): CollectedInputs {
   return {
     model: state.model!,
@@ -517,6 +706,8 @@ function channelDisplayName(choice: Exclude<ChannelChoice, 'none'>): string {
       return 'Telegram'
     case 'kakaotalk':
       return 'KakaoTalk'
+    case 'github':
+      return 'GitHub'
   }
 }
 
@@ -632,8 +823,7 @@ async function pickAuthMethod(
     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')
+  return autoValue(supportsOAuth ? 'oauth' : 'api-key')
 }
 
 async function pickVisionProvider(
@@ -643,7 +833,7 @@ async function pickVisionProvider(
   const providers = uniqueProviders(options)
   if (providers.length === 0) {
     log.warn('No vision-capable models available; skipping vision profile.')
-    return value('skip')
+    return autoValue('skip')
   }
   const choice = await select<KnownProviderId | 'skip'>({
     message: 'Your model is text-only. Pick a provider for the `vision` profile (used for image input)',
@@ -691,6 +881,28 @@ async function askApiKey(provider: (typeof KNOWN_PROVIDERS)[KnownProviderId]): P
   return value(apiKey)
 }
 
+async function askOAuthFailureRecovery(
+  provider: (typeof KNOWN_PROVIDERS)[KnownProviderId],
+  reason: string,
+  apiKeyAvailable: boolean,
+): Promise<OAuthFailureRecovery> {
+  note(reason, `${provider.name} OAuth login failed`)
+  const options: Array<{ value: OAuthFailureRecovery; label: string; hint?: string }> = [
+    { value: 'retry', label: 'Retry OAuth login' },
+  ]
+  if (apiKeyAvailable) {
+    options.push({ value: 'api-key', label: `Use a ${provider.name} API key instead` })
+  }
+  options.push({ value: 'abort', label: 'Abort init', hint: 'you can re-run `typeclaw init` later' })
+  const choice = await select<OAuthFailureRecovery>({
+    message: 'What next?',
+    options,
+    initialValue: 'retry',
+  })
+  if (isCancel(choice)) return 'abort'
+  return choice
+}
+
 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)',
@@ -699,6 +911,7 @@ async function pickChannel(initial: ChannelChoice | undefined): Promise<StepResu
       { value: 'discord', label: 'Discord' },
       { value: 'telegram', label: 'Telegram' },
       { value: 'kakaotalk', label: 'KakaoTalk' },
+      { value: 'github', label: 'GitHub' },
       { value: 'none', label: 'Skip — no channel right now' },
     ],
     initialValue: initial ?? 'slack',
@@ -719,6 +932,8 @@ async function runChannelFlow(choice: ChannelChoice): Promise<StepResult<Collect
       return runSlackFlow()
     case 'telegram':
       return runTelegramFlow()
+    case 'github':
+      return runGithubFlow()
   }
 }
 
@@ -881,6 +1096,151 @@ async function runSlackFlow(): Promise<StepResult<CollectedInputs['channelSecret
   }
 }
 
+async function runGithubFlow(): Promise<StepResult<CollectedInputs['channelSecrets']>> {
+  note(
+    [
+      'Choose PAT auth for a quick setup, or GitHub App auth for expiring installation tokens.',
+      'Required permissions: Issues read/write, Pull requests read/write, Discussions read/write (if used),',
+      'Metadata read, and Webhooks read/write (TypeClaw will create and manage the repository webhooks for you).',
+    ].join('\n'),
+    'Get GitHub credentials',
+  )
+  const authType = await select<'pat' | 'app'>({
+    message: 'GitHub authentication type',
+    options: [
+      { value: 'pat', label: 'Fine-grained personal access token' },
+      { value: 'app', label: 'GitHub App installation token' },
+    ],
+  })
+  if (isCancel(authType)) return back()
+  const auth = authType === 'pat' ? await promptGithubPatAuth() : await promptGithubAppAuth()
+  if (auth === null) return back()
+  note('GitHub webhooks need a public URL. TypeClaw can manage a tunnel for you.', 'GitHub webhook tunnel')
+  const tunnelProvider = await select<GithubTunnelProvider>({
+    message: 'Tunnel provider',
+    options: [
+      {
+        value: 'cloudflare-quick',
+        label: 'Cloudflare Quick Tunnel — no signup, URL rotates on restart (recommended)',
+      },
+      { value: 'external', label: 'External URL — I have my own reverse proxy / tunnel' },
+      { value: 'none', label: 'None — configure later by hand-editing typeclaw.json' },
+    ],
+    initialValue: 'cloudflare-quick',
+  })
+  if (isCancel(tunnelProvider)) return back()
+  const webhookUrl =
+    tunnelProvider === 'external'
+      ? await text({
+          message: 'Public webhook URL (GitHub will POST events here)',
+          validate: (v) => validateGithubUrl(v ?? '', 'Webhook URL is required'),
+        })
+      : undefined
+  if (isCancel(webhookUrl)) return back()
+  const port = await text({
+    message: 'Local webhook port inside the agent container',
+    initialValue: '8975',
+    validate: (v) => {
+      const parsed = Number(v)
+      return Number.isInteger(parsed) && parsed > 0 ? undefined : 'Port must be a positive integer'
+    },
+  })
+  if (isCancel(port)) return back()
+  const secret = await password({
+    message: 'Webhook secret (leave blank to auto-generate)',
+  })
+  if (isCancel(secret)) return back()
+  // clack's password() returns `undefined` on an empty submission (it has no
+  // validate guard and never coerces to ''), so we normalize before the
+  // length checks below to avoid a TypeError on the "leave blank" path.
+  const enteredSecret = typeof secret === 'string' ? secret : ''
+  const reposRaw = await text({
+    message: 'Repositories to allow (comma-separated owner/repo)',
+    validate: (v) => (parseGithubRepos(v ?? '').length > 0 ? undefined : 'At least one owner/repo is required'),
+  })
+  if (isCancel(reposRaw)) return back()
+  const resolvedSecret = enteredSecret.length > 0 ? enteredSecret : randomBytes(32).toString('hex')
+  return value({
+    github: {
+      webhookSecret: resolvedSecret,
+      tunnelProvider,
+      ...(webhookUrl !== undefined ? { webhookUrl } : {}),
+      webhookPort: Number(port),
+      repos: parseGithubRepos(reposRaw),
+      auth,
+    },
+  })
+}
+
+async function promptGithubPatAuth(): Promise<{ type: 'pat'; pat: string } | null> {
+  const pat = await password({
+    message: 'GitHub fine-grained PAT',
+    validate: (v) => (v && v.length > 0 ? undefined : 'PAT is required'),
+  })
+  if (isCancel(pat)) return null
+  return { type: 'pat', pat }
+}
+
+async function promptGithubAppAuth(): Promise<{
+  type: 'app'
+  appId: number
+  privateKey: string
+  installationId?: number
+} | null> {
+  const appId = await text({
+    message: 'GitHub App ID',
+    validate: (v) => validatePositiveInteger(v ?? '', 'App ID is required'),
+  })
+  if (isCancel(appId)) return null
+  const privateKeyInput = await text({
+    message: 'GitHub App private key PEM, escaped PEM, or path to .pem file',
+    validate: (v) => (v && v.length > 0 ? undefined : 'Private key is required'),
+  })
+  if (isCancel(privateKeyInput)) return null
+  const installationId = await text({
+    message: 'Installation ID (optional; leave blank to auto-discover)',
+    validate: (v) =>
+      v === undefined || v === '' ? undefined : validatePositiveInteger(v, 'Installation ID is required'),
+  })
+  if (isCancel(installationId)) return null
+  const parsedInstallationId = installationId === '' ? undefined : Number(installationId)
+  return {
+    type: 'app',
+    appId: Number(appId),
+    privateKey: await resolveGithubPrivateKey(privateKeyInput),
+    ...(parsedInstallationId !== undefined ? { installationId: parsedInstallationId } : {}),
+  }
+}
+
+async function resolveGithubPrivateKey(input: string): Promise<string> {
+  const normalized = input.replace(/\\n/g, '\n')
+  if (normalized.includes('-----BEGIN') && normalized.includes('PRIVATE KEY-----')) return normalized
+  return await readFile(input, 'utf8')
+}
+
+function parseGithubRepos(input: string): string[] {
+  return input
+    .split(',')
+    .map((v) => v.trim())
+    .filter((v) => /^[^\s/]+\/[^\s/]+$/.test(v))
+}
+
+function validateGithubUrl(v: string, requiredMessage: string): string | undefined {
+  if (!v || v.length === 0) return requiredMessage
+  try {
+    new URL(v)
+    return undefined
+  } catch {
+    return 'Must be a valid URL'
+  }
+}
+
+function validatePositiveInteger(v: string, requiredMessage: string): string | undefined {
+  if (!v || v.length === 0) return requiredMessage
+  const parsed = Number(v)
+  return Number.isInteger(parsed) && parsed > 0 ? undefined : 'Must be a positive integer'
+}
+
 async function runTelegramFlow(): Promise<StepResult<CollectedInputs['channelSecrets']>> {
   note(
     [
@@ -950,6 +1310,9 @@ function reportProgress(
       case 'kakaotalk-auth':
         s.stop(reportKakaotalkAuth(event.result))
         break
+      case 'github-webhooks':
+        s.stop(formatEagerGithubWebhookInstallResult(event.result))
+        break
       case 'oauth-login':
         s.stop(event.result.ok ? 'Logged in.' : `OAuth login failed: ${event.result.reason}`)
         break
@@ -1033,37 +1396,6 @@ export async function decideExistingApiKeyReuse(
   return reuse === true ? 'reuse' : 'prompt'
 }
 
-// Wraps the OAuth lifecycle into the same clack idiom the rest of the wizard
-// uses: a spinner over the "waiting for login" period, with onAuth printing
-// the URL the user needs to open and onPrompt falling back to a `text`
-// prompt for the manual code path. The spinner is started by onAuth and
-// stopped by the caller (runInit) — we don't try to manage it here because
-// the spinner lifecycle has to span emit('start') -> emit('done').
-function buildOAuthCallbacks(providerName: string) {
-  return {
-    onAuth: (url: string, instructions?: string) => {
-      // Don't put the URL inside note(): clack wraps long lines with the box
-      // border `│` on each wrapped segment, which corrupts the URL when the
-      // user copy-pastes it. Keep instructional text in the box, but print
-      // the URL itself as a bare console.log line that any terminal will
-      // hyperlink intact.
-      const preamble = [`Open this URL in your browser to authorize ${providerName}.`]
-      if (instructions) preamble.push('', instructions)
-      note(preamble.join('\n'), 'Browser login')
-      console.log(url)
-      console.log('')
-    },
-    onProgress: (message: string) => {
-      log.info(message)
-    },
-    onPrompt: async (message: string, placeholder?: string): Promise<string | null> => {
-      const value = await text({ message, ...(placeholder !== undefined ? { placeholder } : {}) })
-      if (isCancel(value)) return null
-      return value
-    },
-  }
-}
-
 function uniqueProviders(options: ModelOption[]): KnownProviderId[] {
   const seen = new Set<KnownProviderId>()
   const out: KnownProviderId[] = []
@@ -1096,6 +1428,7 @@ const START_MESSAGES: Record<Exclude<InitStep, 'hatching'>, string> = {
   'oauth-login': 'Waiting for browser login...',
   scaffold: 'Laying the egg...',
   'kakaotalk-auth': 'Logging in to KakaoTalk...',
+  'github-webhooks': 'Installing GitHub repository webhooks...',
   install: 'Installing dependencies with bun...',
   dockerfile: 'Writing Dockerfile...',
   git: 'Initializing git repository...',