typeclaw 0.3.1 → 0.4.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'
 
@@ -11,11 +14,14 @@ import {
 import type { DockerAvailability } from '@/container'
 import {
   findAgentDir,
+  formatEagerGithubWebhookInstallResult,
   hasExistingChannelSecrets,
   isDirectoryNonEmpty,
   isHatched,
   readExistingProviderApiKey,
   runInit,
+  type GithubInitCredentials,
+  type GithubTunnelProvider,
   type InitStep,
   type InitStepEvent,
   type KakaotalkAuthResult,
@@ -31,15 +37,33 @@ import { c, done, errorLine } from './ui'
 // 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 {
+  constructor() {
+    super('Wizard aborted by user')
+    this.name = 'WizardAbortedError'
+  }
+}
+
+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 +100,28 @@ 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.')
 
-    const collected = await collectWizardInputs(cwd, defaultWizardPrompts)
+    let collected: CollectedInputs
+    try {
+      collected = await collectWizardInputs(cwd, defaultWizardPrompts)
+    } catch (error) {
+      if (error instanceof WizardAbortedError) {
+        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 +136,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 +172,12 @@ export const init = defineCommand({
                   }),
             }
           : {}),
+        ...(wantsGithub
+          ? {
+              withGithub: true,
+              ...(reuseGithub || githubCredentials === undefined ? {} : { githubCredentials }),
+            }
+          : {}),
         onProgress: reportProgress(
           (ok) => {
             hatchingOk = ok
@@ -149,6 +197,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 +233,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 +255,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
   }
 }
 
@@ -277,11 +336,22 @@ export async function collectWizardInputs(cwd: string, prompts: WizardPrompts):
   const catalog = await prompts.loadCatalog()
   const state: WizardState = { catalog }
   let step: StepId = 'pick-provider'
+  let pendingBackOrigin: StepId | null = null
+
+  const onResult = <T>(currentStep: StepId, result: StepResult<T>): StepResult<T> => {
+    if (result.kind === 'back') {
+      if (pendingBackOrigin === currentStep) throw new WizardAbortedError()
+      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 +367,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 +380,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,7 +403,7 @@ 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
@@ -347,7 +420,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 +432,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 +459,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,7 +491,7 @@ 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
@@ -432,7 +508,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 +519,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 +543,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 +559,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
@@ -517,6 +593,8 @@ function channelDisplayName(choice: Exclude<ChannelChoice, 'none'>): string {
       return 'Telegram'
     case 'kakaotalk':
       return 'KakaoTalk'
+    case 'github':
+      return 'GitHub'
   }
 }
 
@@ -632,8 +710,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 +720,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)',
@@ -699,6 +776,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 +797,8 @@ async function runChannelFlow(choice: ChannelChoice): Promise<StepResult<Collect
       return runSlackFlow()
     case 'telegram':
       return runTelegramFlow()
+    case 'github':
+      return runGithubFlow()
   }
 }
 
@@ -881,6 +961,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 +1175,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
@@ -1096,6 +1324,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...',

package/src/cli/model.ts

@@ -57,7 +57,8 @@ const setSub = defineCommand({
       process.exit(1)
     }
     done({
-      title: c.green(`Profile "${profile}" set to ${ref}.`),
+      title: c.green(`Profile "${profile}" set.`),
+      details: `${profile} → ${ref}`,
       hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
     })
   },
@@ -97,7 +98,8 @@ const addSub = defineCommand({
       process.exit(1)
     }
     done({
-      title: c.green(`Profile "${args.profile}" → ${ref}.`),
+      title: c.green(`Profile "${args.profile}" added.`),
+      details: `${args.profile} → ${ref}`,
       hints: [{ label: 'If the agent is running:', command: 'typeclaw reload' }],
     })
   },

package/src/cli/plugin-command-help.ts

@@ -0,0 +1,49 @@
+import type { z } from 'zod'
+
+import { describeLeaf } from '@/plugin/zod-introspect'
+
+import type { DiscoveredCommand } from './plugin-commands'
+
+export function renderPluginCommandsSection(commands: readonly DiscoveredCommand[]): string | null {
+  if (commands.length === 0) return null
+  const lines: string[] = ['Plugin commands:']
+  const namePad = Math.max(...commands.map((c) => c.commandName.length))
+  for (const c of commands) {
+    lines.push(`  ${c.commandName.padEnd(namePad)}    ${c.command.description}`)
+  }
+  return lines.join('\n')
+}
+
+export function renderCommandHelp(c: DiscoveredCommand): string {
+  const lines: string[] = []
+  lines.push(`typeclaw ${c.commandName} — ${c.command.description}`)
+  lines.push('')
+  lines.push(`  Plugin: ${c.pluginName}${c.pluginVersion !== undefined ? ` v${c.pluginVersion}` : ''}`)
+  lines.push(`  Surface: ${c.command.surface}`)
+  lines.push('')
+
+  if (c.command.args === undefined) {
+    lines.push('  Options:')
+    lines.push('    (no options)')
+    return lines.join('\n')
+  }
+
+  lines.push('  Options:')
+  for (const line of renderFlags(c.command.args)) {
+    lines.push(`    ${line}`)
+  }
+  return lines.join('\n')
+}
+
+export function renderFlags(schema: z.ZodObject<z.ZodRawShape>): string[] {
+  const out: string[] = []
+  const shape = schema.shape as Record<string, unknown>
+  for (const [field, leaf] of Object.entries(shape)) {
+    const info = describeLeaf(leaf)
+    const required = info.required ? ' (required)' : ''
+    const defaultPart = info.defaultValue !== undefined ? ` (default: ${info.defaultValue})` : ''
+    const descPart = info.description !== undefined ? `  ${info.description}` : ''
+    out.push(`--${field}=<${info.kind}>${descPart}${required}${defaultPart}`)
+  }
+  return out
+}

