typeclaw 0.1.5 → 0.1.6

package/src/init/index.ts

@@ -81,7 +81,15 @@ export type InitStepEvent =
 // portbroker — same path `typeclaw start` takes. When omitted (test fixtures,
 // programmatic callers that never want a daemon), `start()` skips the daemon
 // path entirely and the container runs unmanaged.
-export type HatchRunner = (options: { cwd: string; port: number; cliEntry?: string }) => Promise<HatchingResult>
+export type HatchRunner = (options: {
+  cwd: string
+  port: number
+  cliEntry?: string
+  // Set when the wizard wired at least one channel adapter, so the runner
+  // can offer to run `typeclaw role claim` after the container is ready.
+  // Empty / undefined means "no channels — skip the claim flow".
+  configuredChannels?: readonly ChannelKind[]
+}) => Promise<HatchingResult>
 
 export type KakaotalkAuthRunner = (options: { cwd: string }) => Promise<KakaotalkAuthResult>
 
@@ -101,16 +109,27 @@ export type InitOptions = {
   // defaults to the api-key path with `apiKey` (legacy field, still
   // supported for backwards compat with the old `runInit` signature).
   llmAuth?: LLMAuth
+  // Optional second model + auth, written as `models.vision` when the
+  // default model is text-only. Auth is reused from the default path
+  // when both refer to the same provider; the wizard enforces this
+  // pairing rule, so by the time we get here `visionAuth` is either
+  // (a) absent, or (b) the right auth for `visionModel`'s provider.
+  visionModel?: KnownModelRef
+  visionAuth?: LLMAuth
   apiKey?: string
   discordBotToken?: string
-  discordAllowAll?: boolean
   slackBotToken?: string
   slackAppToken?: string
-  slackAllowAll?: boolean
   telegramBotToken?: string
-  telegramAllowAll?: boolean
+  // When reusing existing channel credentials from a pre-init `secrets.json`,
+  // the CLI passes `with<Adapter>: true` without a corresponding token so the
+  // scaffolded `typeclaw.json` wires the adapter while `writeSecrets` leaves
+  // the existing slot in `secrets.json#channels` untouched. Defaults below
+  // mirror the legacy derivation (`<token> !== undefined && !== ''`).
+  withDiscord?: boolean
+  withSlack?: boolean
+  withTelegram?: boolean
   withKakaotalk?: boolean
-  kakaotalkAllowAll?: boolean
   runKakaotalkAuth?: KakaotalkAuthRunner
   onProgress?: (event: InitStepEvent) => void
   runHatching?: HatchRunner
@@ -129,15 +148,16 @@ export async function runInit({
   apiKey,
   llmAuth,
   model = DEFAULT_MODEL_REF,
+  visionModel,
+  visionAuth,
   discordBotToken,
-  discordAllowAll = true,
   slackBotToken,
   slackAppToken,
-  slackAllowAll = true,
   telegramBotToken,
-  telegramAllowAll = true,
+  withDiscord,
+  withSlack,
+  withTelegram,
   withKakaotalk = false,
-  kakaotalkAllowAll = false,
   runKakaotalkAuth,
   onProgress,
   runHatching = defaultRunHatching,
@@ -180,20 +200,36 @@ export async function runInit({
     }
   }
 
-  const wantsDiscord = discordBotToken !== undefined && discordBotToken !== ''
-  const wantsSlack = slackBotToken !== undefined && slackBotToken !== ''
-  const wantsTelegram = telegramBotToken !== undefined && telegramBotToken !== ''
+  // When the vision profile uses a different provider than the default, its
+  // OAuth login runs here too, before any file write. Same-provider vision
+  // reuses the default auth (no separate login). API-key vision auth is
+  // captured in memory and persisted by writeSecrets() below.
+  if (
+    visionAuth !== undefined &&
+    visionAuth.kind === 'oauth' &&
+    visionModel !== undefined &&
+    providerForModelRef(visionModel) !== providerForModelRef(model)
+  ) {
+    emit({ step: 'oauth-login', phase: 'start' })
+    await mkdir(cwd, { recursive: true })
+    const result = await visionAuth.runLogin({ cwd, model: visionModel })
+    emit({ step: 'oauth-login', phase: 'done', result })
+    if (!result.ok) {
+      throw new Error(`OAuth login failed: ${result.reason}`)
+    }
+  }
+
+  const wantsDiscord = withDiscord ?? (discordBotToken !== undefined && discordBotToken !== '')
+  const wantsSlack = withSlack ?? (slackBotToken !== undefined && slackBotToken !== '')
+  const wantsTelegram = withTelegram ?? (telegramBotToken !== undefined && telegramBotToken !== '')
   emit({ step: 'scaffold', phase: 'start' })
   await scaffold(cwd, {
     model,
+    ...(visionModel !== undefined ? { visionModel } : {}),
     withDiscord: wantsDiscord,
-    discordAllowAll,
     withSlack: wantsSlack,
-    slackAllowAll,
     withTelegram: wantsTelegram,
-    telegramAllowAll,
     withKakaotalk,
-    kakaotalkAllowAll,
   })
   // Only write the LLM API key on the api-key path. OAuth providers persist
   // their credentials to secrets.json (via the OAuth login step above); writing
@@ -201,6 +237,9 @@ export async function runInit({
   await writeSecrets(cwd, {
     model,
     apiKey: resolvedAuth.kind === 'api-key' ? resolvedAuth.apiKey : undefined,
+    ...(visionModel !== undefined && visionAuth?.kind === 'api-key'
+      ? { visionModel, visionApiKey: visionAuth.apiKey }
+      : {}),
     discordBotToken,
     slackBotToken,
     slackAppToken,
@@ -235,8 +274,19 @@ export async function runInit({
   const git = await initGitRepo(cwd)
   emit({ step: 'git', phase: 'done', result: git })
 
+  const configuredChannels: ChannelKind[] = []
+  if (wantsDiscord) configuredChannels.push('discord-bot')
+  if (wantsSlack) configuredChannels.push('slack-bot')
+  if (wantsTelegram) configuredChannels.push('telegram-bot')
+  if (withKakaotalk) configuredChannels.push('kakaotalk')
+
   emit({ step: 'hatching', phase: 'start' })
-  const hatching = await runHatching({ cwd, port: config.port, ...(cliEntry !== undefined ? { cliEntry } : {}) })
+  const hatching = await runHatching({
+    cwd,
+    port: config.port,
+    ...(cliEntry !== undefined ? { cliEntry } : {}),
+    ...(configuredChannels.length > 0 ? { configuredChannels } : {}),
+  })
   emit({ step: 'hatching', phase: 'done', result: hatching })
 }
 
@@ -250,16 +300,20 @@ export async function defaultRunHatching({
   cwd,
   port,
   cliEntry,
+  configuredChannels,
   startContainer = start,
   tui: tuiFactory = createTui,
   waitForAgent: waitForAgentFn = waitForAgent,
+  runClaim = defaultRunClaim,
 }: {
   cwd: string
   port: number
   cliEntry?: string
+  configuredChannels?: readonly ChannelKind[]
   startContainer?: typeof start
   tui?: typeof createTui
   waitForAgent?: typeof waitForAgent
+  runClaim?: ClaimRunner
 }): Promise<HatchingResult> {
   try {
     const launch = await startContainer({
@@ -276,6 +330,11 @@ export async function defaultRunHatching({
 
     await waitForAgentFn(`http://127.0.0.1:${hostPort}`, { timeoutMs: 30_000 })
 
+    if (configuredChannels !== undefined && configuredChannels.length > 0) {
+      const url = buildTuiUrl(hostPort, launch.tuiToken)
+      await runClaim({ url, configuredChannels })
+    }
+
     const tui = tuiFactory({
       url: buildTuiUrl(hostPort, launch.tuiToken),
       initialPrompt: HATCHING_PROMPT,
@@ -287,6 +346,13 @@ export async function defaultRunHatching({
   }
 }
 
+export type ClaimRunner = (options: { url: string; configuredChannels: readonly ChannelKind[] }) => Promise<void>
+
+const defaultRunClaim: ClaimRunner = async ({ url, configuredChannels }) => {
+  const { runOwnerClaim } = await import('./run-owner-claim')
+  await runOwnerClaim({ url, configuredChannels })
+}
+
 function buildTuiUrl(hostPort: number, token: string | null): string {
   const url = new URL(`ws://127.0.0.1:${hostPort}`)
   if (token !== null) url.searchParams.set('token', token)
@@ -372,14 +438,11 @@ export async function isHatched(dir: string): Promise<boolean> {
 
 export type ScaffoldOptions = {
   model?: KnownModelRef
+  visionModel?: KnownModelRef
   withDiscord?: boolean
-  discordAllowAll?: boolean
   withSlack?: boolean
-  slackAllowAll?: boolean
   withTelegram?: boolean
-  telegramAllowAll?: boolean
   withKakaotalk?: boolean
-  kakaotalkAllowAll?: boolean
 }
 
 export async function scaffold(root: string, options: ScaffoldOptions = {}): Promise<void> {
@@ -392,30 +455,22 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
   // immediately populated, so packages/ is the only one that needs this.
   await writeFile(join(root, PACKAGES_DIR, GITKEEP_FILE), '', { flag: 'wx' }).catch(ignoreExists)
 
-  // Only fields without sensible defaults elsewhere are emitted, with one
-  // exception: `network.blockInternal` is re-emitted at its default value
-  // (`true`) because the field is security-relevant and users need to
-  // discover it in their `typeclaw.json` to know they can opt out for LAN
-  // access. `mounts` defaults to `[]` in configSchema, and the bundled
-  // memory plugin owns its own defaults in src/bundled-plugins/memory/
-  // index.ts — re-emitting either here would be duplicate noise the user
-  // has to maintain in sync with the source of truth.
+  // Only fields without sensible defaults elsewhere are emitted. Everything
+  // with a schema-provided default (e.g. `network.blockInternal`, `mounts`,
+  // `memory.*`) is omitted to keep the scaffold minimal — duplicating defaults
+  // here would mean every schema change has to be mirrored in two places, and
+  // users would feel obligated to maintain values they never set.
+  const models: Record<string, KnownModelRef> = { default: options.model ?? DEFAULT_MODEL_REF }
+  if (options.visionModel !== undefined) models.vision = options.visionModel
   const config: Record<string, unknown> = {
     $schema: './node_modules/typeclaw/typeclaw.schema.json',
-    model: options.model ?? DEFAULT_MODEL_REF,
-    network: { blockInternal: true },
-  }
-  const channels: Record<string, { allow: string[] }> = {}
-  if (options.withDiscord) channels['discord-bot'] = { allow: options.discordAllowAll === false ? [] : ['*'] }
-  if (options.withSlack) channels['slack-bot'] = { allow: options.slackAllowAll === false ? [] : ['*'] }
-  if (options.withTelegram) channels['telegram-bot'] = { allow: options.telegramAllowAll === false ? [] : ['*'] }
-  if (options.withKakaotalk) {
-    // KakaoTalk involves a personal account, so we default to a tighter
-    // allow list (DMs only) than Slack/Discord/Telegram which scope to a
-    // workspace the user explicitly admitted the bot into. The user can
-    // broaden to `kakao:*` later by editing typeclaw.json.
-    channels.kakaotalk = { allow: options.kakaotalkAllowAll === true ? ['kakao:*'] : ['kakao:dm/*'] }
+    models,
   }
+  const channels: Record<string, Record<string, never>> = {}
+  if (options.withDiscord) channels['discord-bot'] = {}
+  if (options.withSlack) channels['slack-bot'] = {}
+  if (options.withTelegram) channels['telegram-bot'] = {}
+  if (options.withKakaotalk) channels.kakaotalk = {}
   if (Object.keys(channels).length > 0) config.channels = channels
   await writeFile(join(root, CONFIG_FILE), `${JSON.stringify(config, null, 2)}\n`)
 
@@ -578,6 +633,8 @@ export async function writeSecrets(
   {
     model = DEFAULT_MODEL_REF,
     apiKey,
+    visionModel,
+    visionApiKey,
     discordBotToken,
     slackBotToken,
     slackAppToken,
@@ -586,6 +643,8 @@ export async function writeSecrets(
     model?: KnownModelRef
     // Omitted on the OAuth path — credentials live in secrets.json via the OAuth runner.
     apiKey?: string
+    visionModel?: KnownModelRef
+    visionApiKey?: string
     discordBotToken?: string
     slackBotToken?: string
     slackAppToken?: string
@@ -594,8 +653,20 @@ export async function writeSecrets(
 ): Promise<void> {
   const providerId = providerForModelRef(model)
   const apiKeyEnv = KNOWN_PROVIDERS[providerId].apiKeyEnv
-  if (apiKey !== undefined && apiKeyEnv !== null) {
-    createSecretsStoreForAgent(join(root, 'secrets.json')).set(providerId, { type: 'api_key', key: apiKey })
+  const wantsDefaultKey = apiKey !== undefined && apiKeyEnv !== null
+  const visionProviderId = visionModel !== undefined ? providerForModelRef(visionModel) : null
+  const wantsVisionKey =
+    visionModel !== undefined &&
+    visionApiKey !== undefined &&
+    visionProviderId !== providerId &&
+    visionProviderId !== null &&
+    KNOWN_PROVIDERS[visionProviderId].apiKeyEnv !== null
+  if (wantsDefaultKey || wantsVisionKey) {
+    const secretsStore = createSecretsStoreForAgent(join(root, 'secrets.json'))
+    if (wantsDefaultKey) secretsStore.set(providerId, { type: 'api_key', key: apiKey! })
+    if (wantsVisionKey) {
+      secretsStore.set(visionProviderId, { type: 'api_key', key: visionApiKey! })
+    }
   }
 
   const channelTokens: Record<string, Record<string, Secret>> = {}
@@ -630,6 +701,70 @@ export async function readExistingProviderApiKey(root: string, providerId: Known
   return new SecretsBackend(join(root, 'secrets.json')).tryReadProviderApiKeySync(providerId)
 }
 
+// Detects whether the requested channel already has usable credentials in
+// `secrets.json#channels`, so the init wizard can offer to reuse them
+// instead of re-prompting for tokens. Mirrors `readExistingProviderApiKey`:
+// returns `true` only when ALL fields the adapter needs are present in a
+// shape `hydrateChannelEnvFromSecrets` would inject at runtime — both the
+// `{ value }` form and the `{ env }` env-binding form count, matching the
+// runtime resolution rules in `src/secrets/resolve.ts`. Partial slots (e.g.
+// `slack-bot` with `botToken` but no `appToken`) return `false` so the
+// missing field gets filled in by the normal prompt.
+//
+// KakaoTalk reuse is stricter: a usable block requires both a complete
+// account (currentAccount + matching entry in accounts) AND the renewal
+// fields (email + encryptedPassword) the hostd renewal cron needs to mint
+// fresh tokens unattended (`src/secrets/kakao-renewal.ts`). Without those,
+// the saved `oauth_token` will work only until KakaoTalk's ~7-day TTL
+// expires, after which the user has to run `typeclaw channel reauth
+// kakaotalk` anyway — better to re-auth now during init.
+export async function hasExistingChannelSecrets(
+  root: string,
+  channel: 'discord' | 'slack' | 'telegram' | 'kakaotalk',
+): Promise<boolean> {
+  const channels = new SecretsBackend(join(root, 'secrets.json')).tryReadChannelsSync()
+  if (channels === null) return false
+  switch (channel) {
+    case 'discord':
+      return hasSecretField(channels['discord-bot'], 'token')
+    case 'slack':
+      return hasSecretField(channels['slack-bot'], 'botToken') && hasSecretField(channels['slack-bot'], 'appToken')
+    case 'telegram':
+      return hasSecretField(channels['telegram-bot'], 'token')
+    case 'kakaotalk': {
+      const block = channels.kakaotalk
+      if (!isObjectRecord(block)) return false
+      const current = (block as { currentAccount?: unknown }).currentAccount
+      if (typeof current !== 'string' || current.length === 0) return false
+      const accounts = (block as { accounts?: unknown }).accounts
+      if (!isObjectRecord(accounts)) return false
+      const account = accounts[current]
+      if (!isObjectRecord(account)) return false
+      const email = (account as { email?: unknown }).email
+      const encryptedPassword = (account as { encryptedPassword?: unknown }).encryptedPassword
+      return typeof email === 'string' && email.length > 0 && isObjectRecord(encryptedPassword)
+    }
+  }
+}
+
+// Accepts either the `{ value }` form (resolves to a literal at runtime) or
+// the `{ env }` form (resolves at runtime by reading `process.env[<env>]`).
+// String shorthand is sugar for `{ value }`. The schema already rejects
+// empty strings via `z.string().min(1)`, so the length checks here are
+// defense-in-depth against forward-compat shape drift.
+function hasSecretField(slot: unknown, field: string): boolean {
+  if (!isObjectRecord(slot)) return false
+  const secret = slot[field]
+  if (typeof secret === 'string') return secret.length > 0
+  if (isObjectRecord(secret)) {
+    const value = (secret as { value?: unknown }).value
+    if (typeof value === 'string' && value.length > 0) return true
+    const env = (secret as { env?: unknown }).env
+    if (typeof env === 'string' && env.length > 0) return true
+  }
+  return false
+}
+
 function isObjectRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
@@ -689,7 +824,6 @@ export type AddChannelStepEvent =
 // from prompts; tests build them inline.
 export type AddChannelOptions = {
   cwd: string
-  allowAll?: boolean
   onProgress?: (event: AddChannelStepEvent) => void
 } & (
   | { channel: 'discord-bot'; discordBotToken: string }
@@ -717,7 +851,7 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   }
 
   emit({ step: 'config', phase: 'start' })
-  await mergeChannelIntoConfig(options.cwd, options.channel, options.allowAll ?? defaultAllowAll(options.channel))
+  await mergeChannelIntoConfig(options.cwd, options.channel)
   emit({ step: 'config', phase: 'done' })
 
   emit({ step: 'secrets', phase: 'start' })
@@ -728,14 +862,6 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   emit({ step: 'secrets', phase: 'done' })
 }
 
-// `channel add` mirrors `runInit`'s allow defaults: workspace-scoped adapters
-// (discord/slack/telegram) default to `*` because the bot only sees what the
-// operator invited it into, while KakaoTalk uses a personal account and
-// defaults to DMs only.
-function defaultAllowAll(channel: ChannelKind): boolean {
-  return channel !== 'kakaotalk'
-}
-
 function channelSecretsFromOptions(options: AddChannelOptions): ChannelSecrets {
   switch (options.channel) {
     case 'discord-bot':
@@ -774,7 +900,7 @@ export async function readConfiguredChannels(cwd: string): Promise<Set<ChannelKi
   return present
 }
 
-async function mergeChannelIntoConfig(cwd: string, channel: ChannelKind, allowAll: boolean): Promise<void> {
+async function mergeChannelIntoConfig(cwd: string, channel: ChannelKind): Promise<void> {
   const path = join(cwd, CONFIG_FILE)
   let parsed: Record<string, unknown>
   try {
@@ -798,23 +924,18 @@ async function mergeChannelIntoConfig(cwd: string, channel: ChannelKind, allowAl
     // Defense in depth — the CLI already filters configured channels out of
     // the picker and rejects them as the positional arg. Hitting this branch
     // means a programmatic caller passed a duplicate; better to fail loudly
-    // than silently overwrite the user's existing allow list.
+    // than silently overwrite the user's existing config.
     throw new Error(`Channel "${channel}" is already configured in ${CONFIG_FILE}.`)
   }
 
   parsed.channels = {
     ...existingChannels,
-    [channel]: { allow: buildAllow(channel, allowAll) },
+    [channel]: {},
   }
 
   await writeFile(path, `${JSON.stringify(parsed, null, 2)}\n`)
 }
 
-function buildAllow(channel: ChannelKind, allowAll: boolean): string[] {
-  if (channel === 'kakaotalk') return allowAll ? ['kakao:*'] : ['kakao:dm/*']
-  return allowAll ? ['*'] : []
-}
-
 // Writes per-adapter field values into `secrets.json#channels.<adapter>`.
 // Refuses to overwrite existing fields: if the user already has e.g.
 // `botToken` recorded (from a prior `channel add` whose follow-up steps

package/src/init/kakaotalk-auth.ts

@@ -1,7 +1,11 @@
 import { createRequire } from 'node:module'
-import { join } from 'node:path'
+import { join, resolve } from 'node:path'
 
+import { containerNameFromCwd } from '@/container'
+import { keysDir } from '@/hostd/paths'
+import { encrypt } from '@/secrets/encryption'
 import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
+import { createKeyStore, type KeyStore } from '@/secrets/keys'
 
 export type KakaotalkBootstrapStatus = { ok: true } | { ok: false; reason: string }
 
@@ -15,6 +19,13 @@ export type KakaotalkLoginInput = {
   agentDir: string
   callbacks: KakaotalkLoginCallbacks
   loginFlow?: LoginFlowFn
+  // Test seam: inject a custom keystore (typically pointing at a tmpdir).
+  // Production uses ~/.typeclaw/keys/<containerName>.key.
+  keyStore?: KeyStore
+  // Test seam: override the containerName used to bind the encrypted
+  // password's AAD. Production derives it from basename(agentDir) via
+  // containerNameFromCwd to match what `typeclaw start` registers with hostd.
+  containerName?: string
 }
 
 export type LoginFlowOptions = {
@@ -82,6 +93,10 @@ export async function runKakaotalkBootstrap(input: KakaotalkLoginInput): Promise
 
     const now = new Date().toISOString()
     const accountId = result.credentials.user_id || 'default'
+    const containerName = input.containerName ?? containerNameFromCwd(resolve(input.agentDir))
+    const keyStore = input.keyStore ?? createKeyStore({ keysDir: keysDir() })
+    const key = await keyStore.ensure(containerName)
+    const encryptedPassword = encrypt(input.password, key, { containerName, accountId })
     await credManager.setAccount({
       account_id: accountId,
       oauth_token: result.credentials.access_token,
@@ -92,6 +107,8 @@ export async function runKakaotalkBootstrap(input: KakaotalkLoginInput): Promise
       auth_method: 'login',
       created_at: now,
       updated_at: now,
+      email: input.email,
+      encryptedPassword,
     })
     await credManager.setCurrentAccount(accountId)
     await credManager.clearPendingLogin()

package/src/init/models-dev.ts

@@ -14,6 +14,11 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
   // entries are surfaced regardless of upstream membership.
   'openai-codex': 'openai',
   fireworks: 'fireworks-ai',
+  zai: 'zai',
+  // zai-coding (GLM Coding Plan) is a billing surface, not a separate model
+  // catalog. models.dev tracks the underlying model metadata under `zai`,
+  // so we route lookups there. The curated entries still get surfaced.
+  'zai-coding': 'zai',
 }
 
 export type ModelOption = {
@@ -25,6 +30,13 @@ export type ModelOption = {
   reasoning: boolean
   contextWindow: number | null
   curated: boolean
+  // True iff the model accepts image input. Sourced from the curated
+  // `Model.input` array (which is the source of truth — pi-ai consumes it
+  // directly) with a fallback to models.dev's `modalities.input` when the
+  // curated entry omits the field. The init wizard uses this to decide
+  // whether to prompt for a separate `vision` profile after the user picks
+  // a text-only `default` model.
+  supportsVision: boolean
 }
 
 type ModelsDevModel = {
@@ -115,7 +127,10 @@ function buildOption(ref: KnownModelRef, opts: BuildOptionOpts): ModelOption {
   const modelId = ref.slice(slash + 1)
   const provider = KNOWN_PROVIDERS[providerId]
   const curatedModel = (
-    provider.models as Record<string, { name: string; contextWindow?: number; reasoning?: boolean }>
+    provider.models as Record<
+      string,
+      { name: string; contextWindow?: number; reasoning?: boolean; input?: ReadonlyArray<string> }
+    >
   )[modelId]
   return {
     ref,
@@ -126,5 +141,15 @@ function buildOption(ref: KnownModelRef, opts: BuildOptionOpts): ModelOption {
     reasoning: opts.upstream?.reasoning ?? curatedModel?.reasoning ?? false,
     contextWindow: opts.upstream?.limit?.context ?? curatedModel?.contextWindow ?? null,
     curated: opts.curated,
+    supportsVision: resolveSupportsVision(curatedModel?.input, opts.upstream?.modalities?.input),
   }
 }
+
+function resolveSupportsVision(
+  curatedInput: ReadonlyArray<string> | undefined,
+  upstreamInput: ReadonlyArray<string> | undefined,
+): boolean {
+  if (curatedInput !== undefined) return curatedInput.includes('image')
+  if (upstreamInput !== undefined) return upstreamInput.includes('image')
+  return false
+}

package/src/init/run-owner-claim.ts

@@ -0,0 +1,77 @@
+import { confirm, isCancel, log, note, spinner } from '@clack/prompts'
+
+import { c } from '@/cli/ui'
+import { runClaimSession } from '@/role-claim'
+
+import type { ChannelKind } from './index'
+
+const CHANNEL_LABELS: Record<ChannelKind, string> = {
+  'slack-bot': 'Slack',
+  'discord-bot': 'Discord',
+  'telegram-bot': 'Telegram',
+  kakaotalk: 'KakaoTalk',
+}
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000
+
+export type RunOwnerClaimOptions = {
+  url: string
+  configuredChannels: readonly ChannelKind[]
+}
+
+// Drives the post-hatching claim flow: ask the operator whether to pair now,
+// run the claim handshake against the running container, print the result.
+// Aborts (kind: 'cancel' or a clack cancel) drop straight back into the
+// normal hatching path so the TUI still opens — the operator can run
+// `typeclaw role claim` later.
+export async function runOwnerClaim({ url, configuredChannels }: RunOwnerClaimOptions): Promise<void> {
+  if (configuredChannels.length === 0) return
+
+  const channelList = configuredChannels.map((c) => CHANNEL_LABELS[c] ?? c).join(', ')
+
+  const proceed = await confirm({
+    message: `Claim owner role on ${channelList} now?`,
+    initialValue: true,
+  })
+  if (isCancel(proceed) || proceed === false) {
+    log.info(`Skipping. Run ${c.bold('typeclaw role claim')} later when you're ready.`)
+    return
+  }
+
+  const s = spinner()
+  s.start('Generating your claim code...')
+
+  const result = await runClaimSession({
+    url,
+    role: 'owner',
+    ttlMs: DEFAULT_TTL_MS,
+    onStarted: (payload) => {
+      const expiresInMin = Math.max(1, Math.round((payload.expiresAt - Date.now()) / 60_000))
+      s.stop('Code ready.')
+      note(
+        [
+          `Open ${channelList} and DM your bot with this code:`,
+          '',
+          `  ${c.bold(payload.code)}`,
+          '',
+          `(expires in ~${expiresInMin}m)`,
+        ].join('\n'),
+        'Claim your owner role',
+      )
+      s.start('Waiting for your DM...')
+    },
+  })
+
+  if (result.kind === 'completed') {
+    s.stop(c.green(`Paired as owner.`))
+    log.info(`Match rule added to typeclaw.json#roles.owner.match: ${c.bold(result.payload.matchRule)}`)
+    return
+  }
+  if (result.kind === 'error') {
+    s.stop(c.red(`Claim failed: ${result.payload.reason}`))
+    log.info(`You can retry with ${c.bold('typeclaw role claim')} anytime.`)
+    return
+  }
+  s.stop(c.yellow(`Claim timed out — no DM received within the window.`))
+  log.info(`Run ${c.bold('typeclaw role claim')} when you're ready.`)
+}

package/src/permissions/builtins.ts

@@ -0,0 +1,70 @@
+import type { MatchRule } from './match-rule'
+
+export type BuiltinRoleName = 'owner' | 'trusted' | 'member' | 'guest'
+
+export const BUILTIN_ROLE_NAMES: readonly BuiltinRoleName[] = ['owner', 'trusted', 'member', 'guest']
+
+// Core-owned permission strings; not contributed by plugins. The security
+// plugin's `security.bypass.*` strings are NOT listed here — they are
+// collected from plugin contributions and merged into `owner`'s permission
+// set at boot via expandOwnerWildcard.
+export const CORE_PERMISSIONS = {
+  channelRespond: 'channel.respond',
+  cronSchedule: 'cron.schedule',
+  cronModify: 'cron.modify',
+} as const
+
+// Sentinel that `expandOwnerWildcard` swaps for the concrete union of
+// plugin-registered `security.bypass.*` strings. Users cannot write `*` in
+// their own `permissions[]`; the sentinel exists only inside the built-in
+// `owner` spec.
+export const OWNER_SECURITY_WILDCARD = '__BUILTIN_OWNER_SECURITY_WILDCARD__'
+
+export type BuiltinRoleSpec = {
+  readonly match: readonly MatchRule[]
+  readonly permissions: readonly string[]
+}
+
+export const BUILTIN_ROLES: Readonly<Record<BuiltinRoleName, BuiltinRoleSpec>> = {
+  owner: {
+    match: [{ kind: 'tui' }],
+    permissions: [
+      CORE_PERMISSIONS.channelRespond,
+      CORE_PERMISSIONS.cronSchedule,
+      CORE_PERMISSIONS.cronModify,
+      OWNER_SECURITY_WILDCARD,
+    ],
+  },
+  trusted: {
+    match: [],
+    permissions: [CORE_PERMISSIONS.channelRespond, CORE_PERMISSIONS.cronSchedule, 'security.bypass.secretExfilBash'],
+  },
+  member: {
+    match: [],
+    permissions: [CORE_PERMISSIONS.channelRespond],
+  },
+  guest: {
+    match: [],
+    permissions: [],
+  },
+}
+
+export function expandOwnerWildcard(
+  ownerPermissions: readonly string[],
+  pluginContributed: readonly string[],
+): readonly string[] {
+  const bypass = pluginContributed.filter((p) => p.startsWith('security.bypass.'))
+  const out: string[] = []
+  for (const p of ownerPermissions) {
+    if (p === OWNER_SECURITY_WILDCARD) {
+      for (const b of bypass) if (!out.includes(b)) out.push(b)
+      continue
+    }
+    if (!out.includes(p)) out.push(p)
+  }
+  return out
+}
+
+export function isBuiltinRoleName(name: string): name is BuiltinRoleName {
+  return (BUILTIN_ROLE_NAMES as readonly string[]).includes(name)
+}