typeclaw 0.1.2 → 0.1.4

package/src/init/index.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url'
 import { config, configSchema, type Config } from '@/config'
 import { DEFAULT_MODEL_REF, KNOWN_PROVIDERS, providerForModelRef, type KnownModelRef } from '@/config/providers'
 import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
+import { type Channels, type Secret, SecretsBackend } from '@/secrets'
 import { createTui } from '@/tui'
 
 import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
@@ -69,7 +70,13 @@ export type InitStepEvent =
   | { step: 'hatching'; phase: 'start' }
   | { step: 'hatching'; phase: 'done'; result: HatchingResult }
 
-export type HatchRunner = (options: { cwd: string; port: number }) => Promise<HatchingResult>
+// `cliEntry` is the path to the running CLI module (typically `process.argv[1]`).
+// When provided, the hatching step threads it into `start()`, which spawns the
+// host daemon and registers the freshly-hatched container with the supervisor +
+// 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 KakaotalkAuthRunner = (options: { cwd: string }) => Promise<KakaotalkAuthResult>
 
@@ -104,6 +111,12 @@ export type InitOptions = {
   runHatching?: HatchRunner
   runBunInstall?: InstallRunner
   dockerExec?: DockerExec
+  // Production CLI callers (src/cli/init.ts) pass `process.argv[1]` so the
+  // hatching step's `start()` call spawns the host daemon and registers the
+  // freshly-hatched container — same path `typeclaw start` takes. Tests omit
+  // this to skip the daemon entirely (matching the existing seam in
+  // src/container/start.ts).
+  cliEntry?: string
 }
 
 export async function runInit({
@@ -125,6 +138,7 @@ export async function runInit({
   runHatching = defaultRunHatching,
   runBunInstall: installRunner = runBunInstall,
   dockerExec,
+  cliEntry,
 }: InitOptions): Promise<void> {
   const emit = onProgress ?? (() => {})
 
@@ -217,13 +231,37 @@ export async function runInit({
   emit({ step: 'git', phase: 'done', result: git })
 
   emit({ step: 'hatching', phase: 'start' })
-  const hatching = await runHatching({ cwd, port: config.port })
+  const hatching = await runHatching({ cwd, port: config.port, ...(cliEntry !== undefined ? { cliEntry } : {}) })
   emit({ step: 'hatching', phase: 'done', result: hatching })
 }
 
-async function defaultRunHatching({ cwd, port }: { cwd: string; port: number }): Promise<HatchingResult> {
+// Exported for the composition test in index.test.ts: the seam that the
+// hatching-hostd fix turns on (passing `cliEntry` into `start()`) is the bug
+// site itself, so a guard test that proves `defaultRunHatching` forwards
+// `cliEntry` to `start()` is what blocks the regression from coming back.
+// Tests inject `startContainer` and `tui` to avoid Docker / TUI side effects;
+// production callers omit both and get the real `start` + `createTui`.
+export async function defaultRunHatching({
+  cwd,
+  port,
+  cliEntry,
+  startContainer = start,
+  tui: tuiFactory = createTui,
+  waitForAgent: waitForAgentFn = waitForAgent,
+}: {
+  cwd: string
+  port: number
+  cliEntry?: string
+  startContainer?: typeof start
+  tui?: typeof createTui
+  waitForAgent?: typeof waitForAgent
+}): Promise<HatchingResult> {
   try {
-    const launch = await start({ cwd, preferredHostPort: port })
+    const launch = await startContainer({
+      cwd,
+      preferredHostPort: port,
+      ...(cliEntry !== undefined ? { cliEntry } : {}),
+    })
     if (!launch.ok) return { ok: false, reason: launch.reason }
 
     // start() may have allocated a different host port (the preferred one was
@@ -231,9 +269,9 @@ async function defaultRunHatching({ cwd, port }: { cwd: string; port: number }):
     // the preferred port, otherwise we'd connect to the wrong service.
     const hostPort = launch.hostPort
 
-    await waitForAgent(`http://localhost:${hostPort}`, { timeoutMs: 30_000 })
+    await waitForAgentFn(`http://localhost:${hostPort}`, { timeoutMs: 30_000 })
 
-    const tui = createTui({
+    const tui = tuiFactory({
       url: `ws://localhost:${hostPort}`,
       initialPrompt: HATCHING_PROMPT,
     })
@@ -343,14 +381,18 @@ 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. `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, 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.
   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 ? [] : ['*'] }
@@ -516,10 +558,15 @@ export async function initGitRepo(cwd: string): Promise<GitInitResult> {
   }
 }
 
-// Writes the LLM provider's API key (under its provider-specific env var,
-// e.g. OPENAI_API_KEY or FIREWORKS_API_KEY) plus any channel adapter tokens.
-// The provider env var is resolved from KNOWN_PROVIDERS via the model ref,
-// so adding a new provider only requires touching providers.ts.
+// Writes the LLM provider's API key to `.env` (under its provider-specific
+// env var, e.g. OPENAI_API_KEY or FIREWORKS_API_KEY) and the channel adapter
+// tokens to `secrets.json#channels`. Two stores on purpose: api-keys land in
+// `.env` to match the `--env-file .env` boot contract (env-wins: `auth.ts`
+// reads the value at runtime via `setRuntimeApiKey` and never persists it to
+// `secrets.json`, see `src/agent/auth.ts`); channel tokens skip the .env hop
+// entirely and land in `secrets.json#channels` as `{ value }` Secrets that
+// `hydrateChannelEnvFromSecrets` injects into `process.env` only when the
+// canonical env var is unset, see `src/secrets/hydrate.ts`.
 export async function writeSecrets(
   root: string,
   {
@@ -531,8 +578,9 @@ export async function writeSecrets(
     telegramBotToken,
   }: {
     model?: KnownModelRef
-    // Omitted on the OAuth path — credentials live in secrets.json instead. The
-    // .env file still gets written for any channel adapter tokens.
+    // Omitted on the OAuth path — credentials live in secrets.json instead.
+    // The .env file still gets written (empty) so post-init callers that
+    // read it don't ENOENT-crash.
     apiKey?: string
     discordBotToken?: string
     slackBotToken?: string
@@ -546,22 +594,37 @@ export async function writeSecrets(
   if (apiKey !== undefined && apiKeyEnv !== null) {
     lines.push(`${apiKeyEnv}=${apiKey}`)
   }
+  const body = lines.length > 0 ? `${lines.join('\n')}\n` : ''
+  await writeFile(join(root, SECRETS_FILE), body)
+
+  const channelTokens: Record<string, Record<string, Secret>> = {}
   if (discordBotToken !== undefined && discordBotToken !== '') {
-    lines.push(`DISCORD_BOT_TOKEN=${discordBotToken}`)
+    channelTokens['discord-bot'] = { token: { value: discordBotToken } }
   }
   if (slackBotToken !== undefined && slackBotToken !== '') {
-    lines.push(`SLACK_BOT_TOKEN=${slackBotToken}`)
+    channelTokens['slack-bot'] = { ...channelTokens['slack-bot'], botToken: { value: slackBotToken } }
   }
   if (slackAppToken !== undefined && slackAppToken !== '') {
-    lines.push(`SLACK_APP_TOKEN=${slackAppToken}`)
+    channelTokens['slack-bot'] = { ...channelTokens['slack-bot'], appToken: { value: slackAppToken } }
   }
   if (telegramBotToken !== undefined && telegramBotToken !== '') {
-    lines.push(`TELEGRAM_BOT_TOKEN=${telegramBotToken}`)
+    channelTokens['telegram-bot'] = { token: { value: telegramBotToken } }
   }
-  // Always write .env even when empty so existing callers that read it
-  // post-init (channel `add`, runtime startup) don't ENOENT-crash.
-  const body = lines.length > 0 ? `${lines.join('\n')}\n` : ''
-  await writeFile(join(root, SECRETS_FILE), body)
+  if (Object.keys(channelTokens).length === 0) return
+
+  const backend = new SecretsBackend(join(root, 'secrets.json'))
+  const existing = backend.readChannelsSync()
+  const merged: Channels = { ...existing }
+  for (const [adapterId, fields] of Object.entries(channelTokens)) {
+    const priorSlot = isObjectRecord(merged[adapterId]) ? { ...(merged[adapterId] as Record<string, unknown>) } : {}
+    for (const [k, v] of Object.entries(fields)) priorSlot[k] = v
+    merged[adapterId] = priorSlot as Channels[string]
+  }
+  backend.writeChannelsSync(merged)
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
 function resolveLLMAuth(llmAuth: LLMAuth | undefined, apiKey: string | undefined): LLMAuth {
@@ -635,7 +698,7 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   //
   // We run KakaoTalk auth FIRST so a failed login leaves typeclaw.json and
   // .env untouched. The runtime treats `channels.kakaotalk` without a
-  // credentials file as "missing credentials, skip adapter", which silently
+  // secrets.json#channels.kakaotalk block as "missing credentials, skip adapter", which silently
   // drops messages — the same trap `runInit` already guards against. Aborting
   // before any file write means the user's next `typeclaw channel add
   // kakaotalk` retry has no half-applied state to clean up.
@@ -651,7 +714,10 @@ export async function runAddChannel(options: AddChannelOptions): Promise<void> {
   emit({ step: 'config', phase: 'done' })
 
   emit({ step: 'secrets', phase: 'start' })
-  await appendChannelSecrets(options.cwd, channelSecretsFromOptions(options))
+  const tokens = channelSecretsFromOptions(options)
+  if (Object.keys(tokens).length > 0) {
+    await appendChannelSecrets(options.cwd, options.channel, tokens)
+  }
   emit({ step: 'secrets', phase: 'done' })
 }
 
@@ -666,13 +732,14 @@ function defaultAllowAll(channel: ChannelKind): boolean {
 function channelSecretsFromOptions(options: AddChannelOptions): ChannelSecrets {
   switch (options.channel) {
     case 'discord-bot':
-      return { DISCORD_BOT_TOKEN: options.discordBotToken }
+      return { token: options.discordBotToken }
     case 'slack-bot':
-      return { SLACK_BOT_TOKEN: options.slackBotToken, SLACK_APP_TOKEN: options.slackAppToken }
+      return { botToken: options.slackBotToken, appToken: options.slackAppToken }
     case 'telegram-bot':
-      return { TELEGRAM_BOT_TOKEN: options.telegramBotToken }
+      return { token: options.telegramBotToken }
     case 'kakaotalk':
-      // Credentials live in workspace/.agent-messenger/, not .env.
+      // KakaoTalk auth writes its structured multi-account block directly to
+      // secrets.json#channels.kakaotalk before config mutation.
       return {}
   }
 }
@@ -741,56 +808,35 @@ function buildAllow(channel: ChannelKind, allowAll: boolean): string[] {
   return allowAll ? ['*'] : []
 }
 
-// Appends only keys that are not already present in .env. We never rewrite
-// existing values: if the user has `SLACK_BOT_TOKEN=` left over from a manual
-// edit, we surface that as a hard error rather than overwrite the user's
-// hand-rolled value.
-//
-// `.env` parsing is intentionally line-based and dumb (matching dotenv's
-// minimum surface): trim, skip blanks/comments, split on the first `=`. We do
-// not unquote values because we only check for key presence.
-async function appendChannelSecrets(cwd: string, secrets: ChannelSecrets): Promise<void> {
-  if (Object.keys(secrets).length === 0) return
-
-  const path = join(cwd, SECRETS_FILE)
-  let existing: string
-  try {
-    existing = await readFile(path, 'utf8')
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      throw new Error(
-        `${SECRETS_FILE} not found at ${cwd}. Run \`typeclaw init\` before adding channels, or run this command from inside an agent folder.`,
-      )
-    }
-    throw error
+// 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
+// failed, or a hand-edit), we surface that as a hard error rather than
+// silently displace it. Same trap the original .env-append path guarded
+// against, applied to the field-keyed destination.
+async function appendChannelSecrets(cwd: string, channel: ChannelKind, tokens: ChannelSecrets): Promise<void> {
+  if (Object.keys(tokens).length === 0) return
+
+  if (!existsSync(join(cwd, CONFIG_FILE))) {
+    throw new Error(
+      `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` before adding channels, or run this command from inside an agent folder.`,
+    )
   }
 
-  const presentKeys = parseEnvKeys(existing)
-  for (const key of Object.keys(secrets)) {
-    if (presentKeys.has(key)) {
+  const backend = new SecretsBackend(join(cwd, 'secrets.json'))
+  const channels: Record<string, unknown> = backend.readChannelsSync()
+  const slot: Record<string, unknown> = isObjectRecord(channels[channel])
+    ? { ...(channels[channel] as Record<string, unknown>) }
+    : {}
+
+  for (const field of Object.keys(tokens)) {
+    if (slot[field] !== undefined) {
       throw new Error(
-        `${key} is already set in ${SECRETS_FILE}. Remove it before re-adding the channel, or edit the value by hand.`,
+        `${field} is already set in secrets.json under "${channel}". Remove it before re-adding the channel, or edit the value by hand.`,
       )
     }
   }
-
-  // Ensure exactly one trailing newline before our appended block so the
-  // resulting file remains POSIX-clean even if the user's editor stripped it.
-  const trailingNewline = existing.endsWith('\n') || existing === '' ? '' : '\n'
-  const appended = Object.entries(secrets)
-    .map(([k, v]) => `${k}=${v}`)
-    .join('\n')
-  await writeFile(path, `${existing}${trailingNewline}${appended}\n`)
-}
-
-function parseEnvKeys(content: string): Set<string> {
-  const keys = new Set<string>()
-  for (const rawLine of content.split('\n')) {
-    const line = rawLine.trim()
-    if (line === '' || line.startsWith('#')) continue
-    const eq = line.indexOf('=')
-    if (eq <= 0) continue
-    keys.add(line.slice(0, eq).trim())
-  }
-  return keys
+  for (const [k, v] of Object.entries(tokens)) slot[k] = { value: v } satisfies Secret
+  channels[channel] = slot
+  backend.writeChannelsSync(channels as Channels)
 }

package/src/init/kakaotalk-auth.ts

@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module'
 import { join } from 'node:path'
 
-import { KakaoCredentialManager } from 'agent-messenger/kakaotalk'
+import { SecretsKakaoCredentialStore } from '@/secrets/kakao-store'
 
 export type KakaotalkBootstrapStatus = { ok: true } | { ok: false; reason: string }
 
@@ -50,11 +50,17 @@ export function kakaotalkConfigDir(agentDir: string): string {
   return join(agentDir, 'workspace', '.agent-messenger')
 }
 
+export function kakaotalkSecretsPath(agentDir: string): string {
+  return join(agentDir, 'secrets.json')
+}
+
 export async function runKakaotalkBootstrap(input: KakaotalkLoginInput): Promise<KakaotalkBootstrapStatus> {
-  const configDir = kakaotalkConfigDir(input.agentDir)
   try {
     const loginFlow = input.loginFlow ?? (await resolveLoginFlow())
-    const credManager = new KakaoCredentialManager(configDir)
+    const credManager = new SecretsKakaoCredentialStore({
+      mode: 'host',
+      secretsPath: kakaotalkSecretsPath(input.agentDir),
+    })
     const pending = await credManager.loadPendingLogin()
     const existing = await credManager.getAccount()
     const savedDeviceUuid =

package/src/init/run-bun-install.ts

@@ -34,3 +34,37 @@ export async function runBunInstall(cwd: string): Promise<InstallResult> {
     return { ok: false, reason: error instanceof Error ? error.message : String(error) }
   }
 }
+
+// Signature for the function that re-resolves a SINGLE dep against its
+// current spec. Distinct from InstallRunner because the auto-upgrade path
+// MUST force re-resolution against the registry (lockfile-honoring `bun
+// install` would no-op when the existing lockfile entry already satisfies
+// an in-range spec — which is the exact regression auto-upgrade exists to
+// prevent).
+export type UpdateRunner = (cwd: string, pkg: string) => Promise<InstallResult>
+
+export async function runBunUpdate(cwd: string, pkg: string): Promise<InstallResult> {
+  const bun = (globalThis as { Bun?: { spawn: typeof Bun.spawn } }).Bun
+  if (!bun) return { ok: false, reason: 'bun runtime not available' }
+  try {
+    const proc = bun.spawn({
+      // `bun update <pkg> --latest` re-resolves <pkg> against the registry,
+      // capped by the spec in package.json. For a caret/tilde range this
+      // pulls the highest in-range version (the case `bun install` won't
+      // upgrade because the lockfile already satisfies the spec). For an
+      // exact pin it's effectively a force re-fetch of that exact version.
+      // `--linker=hoisted` for the same Bun 1.3.x deadlock reason as
+      // runBunInstall above.
+      cmd: ['bun', 'update', pkg, '--latest', '--linker=hoisted'],
+      cwd,
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
+    const code = await proc.exited
+    if (code === 0) return { ok: true }
+    const stderr = await new Response(proc.stderr).text()
+    return { ok: false, reason: `bun update ${pkg} exited with code ${code}: ${stderr.trim() || 'no stderr'}` }
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) }
+  }
+}

package/src/run/bundled-plugins.ts

@@ -3,6 +3,7 @@ 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
@@ -18,6 +19,11 @@ import type { ResolvedPlugin } from '@/plugin'
 // 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),
@@ -25,6 +31,7 @@ import type { ResolvedPlugin } from '@/plugin'
 // 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 },

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,

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'