@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091853.fbaa2ae

package/src/plugins/external-api.ts

@@ -1,6 +1,16 @@
 /**
  * External plugin runtime — `globalThis.__vellumPluginRuntime` bridge.
  *
+ * ⚠️ DO NOT DELETE THIS AS "UNUSED". There is intentionally NO in-repo consumer:
+ * the consumers are out-of-repo, user-authored workspace plugins under
+ * `<workspaceDir>/plugins/*`, which a repo-wide reference search cannot see. On
+ * a `bun --compile` daemon (the shipped macOS app) this bridge is the ONLY way
+ * such a plugin can reach the daemon's real `assistantEventHub` /
+ * `getSecureKeyAsync` singletons — an absolute-path `import` re-loads a disjoint
+ * copy (see the module-identity note below). Removing it silently breaks every
+ * event-subscribing workspace plugin on the next app rebuild. This was already
+ * removed once on the false "unused" assumption (PR #33825) and restored here.
+ *
  * Workspace-local plugins (`<workspaceDir>/plugins/*`) get dynamic-imported by
  * {@link loadUserPlugins}. They need to call `registerPlugin()` from their
  * module body and they typically also want to read secrets, subscribe to
@@ -31,8 +41,8 @@
  * absolute paths or workspace-local copies — the TypeScript compiler erases
  * them and they have no module-identity effect at runtime.
  *
- * See `assistant/docs/plugins.md` for the full authoring contract and
- * `assistant/examples/plugins/echo/register.ts` for a worked example.
+ * See `experimental/plugins/README.md` for the full authoring contract and
+ * `assistant/examples/plugins/echo/` for a worked example.
  */
 
 import { assistantEventHub } from "../runtime/assistant-event-hub.js";

package/src/plugins/pipeline.ts

