typeclaw 0.1.0

package/src/reload/registry.ts

@@ -0,0 +1,60 @@
+import type { Reloadable, ReloadAllResult, ReloadResult } from './types'
+
+export class ReloadRegistry {
+  private items = new Map<string, Reloadable>()
+
+  register(item: Reloadable): void {
+    if (this.items.has(item.scope)) {
+      throw new Error(`reload scope "${item.scope}" is already registered`)
+    }
+    this.items.set(item.scope, item)
+  }
+
+  has(scope: string): boolean {
+    return this.items.has(scope)
+  }
+
+  get(scope: string): Reloadable | undefined {
+    return this.items.get(scope)
+  }
+
+  list(): Reloadable[] {
+    return Array.from(this.items.values())
+  }
+
+  // Runs serially in registration order. Reloadables observe the side
+  // effects of earlier ones — e.g. cron reload reads the freshly swapped
+  // config when it runs after the config reloadable. Manual reload is rare,
+  // so deterministic ordering wins over parallelism.
+  async reloadAll(): Promise<ReloadAllResult> {
+    const results: ReloadResult[] = []
+    for (const item of this.list()) {
+      try {
+        results.push(await item.reload())
+      } catch (err) {
+        results.push({ scope: item.scope, ok: false, reason: errorMessage(err) })
+      }
+    }
+    return { results }
+  }
+
+  async reloadOne(scope: string): Promise<ReloadResult> {
+    const item = this.items.get(scope)
+    if (!item) return { scope, ok: false, reason: `unknown scope: ${scope}` }
+    try {
+      return await item.reload()
+    } catch (err) {
+      return { scope, ok: false, reason: errorMessage(err) }
+    }
+  }
+}
+
+function errorMessage(err: unknown): string {
+  if (err instanceof Error) return err.message
+  if (typeof err === 'string') return err
+  try {
+    return JSON.stringify(err)
+  } catch {
+    return String(err)
+  }
+}

package/src/reload/types.ts

@@ -0,0 +1,13 @@
+export type ReloadResult =
+  | { scope: string; ok: true; summary: string; details?: unknown }
+  | { scope: string; ok: false; reason: string }
+
+export type Reloadable = {
+  scope: string
+  description: string
+  reload: () => Promise<ReloadResult>
+}
+
+export type ReloadAllResult = {
+  results: ReloadResult[]
+}

package/src/run/bundled-plugins.ts

@@ -0,0 +1,24 @@
+import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
+import guardPlugin from '@/bundled-plugins/guard'
+import memoryPlugin from '@/bundled-plugins/memory'
+import securityPlugin from '@/bundled-plugins/security'
+import type { ResolvedPlugin } from '@/plugin'
+
+// Consumed by both `startAgent` (auto-loaded before user plugins) AND
+// `scripts/generate-schema.ts` (each entry's `defined.configSchema` is merged
+// into `typeclaw.schema.json` keyed by plugin name). Adding a bundled plugin
+// here automatically extends the JSON schema; core `configSchema` does not
+// need to know about plugin-owned blocks.
+//
+// Order matters: `security` is listed first because its `tool.before` hook
+// must get first refusal on every tool call (HookBus runs hooks in
+// registration order and short-circuits on the first `{ block: true }`).
+// 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.
+export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
+  { name: 'security', version: undefined, source: '<bundled>', defined: securityPlugin },
+  { name: 'guard', version: undefined, source: '<bundled>', defined: guardPlugin },
+  { name: 'memory', version: undefined, source: '<bundled>', defined: memoryPlugin },
+  { name: 'agent-browser', version: undefined, source: '<bundled>', defined: agentBrowserPlugin },
+]

package/src/run/channel-session-factory.ts

