@moxxy/core 0.3.0

package/src/plugins/host.ts

@@ -0,0 +1,327 @@
+import type {
+  MoxxyRequirement,
+  Plugin,
+  PluginHostHandle,
+  RequirementCheck,
+  RequirementIssue,
+  ResolvedPluginManifest,
+} from '@moxxy/sdk';
+import { discoverPlugins } from './discovery.js';
+import { toposortPluginManifests, PluginCycleError } from './toposort.js';
+import { REGISTRY_KINDS, type RegistryNameRecord } from './registry-kinds.js';
+
+// PluginHostOptions + PluginLoader live in ./host-options.js (a leaf shared with
+// registry-kinds.ts to avoid an import cycle). Imported for local use and
+// re-exported so existing `import { PluginHostOptions } from './host.js'` call
+// sites keep working.
+import type { PluginHostOptions, PluginLoader } from './host-options.js';
+export type { PluginHostOptions, PluginLoader };
+
+export interface RegisterStaticOptions {
+  /**
+   * Static requirements to enforce before registration. Mirrors the
+   * `moxxy.requirements` field a discovered plugin's package.json would
+   * carry; passed explicitly here because statically-imported builtins
+   * don't go through `discoverPlugins()`.
+   */
+  readonly requirements?: ReadonlyArray<MoxxyRequirement>;
+}
+
+export type PluginSkipSource = 'static' | 'discovered';
+export type PluginSkipReason = 'unmet_requirements' | 'load_error';
+
+export interface PluginSkipRecord {
+  readonly pluginName: string;
+  readonly source: PluginSkipSource;
+  readonly reason: PluginSkipReason;
+  readonly message: string;
+  readonly packageName?: string;
+  readonly issues?: ReadonlyArray<RequirementIssue>;
+  readonly hints: ReadonlyArray<string>;
+}
+
+export class PluginRequirementError extends Error {
+  constructor(
+    readonly pluginName: string,
+    readonly check: RequirementCheck,
+  ) {
+    super(
+      check.issues
+        .filter((issue) => !issue.requirement.optional)
+        .map((issue) => issue.message)
+        .join('; '),
+    );
+    this.name = 'PluginRequirementError';
+  }
+}
+
+interface LoadedRecord extends RegistryNameRecord {
+  readonly plugin: Plugin;
+  readonly manifest?: ResolvedPluginManifest;
+}
+
+export class PluginHost implements PluginHostHandle {
+  private readonly loaded = new Map<string, LoadedRecord>();
+  private readonly skipped = new Map<string, PluginSkipRecord>();
+
+  constructor(private readonly opts: PluginHostOptions) {}
+
+  list(): ReadonlyArray<{
+    name: string;
+    version: string;
+    loaded: boolean;
+    kinds: ReadonlyArray<string>;
+  }> {
+    return [...this.loaded.values()].map((r) => ({
+      name: r.plugin.name,
+      version: r.plugin.version,
+      loaded: true,
+      kinds: contributionKinds(r),
+    }));
+  }
+
+  listSkipped(): ReadonlyArray<PluginSkipRecord> {
+    return [...this.skipped.values()];
+  }
+
+  registerStatic(plugin: Plugin, opts: RegisterStaticOptions = {}): void {
+    if (this.loaded.has(plugin.name)) {
+      throw new Error(`Plugin already registered: ${plugin.name}`);
+    }
+    this.assertRequirementsReady(plugin, opts.requirements, 'static');
+    const record = this.applyPlugin(plugin);
+    this.loaded.set(plugin.name, record);
+    this.clearSkip(plugin.name);
+    this.opts.requirements.registerPlugin(plugin.name, plugin.version);
+    this.refreshDispatcher();
+  }
+
+  registerDiscovered(plugin: Plugin, manifest: ResolvedPluginManifest): void {
+    // Key the loaded map by the PACKAGE name — not the plugin's declared
+    // `name` — so it lines up with `discoverAndLoad`'s dedupe check, `reload`'s
+    // `wanted` set, and `unload(packageName)` callers (self-update, config,
+    // plugins-admin). Keying by `plugin.name` silently broke all three whenever
+    // a plugin's declared name differed from its package name (re-load throws,
+    // reload unloads everything, unload no-ops).
+    if (this.loaded.has(manifest.packageName)) {
+      throw new Error(`Plugin already registered: ${manifest.packageName}`);
+    }
+    this.assertRequirementsReady(plugin, manifest.requirements, 'discovered', manifest);
+    const record = this.applyPlugin(plugin, manifest);
+    this.loaded.set(manifest.packageName, record);
+    this.clearSkip(plugin.name);
+    this.clearSkip(manifest.packageName);
+    // Register the requirement under the PACKAGE name, not the declared
+    // plugin.name. `kind:'plugin'` requirements are resolved by package name —
+    // toposort keys `byPackage` by `manifest.packageName`, so the readiness
+    // gate (`requirements.plugins.get(name)`) must agree. Keying by plugin.name
+    // here meant a dependent's `{kind:'plugin', name:<packageName>}` would pass
+    // toposort ordering but fail the readiness gate whenever a plugin's
+    // declared name differed from its package name (host.ts documents that they
+    // can differ).
+    this.opts.requirements.registerPlugin(manifest.packageName, plugin.version);
+    this.refreshDispatcher();
+  }
+
+  async discoverAndLoad(extraPaths?: ReadonlyArray<string>): Promise<ReadonlyArray<Plugin>> {
+    const manifests = await discoverPlugins({
+      cwd: this.opts.cwd,
+      logger: this.opts.logger,
+      extraPaths,
+    });
+    const loaded: Plugin[] = [];
+    const loader = this.opts.loader;
+    if (!loader) {
+      this.opts.logger.warn(
+        'PluginHost.discoverAndLoad called without a loader; static plugins only. Provide a loader (e.g. jiti loader) to enable dynamic discovery.',
+      );
+      return loaded;
+    }
+    let ordered: ReadonlyArray<ResolvedPluginManifest>;
+    try {
+      ordered = toposortPluginManifests(manifests);
+    } catch (err) {
+      if (err instanceof PluginCycleError) {
+        this.opts.logger.warn('PluginHost: requirement cycle, falling back to unsorted order', {
+          cycle: err.cycle,
+        });
+        ordered = manifests;
+      } else {
+        throw err;
+      }
+    }
+    for (const manifest of ordered) {
+      if (this.loaded.has(manifest.packageName)) continue;
+      // Honor a runtime/config disable: never load a package the user turned off.
+      if (this.opts.isDisabled?.(manifest.packageName)) continue;
+      try {
+        const plugin = await loader.load(manifest);
+        this.registerDiscovered(plugin, manifest);
+        loaded.push(plugin);
+      } catch (err) {
+        if (err instanceof PluginRequirementError) {
+          this.opts.logger.warn('PluginHost: skipped plugin due to unmet requirements', {
+            package: manifest.packageName,
+            plugin: err.pluginName,
+            err: err.message,
+          });
+          continue;
+        }
+        this.recordLoadError(manifest.packageName, 'discovered', manifest.packageName, err);
+        this.opts.logger.warn('PluginHost: failed to load plugin', {
+          package: manifest.packageName,
+          err: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    this.refreshDispatcher();
+    return loaded;
+  }
+
+  async unload(name: string): Promise<void> {
+    const record = this.loaded.get(name);
+    if (!record) return;
+    // Iterate REGISTRY_KINDS in its declared order — the exact set + order the
+    // original hand-written unregister sequence used — so register/unregister
+    // stay in lockstep and a new kind is one table entry, not edits here.
+    for (const kind of REGISTRY_KINDS) {
+      for (const recordedName of record[kind.recordField]) kind.unregister(this.opts, recordedName);
+    }
+    this.loaded.delete(name);
+    // Unregister under the SAME key registration used: package name for
+    // discovered plugins (see registerDiscovered), declared name for statics.
+    this.opts.requirements.unregisterPlugin(record.manifest?.packageName ?? record.plugin.name);
+    this.refreshDispatcher();
+  }
+
+  async reload(): Promise<void> {
+    this.opts.logger.info('PluginHost.reload(): rescanning plugins');
+    // Reuse the same discovery roots the initial load used (incl. the user
+    // plugin dirs) for BOTH the "wanted" scan and the re-load. Omitting them
+    // would mark user plugins as not-wanted (→ unloaded) and never re-add them.
+    const manifests = await discoverPlugins({
+      cwd: this.opts.cwd,
+      logger: this.opts.logger,
+      ...(this.opts.userPaths ? { extraPaths: this.opts.userPaths } : {}),
+    });
+    // A disabled package is excluded from `wanted`, so the loop below unloads it
+    // if currently loaded and discoverAndLoad won't bring it back.
+    const wanted = new Set(
+      manifests
+        .filter((m) => !this.opts.isDisabled?.(m.packageName))
+        .map((m) => m.packageName),
+    );
+    for (const [name] of [...this.loaded]) {
+      // Statically-registered builtins have no manifest; never unload them on
+      // reload — they aren't discovered from disk so they'd never come back.
+      if (this.loaded.get(name)?.manifest && !wanted.has(name)) await this.unload(name);
+    }
+    await this.discoverAndLoad(this.opts.userPaths);
+  }
+
+  private applyPlugin(plugin: Plugin, manifest?: ResolvedPluginManifest): LoadedRecord {
+    // Snapshot the contributed names BEFORE registering (same as the original
+    // two-phase order), keyed by REGISTRY_KINDS field. Building the names from
+    // the same table the registration loop uses keeps the two in lockstep.
+    const names = {} as Record<keyof RegistryNameRecord, ReadonlyArray<string>>;
+    for (const kind of REGISTRY_KINDS) {
+      names[kind.recordField] = kind.defs(plugin).map((def) => kind.nameOf(def));
+    }
+
+    // Register in REGISTRY_KINDS order — the exact set + order the original
+    // hand-written register sequence used (incl. viewRenderers/tunnelProviders
+    // via `replace`).
+    for (const kind of REGISTRY_KINDS) {
+      for (const def of kind.defs(plugin)) kind.register(this.opts, def);
+    }
+
+    return {
+      plugin,
+      manifest,
+      ...(names as RegistryNameRecord),
+    };
+  }
+
+  private assertRequirementsReady(
+    plugin: Plugin,
+    requirements: ReadonlyArray<MoxxyRequirement> | undefined,
+    source: PluginSkipSource = 'static',
+    manifest?: ResolvedPluginManifest,
+  ): void {
+    if (!requirements || requirements.length === 0) return;
+    const check = this.opts.requirements.check(requirements);
+    if (!check.ready) {
+      this.recordRequirementSkip(plugin, source, manifest, check);
+      throw new PluginRequirementError(plugin.name, check);
+    }
+  }
+
+  private refreshDispatcher(): void {
+    this.opts.dispatcher.setPlugins([...this.loaded.values()].map((r) => r.plugin));
+  }
+
+  private recordRequirementSkip(
+    plugin: Plugin,
+    source: PluginSkipSource,
+    manifest: ResolvedPluginManifest | undefined,
+    check: RequirementCheck,
+  ): void {
+    const blocking = check.issues.filter((issue) => !issue.requirement.optional);
+    this.skipped.set(skipKey(plugin.name), {
+      pluginName: plugin.name,
+      source,
+      reason: 'unmet_requirements',
+      message: blocking.map((issue) => issue.message).join('; '),
+      ...(manifest ? { packageName: manifest.packageName } : {}),
+      issues: check.issues,
+      hints: blocking.flatMap((issue) => issue.hint ? [issue.hint] : []),
+    });
+  }
+
+  private recordLoadError(
+    pluginName: string,
+    source: PluginSkipSource,
+    packageName: string | undefined,
+    err: unknown,
+  ): void {
+    this.skipped.set(skipKey(pluginName), {
+      pluginName,
+      source,
+      reason: 'load_error',
+      message: err instanceof Error ? err.message : String(err),
+      ...(packageName ? { packageName } : {}),
+      hints: [],
+    });
+  }
+
+  private clearSkip(pluginName: string): void {
+    this.skipped.delete(skipKey(pluginName));
+  }
+}
+
+function skipKey(pluginName: string): string {
+  return pluginName;
+}
+
+/** The contribution categories a loaded plugin actually registered, in a
+ *  stable order — lets a UI group plugins by kind (tabs in the picker). */
+function contributionKinds(r: LoadedRecord): ReadonlyArray<string> {
+  const kinds: string[] = [];
+  if (r.providerNames.length) kinds.push('provider');
+  if (r.modeNames.length) kinds.push('mode');
+  if (r.channelNames.length) kinds.push('channel');
+  if (r.surfaceNames.length) kinds.push('surface');
+  if (r.embedderNames.length) kinds.push('embedder');
+  if (r.transcriberNames.length) kinds.push('transcriber');
+  if (r.synthesizerNames.length) kinds.push('synthesizer');
+  if (r.isolatorNames.length) kinds.push('isolator');
+  if (r.compactorNames.length) kinds.push('compactor');
+  if (r.cacheStrategyNames.length) kinds.push('cacheStrategy');
+  if (r.viewRendererNames.length) kinds.push('viewRenderer');
+  if (r.tunnelProviderNames.length) kinds.push('tunnelProvider');
+  if (r.workflowExecutorNames.length) kinds.push('workflowExecutor');
+  if (r.agentNames.length) kinds.push('agent');
+  if (r.commandNames.length) kinds.push('command');
+  if (r.toolNames.length) kinds.push('tool');
+  return kinds;
+}

package/src/plugins/lifecycle.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, it, vi } from 'vitest';
+import { definePlugin, asSessionId, asTurnId, asToolCallId } from '@moxxy/sdk';
+import type {
+  AppContext,
+  ToolCallContext,
+  ToolResultContext,
+  ToolResultEvent,
+  TurnContext,
+} from '@moxxy/sdk';
+import { silentLogger } from '../logger.js';
+import { HookDispatcherImpl } from './lifecycle.js';
+
+const sid = asSessionId('s');
+const tid = asTurnId('t');
+
+const appCtx: AppContext = {
+  sessionId: sid,
+  cwd: '/tmp',
+  log: { length: 0, at: () => undefined, slice: () => [], ofType: () => [], byTurn: () => [], toJSON: () => [] },
+  env: {},
+};
+
+const turnCtx: TurnContext = { ...appCtx, turnId: tid, iteration: 0 };
+
+const callCtx: ToolCallContext = {
+  ...turnCtx,
+  call: { callId: asToolCallId('c'), name: 'X', input: {} },
+};
+
+describe('HookDispatcherImpl', () => {
+  it('fires onInit in plugin registration order', async () => {
+    const order: string[] = [];
+    const a = definePlugin({ name: 'a', hooks: { onInit: () => void order.push('a') } });
+    const b = definePlugin({ name: 'b', hooks: { onInit: () => void order.push('b') } });
+    const d = new HookDispatcherImpl({ logger: silentLogger });
+    d.setPlugins([b, a]);
+    await d.dispatchInit(appCtx);
+    expect(order).toEqual(['b', 'a']);
+  });
+
+  it('short-circuits onToolCall on first deny', async () => {
+    const calls: string[] = [];
+    const allow = definePlugin({
+      name: 'allow',
+      hooks: {
+        onToolCall: () => {
+          calls.push('allow');
+          return { action: 'allow' };
+        },
+      },
+    });
+    const deny = definePlugin({
+      name: 'deny',
+      hooks: {
+        onToolCall: () => {
+          calls.push('deny');
+          return { action: 'deny', reason: 'no' };
+        },
+      },
+    });
+    const after = definePlugin({
+      name: 'after',
+      hooks: { onToolCall: () => void calls.push('after') },
+    });
+    const d = new HookDispatcherImpl({ logger: silentLogger });
+    d.setPlugins([allow, deny, after]);
+    const verdict = await d.dispatchToolCall(callCtx);
+    expect(verdict.action).toBe('deny');
+    expect(calls).toEqual(['allow', 'deny']);
+  });
+
+  it('lets a later deny override an earlier rewrite (deny precedence)', async () => {
+    const calls: string[] = [];
+    const rewrite = definePlugin({
+      name: 'rewrite',
+      hooks: {
+        onToolCall: () => {
+          calls.push('rewrite');
+          return { action: 'rewrite', input: { redacted: true } };
+        },
+      },
+    });
+    const deny = definePlugin({
+      name: 'deny',
+      hooks: {
+        onToolCall: () => {
+          calls.push('deny');
+          return { action: 'deny', reason: 'blocked' };
+        },
+      },
+    });
+    const d = new HookDispatcherImpl({ logger: silentLogger });
+    d.setPlugins([rewrite, deny]);
+    const verdict = await d.dispatchToolCall(callCtx);
+    expect(verdict).toEqual({ action: 'deny', reason: 'blocked' });
+    expect(calls).toEqual(['rewrite', 'deny']);
+  });
+
+  it('threads onToolResult through plugins so each sees the prior output', async () => {
+    const baseResult: ToolResultEvent = {
+      id: 'e1' as never,
+      seq: 0,
+      ts: 0,
+      sessionId: sid,
+      turnId: tid,
+      source: 'tool' as never,
+      type: 'tool_result',
+      callId: asToolCallId('c'),
+      ok: true,
+      output: 'raw',
+    };
+    const resultCtx: ToolResultContext = { ...turnCtx, result: baseResult };
+    const seen: unknown[] = [];
+    const a = definePlugin({
+      name: 'a',
+      hooks: {
+        onToolResult: (ctx) => {
+          seen.push(ctx.result.output);
+          return { ...ctx.result, output: `${ctx.result.output as string}-a` };
+        },
+      },
+    });
+    const b = definePlugin({
+      name: 'b',
+      hooks: {
+        onToolResult: (ctx) => {
+          // B must observe A's mutation, not the original.
+          seen.push(ctx.result.output);
+          return { ...ctx.result, output: `${ctx.result.output as string}-b` };
+        },
+      },
+    });
+    const d = new HookDispatcherImpl({ logger: silentLogger });
+    d.setPlugins([a, b]);
+    const final = await d.dispatchToolResult(resultCtx);
+    expect(seen).toEqual(['raw', 'raw-a']);
+    expect(final.output).toBe('raw-a-b');
+  });
+
+  it('pipelines onBeforeProviderCall', async () => {
+    const p1 = definePlugin({
+      name: 'p1',
+      hooks: {
+        onBeforeProviderCall: (req) => ({ ...req, system: (req.system ?? '') + '[p1]' }),
+      },
+    });
+    const p2 = definePlugin({
+      name: 'p2',
+      hooks: {
+        onBeforeProviderCall: (req) => ({ ...req, system: (req.system ?? '') + '[p2]' }),
+      },
+    });
+    const d = new HookDispatcherImpl({ logger: silentLogger });
+    d.setPlugins([p2, p1]);
+    const out = await d.dispatchBeforeProviderCall(
+      { model: 'm', messages: [], system: '' },
+      turnCtx,
+    );
+    expect(out.system).toBe('[p2][p1]');
+  });
+
+  it('hasEventHooks reflects whether any plugin declares onEvent', () => {
+    const d = new HookDispatcherImpl({ logger: silentLogger });
+    expect(d.hasEventHooks()).toBe(false);
+    d.setPlugins([definePlugin({ name: 'noop', hooks: { onInit: () => {} } })]);
+    expect(d.hasEventHooks()).toBe(false);
+    d.setPlugins([definePlugin({ name: 'listener', hooks: { onEvent: () => {} } })]);
+    expect(d.hasEventHooks()).toBe(true);
+  });
+
+  it('logs and continues when a hook throws', async () => {
+    const failed = vi.fn();
+    const bad = definePlugin({
+      name: 'bad',
+      hooks: {
+        onInit: () => {
+          throw new Error('nope');
+        },
+      },
+    });
+    const good = definePlugin({ name: 'good', hooks: { onInit: () => {} } });
+    const d = new HookDispatcherImpl({ logger: silentLogger, onHookFailed: failed });
+    d.setPlugins([bad, good]);
+    await d.dispatchInit(appCtx);
+    expect(failed).toHaveBeenCalledOnce();
+  });
+});

package/src/plugins/lifecycle.ts

@@ -0,0 +1,136 @@
+import type {
+  AppContext,
+  HookDispatcher,
+  LifecycleHooks,
+  MoxxyEvent,
+  Plugin,
+  ProviderRequest,
+  ToolCallContext,
+  ToolCallVerdict,
+  ToolResultContext,
+  ToolResultEvent,
+  TurnContext,
+} from '@moxxy/sdk';
+import type { Logger } from '../logger.js';
+
+export interface DispatcherOptions {
+  readonly hookTimeoutMs?: number;
+  readonly logger: Logger;
+  readonly onHookFailed?: (err: Error, plugin: string, hook: keyof LifecycleHooks) => void;
+}
+
+interface PluginEntry {
+  readonly plugin: Plugin;
+  readonly hooks: LifecycleHooks;
+}
+
+export class HookDispatcherImpl implements HookDispatcher {
+  private entries: PluginEntry[] = [];
+  private readonly timeoutMs: number;
+  private readonly logger: Logger;
+  private readonly onHookFailed?: DispatcherOptions['onHookFailed'];
+
+  constructor(opts: DispatcherOptions) {
+    this.timeoutMs = opts.hookTimeoutMs ?? 5_000;
+    this.logger = opts.logger;
+    this.onHookFailed = opts.onHookFailed;
+  }
+
+  setPlugins(plugins: ReadonlyArray<Plugin>): void {
+    this.entries = plugins.map((plugin) => ({ plugin, hooks: plugin.hooks ?? {} }));
+  }
+
+  /**
+   * Whether any registered plugin declares an `onEvent` hook. Lets the
+   * per-event fan-out skip building an AppContext (which clones the whole
+   * `process.env`) when no plugin would consume it — the common case.
+   */
+  hasEventHooks(): boolean {
+    return this.entries.some((e) => typeof e.hooks.onEvent === 'function');
+  }
+
+  async dispatchInit(ctx: AppContext): Promise<void> {
+    for (const e of this.entries) await this.safe(e, 'onInit', () => e.hooks.onInit?.(ctx));
+  }
+
+  async dispatchTurnStart(ctx: TurnContext): Promise<void> {
+    for (const e of this.entries) await this.safe(e, 'onTurnStart', () => e.hooks.onTurnStart?.(ctx));
+  }
+
+  async dispatchBeforeProviderCall(req: ProviderRequest, ctx: TurnContext): Promise<ProviderRequest> {
+    let current = req;
+    for (const e of this.entries) {
+      const next = await this.safe(e, 'onBeforeProviderCall', () =>
+        e.hooks.onBeforeProviderCall?.(current, ctx),
+      );
+      if (next) current = next;
+    }
+    return current;
+  }
+
+  async dispatchToolCall(ctx: ToolCallContext): Promise<ToolCallVerdict> {
+    let verdict: ToolCallVerdict = { action: 'allow' };
+    for (const e of this.entries) {
+      const next = await this.safe(e, 'onToolCall', () => e.hooks.onToolCall?.(ctx));
+      if (!next) continue;
+      if (next.action === 'deny') return next;
+      if (next.action === 'rewrite') verdict = next;
+    }
+    return verdict;
+  }
+
+  async dispatchToolResult(ctx: ToolResultContext): Promise<ToolResultEvent> {
+    let result = ctx.result;
+    for (const e of this.entries) {
+      const next = await this.safe(e, 'onToolResult', () =>
+        e.hooks.onToolResult?.({ ...ctx, result }),
+      );
+      if (next) result = next;
+    }
+    return result;
+  }
+
+  async dispatchEvent(event: MoxxyEvent, ctx: AppContext): Promise<void> {
+    for (const e of this.entries) {
+      await this.safe(e, 'onEvent', () => e.hooks.onEvent?.(event, ctx));
+    }
+  }
+
+  async dispatchTurnEnd(ctx: TurnContext): Promise<void> {
+    for (const e of this.entries) await this.safe(e, 'onTurnEnd', () => e.hooks.onTurnEnd?.(ctx));
+  }
+
+  async dispatchShutdown(ctx: AppContext): Promise<void> {
+    for (const e of this.entries) await this.safe(e, 'onShutdown', () => e.hooks.onShutdown?.(ctx));
+  }
+
+  private async safe<T>(
+    entry: PluginEntry,
+    hook: keyof LifecycleHooks,
+    fn: () => T | Promise<T> | void | Promise<void>,
+  ): Promise<T | undefined> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const p = Promise.resolve(fn() as Promise<T | undefined | void>);
+      const timeout = new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`Hook ${hook} on ${entry.plugin.name} timed out`)),
+          this.timeoutMs,
+        );
+      });
+      // Attach a no-op rejection handler to the timeout promise so if the
+      // fast path wins, the timer's eventual rejection is swallowed
+      // silently rather than surfacing as an unhandled rejection.
+      timeout.catch(() => undefined);
+      const winner = await Promise.race([p, timeout]);
+      return winner as T | undefined;
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      this.logger.warn('hook failed', { plugin: entry.plugin.name, hook, err: error.message });
+      this.onHookFailed?.(error, entry.plugin.name, hook);
+      return undefined;
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  }
+}