typeclaw 0.1.1 → 0.1.3

package/src/plugin/types.ts

@@ -97,6 +97,24 @@ export type SessionIdleEvent = {
   origin?: SessionOrigin
 }
 
+// Brackets every `session.prompt(...)` invocation. Distinct from
+// `session.start`/`session.end` (which bracket session lifetime) so that
+// long-lived TUI or channel sessions, which can sit idle between turns,
+// don't wedge a turn-counter forever. `origin` carries the session's origin
+// so observers can exclude their own induced turns when counting (e.g. the
+// backup plugin excludes `subagent: 'backup'` to avoid self-gating).
+export type SessionTurnStartEvent = {
+  sessionId: string
+  agentDir: string
+  origin?: SessionOrigin
+}
+
+export type SessionTurnEndEvent = {
+  sessionId: string
+  agentDir: string
+  origin?: SessionOrigin
+}
+
 // Provider prompt caching requires byte-identical prefixes. Mutations near the
 // end of `event.prompt` preserve cache hits across sessions; mutations near
 // the start invalidate the cache on every LLM call.
@@ -136,6 +154,8 @@ export type Hooks = {
   'session.end'?: (event: SessionEndEvent, ctx: HookContext) => Promise<void> | void
   'session.idle'?: (event: SessionIdleEvent, ctx: HookContext) => Promise<void> | void
   'session.prompt'?: (event: SessionPromptEvent, ctx: HookContext) => Promise<void> | void
+  'session.turn.start'?: (event: SessionTurnStartEvent, ctx: HookContext) => Promise<void> | void
+  'session.turn.end'?: (event: SessionTurnEndEvent, ctx: HookContext) => Promise<void> | void
   'tool.before'?: (event: ToolBeforeEvent, ctx: HookContext) => Promise<ToolBeforeResult> | ToolBeforeResult
   'tool.after'?: (event: ToolAfterEvent, ctx: HookContext) => Promise<void> | void
 }
@@ -164,6 +184,51 @@ export type PluginExports = {
   skills?: Record<string, PluginSkill>
   skillsDirs?: string[]
   hooks?: Hooks
+  doctorChecks?: Record<string, PluginDoctorCheck>
+}
+
+// `typeclaw doctor` plugin extension surface. Each check is read-only by
+// default; declaring `fix.apply` opts the check into `typeclaw doctor --fix`,
+// where the host serializes plugin fixes, validates their `changedPaths`
+// against the agent folder, and commits the union of all fixes in a single
+// commit.
+export type PluginDoctorCheck = {
+  description: string
+  category?: string
+  run: (ctx: PluginDoctorContext) => Promise<PluginCheckResult>
+}
+
+export type PluginDoctorContext = {
+  readonly pluginName: string
+  readonly agentDir: string
+  readonly config: unknown
+  readonly logger: PluginLogger
+}
+
+export type PluginCheckStatus = 'ok' | 'warning' | 'error'
+
+export type PluginCheckResult = {
+  status: PluginCheckStatus
+  message: string
+  details?: string[]
+  fix?: PluginFixSuggestion
+}
+
+export type PluginFixSuggestion = {
+  description: string
+  // When omitted, the fix is advisory-only. `typeclaw doctor --fix` only
+  // attempts to remediate checks whose suggestion includes an `apply`.
+  apply?: (ctx: PluginDoctorContext) => Promise<PluginFixResult>
+}
+
+export type PluginFixResult = {
+  // One-line description that appears in the commit body as a bullet.
+  summary: string
+  // POSIX paths relative to agentDir; the host validates each one stays
+  // inside agentDir before `git add`ing. Absolute paths and `..` segments
+  // are rejected to keep plugin fixes from staging files outside the agent
+  // folder. Empty array is valid (e.g. a fix that only logs).
+  changedPaths: string[]
 }
 
 export type DefinedPlugin<TConfig = never> = {

package/src/run/bundled-plugins.ts

@@ -1,7 +1,9 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
+import backupPlugin from '@/bundled-plugins/backup'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import securityPlugin from '@/bundled-plugins/security'
+import toolResultCapPlugin from '@/bundled-plugins/tool-result-cap'
 import type { ResolvedPlugin } from '@/plugin'
 
 // Consumed by both `startAgent` (auto-loaded before user plugins) AND
@@ -16,9 +18,22 @@ import type { ResolvedPlugin } from '@/plugin'
 // Letting `guard` run first would still work today since the two plugins
 // guard disjoint surfaces, but seeding the order now means future overlap
 // (e.g. a security policy on writes) blocks before guard's softer advice.
+//
+// `tool-result-cap` is registered before `guard` so guard's `tool.after`
+// advice (uncommitted-changes warning) appends to already-capped content.
+// Reversing this order would make guard advise on the full oversized payload
+// and then tool-result-cap would clobber the advice text along with the rest.
+//
+// `memory` is registered before `backup` so memory's dreaming commits always
+// land in the same git index window before backup's commit-and-push cycle.
+// They commit disjoint paths today (memory/ vs sessions/ + agent changes),
+// but if either ever holds .git/index.lock the deterministic order makes the
+// contention easier to reason about.
 export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'security', version: undefined, source: '<bundled>', defined: securityPlugin },