@@ -1,297 +1,16 @@
 /**
- * Plugin pipeline runner.
+ * Plugin hook runner.
  *
- * A "pipeline" is a named chain of {@link Middleware}s wrapped around a
- * terminal handler (the original behavior that existed before plugins). The
- * runner composes the chain in onion order, runs it under an optional
- * per-pipeline timeout, and emits one structured log record per invocation
- * covering success, error, and timeout uniformly.
+ * A "hook" is a named lifecycle event (`user-prompt-submit`, `post-tool-use`,
+ * …) that every registered plugin may handle. The runner walks each plugin's
+ * hook for a given event in registration order, threading a context value
+ * through the chain so hooks can observe and transform it.
  *
- * Design doc: `.private/plans/agent-plugin-system.md` (PR 12 notes).
- *
- * Semantics:
- * - Onion composition — the first element of `middlewares` is the outermost
- *   wrapper; it sees the request first and the response last. Terminal runs
- *   in the middle.
- * - Strict-fail — there is NO `try/catch` around user middleware. Errors,
- *   including `PluginTimeoutError` from a breached budget, propagate to the
- *   caller. The `finally` block only handles logging, never error recovery.
- * - Timeout — when `timeoutMs` is a finite number, the invocation races a
- *   timer. A timeout rejection is a `PluginTimeoutError` carrying the
- *   pipeline name, the best-known offending plugin (from `ctx.pluginName`),
- *   and elapsed ms. When `timeoutMs` is `null`/`undefined`, no timer is
- *   armed — pipelines like `compaction` rely on downstream timeouts instead.
+ * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
-import type { Logger } from "pino";
-
 import type { HookName } from "../plugin-api/constants.js";
-import { getLogger } from "../util/logger.js";
 import { getHooksFor } from "./registry.js";
-import {
-  type Middleware,
-  type PipelineName,
-  PluginTimeoutError,
-  type TurnContext,
-} from "./types.js";
-
-const moduleLogger = getLogger("plugin-pipeline");
-
-// ─── Default timeouts ───────────────────────────────────────────────────────
-
-/**
- * Default per-pipeline timeout budgets in milliseconds. A value of `null`
- * means the runner does NOT arm a timer — the pipeline relies on its
- * downstream for budgeting (e.g. `compaction` defers to the provider-level
- * HTTP timeouts of the summary call it wraps).
- *
- * Callers pass the appropriate entry as `runPipeline`'s `timeoutMs` argument.
- * The design doc locks these numbers in; do not tweak without coordinating
- * a design update.
- */
-export const DEFAULT_TIMEOUTS: Record<PipelineName, number | null> = {
-  compaction: null,
-  overflowReduce: null,
-  circuitBreaker: null,
-};
-
-// ─── Composition ────────────────────────────────────────────────────────────
-
-/**
- * Compose an ordered list of {@link Middleware}s around a terminal handler
- * using onion semantics. The first element of `middlewares` is the outermost
- * layer.
- *
- * The returned function accepts `(args, ctx)` and runs the entire chain:
- * ```
- *   middlewares[0] → middlewares[1] → ... → terminal → ... → middlewares[1] → middlewares[0]
- * ```
- *
- * Middlewares that never call `next` short-circuit the chain — the terminal
- * and any deeper middleware are never invoked. Middlewares that throw abort
- * the chain; the error flows back out through any outer middleware unchanged
- * (no internal try/catch).
- */
-export function composeMiddleware<A, R>(
-  middlewares: ReadonlyArray<Middleware<A, R>>,
-  terminal: (args: A) => Promise<R>,
-): (args: A, ctx: TurnContext) => Promise<R> {
-  return (args, ctx) => {
-    // Walk back-to-front, wrapping each middleware around `next`. The last
-    // middleware in the array wraps `terminal`; earlier entries wrap the
-    // accumulated chain so they execute first.
-    let next: (args: A) => Promise<R> = terminal;
-    for (let i = middlewares.length - 1; i >= 0; i--) {
-      const mw = middlewares[i]!;
-      const downstream = next;
-      next = (innerArgs: A) => mw(innerArgs, downstream, ctx);
-    }
-    return next(args);
-  };
-}
-
-// ─── Abort-signal linking ───────────────────────────────────────────────────
-
-/**
- * Return a shallow-cloned `args` object where every `AbortSignal`-typed
- * top-level property is swapped for a signal linked to `internalController`.
- *
- * "Linked" here means: the returned signal aborts when either the caller's
- * original signal aborts OR `internalController` aborts (e.g. the pipeline
- * timer fires). The caller's args are never mutated.
- *
- * When `args` carries no `AbortSignal` property, the original object is
- * returned unchanged — pipelines whose terminals don't consume a signal
- * (e.g. `circuitBreaker`) see identical behavior to before.
- * The return value's `cleanup()` tears down any `addEventListener("abort",
- * ...)` handlers attached to the caller's signal so a pipeline that
- * completes successfully doesn't leak listeners on the caller's controller.
- */
-function linkAbortSignal<A>(
-  args: A,
-  internalController: AbortController,
-): { args: A; cleanup: () => void } {
-  if (args === null || typeof args !== "object") {
-    return { args, cleanup: () => {} };
-  }
-  const abortListeners: Array<{
-    signal: AbortSignal;
-    listener: () => void;
-  }> = [];
-  const record = args as Record<string, unknown>;
-  const patched: Record<string, unknown> = { ...record };
-  let swappedAny = false;
-  for (const key of Object.keys(record)) {
-    const value = record[key];
-    if (value instanceof AbortSignal) {
-      swappedAny = true;
-      if (value.aborted) {
-        // Caller already aborted — propagate immediately so the inner call
-        // sees the abort without waiting for the listener to fire.
-        internalController.abort();
-      } else {
-        const listener = () => internalController.abort();
-        value.addEventListener("abort", listener, { once: true });
-        abortListeners.push({ signal: value, listener });
-      }
-      patched[key] = internalController.signal;
-    }
-  }
-  const cleanup = () => {
-    for (const { signal, listener } of abortListeners) {
-      signal.removeEventListener("abort", listener);
-    }
-  };
-  return { args: (swappedAny ? patched : args) as A, cleanup };
-}
-
-// ─── Runner ─────────────────────────────────────────────────────────────────
-
-type PipelineLogRecord = {
-  event: "plugin.pipeline";
-  pipeline: PipelineName;
-  chain: ReadonlyArray<string>;
-  durationMs: number;
-  outcome: "success" | "error" | "timeout";
-  pluginName?: string;
-  errorName?: string;
-  errorMessage?: string;
-  errorStack?: string;
-  timeoutMs?: number;
-  requestId: string;
-  conversationId: string;
-  turnIndex?: number;
-};
-
-/**
- * Best-effort detection of a pino-compatible logger on the `TurnContext`.
- *
- * `TurnContext` intentionally doesn't require a logger slot — most code paths
- * use the module-level logger. Some callers (notably plugin-scoped pipelines
- * in later PRs) may attach a child logger via `(ctx as any).logger`. We type
- * the field loosely to avoid coupling `TurnContext` to pino.
- */
-function selectLogger(ctx: TurnContext): Logger {
-  const maybe = (ctx as { logger?: unknown }).logger;
-  if (maybe && typeof maybe === "object" && "info" in maybe) {
-    return maybe as Logger;
-  }
-  return moduleLogger;
-}
-
-/**
- * Execute a named pipeline: compose middleware, run it under an optional
- * timeout, and emit one structured log record covering success, error, or
- * timeout uniformly.
- *
- * @param name        The pipeline identifier. Used for telemetry and error
- *                    attribution.
- * @param middlewares Ordered list of middlewares to wrap around `terminal`.
- *                    Names for the log `chain` are pulled from `Function.name`
- *                    (empty strings are kept so length always matches).
- * @param terminal    The original behavior. Runs when all middlewares call
- *                    `next`.
- * @param args        Pipeline-specific input payload.
- * @param ctx         Per-turn context. May carry an optional `logger` slot;
- *                    otherwise the module logger is used.
- * @param timeoutMs   Deadline in milliseconds. `null`/`undefined` disables
- *                    the timer entirely (inherits downstream timeouts).
- *
- * @throws {PluginTimeoutError} When `timeoutMs` is non-null and the chain
- *         exceeds the budget. `ctx.pluginName` (if set) is attached as the
- *         offending plugin.
- * @throws Any error produced by user middleware or the terminal — flows
- *         through unchanged.
- */
-export async function runPipeline<A, R>(
-  name: PipelineName,
-  middlewares: ReadonlyArray<Middleware<A, R>>,
-  terminal: (args: A) => Promise<R>,
-  args: A,
-  ctx: TurnContext,
-  timeoutMs?: number | null,
-): Promise<R> {
-  const logger = selectLogger(ctx);
-  const chain = middlewares.map((m) => m.name || "anonymous");
-  const composed = composeMiddleware(middlewares, terminal);
-  const start = performance.now();
-
-  let outcome: "success" | "error" | "timeout" = "success";
-  let thrown: unknown = undefined;
-  let timer: ReturnType<typeof setTimeout> | undefined;
-
-  try {
-    if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
-      const budget = timeoutMs;
-      // Internal controller: fires on either (a) the timer, so the inner call
-      // actually observes the budget breach instead of running forever after
-      // `Promise.race` rejects; or (b) the caller's own signal, so external
-      // cancellation still reaches the inner call transparently. Any
-      // `AbortSignal`-typed property on `args` (e.g. `signal` on
-      // `CompactionArgs`, `abortSignal` on `OverflowReduceArgs`) is swapped
-      // for this linked signal on a shallow-cloned args object — we never
-      // mutate the caller's args.
-      const internalController = new AbortController();
-      const { args: effectiveArgs, cleanup } = linkAbortSignal(
-        args,
-        internalController,
-      );
-      const timeoutPromise = new Promise<never>((_resolve, reject) => {
-        timer = setTimeout(() => {
-          internalController.abort();
-          reject(
-            new PluginTimeoutError(
-              name,
-              ctx.pluginName,
-              Math.round(performance.now() - start),
-            ),
-          );
-        }, budget);
-      });
-      try {
-        return await Promise.race([
-          composed(effectiveArgs, ctx),
-          timeoutPromise,
-        ]);
-      } finally {
-        cleanup();
-      }
-    }
-    return await composed(args, ctx);
-  } catch (err) {
-    thrown = err;
-    outcome = err instanceof PluginTimeoutError ? "timeout" : "error";
-    throw err;
-  } finally {
-    if (timer !== undefined) clearTimeout(timer);
-    const durationMs = Math.round(performance.now() - start);
-    const record: PipelineLogRecord = {
-      event: "plugin.pipeline",
-      pipeline: name,
-      chain,
-      durationMs,
-      outcome,
-      requestId: ctx.requestId,
-      conversationId: ctx.conversationId,
-    };
-    if (ctx.turnIndex !== undefined) record.turnIndex = ctx.turnIndex;
-    if (ctx.pluginName !== undefined) record.pluginName = ctx.pluginName;
-    if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
-      record.timeoutMs = timeoutMs;
-    }
-    if (thrown !== undefined) {
-      if (thrown instanceof Error) {
-        record.errorName = thrown.name;
-        record.errorMessage = thrown.message;
-        if (thrown.stack) record.errorStack = thrown.stack;
-      } else {
-        record.errorName = "NonError";
-        record.errorMessage = String(thrown);
-      }
-    }
-    logger.info(record, "plugin.pipeline");
-  }
-}
 
 // ─── Hook runner ────────────────────────────────────────────────────────────
 
