typeclaw 0.1.1 → 0.1.3

package/src/init/index.ts

@@ -6,8 +6,10 @@ 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'
 import { buildDockerfile, DOCKERFILE } from './dockerfile'
 import { buildGitignore, GITIGNORE_FILE } from './gitignore'
 import { HATCHING_PROMPT } from './hatching'
@@ -68,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>
 
@@ -103,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({
@@ -124,6 +138,7 @@ export async function runInit({
   runHatching = defaultRunHatching,
   runBunInstall: installRunner = runBunInstall,
   dockerExec,
+  cliEntry,
 }: InitOptions): Promise<void> {
   const emit = onProgress ?? (() => {})
 
@@ -216,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
@@ -230,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,
     })
@@ -342,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 ? [] : ['*'] }
@@ -387,24 +430,29 @@ export async function scaffold(root: string, options: ScaffoldOptions = {}): Pro
 const AGENT_BROWSER_VERSION = '^0.26.0'
 
 function buildPackageJson(root: string, name: string): Record<string, unknown> {
-  const typeclawRoot = findTypeclawRoot()
-  // FIXME: temporary dev-stage wiring. Switch to a published version range
-  // (e.g. "typeclaw": "^x.y.z") once typeclaw is released. The `file:` spec is
-  // computed relative to the agent root because `file:` resolves relative to
-  // the consuming package.
-  const fileSpec = typeclawRoot ? `file:${toFileSpec(relative(root, typeclawRoot))}` : 'file:../typeclaw'
   return {
     name,
     private: true,
     type: 'module',
     workspaces: [`${PACKAGES_DIR}/*`],
     dependencies: {
-      typeclaw: fileSpec,
+      typeclaw: resolveTypeclawSpec(root),
       'agent-browser': AGENT_BROWSER_VERSION,
     },
   }
 }
 
+// Prefer the registry-style range (`^X.Y.Z`) when typeclaw is itself an
+// installed package — that's what lets `bun install` in the agent resolve
+// typeclaw from npm. Fall back to `file:` against the local checkout for
+// dev contributors running `bun run src/cli/index.ts init` from the repo.
+function resolveTypeclawSpec(agentRoot: string): string {
+  const scaffoldVersion = resolveScaffoldVersion()
+  if (scaffoldVersion !== null) return scaffoldVersion
+  const typeclawRoot = findTypeclawRoot()
+  return typeclawRoot ? `file:${toFileSpec(relative(agentRoot, typeclawRoot))}` : 'file:../typeclaw'
+}
+
 function toFileSpec(rel: string): string {
   if (rel === '') return '.'
   // bun/npm accept POSIX-style paths in file: specifiers; normalize separators.
@@ -434,9 +482,11 @@ export async function writeDockerAssets(root: string): Promise<DockerAssetsResul
     const devMode = typeclawSpec.startsWith('file:')
 
     const typeclawConfig = await readTypeclawConfig(root)
-    await writeFile(join(root, DOCKERFILE), buildDockerfile(typeclawConfig.dockerfile), { flag: 'wx' }).catch(
-      ignoreExists,
-    )
+    await writeFile(
+      join(root, DOCKERFILE),
+      buildDockerfile(typeclawConfig.dockerfile, { baseImageVersion: resolveBaseImageVersion(root) }),
+      { flag: 'wx' },
+    ).catch(ignoreExists)
 
     return { ok: true, devMode }
   } catch (error) {
@@ -508,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,
   {
@@ -523,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
@@ -538,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 {
@@ -627,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.
@@ -643,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' })
 }
 
@@ -658,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 {}
   }
 }
@@ -733,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/plugin/hooks.ts

