typeclaw 0.35.1 → 0.36.1

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 },

package/src/sandbox/availability.ts

@@ -209,12 +209,16 @@ export function canBindProcSafely(options?: { bwrapPath?: string }): Promise<boo
 }
 
 // Default backoff between proc-bind safety re-probes, in ms. Array length = retry
-// count (2 retries after the initial attempt = 3 probes total). The probe is
+// count (4 retries after the initial attempt = 5 probes total). The probe is
 // normally sub-ms; it only returns 'inconclusive' under transient CPU/IO
 // contention (e.g. a boot-time storm of concurrent LLM calls saturating the box
-// and tripping the probe's own timeout), so a short staggered wait lets the spike
-// pass before re-proving.
-export const PROC_BIND_RETRY_BACKOFF_MS = [250, 1_000] as const
+// and tripping the probe's own timeout), so a staggered wait lets the spike pass
+// before re-proving. Widened from [250,1000] after a deployed container degraded
+// to tmpfs (breaking `bun install`) when a boot-time load spike outlasted the old
+// two-retry budget; the longer tail rides out a sustained spike before failing
+// closed. 'unsafe' still short-circuits with no retry, so this never weakens the
+// leak-block guarantee — it only buys more chances to PROVE it.
+export const PROC_BIND_RETRY_BACKOFF_MS = [250, 1_000, 2_000, 4_000] as const
 
 // proc-bind selection must distinguish "definitely unavailable" from "couldn't
 // verify right now". A DEFINITIVE verdict is final: 'safe'→true; a real userns
@@ -375,9 +379,13 @@ async function probeProcBind(bwrap: string): Promise<ProcBindProbe> {
 }
 
 // Cap on the in-sandbox bwrap probe so a wedged runtime cannot stall the first
-// low-trust bash call. The probe normally completes in a few ms; this is a
-// generous ceiling, not a tuning knob.
-const PROC_BIND_PROBE_TIMEOUT_MS = 5_000
+// low-trust bash call. The probe normally completes in a few ms. Raised from 5s
+// because a deployed container fell to the tmpfs degraded mode (which breaks
+// `bun install` with Bun's opaque NotDir) when this timeout fired under a
+// boot-time storm of concurrent LLM/tool calls — a transient 'inconclusive' that
+// proves nothing about the host. A wider ceiling lets the real probe finish on a
+// briefly-saturated box; a genuinely wedged runtime still trips it and degrades.
+const PROC_BIND_PROBE_TIMEOUT_MS = 12_000
 
 // Designated probe-script exit codes. ONLY these two are a cacheable verdict;
 // every other code (a setup failure, bwrap startup failure, a signal, 127, …) is

package/src/sandbox/errors.ts

@@ -18,3 +18,26 @@ export class SandboxPolicyError extends Error {
     super(`sandbox policy rejected command: ${reason}`)
   }
 }
+
+// Raised when the /proc strategy degraded to the empty `tmpfs` fallback AND the
+// command needs a real /proc (a bun install / bunx / bun run that reads the
+// kernel-backed /proc/self/{fd,maps}). Without this pre-check Bun aborts deep in
+// its install pipeline with the opaque "NotDir" (ENOTDIR) error, which the model
+// misreads as a bad package or a transient hiccup and retries forever. Surfacing
+// it here, before the command runs, turns the failure into one the operator (or
+// the model) can act on: it is an environment/runtime limitation, not the
+// command's fault, so retrying the same command on the same container is futile.
+export class SandboxDegradedProcError extends Error {
+  override readonly name = 'SandboxDegradedProcError'
+  constructor() {
+    super(
+      'sandbox /proc is in degraded tmpfs mode, so bun package commands ' +
+        '(bun install / bun add / bunx / bun run) cannot run: Bun needs a real ' +
+        '/proc/self/fd, which this strategy cannot provide, and would otherwise ' +
+        'fail with an opaque "NotDir" error. This is a container/runtime limitation ' +
+        '(no usable user namespaces for the cap-free proc-bind strategy), not a ' +
+        'problem with the command or the package. Retrying the same command will ' +
+        'not help; report it as a sandbox/environment issue.',
+    )
+  }
+}

package/src/sandbox/index.ts

@@ -24,10 +24,10 @@ export {
   type WritableZones,
 } from './writable-zones'
 export { resolveSandboxSymlinks, type SandboxSymlinkSpec } from './symlinks'