@@ -302,12 +21,6 @@ export async function runPipeline<A, R>(
  * that replaces the threaded value for subsequent hooks. The final context
  * after the chain settles is returned.
  *
- * `runHook` is the hook-side counterpart to {@link runPipeline}:
- * `runPipeline` composes middleware around a terminal handler for stateful
- * request/response pipelines (compaction, overflow reduction, etc.);
- * `runHook` walks ordered hook functions for declarative chain-style
- * context transformations (`user-prompt-submit`, `post-tool-use`).
- *
  * @param name        The hook identifier — pick one from {@link HOOKS}.
  * @param initialCtx  Context the first hook receives.
  * @returns The final context after the chain settles. Same reference as

package/src/plugins/registry.ts

@@ -10,20 +10,16 @@
  * late-arriving registrations.
  *
  * Registration is order-preserving: {@link getRegisteredPlugins} and
- * {@link getMiddlewaresFor} reflect the order in which {@link registerPlugin}
- * was called, which in turn determines onion order for middleware composition
- * in the pipeline runner.
+ * {@link getHooksFor} reflect the order in which {@link registerPlugin} was
+ * called, which in turn determines the order plugin hooks run.
  *
  * This module does not call `Plugin.init()` — that is the job of the
- * bootstrap (see PR 14). It also does not wire the registry into the daemon;
- * later PRs introduce consumers.
+ * bootstrap. It also does not wire the registry into the daemon.
  *
- * Design doc: `.private/plans/agent-plugin-system.md` (PR 13).
+ * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
 import {
-  type PipelineMiddlewareMap,
-  type PipelineName,
   type Plugin,
   PluginExecutionError,
   type PluginHookFn,
@@ -33,7 +29,7 @@ import {
 
 /**
  * Registered plugins keyed by `manifest.name`. A `Map` preserves insertion
- * order, which the registry relies on for middleware composition and
+ * order, which the registry relies on for hook ordering and
  * `getRegisteredPlugins()` output.
  */
 const registeredPlugins = new Map<string, Plugin>();
@@ -46,8 +42,7 @@ 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 to `getMiddlewaresFor()` with its
- * `init()` hook never invoked.
+ * plugin visible in the registry with its `init()` hook never invoked.
  */
 let registrationClosed = false;
 
@@ -66,7 +61,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 (PR 14).
+ * runs in the bootstrap sequence.
  */
 export function registerPlugin(plugin: Plugin): void {
   // Basic shape / required-field validation. The type system already enforces
@@ -143,27 +138,6 @@ 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
@@ -208,10 +182,8 @@ 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
- * {@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.
+ * after {@link Plugin.onShutdown} and contribution teardown have run, so the
+ * registry no longer exposes a plugin whose `init()` aborted mid-bootstrap.
  * Safe to call on an already-absent name (no-op).
  */
 export function unregisterPlugin(name: string): void {