@@ -6,6 +6,8 @@ import type {
   SessionIdleEvent,
   SessionPromptEvent,
   SessionStartEvent,
+  SessionTurnEndEvent,
+  SessionTurnStartEvent,
   ToolAfterEvent,
   ToolBeforeEvent,
   ToolBeforeResult,
@@ -43,6 +45,8 @@ export type HookBus = {
   runSessionEnd: (event: SessionEndEvent) => Promise<void>
   runSessionIdle: (event: SessionIdleEvent) => Promise<void>
   runSessionPrompt: (event: SessionPromptEvent) => Promise<void>
+  runSessionTurnStart: (event: SessionTurnStartEvent) => Promise<void>
+  runSessionTurnEnd: (event: SessionTurnEndEvent) => Promise<void>
   runToolBefore: (event: ToolBeforeEvent) => Promise<{ block: true; reason: string } | undefined>
   runToolAfter: (event: ToolAfterEvent) => Promise<void>
   count: (name: keyof Hooks) => number
@@ -62,6 +66,8 @@ type Registries = {
   'session.end': RegisteredHook<'session.end'>[]
   'session.idle': RegisteredHook<'session.idle'>[]
   'session.prompt': RegisteredHook<'session.prompt'>[]
+  'session.turn.start': RegisteredHook<'session.turn.start'>[]
+  'session.turn.end': RegisteredHook<'session.turn.end'>[]
   'tool.before': RegisteredHook<'tool.before'>[]
   'tool.after': RegisteredHook<'tool.after'>[]
 }
@@ -74,6 +80,8 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
     'session.end': [],
     'session.idle': [],
     'session.prompt': [],
+    'session.turn.start': [],
+    'session.turn.end': [],
     'tool.before': [],
     'tool.after': [],
   }
@@ -89,6 +97,8 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
       if (hooks['session.end']) r['session.end'].push({ ...base, handler: hooks['session.end'] })
       if (hooks['session.idle']) r['session.idle'].push({ ...base, handler: hooks['session.idle'] })
       if (hooks['session.prompt']) r['session.prompt'].push({ ...base, handler: hooks['session.prompt'] })
+      if (hooks['session.turn.start']) r['session.turn.start'].push({ ...base, handler: hooks['session.turn.start'] })
+      if (hooks['session.turn.end']) r['session.turn.end'].push({ ...base, handler: hooks['session.turn.end'] })
       if (hooks['tool.before']) r['tool.before'].push({ ...base, handler: hooks['tool.before'] })
       if (hooks['tool.after']) r['tool.after'].push({ ...base, handler: hooks['tool.after'] })
     },
@@ -98,6 +108,8 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
       r['session.end'] = r['session.end'].filter((h) => h.pluginName !== pluginName)
       r['session.idle'] = r['session.idle'].filter((h) => h.pluginName !== pluginName)
       r['session.prompt'] = r['session.prompt'].filter((h) => h.pluginName !== pluginName)
+      r['session.turn.start'] = r['session.turn.start'].filter((h) => h.pluginName !== pluginName)
+      r['session.turn.end'] = r['session.turn.end'].filter((h) => h.pluginName !== pluginName)
       r['tool.before'] = r['tool.before'].filter((h) => h.pluginName !== pluginName)
       r['tool.after'] = r['tool.after'].filter((h) => h.pluginName !== pluginName)
     },
@@ -150,6 +162,26 @@ export function createHookBus(options: CreateHookBusOptions = {}): HookBus {
       }
     },
 
+    async runSessionTurnStart(event) {
+      for (const reg of r['session.turn.start']) {
+        try {
+          await reg.handler(event, ctx(reg))
+        } catch (err) {
+          reportHookError(reg, 'session.turn.start', err)
+        }
+      }
+    },
+
+    async runSessionTurnEnd(event) {
+      for (const reg of r['session.turn.end']) {
+        try {
+          await reg.handler(event, ctx(reg))
+        } catch (err) {
+          reportHookError(reg, 'session.turn.end', err)
+        }
+      }
+    },
+
     // First plugin to return `{ block: true, reason }` short-circuits. Earlier
     // plugins' arg mutations remain visible to later plugins via the shared
     // event.args object.

package/src/plugin/index.ts

@@ -18,10 +18,16 @@ export type {
   HookContext,
   HookName,
   Hooks,
+  PluginCheckResult,
+  PluginCheckStatus,
   PluginContext,
   PluginCronJob,
+  PluginDoctorCheck,
+  PluginDoctorContext,
   PluginExecCronJob,
   PluginExports,
+  PluginFixResult,
+  PluginFixSuggestion,
   PluginLogger,
   PluginPromptCronJob,
   PluginSkill,
@@ -55,6 +61,7 @@ export {
   buildPluginCronGlobalId,
   type PluginRegistry,
   type RegisteredCronJob,
+  type RegisteredDoctorCheck,
   type RegisteredSubagent,
   type RegisteredTool,
   type RegisteredSkillEntry,

package/src/plugin/manager.ts

@@ -93,6 +93,7 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
         registry,
         hooks,
         agentDir: opts.agentDir,
+        pluginConfig: validatedConfig,
       })
     } catch (err) {
       discardRegistrationsBy(resolved.name, registry, hooks)
@@ -123,6 +124,7 @@ export function summarizeLoaded(loaded: LoadPluginsResult['loadedPlugins'], regi
     `${registry.cronJobs.length} cron job(s)`,
     `${registry.skills.length} skill(s)`,
     `${registry.skillsDirs.length} skills dir(s)`,
+    `${registry.doctorChecks.length} doctor check(s)`,
   ].join(', ')
   return `${loaded.length} plugin(s): ${head} [${counts}]`
 }