@@ -0,0 +1,105 @@
+import { SessionManager } from '@mariozechner/pi-coding-agent'
+
+import { createSession as defaultCreateSession } from '@/agent'
+import type { CreateSessionForChannel, ChannelRouter } from '@/channels'
+import type { ReloadRegistry } from '@/reload'
+import type { SessionFactory } from '@/sessions'
+import type { Stream } from '@/stream'
+
+import type { PluginRuntime } from './plugin-runtime'
+
+export type BuildChannelSessionFactoryDeps = {
+  cwd: string
+  sessionFactory: SessionFactory
+  stream: Stream
+  reloadRegistry: ReloadRegistry
+  pluginRuntime: PluginRuntime
+  // Late-bound: the router is constructed by the channel manager which itself
+  // takes this factory. Reading the router lazily breaks the construction
+  // cycle while still ensuring the factory's sessions get the same router
+  // their inbound messages came from.
+  getChannelRouter: () => ChannelRouter
+  containerName?: string
+  // Test seam: lets a fake stand in for the agent session creator so tests
+  // can assert exactly which CreateSessionOptions the factory builds without
+  // needing a live LLM, plugin runtime, or session manager on disk.
+  createSession?: typeof defaultCreateSession
+}
+
+// The production wiring for channel-routed sessions. Channel inbounds arrive
+// at the router, the router calls this factory to get an AgentSession, and
+// the agent uses `channel_send` to reply. If `channelRouter` is missing here
+// the agent has no `channel_send` tool and cannot reply — silently. That was
+// the bug this factory exists to prevent. The shape of these options must
+// stay aligned with createSessionForCron in src/run/index.ts; both are
+// "channel-aware" sessions that need the same full plumbing.
+export function buildChannelSessionFactory(deps: BuildChannelSessionFactoryDeps): CreateSessionForChannel {
+  const createSession = deps.createSession ?? defaultCreateSession
+  return async ({ existingSessionId, existingSessionFile, origin }) => {
+    const sessionDir = deps.sessionFactory.sessionDir()
+    const sessionManager =
+      existingSessionId !== undefined
+        ? tryReopenOrCreate(deps.cwd, sessionDir, existingSessionId, existingSessionFile)
+        : SessionManager.create(deps.cwd, sessionDir)
+
+    const snap = deps.pluginRuntime.get()
+    const session = await createSession({
+      reloadRegistry: deps.reloadRegistry,
+      sessionManager,
+      stream: deps.stream,
+      channelRouter: deps.getChannelRouter(),
+      origin,
+      ...(snap.hasAnyPluginContent
+        ? {
+            plugins: {
+              registry: snap.registry,
+              hooks: snap.hooks,
+              sessionId: sessionManager.getSessionId(),
+              agentDir: deps.cwd,
+            },
+          }
+        : {}),
+      ...(deps.containerName !== undefined ? { containerName: deps.containerName } : {}),
+    })
+
+    return {
+      session,
+      sessionId: sessionManager.getSessionId(),
+      dispose: async () => {
+        session.dispose()
+      },
+      ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
+      getTranscriptPath: () => sessionManager.getSessionFile(),
+    }
+  }
+}
+
+// Reopen the persisted session manager when possible so the agent picks up
+// where it left off. We use the persisted basename (sessionFile) directly
+// because pi-coding-agent prefixes filenames with an ISO timestamp at write
+// time that is not derivable from sessionId alone. Failure to reopen
+// (corruption, missing file, schema drift, or v2 mapping with no sessionFile)
+// falls back to a fresh session — matching the router's existing best-effort
+// durability for channel sessions.
+function tryReopenOrCreate(
+  cwd: string,
+  sessionDir: string,
+  existingSessionId: string,
+  existingSessionFile: string | undefined,
+): SessionManager {
+  if (existingSessionFile === undefined) {
+    console.warn(
+      `[channels] session ${existingSessionId} has no sessionFile (v2 mapping not yet migrated); creating new`,
+    )
+    return SessionManager.create(cwd, sessionDir)
+  }
+  try {
+    return SessionManager.open(`${sessionDir}/${existingSessionFile}`)
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    console.warn(
+      `[channels] could not rehydrate session ${existingSessionId} from ${existingSessionFile}: ${reason}; creating new`,
+    )
+    return SessionManager.create(cwd, sessionDir)
+  }
+}

package/src/run/index.ts