-export { isPackageInstallCommand } from './package-install'
+export { commandNeedsRealProc, isPackageInstallCommand } from './package-install'
 export { ensureSessionTmpDir, isUnderTmp, mapVirtualTmpPath, SESSION_TMP_ROOT, sessionTmpDir } from './session-tmp'
 export { formatCommand, shellQuote } from './quote'
-export { SandboxPolicyError, SandboxUnavailableError } from './errors'
+export { SandboxDegradedProcError, SandboxPolicyError, SandboxUnavailableError } from './errors'
 export {
   DEFAULT_SANDBOX_ENV,
   type SandboxCommandFilter,

package/src/sandbox/package-install.ts

@@ -21,3 +21,38 @@ export function isPackageInstallCommand(command: string): boolean {
 
   return !words.some((word) => GLOBAL_FLAG.test(word))
 }
+
+// The bun subcommands whose work (or whose spawned child) reads the kernel-backed
+// /proc/self/{fd,maps} magic symlinks: package installs (add/install/i), the
+// package runners (x/create), and `run` (which can exec a package bin). Under the
+// degraded `tmpfs` /proc strategy those reads return ENOTDIR and Bun aborts with
+// its opaque "NotDir". `bunx` is the bare-binary alias for `bun x`.
+const REAL_PROC_BUN_SUBCOMMANDS = new Set(['add', 'install', 'i', 'x', 'create', 'run'])
+
+// Splits a command line at the shell operators that begin a NEW simple command —
+// `&&`, `||`, `;`, `|`, `|&`, `&`, newline — and the subshell opener `(`. A bun
+// invocation after a prelude (`cd app && bun install`, `mkdir a; cd a; bunx foo`)
+// starts a fresh segment, so checking each segment's head catches it where a
+// whole-string `words[0]` check would not. Coarse on purpose: it over-splits
+// inside quotes/`$()`, but this only feeds the DIAGNOSTIC below, never a privilege
+// decision, so a spurious extra segment can only make the error message MORE
+// likely, never widen the sandbox.
+const SHELL_COMMAND_SEPARATOR = /(?:&&|\|\||[;|&\n()])+/
+
+// Whether a command will exercise the real /proc, so a caller can turn the
+// degraded-mode `tmpfs` fallback into an actionable diagnostic instead of letting
+// Bun surface its opaque "NotDir". UNLIKE isPackageInstallCommand this is a
+// DIAGNOSTIC heuristic, not a privilege gate — it deliberately fires through shell
+// metacharacters and chained preludes (a `cd app && bunx foo` still runs bunx) and
+// never widens the sandbox surface, so erring toward catching more only improves
+// the error message.
+export function commandNeedsRealProc(command: string): boolean {
+  return command.split(SHELL_COMMAND_SEPARATOR).some((segment) => segmentInvokesRealProcBun(segment.trim()))
+}
+
+function segmentInvokesRealProcBun(segment: string): boolean {
+  if (segment === 'bunx' || segment.startsWith('bunx ')) return true
+  const words = segment.split(/\s+/)
+  if (words[0] !== 'bun') return false
+  return words[1] !== undefined && REAL_PROC_BUN_SUBCOMMANDS.has(words[1])
+}

package/src/secrets/storage.ts

@@ -243,6 +243,33 @@ export class SecretsBackend implements AuthStorageBackend {
     }
   }
 
+  // Removes `channels.<kind>` from the envelope. Returns `true` when the
+  // adapter slot was present and removed, `false` when nothing changed
+  // (idempotent on the CLI side — `channel remove discord-bot` twice should
+  // not error on the second call). Mirrors `removeProviderCredentialSync`:
+  // rewrites the file only when something changed so canonical-shape reads
+  // pay zero cost.
+  removeChannelSync(kind: string): boolean {
+    if (!existsSync(this.secretsPath)) return false
+    let release: (() => void) | undefined
+    try {
+      release = this.acquireSyncLockWithRetry()
+      const envelope = this.readEnvelope()
+      if (!(kind in envelope.channels)) return false
+      const { [kind]: _removed, ...rest } = envelope.channels
+      const next: SecretsFile = {
+        ...envelope,
+        $schema: envelope.$schema ?? SCHEMA_REL,
+        version: SECRETS_FILE_VERSION,
+        channels: rest,
+      }
+      this.writeEnvelopeAtomic(next)
+      return true
+    } finally {
+      release?.()
+    }
+  }
+
   writeChannelsSync(next: Channels): void {
     this.ensureParentDir()
     this.ensureFileExists()