typeclaw 0.36.1 → 0.36.2

package/src/plugin/manager.ts

@@ -11,10 +11,22 @@ import {
 
 import { createPluginContext, createPluginLogger, type SpawnSubagentFn } from './context'
 import { createHookBus, type HookBus } from './hooks'
-import { loadPluginEntry, type LoadPluginEntryFn, PluginNotFoundError, type ResolvedPlugin } from './loader'
+import { loadPluginEntry, type LoadPluginEntryFn, PluginSecurityError, type ResolvedPlugin } from './loader'
 import { discardRegistrationsBy, emptyRegistry, type PluginRegistry, registerContributions } from './registry'
 import type { PluginExports } from './types'
 
+export type FailedPlugin = { entry: string; phase: 'resolve' | 'config' | 'factory' | 'register'; error: string }
+
+// A user (typeclaw.json / local / npm) plugin that fails to load must not brick
+// the agent: the agent can edit its own plugins, and a self-introduced bug would
+// otherwise leave the container unable to boot and repair itself. Such failures
+// are isolated (skip + warn, keep the rest). Bundled plugins are part of the
+// trusted runtime, so their failure stays fatal — and PluginSecurityError stays
+// fatal for everyone.
+function isToleratedUserError(err: unknown): boolean {
+  return !(err instanceof PluginSecurityError)
+}
+
 export type LoadPluginsOptions = {
   entries: string[]
   agentDir: string
@@ -36,6 +48,7 @@ export type LoadPluginsResult = {
   permissions: PermissionService
   declaredPermissions: readonly string[]
   loadedPlugins: { name: string; version: string | undefined; source: string }[]
+  failedPlugins: FailedPlugin[]
   markBooted: () => void
   setSpawnSubagent: (fn: SpawnSubagentFn) => void
 }
@@ -51,113 +64,117 @@ 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 failed: FailedPlugin[] = []
+
+  // A user entry that fails to resolve OR throws at import time (typo,
+  // uninstalled package, syntax error in a local plugin the agent just edited)
+  // is isolated: warn, record, skip — the rest still boot. PluginSecurityError
+  // (path escape) is the one exception and stays fatal.
   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}`)
+        if (!isToleratedUserError(err)) throw err
+        const message = err instanceof Error ? err.message : String(err)
+        console.warn(`[plugin] failed to load "${entry}", skipping: ${message}`)
+        failed.push({ entry, phase: 'resolve', error: message })
         return null
       }
     }),
   )
-  const allPlugins: { entry: string; resolved: ResolvedPlugin }[] = [
-    ...(opts.bundled?.map((resolved) => ({ entry: `<bundled:${resolved.name}>`, resolved })) ?? []),
-    ...resolvedEntries.filter((e): e is { entry: string; resolved: ResolvedPlugin } => e !== null),
+  const allPlugins: { entry: string; resolved: ResolvedPlugin; isBundled: boolean }[] = [
+    ...(opts.bundled?.map((resolved) => ({ entry: `<bundled:${resolved.name}>`, resolved, isBundled: true })) ?? []),
+    ...resolvedEntries
+      .filter((e): e is { entry: string; resolved: ResolvedPlugin } => e !== null)
+      .map((e) => ({ ...e, isBundled: false })),
   ]
 
-  const declaredPermissions = collectDeclaredPermissions(allPlugins)
-  const ownerWildcardExclusions = collectOwnerWildcardExclusions(allPlugins)
+  // Seed the permission service from BUNDLED plugins only. A user plugin's
+  // declared permissions / owner-wildcard exclusions must not enter the live
+  // service until the plugin actually survives registration — otherwise a
+  // plugin reported as disabled could still widen the allowed set or (worse)
+  // strip an owner-wildcard bypass. Bundled plugins are always survivors:
+  // their failure is fatal, so the boot aborts before this service is used.
+  const bundledPlugins = allPlugins.filter((p) => p.isBundled)
   const permissions = createPermissionService({
     ...(opts.roles !== undefined ? { roles: opts.roles } : {}),
-    pluginPermissions: declaredPermissions,
-    ownerWildcardExclusions,
+    pluginPermissions: collectDeclaredPermissions(bundledPlugins),
+    ownerWildcardExclusions: collectOwnerWildcardExclusions(bundledPlugins),
   })
 
-  // Non-fatal: surface user-declared `permissions[]` strings that aren't in
-  // the known set, so a typo like `security.bypass.secretExfilBach` is
-  // visible at boot rather than silently failing to bypass the matching
-  // guard. We log instead of throw because the runtime still functions --
-  // the unknown string just never matches anything.
-  for (const warning of findUnknownPermissions(opts.roles, declaredPermissions)) {
-    console.warn(
-      `[permissions] role "${warning.role}" declares unknown permission "${warning.permission}" — ${warning.hint}`,
-    )
-  }
+  const survivors: { entry: string; resolved: ResolvedPlugin; isBundled: boolean }[] = []
 
-  for (const { entry, resolved } of allPlugins) {
+  for (const plugin of allPlugins) {
+    const { entry, resolved, isBundled } = plugin
+    // Name conflict is a global invariant (two plugins claiming one name make
+    // every later name-keyed lookup ambiguous), so it stays fatal regardless of
+    // origin — never demoted to a per-plugin skip.
     if (loaded.find((l) => l.name === resolved.name)) {
       throw new Error(`plugin name conflict: ${resolved.name} (entry ${entry}) already loaded`)
     }
 
-    let validatedConfig: unknown = undefined
-    if (resolved.defined.configSchema) {
-      const raw = opts.configsByName[resolved.name]
-      const parsed = (resolved.defined.configSchema as z.ZodType<unknown>).safeParse(raw ?? {})
-      if (!parsed.success) {
-        throw new Error(`plugin ${resolved.name}: config invalid: ${formatZodIssues(parsed.error)}`)
-      }
-      validatedConfig = parsed.data
-    } else if (opts.configsByName[resolved.name] !== undefined) {
-      throw new Error(
-        `plugin ${resolved.name}: config block "${resolved.name}" present in typeclaw.json but plugin declares no configSchema`,
-      )
-    }
-
-    const logger = createPluginLogger(resolved.name)
-    const ctx = createPluginContext({
-      name: resolved.name,
-      version: resolved.version,
-      agentDir: opts.agentDir,
-      config: validatedConfig as never,
-      logger,
-      permissions,
-      resolveGithubTokenForRepo: opts.resolveGithubTokenForRepo,
-      hasGithubAppTokenResolver: opts.hasGithubAppTokenResolver,
-      spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
-      isBooted: () => booted,
-    })
-
-    let exports: PluginExports
-    try {
-      exports = await resolved.defined.plugin(ctx)
-    } catch (err) {
-      discardRegistrationsBy(resolved.name, registry, hooks)
-      const message = err instanceof Error ? err.message : String(err)
-      throw new Error(`plugin ${resolved.name}: factory threw: ${message}`)
-    }
-
     try {
-      registerContributions({
-        pluginName: resolved.name,
-        logger,
-        exports,
-        ...(resolved.defined.commands !== undefined ? { commands: resolved.defined.commands } : {}),
+      await registerOnePlugin({
+        resolved,
+        config: opts.configsByName[resolved.name],
+        agentDir: opts.agentDir,
         registry,
         hooks,
-        agentDir: opts.agentDir,
-        pluginConfig: validatedConfig,
+        permissions,
+        ctxDeps: {
+          resolveGithubTokenForRepo: opts.resolveGithubTokenForRepo,
+          hasGithubAppTokenResolver: opts.hasGithubAppTokenResolver,
+          spawnSubagent: (name, payload, options) => spawnSubagentImpl(name, payload, options),
+          isBooted: () => booted,
+        },
       })
     } catch (err) {
+      const phase = err instanceof PluginPhaseError ? err.phase : 'factory'
+      const message = err instanceof PluginPhaseError ? err.detail : err instanceof Error ? err.message : String(err)
+      // Bundled/core plugin failures are typeclaw bugs (or a compromised
+      // runtime) — fail loud. Only user plugin failures are isolated.
+      if (isBundled || !isToleratedUserError(err instanceof PluginPhaseError ? err.original : err)) {
+        throw err instanceof PluginPhaseError ? err.original : err
+      }
       discardRegistrationsBy(resolved.name, registry, hooks)
-      throw err
+      console.warn(`[plugin] failed to load "${entry}", skipping: ${message}`)
+      failed.push({ entry, phase, error: message })
+      continue
     }
 
+    survivors.push(plugin)
     loaded.push({ name: resolved.name, version: resolved.version, source: resolved.source })
   }
 
+  // Finalize the permission model from the survivor set only. Plugin factories
+  // captured `permissions` by reference (their hooks read it at request time),
+  // so we mutate that same object in place rather than returning a new one.
+  const declaredPermissions = collectDeclaredPermissions(survivors)
+  permissions.replacePluginPermissions?.({
+    pluginPermissions: declaredPermissions,
+    ownerWildcardExclusions: collectOwnerWildcardExclusions(survivors),
+  })
+
+  // Non-fatal: surface user-declared `permissions[]` strings that aren't in
+  // the known set, so a typo like `security.bypass.secretExfilBach` is
+  // visible at boot rather than silently failing to bypass the matching
+  // guard. We log instead of throw because the runtime still functions --
+  // the unknown string just never matches anything. Run AFTER finalization so
+  // a failed plugin's declarations don't make a role's permission look known.
+  for (const warning of findUnknownPermissions(opts.roles, declaredPermissions)) {
+    console.warn(
+      `[permissions] role "${warning.role}" declares unknown permission "${warning.permission}" — ${warning.hint}`,
+    )
+  }
+
   return {
     registry,
     hooks,
     permissions,
     declaredPermissions,
     loadedPlugins: loaded,
+    failedPlugins: failed,
     markBooted: () => {
       booted = true
     },
@@ -167,6 +184,93 @@ export async function loadPlugins(opts: LoadPluginsOptions): Promise<LoadPlugins
   }
 }
 
+// Tags WHICH sub-phase failed (for the failedPlugins report) while preserving
+// the ORIGINAL error so the caller can keep PluginSecurityError fatal even when
+// it surfaces deep inside registration.
+class PluginPhaseError extends Error {
+  readonly phase: FailedPlugin['phase']
+  readonly detail: string
+  readonly original: unknown
+  constructor(phase: FailedPlugin['phase'], detail: string, original: unknown) {
+    super(detail)
+    this.name = 'PluginPhaseError'
+    this.phase = phase
+    this.detail = detail
+    this.original = original
+  }
+}
+
+type RegisterOnePluginArgs = {
+  resolved: ResolvedPlugin
+  config: unknown
+  agentDir: string
+  registry: PluginRegistry
+  hooks: HookBus
+  permissions: PermissionService
+  ctxDeps: {
+    resolveGithubTokenForRepo?: ResolveGithubTokenForRepo
+    hasGithubAppTokenResolver?: () => boolean
+    spawnSubagent: SpawnSubagentFn
+    isBooted: () => boolean
+  }
+}
+
+async function registerOnePlugin(args: RegisterOnePluginArgs): Promise<void> {
+  const { resolved, registry, hooks } = args
+
+  let validatedConfig: unknown = undefined
+  if (resolved.defined.configSchema) {
+    const parsed = (resolved.defined.configSchema as z.ZodType<unknown>).safeParse(args.config ?? {})
+    if (!parsed.success) {
+      const message = `plugin ${resolved.name}: config invalid: ${formatZodIssues(parsed.error)}`
+      throw new PluginPhaseError('config', message, new Error(message))
+    }
+    validatedConfig = parsed.data
+  } else if (args.config !== undefined) {
+    const message = `plugin ${resolved.name}: config block "${resolved.name}" present in typeclaw.json but plugin declares no configSchema`
+    throw new PluginPhaseError('config', message, new Error(message))
+  }
+
+  const logger = createPluginLogger(resolved.name)
+  const ctx = createPluginContext({
+    name: resolved.name,
+    version: resolved.version,
+    agentDir: args.agentDir,
+    config: validatedConfig as never,
+    logger,
+    permissions: args.permissions,
+    resolveGithubTokenForRepo: args.ctxDeps.resolveGithubTokenForRepo,
+    hasGithubAppTokenResolver: args.ctxDeps.hasGithubAppTokenResolver,
+    spawnSubagent: args.ctxDeps.spawnSubagent,
+    isBooted: args.ctxDeps.isBooted,
+  })
+
+  let exports: PluginExports
+  try {
+    exports = await resolved.defined.plugin(ctx)
+  } catch (err) {
+    discardRegistrationsBy(resolved.name, registry, hooks)
+    const message = `plugin ${resolved.name}: factory threw: ${err instanceof Error ? err.message : String(err)}`
+    throw new PluginPhaseError('factory', message, err)
+  }
+
+  try {
+    registerContributions({
+      pluginName: resolved.name,
+      logger,
+      exports,
+      ...(resolved.defined.commands !== undefined ? { commands: resolved.defined.commands } : {}),
+      registry,
+      hooks,
+      agentDir: args.agentDir,
+      pluginConfig: validatedConfig,
+    })
+  } catch (err) {
+    discardRegistrationsBy(resolved.name, registry, hooks)
+    throw new PluginPhaseError('register', err instanceof Error ? err.message : String(err), err)
+  }
+}
+
 function collectDeclaredPermissions(
   plugins: readonly { entry: string; resolved: ResolvedPlugin }[],
 ): readonly string[] {

package/src/run/codex-fetch-observer.ts

@@ -25,9 +25,29 @@ export type CodexFetchObserverOptions = {
   ttfbMs?: number
   // Override the sliding inter-chunk idle deadline applied to the SSE body
   // reader. Resets on every chunk; if no bytes arrive within this window the
-  // body stream errors. Default: 300_000 ms, matches `openai/codex`'s Rust CLI
-  // `DEFAULT_STREAM_IDLE_TIMEOUT_MS`. Set to 0 to disable just this timer.
+  // body stream errors. Like the overall deadline, this doubles as a recovery
+  // bound: on a silent stall the user waits this long before the retry fires,
+  // so it should not exceed the overall ceiling. Default 120_000 ms (was
+  // 300_000, which matched `openai/codex`'s Rust CLI but is 5min of dead air
+  // before recovery). 120s is loose enough for OpenAI's keepalive-less
+  // reasoning pauses (the Responses API sends no SSE heartbeats, so a quiet
+  // reasoning window is genuinely byte-silent) while bounded by the overall
+  // cap. Set to 0 to disable just this timer.
   idleMs?: number
+  // Override the absolute wall-clock ceiling on a single Codex request,
+  // measured from fetch start to body completion. Unlike `idleMs`, it does NOT
+  // reset on chunk arrival, so it catches a "slow-trickle" stream that emits
+  // bytes inside every idle window yet never reaches a terminal SSE event —
+  // the failure mode behind issue #394's multi-minute hang (one observed
+  // request occupied 901s before Bun's OS socket deadline fired). On expiry the
+  // request is aborted with a retryable error, so this also bounds how long a
+  // user waits before the retry fires — keeping it low is a UX requirement, not
+  // just a safety net. Default 120_000 ms: across 96 observed requests the
+  // slowest *healthy* (completed) one was 45s and p99 was ~30s, with a clean
+  // gap up to the 901s hang — so 120s is ~2.7x the healthy max (ample headroom
+  // for PoP/TLS outliers) while capping a real hang at ~2min instead of ~15min.
+  // Set to 0 to disable just this timer.
+  overallMs?: number
   // Schedule fn for tests. Receives (delayMs, callback) and returns a handle
   // the wrapper can pass to `clear`. Default: `setTimeout`/`clearTimeout`.
   scheduler?: TimeoutScheduler
@@ -44,8 +64,10 @@ const ENV_DISABLE_OBSERVER = 'TYPECLAW_CODEX_FETCH_OBSERVER'
 const ENV_DISABLE_TIMEOUTS = 'TYPECLAW_CODEX_TIMEOUTS'
 const ENV_TTFB_MS = 'TYPECLAW_CODEX_TTFB_MS'
 const ENV_IDLE_MS = 'TYPECLAW_CODEX_IDLE_MS'
+const ENV_OVERALL_MS = 'TYPECLAW_CODEX_OVERALL_MS'
 const DEFAULT_TTFB_MS = 15_000
-const DEFAULT_IDLE_MS = 300_000
+const DEFAULT_IDLE_MS = 120_000
+const DEFAULT_OVERALL_MS = 120_000
 const LOG_PREFIX = '[codex-fetch]'
 
 const defaultScheduler: TimeoutScheduler = {
@@ -126,6 +148,7 @@ function readEnvMs(name: string, fallback: number): number {
 
 type BodyTapConfig = {
   idleMs: number
+  overallMs: number
   scheduler: TimeoutScheduler
 }
 
@@ -193,17 +216,44 @@ function attachBodyTimingTap(
 
   const piped = response.body.pipeThrough(tap, { preventCancel: false })
 
-  const idleController = config.idleMs > 0 ? new AbortController() : null
+  const idleController = config.idleMs > 0 || config.overallMs > 0 ? new AbortController() : null
   let idleHandle: unknown = null
   const armIdleTimer = () => {
-    if (idleController === null) return
+    if (idleController === null || config.idleMs <= 0) return
     if (idleHandle !== null) config.scheduler.clear(idleHandle)
     idleHandle = config.scheduler.set(config.idleMs, () => {
       cause = 'idle_timeout'
       idleController.abort(new Error(`Codex SSE body idle for ${config.idleMs}ms (typeclaw observer timeout)`))
     })
   }
+
+  // Absolute ceiling on the whole request, armed once and never reset. The
+  // budget is measured from `start` (before originalFetch), so the time already
+  // spent waiting for headers is subtracted here — otherwise a slow-headers
+  // request would get a fresh full `overallMs` for its body on top of the
+  // headers wait, doubling the intended ceiling. A non-positive remainder means
+  // the budget is already spent, so we schedule at 0 to abort on the next tick.
+  // Aborts the shared controller so the existing reader race tears the stream
+  // down on the first deadline to fire — idle or overall, whichever comes first.
+  let overallHandle: unknown = null
+  if (idleController !== null && config.overallMs > 0) {
+    const remainingOverallMs = Math.max(0, config.overallMs - (now() - start))
+    overallHandle = config.scheduler.set(remainingOverallMs, () => {
+      cause = 'overall_timeout'
+      idleController.abort(
+        new Error(`Codex SSE body exceeded overall deadline of ${config.overallMs}ms (typeclaw observer timeout)`),
+      )
+    })
+  }
+  const disarmOverallTimer = () => {
+    if (overallHandle !== null) {
+      config.scheduler.clear(overallHandle)
+      overallHandle = null
+    }
+  }
+
   const disarmIdleTimer = () => {
+    disarmOverallTimer()
     if (idleHandle !== null) {
       config.scheduler.clear(idleHandle)
       idleHandle = null
@@ -295,6 +345,7 @@ export function installCodexFetchObserver(opts: CodexFetchObserverOptions = {}):
   const timeoutsEnabled = process.env[ENV_DISABLE_TIMEOUTS] !== 'off'
   const ttfbMs = timeoutsEnabled ? (opts.ttfbMs ?? readEnvMs(ENV_TTFB_MS, DEFAULT_TTFB_MS)) : 0
   const idleMs = timeoutsEnabled ? (opts.idleMs ?? readEnvMs(ENV_IDLE_MS, DEFAULT_IDLE_MS)) : 0
+  const overallMs = timeoutsEnabled ? (opts.overallMs ?? readEnvMs(ENV_OVERALL_MS, DEFAULT_OVERALL_MS)) : 0
   const originalFetch = globalThis.fetch
 
   const wrappedImpl = async (
@@ -352,6 +403,7 @@ export function installCodexFetchObserver(opts: CodexFetchObserverOptions = {}):
     const requestId = response.headers.get('x-request-id')
     return attachBodyTimingTap(response, start, headersMs, response.status, retryAfter, requestId, now, logger, {
       idleMs,
+      overallMs,
       scheduler,
     })
   }

package/src/run/index.ts

@@ -321,6 +321,7 @@ export async function startAgent({
                 ? { originatingSessionFile: ctx.originatingSessionFile }
                 : {}),
               handoffOrigin: ctx.handoffOrigin,
+              ...(ctx.triggeringAuthorId !== undefined ? { triggeringAuthorId: ctx.triggeringAuthorId } : {}),
             }
           : {}),
       })
@@ -701,6 +702,10 @@ export async function startAgent({
     console.log(`[plugin] loaded ${summarizeLoaded(pluginsLoaded.loadedPlugins, pluginRegistry)}`)
   }
 
+  for (const f of pluginsLoaded.failedPlugins) {
+    console.warn(`[plugin] DEGRADED: "${f.entry}" disabled (${f.phase}): ${f.error}`)
+  }
+
   // 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

package/src/sandbox/policy.ts

@@ -142,8 +142,19 @@ export type SandboxPolicy = {
 // guard: the container env holds FIREWORKS_API_KEY and GH_TOKEN, and env
 // inheritance is the single highest-risk exfil path for prompt-injected bash.
 // HOME points at /tmp because the sandbox mounts /tmp as a fresh tmpfs.
+//
+// BUN_TMPDIR / BUN_INSTALL both point under /tmp because `--clearenv` strips
+// the host's TMPDIR, and bun refuses to run without a writable scratch dir it
+// can discover: `bunx`, `bun add`, and `bun run <pkg-bin>` abort with
+// "Unexpected accessing temporary directory. Please set $BUN_TMPDIR or
+// $BUN_INSTALL". /tmp is always writable inside the sandbox (fresh tmpfs, or
+// the per-session bind that overrides it), so both are safe targets. Without
+// these, every sandboxed bun invocation — the core subagent install path —
+// fails before it starts.
 export const DEFAULT_SANDBOX_ENV: Record<string, string> = {
   PATH: '/usr/local/bin:/usr/bin:/bin',
   HOME: '/tmp',
   LANG: 'C.UTF-8',
+  BUN_TMPDIR: '/tmp',
+  BUN_INSTALL: '/tmp/.bun',
 }