@@ -0,0 +1,432 @@
+import { SessionManager } from '@mariozechner/pi-coding-agent'
+
+import { createSession, createSessionWithDispose } from '@/agent'
+import {
+  createSubagentConsumer,
+  defaultCreateSessionForSubagent,
+  invokeSubagent,
+  type Subagent as InternalSubagent,
+  type SubagentConsumer,
+  type SubagentRegistry,
+} from '@/agent/subagents'
+import { createChannelManager, createChannelsReloadable, type ChannelManager } from '@/channels'
+import { createConfigReloadable, getConfig, loadConfigSync, loadPluginConfigsSync } from '@/config'
+import {
+  type CronConsumer,
+  type CronJob,
+  type CronFile,
+  createCronConsumer,
+  createCronReloadable,
+  createScheduler,
+  type LoadCronResult,
+  loadCron as loadCronDefault,
+  type Scheduler,
+} from '@/cron'
+import { loadPlugins, type LoadPluginsResult, pluginCronJobs, type PluginRegistry, summarizeLoaded } from '@/plugin'
+import { createContainerBroker, publishForwardResult } from '@/portbroker'
+import { ReloadRegistry } from '@/reload'
+import { createServer, type Server } from '@/server'
+import { createSessionFactory, type SessionFactory } from '@/sessions'
+import { createStream, type Stream } from '@/stream'
+import { createTui as createTuiDefault, type TuiOptions } from '@/tui'
+
+import { BUNDLED_PLUGINS } from './bundled-plugins'
+import { buildChannelSessionFactory } from './channel-session-factory'
+import { createPluginRuntime, type PluginRuntime, type PluginSubagentEntry } from './plugin-runtime'
+
+type BunServer = ReturnType<Server['start']>
+
+export type TuiFactory = (options: TuiOptions) => { run: () => Promise<void> }
+
+export type LoadCronFn = (agentDir: string, options?: { subagents?: SubagentRegistry }) => Promise<LoadCronResult>
+export type SchedulerFactory = (options: { cwd: string; file: CronFile; onFire: (job: CronJob) => void }) => Scheduler
+
+export type StartAgentOptions = {
+  port: number
+  attachTui: boolean
+  initialPrompt?: string
+  cwd?: string
+  createTui?: TuiFactory
+  loadCron?: LoadCronFn
+  createSchedulerFor?: SchedulerFactory
+  sessionFactory?: SessionFactory
+  stream?: Stream
+}
+
+export type StartAgentResult = {
+  server: BunServer
+  tuiPromise: Promise<void> | null
+  scheduler: Scheduler | null
+  cronConsumer: CronConsumer | null
+  subagentConsumer: SubagentConsumer
+  reloadRegistry: ReloadRegistry
+  stream: Stream
+  pluginRuntime: PluginRuntime
+  loadedPlugins: LoadPluginsResult['loadedPlugins']
+  channelManager: ChannelManager
+  stop: () => void | Promise<void>
+}
+
+export async function startAgent({
+  port,
+  attachTui,
+  initialPrompt,
+  cwd = process.cwd(),
+  createTui = createTuiDefault,
+  loadCron = loadCronDefault,
+  createSchedulerFor,
+  sessionFactory = createSessionFactory({ agentDir: cwd }),
+  stream = createStream(),
+}: StartAgentOptions): Promise<StartAgentResult> {
+  const reloadRegistry = new ReloadRegistry()
+
+  // The host CLI sets TYPECLAW_CONTAINER_NAME when it `docker run`s us. When
+  // running outside a typeclaw container (tests, ad-hoc `bun run typeclaw run`
+  // outside docker), the env var is absent and the `restart` tool is omitted —
+  // which is what we want, since there is no host daemon to honor it anyway.
+  const containerName = process.env.TYPECLAW_CONTAINER_NAME
+  const containerNameOpt = containerName !== undefined ? { containerName } : {}
+  reloadRegistry.register(createConfigReloadable({ cwd }))
+
+  const pluginConfigsByName = loadPluginConfigsSync(cwd)
+  const cwdConfig = loadConfigSync(cwd)
+  const pluginsLoaded = await loadPlugins({
+    entries: cwdConfig.plugins,
+    agentDir: cwd,
+    configsByName: pluginConfigsByName,
+    bundled: BUNDLED_PLUGINS,
+  })
+  const pluginRegistry = pluginsLoaded.registry
+  const pluginHooks = pluginsLoaded.hooks
+
+  const { registry: subagents, pluginSubagentByShim, pluginSubagentByName } = mergeSubagents(pluginRegistry)
+
+  const hasAnyPluginContent =
+    pluginRegistry.tools.length > 0 ||
+    pluginRegistry.subagents.length > 0 ||
+    pluginRegistry.cronJobs.length > 0 ||
+    pluginRegistry.skills.length > 0 ||
+    pluginRegistry.skillsDirs.length > 0 ||
+    pluginsLoaded.loadedPlugins.length > 0
+
+  const pluginRuntime = createPluginRuntime({
+    registry: pluginRegistry,
+    hooks: pluginHooks,
+    subagents,
+    pluginSubagentByShim,
+    hasAnyPluginContent,
+    loadedPlugins: pluginsLoaded.loadedPlugins,
+    materializedSkills: null,
+  })
+
+  const channelManager = createChannelManager({
+    agentDir: cwd,
+    channelsConfigRef: () => getConfig().channels,
+    aliasesRef: () => getConfig().alias,
+    createSessionForChannel: buildChannelSessionFactory({
+      cwd,
+      sessionFactory,
+      stream,
+      reloadRegistry,
+      pluginRuntime,
+      getChannelRouter: () => channelManager.router,
+      ...containerNameOpt,
+    }),
+  })
+
+  const createSessionForSubagent: import('@/agent/subagents').CreateSessionForSubagent = async (
+    subagent,
+    subagentOptions,
+  ) => {
+    const snap = pluginRuntime.get()
+    const entry = snap.pluginSubagentByShim.get(subagent)
+    if (entry) {
+      const sessionId = `subagent-${entry.pluginName}-${crypto.randomUUID()}`
+      const created = await createSessionWithDispose({
+        systemPromptOverride: entry.pluginSubagent.systemPrompt,
+        channelRouter: channelManager.router,
+        origin: {
+          kind: 'subagent',
+          subagent: subagentOptions?.name ?? entry.subagentName,
+          parentSessionId: subagentOptions?.parentSessionId ?? '<unknown>',
+        },
+        plugins: {
+          registry: snap.registry,
+          hooks: snap.hooks,
+          sessionId,
+          agentDir: cwd,
+        },
+        pluginSubagent: {
+          pluginName: entry.pluginName,
+          ...(entry.pluginSubagent.tools ? { toolRefs: entry.pluginSubagent.tools } : {}),
+          ...(entry.pluginSubagent.customTools ? { customTools: entry.pluginSubagent.customTools } : {}),
+          toolNamePrefix: `__plugin_${entry.pluginName}_${entry.subagentName}`,
+        },
+      })
+      return {
+        ...created,
+        hooks: snap.hooks,
+        sessionId,
+      }
+    }
+    return defaultCreateSessionForSubagent(subagent, subagentOptions)
+  }
+
+  const subagentConsumer = createSubagentConsumer({
+    stream,
+    getRegistry: () => pluginRuntime.get().subagents,
+    agentDir: cwd,
+    createSessionForSubagent,
+    inFlightKey: (name, payload) => {
+      const entry = pluginSubagentByName.get(name)
+      const fn = entry?.pluginSubagent.inFlightKey
+      if (fn !== undefined) {
+        try {
+          return `${name}:${fn(payload)}`
+        } catch {
+          return name
+        }
+      }
+      return name
+    },
+  })
+  subagentConsumer.start()
+
+  const cronConsumer = createCronConsumer({
+    stream,
+    cwd,
+    createSessionForCron: async (job) => {
+      const snap = pluginRuntime.get()
+      const sessionManager = SessionManager.create(cwd, sessionFactory.sessionDir())
+      const sessionId = sessionManager.getSessionId()
+      const session = await createSession({
+        reloadRegistry,
+        sessionManager,
+        stream,
+        channelRouter: channelManager.router,
+        origin: { kind: 'cron', jobId: job.id, jobKind: 'prompt' },
+        ...(snap.hasAnyPluginContent
+          ? {
+              plugins: {
+                registry: snap.registry,
+                hooks: snap.hooks,
+                sessionId,
+                agentDir: cwd,
+              },
+            }
+          : {}),
+        ...containerNameOpt,
+      })
+      return {
+        prompt: (text) => session.prompt(text),
+        dispose: () => session.dispose(),
+        sessionId,
+        ...(snap.hasAnyPluginContent ? { hooks: snap.hooks } : {}),
+        getTranscriptPath: () => sessionManager.getSessionFile(),
+      }
+    },
+  })
+
+  const internalJobs = () => pluginCronJobs(pluginRuntime.get().registry)
+  const factory = createSchedulerFor ?? makeDefaultSchedulerFactory(internalJobs)
+  const scheduler = await startScheduler({
+    cwd,
+    loadCron,
+    createSchedulerFor: factory,
+    stream,
+    hasInternalJobs: internalJobs().length > 0,
+    getSubagents: () => pluginRuntime.get().subagents,
+  })
+
+  if (scheduler) {
+    cronConsumer.start()
+    reloadRegistry.register(
+      createCronReloadable({ cwd, scheduler, internalJobs, getSubagents: () => pluginRuntime.get().subagents }),
+    )
+  }
+
+  reloadRegistry.register(createChannelsReloadable({ manager: channelManager }))
+  await channelManager.start()
+
+  pluginsLoaded.setSpawnSubagent(async (name, payload) => {
+    await invokeSubagent(name, {
+      registry: pluginRuntime.get().subagents,
+      createSessionForSubagent,
+      agentDir: cwd,
+      userPrompt: '',
+      payload,
+    })
+  })
+  pluginsLoaded.markBooted()
+
+  if (pluginsLoaded.loadedPlugins.length > 0) {
+    console.log(`[plugin] loaded ${summarizeLoaded(pluginsLoaded.loadedPlugins, pluginRegistry)}`)
+  }
+
+  // Container-side portbroker is instantiated only when the host plumbed a
+  // broker token in via env var. Outside the container (tests, ad-hoc dev
+  // runs), the env var is absent and the broker stays off — same fence as
+  // TYPECLAW_CONTAINER_NAME guards the restart tool.
+  const brokerTokenEnv = process.env.TYPECLAW_HOSTD_BROKER_TOKEN
+  const containerBroker =
+    brokerTokenEnv !== undefined && brokerTokenEnv.length > 0
+      ? createContainerBroker({
+          expectedToken: brokerTokenEnv,
+          onLog: (event) => {
+            if (event.kind === 'subscribed') return
+            stream.publish({
+              target: { kind: 'broadcast' },
+              payload: { kind: 'portbroker-log', event },
+            })
+          },
+          // Re-publish to the in-process bus so consumers (today: the
+          // agent-browser plugin's bind-with-forward retry loop) can subscribe
+          // without holding a reference to the broker. See src/portbroker/
+          // forward-result-bus.ts for the contract.
+          onForwardResult: (event) => publishForwardResult(event),
+        })
+      : undefined
+  const containerBrokerOpt = containerBroker ? { containerBroker } : {}
+
+  const server = createServer({
+    port,
+    reloadAll: () => reloadRegistry.reloadAll(),
+    reloadRegistry,
+    sessionFactory,
+    stream,
+    channelRouter: channelManager.router,
+    agentDir: cwd,
+    pluginRuntime,
+    ...containerNameOpt,
+    ...containerBrokerOpt,
+  }).start()
+
+  let stopped = false
+  const stop = async () => {
+    if (stopped) return
+    stopped = true
+    scheduler?.stop()
+    cronConsumer.stop()
+    subagentConsumer.stop()
+    server.stop(true)
+    void disposeMaterializedSkills(pluginRuntime)
+    await channelManager.stop()
+  }
+
+  if (!attachTui) {
+    return {
+      server,
+      tuiPromise: null,
+      scheduler,
+      cronConsumer: scheduler ? cronConsumer : null,
+      subagentConsumer,
+      reloadRegistry,
+      stream,
+      pluginRuntime,
+      loadedPlugins: pluginsLoaded.loadedPlugins,
+      channelManager,
+      stop,
+    }
+  }
+
+  const url = `ws://localhost:${server.port}`
+  const tui = createTui({ url, initialPrompt })
+  const tuiPromise = tui.run()
+  return {
+    server,
+    tuiPromise,
+    scheduler,
+    cronConsumer: scheduler ? cronConsumer : null,
+    subagentConsumer,
+    reloadRegistry,
+    stream,
+    pluginRuntime,
+    loadedPlugins: pluginsLoaded.loadedPlugins,
+    channelManager,
+    stop,
+  }
+}
+
+async function disposeMaterializedSkills(pluginRuntime: PluginRuntime): Promise<void> {
+  const pending = pluginRuntime.drainPendingDisposal()
+  const current = pluginRuntime.get().materializedSkills
+  const all = current ? [...pending, current] : pending
+  await Promise.allSettled(all.map((m) => m.dispose()))
+}
+
+async function startScheduler({
+  cwd,
+  loadCron,
+  createSchedulerFor,
+  stream,
+  hasInternalJobs,
+  getSubagents,
+}: {
+  cwd: string
+  loadCron: LoadCronFn
+  createSchedulerFor: SchedulerFactory
+  stream: Stream
+  hasInternalJobs: boolean
+  getSubagents?: () => SubagentRegistry
+}): Promise<Scheduler | null> {
+  let result: LoadCronResult
+  const subagents = getSubagents?.()
+  try {
+    result = await loadCron(cwd, subagents !== undefined ? { subagents } : {})
+  } catch (err) {
+    console.error(`[cron] load failed: ${err instanceof Error ? err.message : err}`)
+    return null
+  }
+  if (!result.ok) {
+    console.error(`[cron] failed to load cron.json: ${result.reason}`)
+    return null
+  }
+  const file: CronFile = result.file ?? { jobs: [] }
+  if (!result.file && !hasInternalJobs) return null
+
+  const onFire = (job: CronJob) => {
+    stream.publish({ target: { kind: 'cron', jobId: job.id }, payload: job })
+  }
+  const scheduler = createSchedulerFor({ cwd, file, onFire })
+  scheduler.start()
+  return scheduler
+}
+
+function makeDefaultSchedulerFactory(internalJobs: () => CronJob[]): SchedulerFactory {
+  return ({ file, onFire }) => createScheduler({ jobs: [...file.jobs, ...internalJobs()], onFire })
+}
+
+function mergeSubagents(pluginRegistry: PluginRegistry): {
+  registry: SubagentRegistry
+  pluginSubagentByShim: WeakMap<InternalSubagent<any>, PluginSubagentEntry>
+  pluginSubagentByName: Map<string, PluginSubagentEntry>
+} {
+  const merged: Record<string, InternalSubagent<any>> = {}
+  const pluginSubagentByShim = new WeakMap<InternalSubagent<any>, PluginSubagentEntry>()
+  const pluginSubagentByName = new Map<string, PluginSubagentEntry>()
+  for (const reg of pluginRegistry.subagents) {
+    if (merged[reg.subagentName] !== undefined) {
+      throw new Error(
+        `plugin ${reg.pluginName}: subagent name "${reg.subagentName}" already registered (across plugins)`,
+      )
+    }
+    const shim = pluginSubagentShim(reg.subagent)
+    merged[reg.subagentName] = shim
+    const entry: PluginSubagentEntry = {
+      pluginName: reg.pluginName,
+      subagentName: reg.subagentName,
+      pluginSubagent: reg.subagent,
+    }
+    pluginSubagentByShim.set(shim, entry)
+    pluginSubagentByName.set(reg.subagentName, entry)
+  }
+  return { registry: merged, pluginSubagentByShim, pluginSubagentByName }
+}
+
+function pluginSubagentShim(subagent: import('@/plugin').Subagent<any>): InternalSubagent<any> {
+  return {
+    systemPrompt: subagent.systemPrompt,
+    ...(subagent.payloadSchema ? { payloadSchema: subagent.payloadSchema } : {}),
+    ...(subagent.handler ? { handler: subagent.handler as InternalSubagent<any>['handler'] } : {}),
+  }
+}