+  { name: 'tool-result-cap', version: undefined, source: '<bundled>', defined: toolResultCapPlugin },
   { name: 'guard', version: undefined, source: '<bundled>', defined: guardPlugin },
   { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
+  { name: 'backup', version: undefined, source: '<bundled>', defined: backupPlugin },
   { name: 'agent-browser', version: undefined, source: '<bundled>', defined: agentBrowserPlugin },
 ]

package/src/run/index.ts

@@ -25,6 +25,7 @@ import {
 import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
 import { createContainerBroker, publishForwardResult } from '@/portbroker'
 import { ReloadRegistry } from '@/reload'
+import { hydrateChannelEnvFromSecrets } from '@/secrets'
 import { createServer, type Server } from '@/server'
 import { createSessionFactory, type SessionFactory } from '@/sessions'
 import { createStream, type Stream } from '@/stream'
@@ -119,6 +120,14 @@ export async function startAgent({
     materializedSkills: null,
   })
 
+  // Channel adapters read `process.env[TOKEN_ENV]` (see channels/manager.ts).
+  // Hydrate fills any unset env var from secrets.json#channels via env-wins:
+  // values already in process.env (from `docker --env-file .env`) are kept
+  // as-is; missing ones get the resolved Secret value injected. The pre-v2
+  // auto-promotion from .env to secrets.json has been removed — env values
+  // stay in env, the file stays user-owned. See src/secrets/hydrate.ts.
+  hydrateChannelEnvFromSecrets({ agentDir: cwd })
+
   const channelManager = createChannelManager({
     agentDir: cwd,
     channelsConfigRef: () => getConfig().channels,
@@ -142,14 +151,15 @@ export async function startAgent({
     const entry = snap.pluginSubagentByShim.get(subagent)
     if (entry) {
       const sessionId = `subagent-${entry.pluginName}-${crypto.randomUUID()}`
+      const origin = {
+        kind: 'subagent' as const,
+        subagent: subagentOptions?.name ?? entry.subagentName,
+        parentSessionId: subagentOptions?.parentSessionId ?? '<unknown>',
+      }
       const created = await createSessionWithDispose({
         systemPromptOverride: entry.pluginSubagent.systemPrompt,
         channelRouter: channelManager.router,
-        origin: {
-          kind: 'subagent',
-          subagent: subagentOptions?.name ?? entry.subagentName,
-          parentSessionId: subagentOptions?.parentSessionId ?? '<unknown>',
-        },
+        origin,
         plugins: {
           registry: snap.registry,
           hooks: snap.hooks,
@@ -167,6 +177,8 @@ export async function startAgent({
         ...created,
         hooks: snap.hooks,
         sessionId,
+        agentDir: cwd,
+        origin,
       }
     }
     return defaultCreateSessionForSubagent(subagent, subagentOptions)
@@ -221,6 +233,8 @@ export async function startAgent({
         prompt: (text) => session.prompt(text),
         dispose: () => session.dispose(),
         sessionId,
+        agentDir: cwd,
+        origin: { kind: 'cron' as const, jobId: job.id, jobKind: 'prompt' as const },
         ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
         getTranscriptPath: () => sessionManager.getSessionFile(),
       }

package/src/secrets/defaults.ts

@@ -0,0 +1,67 @@
+import { KNOWN_PROVIDERS, type KnownProviderId } from '@/config/providers'
+
+// DEFAULT_ENV_NAMES is the single source of truth for the env-var name each
+// secret-bearing field uses when the user does not override it via the `env`
+// field of a `Secret` object. Three layers depend on it:
+//
+//   1. resolveSecret (src/secrets/resolve.ts) — when the on-disk Secret has
+//      no explicit `env`, it falls back to this table to know which env var
+//      to consult for env-wins resolution.
+//   2. hydrateChannelEnvFromSecrets (src/secrets/hydrate.ts) — when injecting
+//      resolved channel field values into `process.env`, it uses these names
+//      so that `src/channels/manager.ts` (which reads `env.DISCORD_BOT_TOKEN`
+//      etc. directly) keeps working without per-adapter refactoring.
+//   3. parseSecretsFile legacy upgrade — when reading a v1 file with the old
+//      `{ ENV_NAME: value }` channel shape, it inverts this table to rename
+//      the keys to the new per-adapter field names.
+//
+// Providers come from `KNOWN_PROVIDERS[id].apiKeyEnv` — derived, not duplicated.
+// OAuth-only providers are intentionally absent: OAuth credentials are not
+// env-injectable (refresh tokens are stateful).
+
+export const CHANNEL_FIELD_ENV = {
+  'discord-bot': { token: 'DISCORD_BOT_TOKEN' },
+  'slack-bot': { botToken: 'SLACK_BOT_TOKEN', appToken: 'SLACK_APP_TOKEN' },
+  'telegram-bot': { token: 'TELEGRAM_BOT_TOKEN' },
+} as const satisfies Record<string, Record<string, string>>
+
+export type KnownAdapterId = keyof typeof CHANNEL_FIELD_ENV
+
+export function isKnownAdapterId(id: string): id is KnownAdapterId {
+  return id in CHANNEL_FIELD_ENV
+}
+
+// Reverse map: env-var name -> { adapterId, fieldName }. Built from
+// CHANNEL_FIELD_ENV so adding a new adapter field updates both directions
+// automatically. Used exclusively by the legacy v1 channels-shape upgrade.
+export const CHANNEL_ENV_TO_FIELD: Record<string, { adapterId: KnownAdapterId; fieldName: string }> = (() => {
+  const out: Record<string, { adapterId: KnownAdapterId; fieldName: string }> = {}
+  for (const [adapterId, fields] of Object.entries(CHANNEL_FIELD_ENV)) {
+    for (const [fieldName, envName] of Object.entries(fields)) {
+      out[envName] = { adapterId: adapterId as KnownAdapterId, fieldName }
+    }
+  }
+  return out
+})()
+
+// Returns the default env-var name for a known channel field, or undefined
+// when the adapter or field is not in CHANNEL_FIELD_ENV (forward-compat: a
+// future adapter contributed via plugin would not appear in this table).
+export function channelFieldDefaultEnv(adapterId: string, fieldName: string): string | undefined {
+  if (!isKnownAdapterId(adapterId)) return undefined
+  const adapterFields = CHANNEL_FIELD_ENV[adapterId] as Record<string, string>
+  return adapterFields[fieldName]
+}
+
+// Returns the canonical env-var name for an api-key provider, or undefined
+// when the provider is OAuth-only (apiKeyEnv === null in KNOWN_PROVIDERS).
+// OAuth-only providers never participate in env-wins resolution.
+export function providerKeyDefaultEnv(providerId: string): string | undefined {
+  const provider = (KNOWN_PROVIDERS as Record<string, { apiKeyEnv: string | null }>)[providerId]
+  if (!provider) return undefined
+  return provider.apiKeyEnv ?? undefined
+}
+
+export function isKnownProviderId(id: string): id is KnownProviderId {
+  return id in KNOWN_PROVIDERS
+}

package/src/secrets/hydrate.ts

@@ -0,0 +1,99 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { channelFieldDefaultEnv } from './defaults'
+import { resolveSecret, secretFieldSchema, type Secret } from './resolve'
+import { parseSecretsFile } from './schema'
+
+// hydrateChannelEnvFromSecrets is the seam that lets channel adapters keep
+// reading `process.env[TOKEN_ENV]` (in `src/channels/manager.ts`) without
+// knowing about the new per-adapter Secret-typed config shape. Boot flow:
+//
+//   1. Read secrets.json#channels. Each field is a Secret (string shorthand
+//      or `{ value?, env? }` object).
+//   2. For each (adapter, field) pair, look up the default env-var name via
+//      CHANNEL_FIELD_ENV (e.g. slack-bot.botToken -> SLACK_BOT_TOKEN).
+//   3. Resolve the Secret via env-wins: if the target env var is already
+//      set, do nothing (env wins, intentional, by design). Otherwise inject
+//      the resolved file value into process.env under the default env name.
+//
+// Three explicit non-behaviors versus the pre-v2 implementation:
+//   - We DO NOT strip `.env` after injecting. Env values stay in `.env`; the
+//     boot-time file mutation that previously erased migrated keys is gone.
+//     The user's `.env` is treated as a first-class source, not a one-way
+//     migration channel.
+//   - We DO NOT promote env values into secrets.json. The old
+//     `promoteChannelEnvIntoSecrets` step has been deleted as part of the
+//     env-wins reshape. If the user wants the value in the file, they put it
+//     there explicitly (init writes it, or a manual edit).
+//   - We DO NOT touch unknown adapter ids (no entry in CHANNEL_FIELD_ENV)
+//     or unknown field names. Skipped silently. A future plugin adapter
+//     would need its own injection mechanism; the field-name-keyed shape is
+//     reserved for the curated set in CHANNEL_FIELD_ENV.
+//
+// Errors are non-fatal: a missing or malformed `secrets.json` returns an
+// empty result rather than throwing, so an agent that hasn't run init yet
+// can still boot.
+export function hydrateChannelEnvFromSecrets(options: { agentDir: string; env?: NodeJS.ProcessEnv }): {
+  applied: string[]
+  skipped: string[]
+} {
+  const env = options.env ?? process.env
+  const secretsPath = join(options.agentDir, 'secrets.json')
+  const channels = readChannelSecrets(secretsPath)
+
+  const applied: string[] = []
+  const skipped: string[] = []
+
+  for (const [adapterId, fields] of Object.entries(channels)) {
+    for (const [fieldName, secret] of Object.entries(fields)) {
+      const envName = channelFieldDefaultEnv(adapterId, fieldName)
+      if (envName === undefined) continue
+
+      const existing = env[envName]
+      if (existing !== undefined && existing !== '') {
+        skipped.push(envName)
+        continue
+      }
+
+      const resolved = resolveSecret(secret, envName, env)
+      if (resolved === undefined) continue
+
+      env[envName] = resolved
+      applied.push(envName)
+    }
+  }
+
+  return { applied, skipped }
+}
+
+function readChannelSecrets(secretsPath: string): Record<string, Record<string, Secret>> {
+  let raw: string
+  try {
+    raw = readFileSync(secretsPath, 'utf8')
+  } catch {
+    return {}
+  }
+  if (raw.trim() === '') return {}
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return {}
+  }
+  const result = parseSecretsFile(parsed)
+  if (!result.ok) return {}
+
+  const out: Record<string, Record<string, Secret>> = {}
+  for (const [adapterId, slot] of Object.entries(result.file.channels)) {
+    if (typeof slot !== 'object' || slot === null || Array.isArray(slot)) continue
+    const slotRecord = slot as Record<string, unknown>
+    const fields: Record<string, Secret> = {}
+    for (const [fieldName, value] of Object.entries(slotRecord)) {
+      const ok = secretFieldSchema.safeParse(value)
+      if (ok.success) fields[fieldName] = ok.data
+    }
+    if (Object.keys(fields).length > 0) out[adapterId] = fields
+  }
+  return out
+}

package/src/secrets/index.ts

@@ -1,15 +1,9 @@
-export {
-  channelsSchema,
-  llmCredentialSchema,
-  llmCredentialsSchema,
-  parseSecretsFile,
-  secretsFileSchema,
-  type LlmCredential,
-  type LlmCredentials,
-  type ParseSecretsResult,
-  type SecretsFile,
-} from './schema'
+export { type Channels } from './schema'
 
 export { createSecretsStoreForAgent, SecretsBackend } from './storage'
 
-export { stripEnvKey } from './env'
+export { type Secret } from './resolve'
+
+export { hydrateChannelEnvFromSecrets } from './hydrate'
+
+export { migrateKakaotalkCredentials } from './migrate-kakaotalk'

package/src/secrets/kakao-store.ts

@@ -0,0 +1,129 @@
+import type { KakaoAccountCredentials, KakaoConfig } from 'agent-messenger/kakaotalk'
+import type { PendingLoginState } from 'agent-messenger/kakaotalk'
+
+import { sendHttp } from '@/hostd/client'
+
+import { type KakaoChannelBlock, kakaoChannelBlockSchema } from './schema'
+import { SecretsBackend } from './storage'
+
+export type SecretsKakaoCredentialStoreOptions =
+  | { mode: 'host'; secretsPath: string }
+  | { mode: 'container'; secretsPath: string; hostdUrl: string; restartToken: string; containerName: string }
+
+const EMPTY_BLOCK: KakaoChannelBlock = { currentAccount: null, accounts: {} }
+
+export class SecretsKakaoCredentialStore {
+  private readonly backend: SecretsBackend
+  private writeChain: Promise<void> = Promise.resolve()
+
+  constructor(private readonly options: SecretsKakaoCredentialStoreOptions) {
+    this.backend = new SecretsBackend(options.secretsPath)
+  }
+
+  async load(): Promise<KakaoConfig> {
+    return toKakaoConfig(this.readBlock())
+  }
+
+  async save(config: KakaoConfig): Promise<void> {
+    await this.writeBlock(() => fromKakaoConfig(config))
+  }
+
+  async getAccount(id?: string): Promise<KakaoAccountCredentials | null> {
+    const config = await this.load()
+    if (id) return config.accounts[id] ?? null
+    if (!config.current_account) return null
+    return config.accounts[config.current_account] ?? null
+  }
+
+  async setAccount(account: KakaoAccountCredentials): Promise<void> {
+    await this.writeBlock((block) => {
+      const accounts = { ...block.accounts, [account.account_id]: account }
+      return { ...block, currentAccount: block.currentAccount ?? account.account_id, accounts }
+    })
+  }
+
+  async removeAccount(id: string): Promise<void> {
+    await this.writeBlock((block) => {
+      const accounts = { ...block.accounts }
+      delete accounts[id]
+      const currentAccount = block.currentAccount === id ? (Object.keys(accounts)[0] ?? null) : block.currentAccount
+      return { ...block, currentAccount, accounts }
+    })
+  }
+
+  async listAccounts(): Promise<Array<KakaoAccountCredentials & { is_current: boolean }>> {
+    const config = await this.load()
+    return Object.values(config.accounts).map((account) => ({
+      ...account,
+      is_current: account.account_id === config.current_account,
+    }))
+  }
+
+  async setCurrentAccount(id: string): Promise<void> {
+    await this.writeBlock((block) => ({ ...block, currentAccount: id }))
+  }
+
+  async savePendingLogin(state: PendingLoginState): Promise<void> {
+    await this.writeBlock((block) => ({ ...block, pendingLogin: state }))
+  }
+
+  async loadPendingLogin(): Promise<PendingLoginState | null> {
+    return this.readBlock().pendingLogin ?? null
+  }
+
+  async clearPendingLogin(): Promise<void> {
+    await this.writeBlock((block) => {
+      const { pendingLogin: _pendingLogin, ...next } = block
+      return next
+    })
+  }
+
+  private readBlock(): KakaoChannelBlock {
+    const channels =
+      this.options.mode === 'container' ? this.backend.tryReadChannelsSync() : this.backend.readChannelsSync()
+    const raw = channels?.kakaotalk
+    return parseBlock(raw)
+  }
+
+  private async writeBlock(update: (current: KakaoChannelBlock) => KakaoChannelBlock): Promise<void> {
+    return this.enqueueWrite(async () => {
+      if (this.options.mode === 'container') {
+        const next = update(this.readBlock())
+        const response = await sendHttp(
+          {
+            kind: 'secrets-patch',
+            containerName: this.options.containerName,
+            patch: { channels: { kakaotalk: next } },
+          },
+          { url: this.options.hostdUrl, token: this.options.restartToken },
+        )
+        if (!response.ok) throw new Error(`secrets-patch failed: ${response.reason}`)
+        return
+      }
+
+      await this.backend.updateChannelsAsync(async (channels) => {
+        const next = { ...channels, kakaotalk: update(parseBlock(channels.kakaotalk)) }
+        return { result: undefined, next }
+      })
+    })
+  }
+
+  private enqueueWrite(op: () => Promise<void>): Promise<void> {
+    const next = this.writeChain.then(op, op)
+    this.writeChain = next.catch(() => {})
+    return next
+  }
+}
+
+function parseBlock(value: unknown): KakaoChannelBlock {
+  if (value === undefined) return EMPTY_BLOCK
+  return kakaoChannelBlockSchema.parse(value)
+}
+
+function toKakaoConfig(block: KakaoChannelBlock): KakaoConfig {
+  return { current_account: block.currentAccount, accounts: block.accounts }
+}
+
+function fromKakaoConfig(config: KakaoConfig): KakaoChannelBlock {
+  return { currentAccount: config.current_account, accounts: config.accounts }
+}

package/src/secrets/migrate-kakaotalk.ts

@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { rename } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { KakaoCredentialManager } from 'agent-messenger/kakaotalk'
+import type { KakaoConfig, PendingLoginState } from 'agent-messenger/kakaotalk'
+
+import { type KakaoChannelBlock, kakaoChannelBlockSchema } from './schema'
+import { SecretsBackend } from './storage'
+
+const KAKAO_CONFIG_DIR = join('workspace', '.agent-messenger')
+const CREDENTIALS_FILE = 'kakaotalk-credentials.json'
+const PENDING_LOGIN_FILE = 'kakaotalk-pending-login.json'
+
+export type KakaotalkCredentialMigrationResult = { promoted: boolean }
+
+export async function migrateKakaotalkCredentials(agentDir: string): Promise<KakaotalkCredentialMigrationResult> {
+  const configDir = join(agentDir, KAKAO_CONFIG_DIR)
+  const credentialsPath = join(configDir, CREDENTIALS_FILE)
+  const pendingLoginPath = join(configDir, PENDING_LOGIN_FILE)
+  if (!existsSync(credentialsPath) && !existsSync(pendingLoginPath)) return { promoted: false }
+
+  const secretsPath = join(agentDir, 'secrets.json')
+  const legacy = new KakaoCredentialManager(configDir)
+  const config = await legacy.load()
+  const pendingLogin = await legacy.loadPendingLogin()
+  if (Object.keys(config.accounts).length === 0 && pendingLogin === null) return { promoted: false }
+
+  const backend = new SecretsBackend(secretsPath)
+  const result = await backend.updateChannelsAsync(async (channels) => {
+    const existing = parseExistingBlock(channels.kakaotalk)
+    const next = mergeLegacyBlock(existing, config, pendingLogin)
+    if (next === existing) return { result: { promoted: false, renameCredentials: false, renamePending: false } }
+
+    return {
+      result: {
+        promoted: true,
+        renameCredentials: isEmptyBlock(existing) && Object.keys(config.accounts).length > 0,
+        renamePending: pendingLogin !== null && existing?.pendingLogin === undefined,
+      },
+      next: { ...channels, kakaotalk: next },
+    }
+  })
+  if (!result.promoted) return { promoted: false }
+
+  if (result.renameCredentials) await renameIfPresent(credentialsPath, `${credentialsPath}.migrated`)
+  if (result.renamePending) await renameIfPresent(pendingLoginPath, `${pendingLoginPath}.migrated`)
+  return { promoted: true }
+}
+
+function parseExistingBlock(value: unknown): KakaoChannelBlock | null {
+  if (value === undefined) return null
+  return kakaoChannelBlockSchema.parse(value)
+}
+
+function isEmptyBlock(block: KakaoChannelBlock | null): boolean {
+  return (
+    block === null ||
+    (block.currentAccount === null && Object.keys(block.accounts).length === 0 && block.pendingLogin === undefined)
+  )
+}
+
+function mergeLegacyBlock(
+  existing: KakaoChannelBlock | null,
+  config: KakaoConfig,
+  pendingLogin: PendingLoginState | null,
+): KakaoChannelBlock | null {
+  if (existing === null || isEmptyBlock(existing)) {
+    return {
+      currentAccount: config.current_account,
+      accounts: config.accounts,
+      ...(pendingLogin ? { pendingLogin } : {}),
+    }
+  }
+  if (pendingLogin === null || existing.pendingLogin !== undefined) return existing
+  return { ...existing, pendingLogin }
+}
+
+async function renameIfPresent(from: string, to: string): Promise<void> {
+  if (!existsSync(from)) return
+  await rename(from, to)
+}

package/src/secrets/migrate.ts

@@ -70,9 +70,10 @@ function renameWithRaceFallback(from: string, to: string): void {
   }
 }
 
-// "Empty envelope" = no actual credentials. Parsed shape with empty llm and
-// empty channels. We do NOT try to be clever about "approximately empty" —
-// exact emptiness is the only safe auto-delete / auto-overwrite case.
+// "Empty envelope" = no actual credentials. parseSecretsFile normalises both
+// legacy v1 and current v2 to a v2-shaped SecretsFile, so we only check the
+// v2 fields. We do NOT try to be clever about "approximately empty" — exact
+// emptiness is the only safe auto-delete / auto-overwrite case.
 function isEmptyEnvelope(path: string): boolean {
   let raw: string
   try {
@@ -91,5 +92,5 @@ function isEmptyEnvelope(path: string): boolean {
 
   const result = parseSecretsFile(parsed)
   if (!result.ok) return false
-  return Object.keys(result.file.llm).length === 0 && Object.keys(result.file.channels).length === 0
+  return Object.keys(result.file.providers).length === 0 && Object.keys(result.file.channels).length === 0
 }

package/src/secrets/resolve.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod'
+
+// A Secret is the on-disk shape for any env-injectable credential field.
+// String shorthand is sugar for `{ value }`. The schema normalises to the
+// object form at parse time so consumers only ever handle one shape, but
+// writers MAY emit the string shorthand for the common no-custom-env case
+// to keep `secrets.json` terse.
+//
+// Empty objects `{}` are rejected because they carry no information — the
+// resolver would always return undefined for them and the file would silently
+// fail to provide credentials at boot.
+const secretObjectSchema = z
+  .object({
+    value: z.string().min(1).optional(),
+    env: z.string().min(1).optional(),
+  })
+  .refine((s) => s.value !== undefined || s.env !== undefined, {
+    message: 'Secret object must have at least one of `value` or `env`',
+  })
+
+export const secretFieldSchema = z
+  .union([z.string().min(1), secretObjectSchema])
+  .transform((v) => (typeof v === 'string' ? { value: v } : v))
+
+export type Secret = z.infer<typeof secretFieldSchema>
+
+// Env-wins resolution. The single place env-vs-file precedence lives.
+//
+// Precedence (highest to lowest):
+//   1. process.env[secret.env]    — explicit binding wins
+//   2. process.env[defaultEnv]    — canonical env-var-name fallback
+//   3. secret.value               — on-disk value
+//   4. undefined                  — caller decides (missing-credential error)
+//
+// Empty-string env values are treated as unset, matching the existing
+// hydrate.ts policy (`env[key] !== '' `). This keeps `unset` and `set to ""`
+// behaviorally identical for credentials, which is what every shell ecosystem
+// converges on.
+export function resolveSecret(
+  secret: Secret,
+  defaultEnv: string | undefined,
+  env: NodeJS.ProcessEnv,
+): string | undefined {
+  const envName = secret.env ?? defaultEnv
+  if (envName !== undefined) {
+    const fromEnv = env[envName]
+    if (fromEnv !== undefined && fromEnv !== '') return fromEnv
+  }
+  return secret.value
+}
+
+// Returns the env-var name that resolveSecret would consult for a given
+// Secret + default. Used by doctor / diagnostics to report "if you want to
+// override this, set $envName". Does NOT consult process.env — pure mapping.
+export function effectiveEnvName(secret: Secret, defaultEnv: string | undefined): string | undefined {
+  return secret.env ?? defaultEnv
+}