package/src/cli/plugin-commands-dispatch.ts

@@ -0,0 +1,112 @@
+import { proxyContainerCommand } from './container-command-client'
+import { parseArgs, runHostCommand } from './host-command-runner'
+import { renderCommandHelp } from './plugin-command-help'
+import { discoverCommands } from './plugin-commands'
+
+export type PluginCommandDispatchOutcome =
+  | { kind: 'not-found' }
+  | { kind: 'dispatched'; exitCode: number }
+  | { kind: 'error'; exitCode: number; message: string }
+
+export type DispatchOptions = {
+  name: string
+  rawArgs: readonly string[]
+  cwd: string
+  stdin?: ReadableStream<Uint8Array>
+  stdout?: WritableStream<Uint8Array>
+  stderr?: WritableStream<Uint8Array>
+  signal?: AbortSignal
+}
+
+export async function dispatchPluginCommand(opts: DispatchOptions): Promise<PluginCommandDispatchOutcome> {
+  const discovery = await discoverCommands({ cwd: opts.cwd })
+  const match = discovery.commands.find((c) => c.commandName === opts.name)
+  if (match === undefined) {
+    // Surface plugin load failures so a user typing `typeclaw <cmd>` sees why
+    // their plugin's command isn't listed, instead of a generic "not found".
+    if (discovery.loadErrors.length > 0) {
+      const stderr = opts.stderr ?? defaultStderr()
+      const writer = stderr.getWriter()
+      const encoder = new TextEncoder()
+      for (const e of discovery.loadErrors) {
+        await writer.write(encoder.encode(`[plugin-commands] ${e.entry}: ${e.error}\n`))
+      }
+      writer.releaseLock()
+    }
+    return { kind: 'not-found' }
+  }
+
+  const stdin = opts.stdin ?? defaultStdin()
+  const stdout = opts.stdout ?? defaultStdout()
+  const stderr = opts.stderr ?? defaultStderr()
+  const signal = opts.signal ?? new AbortController().signal
+
+  if (opts.rawArgs.includes('--help') || opts.rawArgs.includes('-h')) {
+    const help = renderCommandHelp(match)
+    const writer = stdout.getWriter()
+    await writer.write(new TextEncoder().encode(`${help}\n`))
+    writer.releaseLock()
+    return { kind: 'dispatched', exitCode: 0 }
+  }
+
+  if (match.command.surface === 'container') {
+    const parsed = parseArgs(match.command, opts.rawArgs)
+    if (!parsed.ok) {
+      return { kind: 'error', exitCode: 2, message: parsed.message }
+    }
+    const containerResult = await proxyContainerCommand({
+      agentDir: discovery.agentDir,
+      commandName: match.commandName,
+      args: parsed.value,
+      stdin,
+      stdout,
+      stderr,
+      abortSignal: signal,
+    })
+    if (!containerResult.ok) {
+      return { kind: 'error', exitCode: containerResult.exitCode, message: containerResult.message }
+    }
+    return { kind: 'dispatched', exitCode: containerResult.exitCode }
+  }
+
+  const result = await runHostCommand({
+    agentDir: discovery.agentDir,
+    pluginName: match.pluginName,
+    pluginVersion: match.pluginVersion,
+    command: match.command,
+    rawArgs: opts.rawArgs,
+    signal,
+    stdin,
+    stdout,
+    stderr,
+  })
+
+  if (!result.ok) {
+    return { kind: 'error', exitCode: result.exitCode, message: result.message }
+  }
+  return { kind: 'dispatched', exitCode: result.exitCode }
+}
+
+function defaultStdin(): ReadableStream<Uint8Array> {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.close()
+    },
+  })
+}
+
+function defaultStdout(): WritableStream<Uint8Array> {
+  return new WritableStream<Uint8Array>({
+    write(chunk) {
+      process.stdout.write(chunk)
+    },
+  })
+}
+
+function defaultStderr(): WritableStream<Uint8Array> {
+  return new WritableStream<Uint8Array>({
+    write(chunk) {
+      process.stderr.write(chunk)
+    },
+  })
+}