typeclaw 0.35.0 → 0.36.0

package/src/inspect/live.ts

@@ -11,9 +11,15 @@ export type StreamLiveOptions = {
   onSubscribed?: (live: boolean) => void
   onError?: (message: string) => void
   connectTimeoutMs?: number
+  heartbeatIntervalMs?: number
+  pongTimeoutMs?: number
+  bufferedAmountCeiling?: number
 }
 
 const DEFAULT_CONNECT_TIMEOUT_MS = 5_000
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 10_000
+const DEFAULT_PONG_TIMEOUT_MS = 30_000
+const DEFAULT_BUFFERED_AMOUNT_CEILING = 1_048_576
 
 export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<InspectEvent> {
   const WS = opts.WebSocketImpl ?? WebSocket
@@ -26,6 +32,17 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
   const accumulators = new Map<string, string>()
   const thinkingAccumulators = new Map<string, string>()
 
+  let heartbeat: ReturnType<typeof setInterval> | null = null
+  let awaitingPongSince: number | null = null
+  let supportsPing = false
+
+  const stopHeartbeat = (): void => {
+    if (heartbeat !== null) {
+      clearInterval(heartbeat)
+      heartbeat = null
+    }
+  }
+
   const wake = (): void => {
     if (resolveNext !== null) {
       const fn = resolveNext
@@ -43,13 +60,19 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
       return
     }
     if (msg.type === 'subscribed') {
+      supportsPing = msg.supportsPing === true
       opts.onSubscribed?.(msg.sessionLive)
       return
     }
+    if (msg.type === 'pong') {
+      awaitingPongSince = null
+      return
+    }
     if (msg.type === 'error') {
       opts.onError?.(msg.message)
       pendingError = msg.message
       closed = true
+      stopHeartbeat()
       try {
         ws.close()
       } catch {
@@ -84,6 +107,7 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
   })
   ws.addEventListener('close', () => {
     closed = true
+    stopHeartbeat()
     wake()
   })
 
@@ -99,6 +123,7 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
         'abort',
         () => {
           closed = true
+          stopHeartbeat()
           try {
             ws.close()
           } catch {
@@ -134,25 +159,115 @@ export async function* streamLive(opts: StreamLiveOptions): AsyncGenerator<Inspe
   }
   ws.send(JSON.stringify(subscribe))
 
-  while (true) {
-    if (buffer.length > 0) {
-      const next = buffer.shift()!
-      yield next
-      continue
+  startHeartbeat({
+    ws,
+    intervalMs: opts.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS,
+    pongTimeoutMs: opts.pongTimeoutMs ?? DEFAULT_PONG_TIMEOUT_MS,
+    bufferedAmountCeiling: opts.bufferedAmountCeiling ?? DEFAULT_BUFFERED_AMOUNT_CEILING,
+    supportsPing: () => supportsPing,
+    isAwaitingPongSince: () => awaitingPongSince,
+    setAwaitingPongSince: (at) => {
+      awaitingPongSince = at
+    },
+    setTimer: (timer) => {
+      heartbeat = timer
+    },
+    onDead: () => {
+      closed = true
+      stopHeartbeat()
+      try {
+        ws.close()
+      } catch {
+        /* ignore */
+      }
+      wake()
+    },
+  })
+
+  try {
+    while (true) {
+      if (buffer.length > 0) {
+        const next = buffer.shift()!
+        yield next
+        continue
+      }
+      if (closed) {
+        if (pendingError !== null) throw new Error(pendingError)
+        return
+      }
+      const { event, done } = await new Promise<{ event: InspectEvent | null; done: boolean }>((resolve) => {
+        resolveNext = resolve
+      })
+      if (event !== null) yield event
+      if (done) {
+        if (pendingError !== null) throw new Error(pendingError)
+        return
+      }
+    }
+  } finally {
+    // Also fired when the consumer abandons the generator (break from a
+    // `for await` calls .return()): close the socket so it can't outlive the
+    // viewer, not just the heartbeat timer.
+    stopHeartbeat()
+    closed = true
+    try {
+      ws.close()
+    } catch {
+      /* ignore */
     }
-    if (closed) {
-      if (pendingError !== null) throw new Error(pendingError)
+  }
+}
+
+type HeartbeatOptions = {
+  ws: WebSocket
+  intervalMs: number
+  pongTimeoutMs: number
+  bufferedAmountCeiling: number
+  // Read live: the `subscribed` reply that sets it arrives after the timer is
+  // armed, so a snapshot taken at startHeartbeat time would always be false.
+  supportsPing: () => boolean
+  isAwaitingPongSince: () => number | null
+  setAwaitingPongSince: (at: number | null) => void
+  setTimer: (timer: ReturnType<typeof setInterval>) => void
+  onDead: () => void
+}
+
+// Steady-state liveness watchdog. The connect gate only bounds the OPENING
+// phase; once subscribed, a wedged socket (send queue not draining, no
+// 'close'/'error') would park the read loop forever. The interval fires on the
+// event-loop timer queue independent of the dead socket, so it always runs.
+// Two death signals, both treated as a clean close (return, never throw) so the
+// viewer recovers to the picker:
+//   1. bufferedAmount past a ceiling — our writes are not draining. Always on:
+//      it needs no server cooperation, so it works against any server version.
+//   2. a ping with no pong within the deadline — round-trip liveness lost,
+//      which also covers idle tails (a quiet-but-healthy tail still pongs). Only
+//      armed when the server advertised supportsPing; a pre-heartbeat server
+//      answers an unknown ping with error+close, so probing it would kill the
+//      tail. Such a server degrades to bufferedAmount-only detection.
+function startHeartbeat(opts: HeartbeatOptions): void {
+  let pingId = 0
+  const tick = (): void => {
+    if (opts.ws.bufferedAmount >= opts.bufferedAmountCeiling) {
+      opts.onDead()
       return
     }
-    const { event, done } = await new Promise<{ event: InspectEvent | null; done: boolean }>((resolve) => {
-      resolveNext = resolve
-    })
-    if (event !== null) yield event
-    if (done) {
-      if (pendingError !== null) throw new Error(pendingError)
+    if (!opts.supportsPing()) return
+    const awaiting = opts.isAwaitingPongSince()
+    if (awaiting !== null) {
+      if (Date.now() - awaiting >= opts.pongTimeoutMs) opts.onDead()
       return
     }
+    pingId += 1
+    const ping: InspectClientMessage = { type: 'ping', id: pingId }
+    try {
+      opts.ws.send(JSON.stringify(ping))
+      opts.setAwaitingPongSince(Date.now())
+    } catch {
+      opts.onDead()
+    }
   }
+  opts.setTimer(setInterval(tick, opts.intervalMs))
 }
 
 function frameToEvent(

package/src/inspect/loop.ts

@@ -10,7 +10,15 @@ export type OpenItemContext = {
   createTailScope: () => TailController
 }
 
-export type SelectItem<TItem> = (items: TItem[], opts: { initialKey?: string }) => Promise<TItem | null>
+// `refresh` (the `r` key) re-lists and re-renders the picker without opening
+// anything; `highlightKey` is the row highlighted when `r` was pressed, so the
+// selection survives the refresh.
+export type SelectOutcome<TItem> =
+  | { kind: 'picked'; item: TItem }
+  | { kind: 'cancelled' }
+  | { kind: 'refresh'; highlightKey?: string }
+
+export type SelectItem<TItem> = (items: TItem[], opts: { initialKey?: string }) => Promise<SelectOutcome<TItem>>
 
 export type OpenItemResult = {
   result: RunInspectResult
@@ -46,8 +54,12 @@ export type RunViewerLoopOptions<TItem> = {
 // inside `openItem` AFTER the picker resolves and disposed before the picker
 // re-opens, so clack always owns a clean cooked-mode stdin.
 export async function runViewerLoop<TItem>(opts: RunViewerLoopOptions<TItem>): Promise<RunInspectResult> {
+  // `preselectKey` auto-opens a row once (the `inspect <id>` arg). `highlightKey`
+  // only seeds the picker's initial highlight (esc-return + `r` refresh) and
+  // never bypasses the picker — keeping the two apart is what lets refresh
+  // re-render the list instead of re-opening the last viewer.
   let preselectKey = opts.preselectKey
-  let lastPickedKey: string | undefined
+  let highlightKey: string | undefined
   // Writable is only safe on the very first list. Returning to the picker means
   // a viewer was just opened and left — any writable session it might represent
   // is gone (detach ends the live session), so subsequent refreshes are
@@ -58,16 +70,21 @@ export async function runViewerLoop<TItem>(opts: RunViewerLoopOptions<TItem>): P
     const items = await opts.listItems({ allowWritable })
     if (items.length === 0) return opts.onEmpty()
 
-    let chosen: TItem | null
+    let chosen: TItem
     if (preselectKey !== undefined) {
-      chosen = items.find((i) => opts.keyOf(i) === preselectKey) ?? null
+      const match = items.find((i) => opts.keyOf(i) === preselectKey) ?? null
       preselectKey = undefined
-      if (chosen === null) return opts.onEmpty()
+      if (match === null) return opts.onEmpty()
+      chosen = match
     } else {
-      const hint = lastPickedKey
-      chosen = await opts.selectItem(items, hint !== undefined ? { initialKey: hint } : {})
-      if (chosen === null) return { ok: false, exitCode: 130, reason: 'cancelled' }
-      lastPickedKey = opts.keyOf(chosen)
+      const outcome = await opts.selectItem(items, highlightKey !== undefined ? { initialKey: highlightKey } : {})
+      if (outcome.kind === 'cancelled') return { ok: false, exitCode: 130, reason: 'cancelled' }
+      if (outcome.kind === 'refresh') {
+        if (outcome.highlightKey !== undefined) highlightKey = outcome.highlightKey
+        continue
+      }
+      chosen = outcome.item
+      highlightKey = opts.keyOf(chosen)
     }
 
     const opened = await opts.openItem(chosen, { createTailScope: opts.createTailScope })

package/src/inspect/render.ts

@@ -6,15 +6,42 @@ import type { InspectEvent } from './types'
 export type RenderOptions = {
   color: boolean
   maxTextLength?: number
+  // When false, the timestamp column is blanked (kept the same width so the tag
+  // column stays aligned). The line view passes this from a TimeGate so a run of
+  // same-category events shows the timestamp only on its first line.
+  showTime?: boolean
 }
 
+const TIME_WIDTH = '--:--:--'.length
+
 export function renderEvent(event: InspectEvent, opts: RenderOptions): string {
-  const time = renderTime(event.ts, opts)
+  const time = opts.showTime === false ? ' '.repeat(TIME_WIDTH) : renderTime(event.ts, opts)
   const tag = renderTag(event, opts)
   const body = renderBody(event, opts)
   return `${time}  ${tag}  ${body}`
 }
 
+// Decides whether an event's timestamp should be shown, given the running render
+// position: a timestamp prints only when the event's category differs from the
+// previous one, so a run of same-category events (e.g. back-to-back thinking
+// blocks or a tool start/end pair) carries a single timestamp at its start.
+export class TimeGate {
+  private prevCat: InspectEvent['cat'] | null = null
+
+  shouldShow(cat: InspectEvent['cat']): boolean {
+    const show = cat !== this.prevCat
+    this.prevCat = cat
+    return show
+  }
+
+  // Clear the running category so the next event always shows its timestamp.
+  // Called at a visible section boundary (the live divider) so the first live
+  // row is stamped even when it shares the last replayed event's category.
+  reset(): void {
+    this.prevCat = null
+  }
+}
+
 const DEFAULT_MAX_TEXT = 200
 
 function renderTime(ts: number, opts: RenderOptions): string {

package/src/inspect/transcript-view.ts

@@ -14,6 +14,7 @@ import { colors, markdownTheme } from '@/tui/theme'
 
 import { streamSessionEvents, type LiveSourceFactory, type StreamPhase } from './index'
 import { originLabel, shortSessionId } from './label'
+import { TimeGate } from './render'
 import type { SessionSummary } from './session-list'
 import type { InspectEvent, InspectFilter } from './types'
 
@@ -25,6 +26,7 @@ export type TranscriptViewOptions = {
   sinceMs: number | undefined
   liveSource?: LiveSourceFactory
   createTerminal?: () => Terminal
+  maxHistoryEntries?: number
 }
 
 export const MAX_LIVE_HISTORY_ENTRIES = 250
@@ -53,12 +55,15 @@ export function createTranscriptView(opts: TranscriptViewOptions) {
     // grow until the viewer stalls; the window evicts the oldest entry to keep
     // render cost bounded. Components are evicted per event so a timestamp never
     // outlives its body. Header and pinned status are never evicted.
-    const history = new BoundedComponentWindow(MAX_LIVE_HISTORY_ENTRIES)
-    const appendEntry = (components: HistoryEntry): void => {
+    const history = new BoundedComponentWindow<HistoryEntry>(opts.maxHistoryEntries ?? MAX_LIVE_HISTORY_ENTRIES)
+    const appendEntry = (entry: HistoryEntry): void => {
       tui.removeChild(status)
-      const evicted = history.push(components)
-      if (evicted !== null) for (const component of evicted) tui.removeChild(component)
-      for (const component of components) tui.addChild(component)
+      const evicted = history.push(entry)
+      if (evicted !== null) {
+        for (const component of evicted.components) tui.removeChild(component)
+        promoteVisibleRunHead(history, evicted)
+      }
+      for (const component of entry.components) tui.addChild(component)
       tui.addChild(status)
     }
 
@@ -91,15 +96,23 @@ export function createTranscriptView(opts: TranscriptViewOptions) {
     // during replay (one render at replay-end) to avoid redraw storms on long
     // transcripts; render per event once live.
     let live = false
+    const timeGate = new TimeGate()
     const onEvent = (event: InspectEvent): void => {
-      appendEntry([new Text(formatEventTime(event.ts), 0, 0), componentFor(event)])
+      const body = componentFor(event)
+      const stamped = timeGate.shouldShow(event.cat)
+      const time = new Text(stamped ? formatEventTime(event.ts) : '', 0, 0)
+      appendEntry({ kind: 'event', cat: event.cat, ts: event.ts, time, stamped, components: [time, body] })
       if (live) tui.requestRender()
     }
     const onPhase = (phase: StreamPhase): void => {
       if (phase.phase === 'replay-end') {
         tui.requestRender()
       } else if (phase.phase === 'live-start') {
-        appendEntry([new Text(divider(phase.sessionLive ? 'live' : 'live (broadcasts only)'), 0, 0)])
+        timeGate.reset()
+        appendEntry({
+          kind: 'divider',
+          components: [new Text(divider(phase.sessionLive ? 'live' : 'live (broadcasts only)'), 0, 0)],
+        })
         live = true
         tui.requestRender()
       }
@@ -199,19 +212,47 @@ function divider(text: string): string {
   return colors.dim(`─── ${text} ───`)
 }
 
-export type HistoryEntry = readonly Component[]
+// After the stamped head of a same-category run is evicted, the new first
+// visible row of that run would have a blank timestamp. Fill its already-present
+// (blank) Text so the visible window never shows a run with no timestamp at all.
+// Mutates text in place — no child add/remove/reorder.
+function promoteVisibleRunHead(history: BoundedComponentWindow<HistoryEntry>, evicted: HistoryEntry): void {
+  if (evicted.kind !== 'event' || !evicted.stamped) return
+  const first = history.first()
+  if (first === undefined || first.kind !== 'event' || first.stamped || first.cat !== evicted.cat) return
+  first.time.setText(formatEventTime(first.ts))
+  first.stamped = true
+}
+
+// An event row carries its category + ts + the (possibly blank) timestamp Text
+// so the window can re-stamp the visible run head after eviction. Non-event rows
+// (the live divider) have no category and never participate in re-stamping.
+export type HistoryEntry =
+  | {
+      kind: 'event'
+      cat: InspectEvent['cat']
+      ts: number
+      time: Text
+      stamped: boolean
+      components: readonly Component[]
+    }
+  | { kind: 'divider'; components: readonly Component[] }
 
-export class BoundedComponentWindow {
-  private readonly entries: HistoryEntry[] = []
+export class BoundedComponentWindow<T> {
+  private readonly entries: T[] = []
 
   constructor(private readonly maxEntries: number) {}
 
-  push(entry: HistoryEntry): HistoryEntry | null {
+  push(entry: T): T | null {
     this.entries.push(entry)
     if (this.entries.length <= this.maxEntries) return null
     return this.entries.shift() ?? null
   }
 
+  first(): T | undefined {
+    return this.entries[0]
+  }
+
   get size(): number {
     return this.entries.length
   }

package/src/plugin/index.ts

@@ -72,8 +72,8 @@ export {
   type LoadPluginsResult,
 } from './manager'
 export type { PermissionService } from '@/permissions'
-export type { LoadPluginEntryFn, ResolvedPlugin } from './loader'
-export { loadPluginEntry, derivePluginNameFromPackage } from './loader'
+export type { LoadPluginEntryFn, PluginEntrySpec, ResolvedPlugin } from './loader'
+export { derivePluginNameFromPackage, loadPluginEntry, PluginNotFoundError, splitPluginEntrySpec } from './loader'
 export { materializeSkills, type MaterializedSkills, type SkillEntry } from './skills'
 export {
   createLoadSkillTool,

package/src/plugin/loader.ts

@@ -13,6 +13,20 @@ export type ResolvedPlugin = {
 
 export type LoadPluginEntryFn = (entry: string, agentDir: string) => Promise<ResolvedPlugin>
 
+// Thrown only when a plugin entry cannot be resolved at all (uninstalled
+// package, missing local file, unresolvable export subpath). The manager
+// treats this as non-fatal and skips the entry. Every other failure --
+// path-escape, import-time evaluation throws, invalid definition -- stays a
+// plain Error so it remains a hard boot error.
+export class PluginNotFoundError extends Error {
+  readonly entry: string
+  constructor(entry: string, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'PluginNotFoundError'
+    this.entry = entry
+  }
+}
+
 export async function loadPluginEntry(entry: string, agentDir: string): Promise<ResolvedPlugin> {
   if (isLocalPath(entry)) {
     return loadLocal(entry, agentDir)
@@ -33,7 +47,7 @@ async function loadLocal(entry: string, agentDir: string): Promise<ResolvedPlugi
     throw new Error(`plugin path escapes agent directory: ${entry} (resolved to ${resolved})`)
   }
   if (!existsSync(resolved)) {
-    throw new Error(`plugin path does not exist: ${entry} (resolved to ${resolved})`)
+    throw new PluginNotFoundError(entry, `plugin path does not exist: ${entry} (resolved to ${resolved})`)
   }
   const url = pathToFileURL(resolved).href
   const mod = (await import(url)) as { default?: unknown }
@@ -43,8 +57,14 @@ async function loadLocal(entry: string, agentDir: string): Promise<ResolvedPlugi
 }
 
 async function loadNpm(entry: string, agentDir: string): Promise<ResolvedPlugin> {
-  const pkgJsonPath = findPackageJson(entry, agentDir)
-  let pkgName = entry
+  // The version suffix (`name@1.2.3`, `@scope/name@1.2.3`) is consumed by the
+  // host reconcile step when materializing the entry into package.json. By load
+  // time the package is installed at `node_modules/<name>/` under its bare name,
+  // so passing the raw `name@version` here would miss the dir and fail the
+  // bare-import fallback too.
+  const { name: packageName } = splitPluginEntrySpec(entry)
+  const pkgJsonPath = findPackageJson(packageName, agentDir)
+  let pkgName = packageName
   let version: string | undefined
   let entryPath: string | null = null
   if (pkgJsonPath !== null) {
@@ -68,16 +88,46 @@ async function loadNpm(entry: string, agentDir: string): Promise<ResolvedPlugin>
       // Fall through to bare-import resolution.
     }
   }
-  // Falls back to bare-import resolution when entryPath cannot be located on
-  // disk. Modern packages with `exports` map (and no `main`/`module`) take
-  // this path so Bun's resolver can read `exports`.
-  const importTarget = entryPath !== null ? pathToFileURL(entryPath).href : entry
+  // Resolve before importing so an unresolvable entry (uninstalled package,
+  // missing export subpath) is classified as PluginNotFoundError WITHOUT
+  // running the module. Once resolution succeeds, any import-time throw is a
+  // genuine plugin bug and propagates fatally -- never swallowed as not-found.
+  // The entryPath branch covers packages whose `main`/`module` was already
+  // located on disk; the else branch lets Bun's resolver read `exports` maps.
+  let importTarget: string
+  if (entryPath !== null) {
+    importTarget = pathToFileURL(entryPath).href
+  } else {
+    try {
+      importTarget = Bun.resolveSync(packageName, agentDir)
+    } catch (err) {
+      throw new PluginNotFoundError(entry, `cannot resolve plugin "${entry}": ${describeError(err)}`, { cause: err })
+    }
+  }
   const mod = (await import(importTarget)) as { default?: unknown }
   const defined = expectDefined(mod, entry)
   const name = derivePluginNameFromPackage(pkgName)
   return { name, version, source: entry, defined }
 }
 
+export type PluginEntrySpec = { name: string; versionSpec: string | undefined }
+
+// Splits an npm-style entry into package name and optional version spec. The
+// version delimiter is the LAST `@` that isn't the leading scope marker, so
+// `@scope/pkg@1.2.3` → { name: '@scope/pkg', versionSpec: '1.2.3' } while
+// `@scope/pkg` → { name: '@scope/pkg', versionSpec: undefined }.
+export function splitPluginEntrySpec(entry: string): PluginEntrySpec {
+  const scoped = entry.startsWith('@')
+  const searchFrom = scoped ? entry.indexOf('/') + 1 : 0
+  const at = entry.indexOf('@', searchFrom)
+  if (at <= 0) return { name: entry, versionSpec: undefined }
+  const versionSpec = entry.slice(at + 1)
+  return {
+    name: entry.slice(0, at),
+    versionSpec: versionSpec.length > 0 ? versionSpec : undefined,
+  }
+}
+
 export function derivePluginNameFromPackage(packageName: string): string {
   const PREFIX = 'typeclaw-plugin-'
   const SCOPED_PREFIX_RE = /^@[^/]+\//
@@ -85,6 +135,10 @@ export function derivePluginNameFromPackage(packageName: string): string {
   return stripped.startsWith(PREFIX) ? stripped.slice(PREFIX.length) : stripped
 }
 
+function describeError(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
 function findPackageJson(entry: string, agentDir: string): string | null {
   const PACKAGE_JSON = 'package.json'
   let cur = agentDir

package/src/plugin/manager.ts

@@ -11,7 +11,7 @@ import {
 
 import { createPluginContext, createPluginLogger, type SpawnSubagentFn } from './context'
 import { createHookBus, type HookBus } from './hooks'
-import { loadPluginEntry, type LoadPluginEntryFn, type ResolvedPlugin } from './loader'
+import { loadPluginEntry, type LoadPluginEntryFn, PluginNotFoundError, type ResolvedPlugin } from './loader'
 import { discardRegistrationsBy, emptyRegistry, type PluginRegistry, registerContributions } from './registry'
 import type { PluginExports } from './types'
 
@@ -51,11 +51,25 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
     throw new Error('plugin: spawnSubagent is not yet wired')
   }
 
+  // Non-fatal: a single unresolvable entry (uninstalled package, typo) must
+  // not abort boot for every other plugin -- warn and skip it. Only genuine
+  // resolution failures (PluginNotFoundError) are swallowed; path-escape,
+  // import-time throws, and invalid definitions stay fatal so a broken or
+  // malicious plugin still hard-fails boot.
+  const resolvedEntries = await Promise.all(
+    opts.entries.map(async (entry) => {
+      try {
+        return { entry, resolved: await loadEntry(entry, opts.agentDir) }
+      } catch (err) {
+        if (!(err instanceof PluginNotFoundError)) throw err
+        console.warn(`[plugin] failed to load "${entry}", ignoring: ${err.message}`)
+        return null
+      }
+    }),
+  )
   const allPlugins: { entry: string; resolved: ResolvedPlugin }[] = [
     ...(opts.bundled?.map((resolved) => ({ entry: `<bundled:${resolved.name}>`, resolved })) ?? []),
-    ...(await Promise.all(
-      opts.entries.map(async (entry) => ({ entry, resolved: await loadEntry(entry, opts.agentDir) })),
-    )),
+    ...resolvedEntries.filter((e): e is { entry: string; resolved: ResolvedPlugin } => e !== null),
   ]
 
   const declaredPermissions = collectDeclaredPermissions(allPlugins)

package/src/run/bundled-plugins.ts

@@ -1,6 +1,7 @@
 import agentBrowserPlugin from '@/bundled-plugins/agent-browser'
 import backupPlugin from '@/bundled-plugins/backup'
 import bunHygienePlugin from '@/bundled-plugins/bun-hygiene'
+import docRenderPlugin from '@/bundled-plugins/doc-render'
 import explorerPlugin from '@/bundled-plugins/explorer'
 import githubCliAuthPlugin from '@/bundled-plugins/github-cli-auth'
 import guardPlugin from '@/bundled-plugins/guard'
@@ -58,6 +59,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { 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 },
+  { name: 'doc-render', version: undefined, source: '<bundled>', defined: docRenderPlugin },
   { name: 'explorer', version: undefined, source: '<bundled>', defined: explorerPlugin },
   { name: 'scout', version: undefined, source: '<bundled>', defined: scoutPlugin },
   { name: 'reviewer', version: undefined, source: '<bundled>', defined: reviewerPlugin },