package/src/run/plugin-runtime.ts

@@ -0,0 +1,43 @@
+import type { Subagent as InternalSubagent, SubagentRegistry } from '@/agent/subagents'
+import type { HookBus, MaterializedSkills, PluginRegistry, Subagent as PluginSubagent } from '@/plugin'
+
+export type PluginSubagentEntry = {
+  pluginName: string
+  subagentName: string
+  pluginSubagent: PluginSubagent<any>
+}
+
+export type PluginRuntimeState = {
+  registry: PluginRegistry
+  hooks: HookBus
+  subagents: SubagentRegistry
+  pluginSubagentByShim: WeakMap<InternalSubagent<any>, PluginSubagentEntry>
+  hasAnyPluginContent: boolean
+  loadedPlugins: { name: string; version: string | undefined; source: string }[]
+  materializedSkills: MaterializedSkills | null
+}
+
+export type PluginRuntime = {
+  get: () => PluginRuntimeState
+  swap: (next: PluginRuntimeState) => PluginRuntimeState
+  trackPendingDisposal: (skills: MaterializedSkills) => void
+  drainPendingDisposal: () => MaterializedSkills[]
+}
+
+export function createPluginRuntime(initial: PluginRuntimeState): PluginRuntime {
+  let current = initial
+  const pendingDisposal: MaterializedSkills[] = []
+
+  return {
+    get: () => current,
+    swap: (next) => {
+      const prev = current
+      current = next
+      return prev
+    },
+    trackPendingDisposal: (skills) => {
+      pendingDisposal.push(skills)
+    },
+    drainPendingDisposal: () => pendingDisposal.splice(0, pendingDisposal.length),
+  }
+}

package/src/run/schema-with-plugins.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod'
+
+import { BUNDLED_PLUGINS } from './bundled-plugins'
+
+export function buildConfigSchemaWithBundledPlugins(coreSchema: z.ZodObject): z.ZodObject {
+  const pluginShape: Record<string, z.ZodType> = {}
+  for (const plugin of BUNDLED_PLUGINS) {
+    const schema = plugin.defined.configSchema
+    if (schema !== undefined) {
+      pluginShape[plugin.name] = schema as z.ZodType
+    }
+  }
+  return coreSchema.extend(pluginShape)
+}