@vellumai/assistant 0.8.7-dev.202606052232.2ddc989 → 0.8.8

package/src/plugins/registry.ts

@@ -10,16 +10,20 @@
  * late-arriving registrations.
  *
  * Registration is order-preserving: {@link getRegisteredPlugins} and
- * {@link getHooksFor} reflect the order in which {@link registerPlugin} was
- * called, which in turn determines the order plugin hooks run.
+ * {@link getMiddlewaresFor} reflect the order in which {@link registerPlugin}
+ * was called, which in turn determines onion order for middleware composition
+ * in the pipeline runner.
  *
  * This module does not call `Plugin.init()` — that is the job of the
- * bootstrap. It also does not wire the registry into the daemon.
+ * bootstrap (see PR 14). It also does not wire the registry into the daemon;
+ * later PRs introduce consumers.
  *
- * Design doc: `.private/plans/agent-plugin-system.md`.
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 13).
  */
 
 import {
+  type PipelineMiddlewareMap,
+  type PipelineName,
   type Plugin,
   PluginExecutionError,
   type PluginHookFn,
@@ -29,7 +33,7 @@ import {
 
 /**
  * Registered plugins keyed by `manifest.name`. A `Map` preserves insertion
- * order, which the registry relies on for hook ordering and
+ * order, which the registry relies on for middleware composition and
  * `getRegisteredPlugins()` output.
  */
 const registeredPlugins = new Map<string, Plugin>();
@@ -42,7 +46,8 @@ const registeredPlugins = new Map<string, Plugin>();
  * top-level `await` later resolves and still tries to call
  * {@link registerPlugin}. Without the latch such a late arrival would land in
  * the registry after `bootstrapPlugins()` has already walked it, leaving the
- * plugin visible in the registry with its `init()` hook never invoked.
+ * plugin visible to `getMiddlewaresFor()` with its
+ * `init()` hook never invoked.
  */
 let registrationClosed = false;
 
@@ -61,7 +66,7 @@ let registrationClosed = false;
  *
  * On success the plugin is appended to the registry in the order this
  * function is called. This function does NOT invoke `plugin.init()` — that
- * runs in the bootstrap sequence.
+ * runs in the bootstrap sequence (PR 14).
  */
 export function registerPlugin(plugin: Plugin): void {
   // Basic shape / required-field validation. The type system already enforces
@@ -138,6 +143,27 @@ export function getRegisteredPlugins(): Plugin[] {
   return Array.from(registeredPlugins.values());
 }
 
+/**
+ * Collect the middleware each registered plugin contributes for the given
+ * pipeline, in registration order. Consumers feed the returned array into the
+ * pipeline runner's `composeMiddleware` helper (PR 12), which applies the
+ * outermost-first convention.
+ *
+ * Plugins that don't declare a middleware for `pipeline` are skipped.
+ */
+export function getMiddlewaresFor<P extends PipelineName>(
+  pipeline: P,
+): PipelineMiddlewareMap[P][] {
+  const out: PipelineMiddlewareMap[P][] = [];
+  for (const plugin of registeredPlugins.values()) {
+    const middleware = plugin.middleware?.[pipeline];
+    if (middleware) {
+      out.push(middleware);
+    }
+  }
+  return out;
+}
+
 /**
  * Collect every registered plugin's hook for the given name, in
  * registration order. Plugins that don't declare a hook for `name` are
@@ -182,8 +208,10 @@ export function closeRegistration(): void {
 
 /**
  * Remove a plugin from the registry. Invoked from the bootstrap's failure path
- * after {@link Plugin.onShutdown} and contribution teardown have run, so the
- * registry no longer exposes a plugin whose `init()` aborted mid-bootstrap.
+ * after {@link Plugin.onShutdown} and contribution teardown have run, so
+ * {@link getMiddlewaresFor} no longer exposes a plugin whose `init()` aborted
+ * mid-bootstrap. Without this, every subsequent pipeline invocation would
+ * re-enter the uninitialized plugin's middleware.
  * Safe to call on an already-absent name (no-op).
  */
 export function unregisterPlugin(name: string): void {

package/src/plugins/types.ts

@@ -1,20 +1,34 @@
 /**
  * Plugin core types.
  *
- * A plugin may contribute lifecycle hooks ({@link PluginHooks}) that the
- * runtime invokes at named events, and model-visible capabilities (`tools`,
- * `routes`, `skills`). The registry tracks every registered plugin in
- * registration order.
+ * This file is scaffolding only — it defines the shape of the plugin system
+ * without wiring any behavior. Later PRs in the `agent-plugin-system` plan
+ * refine per-pipeline argument/result types (currently `unknown`-based
+ * placeholders) and add the pipeline runner, registry, and bootstrap.
+ *
+ * The assistant composes behavior around a small set of named pipelines
+ * (`compaction`, `overflowReduce`, ...). Each plugin may contribute one
+ * {@link Middleware} per pipeline; the registry composes them in onion
+ * order at runtime. Plugins may also contribute {@link Injector}s that emit
+ * system-prompt-time content, as well as model-visible capabilities
+ * (`tools`, `routes`, `skills`).
  *
  * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
 import type { CompactionCircuitClosedEvent } from "../api/events/compaction-circuit-closed.js";
 import type { CompactionCircuitOpenEvent } from "../api/events/compaction-circuit-open.js";
+import type { ContextWindowConfig } from "../config/schemas/inference.js";
 import type { LLMCallSite } from "../config/schemas/llm.js";
-import type { ContextWindowManager } from "../context/window-manager.js";
 import type {
+  ContextWindowManager,
+  ContextWindowResult,
+} from "../context/window-manager.js";
+import type { ReducerState } from "../daemon/context-overflow-reducer.js";
+import type {
+  ActiveSurfaceContext,
   ChannelCapabilities,
+  ChannelCommandContext,
   InjectionMode,
 } from "../daemon/conversation-runtime-assembly.js";
 import type { TrustContext } from "../daemon/trust-context.js";
@@ -74,7 +88,32 @@ export type {
   PluginShutdownContext,
 } from "../plugin-api/types.js";
 
-// ─── Memory-graph result ─────────────────────────────────────────────────────
+// ─── Middleware ──────────────────────────────────────────────────────────────
+
+/**
+ * Generic onion-style middleware. Each middleware may observe/modify the
+ * arguments, decide whether to call `next` (short-circuit) or return a
+ * synthetic result, and observe/modify the downstream result. `ctx` is the
+ * immutable per-turn {@link TurnContext}.
+ */
+export type Middleware<A, R> = (
+  args: A,
+  next: (args: A) => Promise<R>,
+  ctx: TurnContext,
+) => Promise<R>;
+
+// ─── Pipeline names ──────────────────────────────────────────────────────────
+
+/**
+ * Exhaustive list of pipeline slot names. New pipelines must be added here
+ * and in `DEFAULT_TIMEOUTS` (PR 12). The registry only understands these.
+ */
+export type PipelineName = "compaction" | "overflowReduce" | "circuitBreaker";
+
+// ─── Per-pipeline args / results (placeholder shapes) ────────────────────────
+// Concrete field-level types land in M2/M3 PRs as each pipeline is wrapped.
+// Until then we expose `unknown`-tagged aliases so downstream code can name
+// the types without depending on unstable internal shapes.
 
 /**
  * Full output of a single memory-graph retrieval — the object returned by
@@ -87,7 +126,186 @@ export type GraphMemoryResult = Awaited<
 >;
 
 /**
- * The complete set of compaction circuit-breaker transition events:
+ * Pipeline inputs for the `compaction` slot — the arguments the assistant
+ * would otherwise have passed to {@link ContextWindowManager.maybeCompact}.
+ *
+ * Typed via `unknown`-forwarded aliases to keep this module free of runtime
+ * imports from `context/window-manager.ts` (which would pull the full
+ * compaction machinery into anything that merely imports plugin types).
+ * The default compaction plugin re-casts back to the concrete types before
+ * delegating to the manager.
+ */
+export type CompactionArgs = {
+  /** The message history to consider for compaction. */
+  readonly messages: unknown;
+  /** Abort signal forwarded to the compaction summary call. */
+  readonly signal?: AbortSignal;
+  /** `ContextWindowCompactOptions` — options block forwarded verbatim. */
+  readonly options?: unknown;
+};
+/**
+ * Pipeline result for the `compaction` slot — the full
+ * {@link import("../context/window-manager.js").ContextWindowResult}
+ * object returned by `maybeCompact()`. Kept as `unknown` here for the
+ * same decoupling reason as {@link CompactionArgs}; consumers in
+ * `daemon/conversation-agent-loop.ts` cast back to the concrete shape.
+ */
+export type CompactionResult = unknown;
+
+/**
+ * Input to the `overflowReduce` pipeline. Captures everything the reducer
+ * tier loop needs, including the message history, reducer configuration,
+ * and side-effect callbacks that bridge the pipeline back to the orchestrator's
+ * mutable per-turn state (context-window manager, activity emitter, runtime
+ * injection reassembly, memory reinjection).
+ *
+ * The callbacks are supplied by the orchestrator because the reducer loop
+ * needs to coordinate with state that lives on the `AgentLoopConversationContext`
+ * (message mutation, compaction event emission, circuit breaker tracking,
+ * injection block reassembly). Keeping them as explicit callbacks — rather
+ * than pulling the whole context into the pipeline — preserves the rule that
+ * `TurnContext` stays minimal and pipeline-agnostic.
+ */
+export interface OverflowReduceArgs {
+  /** Bare persisted message history (mutable copy — the default middleware
+   *  applies reducer results in-place via the `applyMessages` callback). */
+  readonly messages: Message[];
+  /** Current run-time message array with runtime injections applied. */
+  readonly runMessages: Message[];
+  /** System prompt used for post-step token estimation. */
+  readonly systemPrompt: string;
+  /** Provider name used for token estimation (calibration provider key). */
+  readonly providerName: string;
+  /** Context window config (drives compaction behavior). */
+  readonly contextWindow: ContextWindowConfig;
+  /** Token budget the reducer must get below (preflight budget). */
+  readonly preflightBudget: number;
+  /** Tool-token overhead included in every estimation call. */
+  readonly toolTokenBudget?: number;
+  /** Maximum reducer iterations before the loop exits unconditionally. */
+  readonly maxAttempts: number;
+  /** Abort signal threaded through compaction calls. */
+  readonly abortSignal?: AbortSignal;
+  /**
+   * Compaction callback — the reducer never owns the ContextWindowManager
+   * instance. The orchestrator supplies this closure so the default plugin
+   * can delegate the forced-compaction tier without crossing the
+   * pipeline/infra boundary on its own.
+   */
+  readonly compactFn: (
+    messages: Message[],
+    signal: AbortSignal | undefined,
+    options: unknown,
+  ) => Promise<ContextWindowResult>;
+  /**
+   * Invoked before each reducer iteration to emit the `context_compacting`
+   * activity state. The orchestrator owns activity emission because the
+   * signal is trust/channel aware.
+   */
+  readonly emitActivityState: () => void;
+  /**
+   * Invoked after each reducer step that produced a successful compaction.
+   * Handles circuit-breaker tracking, event emission, and context mutation.
+   * The pipeline passes back `didCompact` so the orchestrator can flip its
+   * `reducerCompacted` / `shouldInjectWorkspace` flags and the next
+   * re-injection uses the fresh messages.
+   */
+  readonly onCompactionResult: (
+    result: ContextWindowResult,
+    compactedBasis?: Message[],
+  ) => void | Promise<void>;
+  /**
+   * Invoked after each step to rebuild `runMessages` from the step's
+   * reduced history with the requested injection mode. The orchestrator
+   * owns this helper so the full per-turn injection options object doesn't
+   * leak into the pipeline surface. The plugin passes the current reduced
+   * messages array explicitly so the orchestrator doesn't need to read
+   * mutable shared state. Returns the new `runMessages`.
+   *
+   * Two distinct "did compact" signals are passed so the orchestrator can
+   * apply the correct per-iteration vs sticky gating:
+   * - `stepCompacted` — whether THIS iteration's reducer step produced a
+   *   fresh compaction. Gates PKB / NOW re-injection: compaction strips the
+   *   existing blocks, so only iterations that just compacted need the
+   *   content re-threaded. Iterations that only truncated tool results or
+   *   downgraded injections must NOT force a re-injection or the token
+   *   count grows each round.
+   * - `accumulatedCompacted` — whether ANY iteration in this pipeline
+   *   invocation has compacted. Gates `slackChronologicalMessages`
+   *   suppression: once compaction has run, the captured Slack transcript
+   *   snapshot would overwrite the compacted history, so it must stay
+   *   suppressed for every subsequent iteration even if that iteration
+   *   didn't re-compact.
+   */
+  readonly reinjectForMode: (
+    messages: Message[],
+    mode: InjectionMode,
+    stepCompacted: boolean,
+    accumulatedCompacted: boolean,
+  ) => Promise<Message[]>;
+  /**
+   * Invoked after each step to post-estimate the rebuilt `runMessages`.
+   * Pulled out so the orchestrator controls how estimation is performed
+   * (and which fields feed it) without the pipeline reimplementing it.
+   */
+  readonly estimatePostInjection: (runMessages: Message[]) => number;
+}
+
+/** Output of the `overflowReduce` pipeline. */
+export interface OverflowReduceResult {
+  /** Final reduced `ctx.messages` value (mutated in place by the reducer). */
+  readonly messages: Message[];
+  /** Final `runMessages` with re-applied runtime injections. */
+  readonly runMessages: Message[];
+  /** Final injection mode (may be `"minimal"` if the downgrade tier fired). */
+  readonly injectionMode: InjectionMode;
+  /** Accumulated reducer state at exit. */
+  readonly reducerState: ReducerState;
+  /** True if any step successfully compacted history. */
+  readonly reducerCompacted: boolean;
+  /** How many iterations of the tier loop executed. */
+  readonly attempts: number;
+}
+
+/**
+ * Arguments for the `circuitBreaker` pipeline.
+ *
+ * A single call pattern handles both querying and updating the breaker:
+ * - `{ key }` — query-only. Returns the current `{ open, cooldownRemainingMs? }`.
+ * - `{ key, outcome }` — update state, then return the post-update decision.
+ *
+ * `key` identifies the circuit bucket so independent circuits (e.g. per
+ * conversation, per provider) can coexist. The default compaction plugin
+ * uses `"compaction:<conversationId>"`.
+ *
+ * `state` is a pragmatic extension beyond the minimal `{ key, outcome? }`
+ * shape: the `Conversation` owns `consecutiveCompactionFailures` and
+ * `compactionCircuitOpenUntil` because dev-only playground routes read and
+ * mutate those fields directly. The default plugin reads/updates the same
+ * container so the pipeline stays a pure wrapper rather than forking state
+ * ownership.
+ *
+ * `onEvent` is optional — when provided, the default plugin emits
+ * `compaction_circuit_open` / `compaction_circuit_closed` transition events
+ * through it. Its parameter is narrowed to {@link CompactionCircuitEvent} (the
+ * only two messages this pipeline ever emits) rather than the full
+ * `ServerMessage` union, so a caller whose outbound channel can carry just
+ * these two events can satisfy it. Callers that only want to query without
+ * emitting can omit it.
+ */
+export type CircuitBreakerArgs = {
+  readonly key: string;
+  readonly outcome?: "success" | "failure";
+  readonly state: {
+    readonly conversationId: string;
+    consecutiveCompactionFailures: number;
+    compactionCircuitOpenUntil: number | null;
+  };
+  readonly onEvent?: (msg: CompactionCircuitEvent) => void;
+};
+
+/**
+ * The complete set of transition events the `circuitBreaker` pipeline emits:
  * `compaction_circuit_open` when the breaker trips and `compaction_circuit_closed`
  * on the open→closed transition. Both are a subset of `ServerMessage`, so any
  * existing `ServerMessage` sink remains assignable to a
@@ -97,6 +315,31 @@ export type CompactionCircuitEvent =
   | CompactionCircuitOpenEvent
   | CompactionCircuitClosedEvent;
 
+/**
+ * Result of a `circuitBreaker` pipeline invocation.
+ *
+ * - `open` — `true` when the breaker is currently tripped (auto paths must
+ *   skip). `false` when closed (auto paths may proceed).
+ * - `cooldownRemainingMs` — when `open` is `true`, the number of ms until
+ *   the breaker auto-closes (for informational display). Omitted when the
+ *   breaker is closed.
+ */
+export type CircuitBreakerResult = {
+  readonly open: boolean;
+  readonly cooldownRemainingMs?: number;
+};
+
+/**
+ * Mapping from {@link PipelineName} to the middleware signature the registry
+ * expects for that slot. Used both to shape `Plugin.middleware` and to drive
+ * `getMiddlewaresFor<P>()` type narrowing in PR 13.
+ */
+export interface PipelineMiddlewareMap {
+  compaction: Middleware<CompactionArgs, CompactionResult>;
+  overflowReduce: Middleware<OverflowReduceArgs, OverflowReduceResult>;
+  circuitBreaker: Middleware<CircuitBreakerArgs, CircuitBreakerResult>;
+}
+
 // ─── TurnContext ─────────────────────────────────────────────────────────────
 
 /**
@@ -122,6 +365,10 @@ export interface TurnInjectionInputs {
    * context (unified turn context, etc.). Drives per-injector gating.
    */
   readonly mode?: InjectionMode;
+  /** Disk-pressure cleanup-mode context or null to skip the warning. */
+  readonly diskPressureContext?: DiskPressureInjectionContext | null;
+  /** Workspace top-level context text (`<workspace>...`) or null to skip. */
+  readonly workspaceTopLevelContext?: string | null;
   /** Pre-built unified-turn-context text (`<turn_context>...`) or null to skip. */
   readonly unifiedTurnContext?: string | null;
   /** Pre-built `<active_subagents>` block or null to skip. */
@@ -140,6 +387,18 @@ export interface TurnInjectionInputs {
    * no focus block is appended.
    */
   readonly slackActiveThreadFocusBlock?: string | null;
+  /**
+   * Active dashboard-surface context (read from `<active_workspace>`). Kept
+   * on the injection inputs bag (not its own injector) because it is
+   * orchestrator-owned surface state, not a default-chain element.
+   */
+  readonly activeSurface?: ActiveSurfaceContext | null;
+  /** Channel command context (e.g. Telegram /start) or null to skip. */
+  readonly channelCommandContext?: ChannelCommandContext | null;
+  /** Voice call-control prompt or null to skip. */
+  readonly voiceCallControlPrompt?: string | null;
+  /** Gateway-provided transport hints (e.g. Slack thread context). */
+  readonly transportHints?: string[] | null;
   /**
    * When true, inject the `<non_interactive_context>` block so the model
    * knows no human is present to answer clarification questions.
@@ -165,12 +424,18 @@ export interface TurnInjectionInputs {
   }> | null;
 }
 
+export interface DiskPressureInjectionContext {
+  /** True when the current turn is allowed to run only for storage cleanup. */
+  readonly cleanupModeActive: boolean;
+}
+
 /**
- * Per-turn execution context threaded to the injector chain and to hook
- * consumers that need turn-level identity.
+ * Per-turn execution context threaded through every middleware invocation.
  *
  * Combines turn-level identifiers (`requestId`, `conversationId`,
- * `turnIndex`) with the canonical {@link TrustContext} that carries trust
+ * `turnIndex`), the optionally-bound `pluginName` (set by the pipeline
+ * runner when invoking a specific plugin's middleware, for error
+ * attribution), and the canonical {@link TrustContext} that carries trust
  * class and channel identity for the inbound actor.
  *
  * `TrustContext` is re-exposed here (rather than redefined) so the plugin
@@ -183,42 +448,51 @@ export interface TurnContext {
   conversationId: string;
   /** 0-based turn index within the conversation. */
   turnIndex: number;
+  /**
+   * When the pipeline runner is executing a specific plugin's middleware,
+   * this is set to that plugin's name so downstream code (error wrapping,
+   * telemetry) can attribute work accurately.
+   */
+  pluginName?: string;
   /** Trust classification and channel identity for the inbound actor. */
   trust: TrustContext;
   /**
    * Optional handle to the conversation's {@link ContextWindowManager}.
    *
-   * Attached by the orchestrator so the default compaction implementation can
-   * defer to the real compaction machinery via `context.manager`. Call sites
-   * that never touch compaction may omit it.
+   * Attached by the orchestrator when building the per-turn context for
+   * pipeline invocations that need to defer to the real compaction machinery
+   * (notably the default `compaction` plugin). Pipelines that never touch
+   * compaction can ignore this field; the default compaction plugin throws
+   * a {@link PluginExecutionError} if it is missing, which keeps the failure
+   * attributed to the plugin rather than surfacing as a late NPE downstream.
    *
    * Declared as an optional typed field so plugin code can read it without a
-   * lenient cast. The optional shape is load-bearing: synthesized handler
-   * contexts and other non-compaction call sites still construct valid
-   * `TurnContext` literals without attaching a manager.
+   * lenient cast. The optional shape is load-bearing: pipeline runner tests,
+   * synthesized handler contexts, and other non-compaction call sites still
+   * construct valid `TurnContext` literals without attaching a manager.
    */
   contextWindowManager?: ContextWindowManager;
   /**
    * Per-turn injection inputs consumed by the default injector chain.
    *
-   * Omitted for call sites that don't drive runtime injection (synthesized
-   * handler contexts, some background jobs). Each default injector treats
-   * missing/absent fields as "no injection on this turn", so a context
-   * without `injectionInputs` produces an empty injection chain.
+   * Omitted for call sites that don't drive runtime injection (pipeline-runner
+   * tests, synthesized handler contexts, some background jobs). Each default
+   * injector treats missing/absent fields as "no injection on this turn", so
+   * a context without `injectionInputs` produces an empty injection chain.
    */
   injectionInputs?: TurnInjectionInputs;
   /**
-   * The {@link LLMCallSite} this turn belongs to — `"mainAgent"` for the
-   * user-facing conversational reply, or the specific background/utility site
-   * (`"compactionAgent"`, `"subagentSpawn"`, `"memoryConsolidation"`,
-   * `"conversationTitle"`, …) when the agent loop is driving non-main work
-   * that happens to share the same `conversationId`.
+   * The {@link LLMCallSite} this turn's pipeline work belongs to —
+   * `"mainAgent"` for the user-facing conversational reply, or the specific
+   * background/utility site (`"compactionAgent"`, `"subagentSpawn"`,
+   * `"memoryConsolidation"`, `"conversationTitle"`, …) when the agent loop is
+   * driving non-main work that happens to share the same `conversationId`.
    *
-   * Lets {@link Injector}s scope their behaviour to the main reply and stay
-   * out of background turns, which `onEvent` presence alone cannot distinguish
-   * (compaction and subagent loops also stream). Omitted by call sites that
-   * don't tag a site (synthesized test contexts); consumers should treat
-   * absence conservatively.
+   * Lets {@link Injector}s and pipeline middleware scope their behaviour to
+   * the main reply and stay out of background turns, which `onEvent` presence
+   * alone cannot distinguish (compaction and subagent loops also stream).
+   * Omitted by call sites that don't tag a site (synthesized test contexts);
+   * consumers should treat absence conservatively.
    */
   callSite?: LLMCallSite;
 }
@@ -401,7 +675,7 @@ export type PluginHooks = Record<string, PluginHookFn<any>>;
 
 /**
  * A registered plugin. Every field besides `manifest` is optional — a plugin
- * may contribute any combination of lifecycle hooks and model-visible
+ * may contribute any combination of middleware and model-visible
  * capabilities. Lifecycle hooks live under `hooks`.
  */
 export interface Plugin {
@@ -423,13 +697,43 @@ export interface Plugin {
   routes?: PluginRouteRegistration[];
   /** Skill registrations loaded at startup. */
   skills?: PluginSkillRegistration[];
+  /**
+   * Named middleware slots. At most one middleware per slot per plugin.
+   * The registry composes multiple plugins' middleware for a slot in
+   * registration order (outermost first).
+   */
+  middleware?: Partial<PipelineMiddlewareMap>;
 }
 
 // ─── Errors ──────────────────────────────────────────────────────────────────
 
+/**
+ * Thrown by the pipeline runner when a plugin's middleware exceeds the
+ * pipeline's configured timeout. Carries the pipeline name, the offending
+ * plugin (if known), and the elapsed-milliseconds budget that was breached.
+ */
+export class PluginTimeoutError extends AssistantError {
+  constructor(
+    public readonly pipeline: PipelineName,
+    public readonly pluginName: string | undefined,
+    public readonly elapsedMs: number,
+    options?: { cause?: unknown },
+  ) {
+    super(
+      `Plugin pipeline '${pipeline}' timed out after ${elapsedMs}ms${
+        pluginName ? ` (offending plugin: ${pluginName})` : ""
+      }`,
+      ErrorCode.INTERNAL_ERROR,
+      options,
+    );
+    this.name = "PluginTimeoutError";
+  }
+}
+
 /**
  * Thrown by registry and bootstrap for plugin lifecycle errors — registration
- * validation failures, API-version mismatches, init throw-outs.
+ * validation failures, API-version mismatches, init throw-outs. Distinct from
+ * {@link PluginTimeoutError} so callers can discriminate.
  */
 export class PluginExecutionError extends AssistantError {
   constructor(