package/src/plugin/registry.ts

@@ -3,13 +3,28 @@ import { existsSync } from 'node:fs'
 import type { CronJob, PromptJob } from '@/cron'
 
 import type { HookBus } from './hooks'
-import type { PluginCronJob, PluginExports, PluginLogger, PluginSkill, Subagent, Tool } from './types'
+import type {
+  PluginCronJob,
+  PluginDoctorCheck,
+  PluginExports,
+  PluginLogger,
+  PluginSkill,
+  Subagent,
+  Tool,
+} from './types'
 
 export type RegisteredTool = { pluginName: string; toolName: string; tool: Tool<any>; logger: PluginLogger }
 export type RegisteredSubagent = { pluginName: string; subagentName: string; subagent: Subagent<any> }
 export type RegisteredCronJob = { pluginName: string; localId: string; globalId: string; job: CronJob }
 export type RegisteredSkillEntry = { pluginName: string; localName: string; skill: PluginSkill }
 export type RegisteredSkillDir = { pluginName: string; path: string }
+export type RegisteredDoctorCheck = {
+  pluginName: string
+  checkName: string
+  pluginConfig: unknown
+  logger: PluginLogger
+  check: PluginDoctorCheck
+}
 
 export type PluginRegistry = {
   tools: RegisteredTool[]
@@ -17,6 +32,7 @@ export type PluginRegistry = {
   cronJobs: RegisteredCronJob[]
   skills: RegisteredSkillEntry[]
   skillsDirs: RegisteredSkillDir[]
+  doctorChecks: RegisteredDoctorCheck[]
 }
 
 export type RegisterContributionsOptions = {
@@ -26,6 +42,7 @@ export type RegisterContributionsOptions = {
   registry: PluginRegistry
   hooks: HookBus
   agentDir: string
+  pluginConfig: unknown
 }
 
 export function buildPluginCronGlobalId(pluginName: string, localId: string): string {
@@ -33,7 +50,7 @@ export function buildPluginCronGlobalId(pluginName: string, localId: string): st
 }
 
 export function registerContributions(opts: RegisterContributionsOptions): void {
-  const { pluginName, logger, exports: ex, registry, hooks, agentDir } = opts
+  const { pluginName, logger, exports: ex, registry, hooks, agentDir, pluginConfig } = opts
 
   if (ex.tools) {
     for (const [toolName, tool] of Object.entries(ex.tools)) {
@@ -99,6 +116,17 @@ export function registerContributions(opts: RegisterContributionsOptions): void
   if (ex.hooks) {
     hooks.registerAll(pluginName, agentDir, logger, ex.hooks)
   }
+
+  if (ex.doctorChecks) {
+    for (const [checkName, check] of Object.entries(ex.doctorChecks)) {
+      assertNotEmpty('doctor check name', checkName, pluginName)
+      const conflict = registry.doctorChecks.find((c) => c.pluginName === pluginName && c.checkName === checkName)
+      if (conflict) {
+        throw new Error(`plugin ${pluginName}: doctor check "${checkName}" already registered`)
+      }
+      registry.doctorChecks.push({ pluginName, checkName, pluginConfig, logger, check })
+    }
+  }
 }
 
 export function discardRegistrationsBy(pluginName: string, registry: PluginRegistry, hooks: HookBus): void {
@@ -107,11 +135,12 @@ export function discardRegistrationsBy(pluginName: string, registry: PluginRegis
   registry.cronJobs = registry.cronJobs.filter((j) => j.pluginName !== pluginName)
   registry.skills = registry.skills.filter((s) => s.pluginName !== pluginName)
   registry.skillsDirs = registry.skillsDirs.filter((d) => d.pluginName !== pluginName)
+  registry.doctorChecks = registry.doctorChecks.filter((d) => d.pluginName !== pluginName)
   hooks.unregisterAll(pluginName)
 }
 
 export function emptyRegistry(): PluginRegistry {
-  return { tools: [], subagents: [], cronJobs: [], skills: [], skillsDirs: [] }
+  return { tools: [], subagents: [], cronJobs: [], skills: [], skillsDirs: [], doctorChecks: [] }
 }
 
 function assertNotEmpty(kind: string, value: string, pluginName: string): void {