@vellumai/assistant 0.6.4 → 0.6.6

package/src/plugins/pipeline.ts

@@ -0,0 +1,316 @@
+/**
+ * Plugin pipeline 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.
+ *
+ * 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 `llmCall` and `toolExecute` rely on downstream
+ *   timeouts instead.
+ */
+
+import type { Logger } from "pino";
+
+import { getLogger } from "../util/logger.js";
+import {
+  type Middleware,
+  type PipelineName,
+  PluginTimeoutError,
+  type TurnContext,
+} from "./types.js";
+
+// Side-effect import: register every first-party default plugin at module
+// load so downstream consumers (production bootstrap AND tests that skip
+// `bootstrapPlugins()`) observe a fully-populated registry by default.
+// Every code path that calls `runPipeline` imports this module, so by the
+// time the first pipeline runs the defaults are already in place. User
+// plugins load via `loadUserPlugins()` inside `bootstrapPlugins()` (which
+// runs AFTER all static side-effect imports), so the onion ordering
+// (defaults inner, user middleware outer) across all 14 pipelines is
+// preserved in production.
+import "./defaults/index.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. `llmCall` defers to provider-level HTTP
+ * timeouts; `toolExecute` defers to the per-tool timeout already enforced
+ * by `ToolExecutor`).
+ *
+ * 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> = {
+  turn: null,
+  llmCall: null,
+  toolExecute: null,
+  memoryRetrieval: null,
+  historyRepair: null,
+  tokenEstimate: null,
+  compaction: null,
+  overflowReduce: null,
+  persistence: null,
+  titleGenerate: null,
+  toolResultTruncate: null,
+  emptyResponse: null,
+  toolError: 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. `persistence`, `tokenEstimate`) 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");
+  }
+}

package/src/plugins/plugin-skill-contributions.ts

@@ -0,0 +1,292 @@
+/**
+ * In-memory registry of plugin-contributed skills.
+ *
+ * Plugins with `manifest.skills` (or {@link Plugin.skills}) declared in their
+ * {@link PluginSkillRegistration} list get their entries indexed here during
+ * bootstrap (PR 14 -> PR 33). {@link loadSkillCatalog} in
+ * `config/skills.ts` merges these entries into the regular catalog so the
+ * model's `skill_load` / `skill_execute` flow can resolve them under
+ * `source: "plugin"`.
+ *
+ * ## Ref-counted lifecycle
+ *
+ * Registration is per-plugin — a plugin declares zero or more skills and the
+ * registry stores them keyed by plugin name. Several tests and hot-reload
+ * flows may call {@link registerPluginSkills} more than once for the same
+ * plugin (same skills, same body). Each call bumps a reference counter;
+ * {@link unregisterPluginSkills} decrements it and only tears the entry down
+ * when the counter reaches zero. This mirrors the ref-counted teardown
+ * semantics of `registerSkillTools` / `unregisterSkillTools` in the tool
+ * registry, so the plugin layer's lifecycle matches the skill layer's.
+ *
+ * Collision rules:
+ *
+ * - A plugin cannot register two skills with the same id in a single call —
+ *   the duplicate is rejected at registration time.
+ * - Two different plugins cannot contribute skills with the same id. The
+ *   second registration throws so the operator notices, rather than silently
+ *   shadowing the first plugin's contribution.
+ * - The catalog merge logic in {@link loadSkillCatalog} decides how plugin
+ *   skills interact with filesystem skills (bundled/managed/workspace) —
+ *   this module just owns the in-memory set.
+ */
+
+import type {
+  SkillDefinition,
+  SkillSummary,
+  SkillToolManifestMeta,
+} from "../config/skills.js";
+import { getLogger } from "../util/logger.js";
+import { PluginExecutionError, type PluginSkillRegistration } from "./types.js";
+
+// This module imports ONLY types from `config/skills.js`. `config/skills.ts`
+// in turn imports values from here to merge plugin-contributed skills into
+// the catalog output. TypeScript / ESM handles the type-only edge of the
+// cycle cleanly; converting any of the imports above to value imports would
+// introduce a runtime cycle and a load-order hazard with `loadSkillCatalog`.
+
+const log = getLogger("plugin-skills");
+
+/**
+ * Virtual directory path prefix for plugin-contributed skills. `SkillSummary`
+ * requires a `directoryPath` — plugin skills aren't on disk, so we synthesize
+ * a stable, recognizable path that encodes the plugin name. Downstream code
+ * that reads from disk (inline-command rendering, reference-file listing,
+ * icon caching) gates on `source` so these paths are never stat'd.
+ */
+const PLUGIN_VIRTUAL_PATH_PREFIX = "<plugin>/";
+
+/**
+ * One stored plugin skill. Keeps the original registration for re-exposure
+ * and a pre-built {@link SkillDefinition} so the catalog / loader paths can
+ * return summary/definition objects without re-synthesizing them on every
+ * lookup.
+ */
+interface StoredPluginSkill {
+  /** Name of the plugin that contributed the skill. */
+  pluginName: string;
+  /** Pre-built definition (includes the body) returned to `skill_load`. */
+  definition: SkillDefinition;
+}
+
+/** All skills contributed by plugins, keyed by skill id. */
+const pluginSkillsById = new Map<string, StoredPluginSkill>();
+
+/**
+ * Ref-count of active registrations per plugin name. Bumped on
+ * {@link registerPluginSkills}, decremented on {@link unregisterPluginSkills}.
+ * Only when the counter hits zero do we actually remove the plugin's
+ * contributed skills from {@link pluginSkillsById}.
+ */
+const pluginRefCount = new Map<string, number>();
+
+/**
+ * Skill-id -> owning plugin name. Maintained alongside
+ * {@link pluginSkillsById} so {@link unregisterPluginSkills} can drop exactly
+ * the entries the plugin owns without scanning the full id map.
+ */
+const pluginSkillIdsByPlugin = new Map<string, Set<string>>();
+
+/**
+ * Build the {@link SkillDefinition} object that {@link loadSkillCatalog} and
+ * {@link loadSkillBySelector} hand back to consumers. Kept in one place so
+ * summary and definition stay in lockstep — any field added to
+ * {@link PluginSkillRegistration} shows up in both.
+ */
+function buildDefinition(
+  pluginName: string,
+  reg: PluginSkillRegistration,
+): SkillDefinition {
+  // Synthetic directory path. Using a non-filesystem prefix keeps the path
+  // recognizable in logs while preventing accidental `fs.existsSync` loops
+  // elsewhere in the catalog (all such loops live behind source !== "plugin"
+  // guards).
+  const directoryPath = `${PLUGIN_VIRTUAL_PATH_PREFIX}${pluginName}/${reg.id}`;
+  const skillFilePath = `${directoryPath}/SKILL.md`;
+
+  // toolManifest stays undefined for plugin skills — plugin tool contributions
+  // flow through `Plugin.tools` (PR 31), not through a synthetic TOOLS.json.
+  const toolManifest: SkillToolManifestMeta | undefined = undefined;
+
+  return {
+    id: reg.id,
+    name: reg.name,
+    displayName: reg.displayName ?? reg.name,
+    description: reg.description,
+    directoryPath,
+    skillFilePath,
+    body: reg.body,
+    emoji: reg.emoji,
+    source: "plugin",
+    toolManifest,
+    includes: reg.includes,
+    featureFlag: reg.featureFlag,
+    activationHints: reg.activationHints,
+    avoidWhen: reg.avoidWhen,
+    // Plugin skills do not support inline command expansion in this PR.
+    inlineCommandExpansions: undefined,
+  };
+}
+
+/**
+ * Register every skill declared by a plugin's `Plugin.skills` list.
+ *
+ * Must be called after the plugin's `init()` completes successfully (see
+ * `external-plugins-bootstrap.ts`). Throws {@link PluginExecutionError} if a
+ * skill id collides with another plugin's skill or with an id already
+ * registered in an earlier successful registration from the same plugin
+ * that hasn't been torn down.
+ *
+ * Ref-count semantics: each call bumps the plugin-level ref counter.
+ * Duplicate registrations of the *same* plugin's skills are accepted and
+ * treated as a no-op past the first call — the second invocation increments
+ * the counter without re-inserting entries.
+ */
+export function registerPluginSkills(
+  pluginName: string,
+  skills: readonly PluginSkillRegistration[],
+): void {
+  const currentCount = pluginRefCount.get(pluginName) ?? 0;
+
+  if (currentCount > 0) {
+    // The plugin already has skills registered — bump the counter without
+    // re-adding. Duplicate register calls for the same plugin are legitimate
+    // (hot-reload, re-bootstrap) so we accept them rather than throw.
+    pluginRefCount.set(pluginName, currentCount + 1);
+    log.debug(
+      { pluginName, refCount: currentCount + 1 },
+      "Bumped plugin-skills ref count (skills kept)",
+    );
+    return;
+  }
+
+  // First-time registration for this plugin — validate and insert.
+  //
+  // We validate intra-batch uniqueness first so a plugin that accidentally
+  // declares the same skill twice gets a clear error at registration,
+  // rather than the second declaration silently overwriting the first
+  // inside the map.
+  const seenInBatch = new Set<string>();
+  for (const reg of skills) {
+    if (seenInBatch.has(reg.id)) {
+      throw new PluginExecutionError(
+        `plugin ${pluginName} declared skill "${reg.id}" more than once`,
+        pluginName,
+      );
+    }
+    seenInBatch.add(reg.id);
+
+    const existing = pluginSkillsById.get(reg.id);
+    if (existing) {
+      throw new PluginExecutionError(
+        `plugin ${pluginName} cannot contribute skill "${reg.id}" — ` +
+          `already registered by plugin "${existing.pluginName}"`,
+        pluginName,
+      );
+    }
+  }
+
+  const ownedIds = new Set<string>();
+  for (const reg of skills) {
+    pluginSkillsById.set(reg.id, {
+      pluginName,
+      definition: buildDefinition(pluginName, reg),
+    });
+    ownedIds.add(reg.id);
+    log.info({ pluginName, skillId: reg.id }, "Plugin skill registered");
+  }
+
+  pluginSkillIdsByPlugin.set(pluginName, ownedIds);
+  pluginRefCount.set(pluginName, 1);
+}
+
+/**
+ * Decrement the ref count for a plugin's skills. When the count hits zero
+ * the plugin's contributed skills are removed from the in-memory catalog.
+ *
+ * Idempotent — calling on a plugin that was never registered is a no-op
+ * (logged at debug level).
+ */
+export function unregisterPluginSkills(pluginName: string): void {
+  const current = pluginRefCount.get(pluginName) ?? 0;
+  if (current === 0) {
+    log.debug(
+      { pluginName },
+      "unregisterPluginSkills called on unregistered plugin (no-op)",
+    );
+    return;
+  }
+
+  if (current > 1) {
+    pluginRefCount.set(pluginName, current - 1);
+    log.info(
+      { pluginName, remaining: current - 1 },
+      "Decremented plugin-skills ref count, skills kept",
+    );
+    return;
+  }
+
+  // Last reference — actually remove the skills.
+  pluginRefCount.delete(pluginName);
+  const ownedIds = pluginSkillIdsByPlugin.get(pluginName);
+  if (ownedIds) {
+    for (const id of ownedIds) {
+      pluginSkillsById.delete(id);
+      log.info({ pluginName, skillId: id }, "Plugin skill unregistered");
+    }
+    pluginSkillIdsByPlugin.delete(pluginName);
+  }
+}
+
+/**
+ * Return a shallow-copied list of {@link SkillSummary} entries for every
+ * plugin-contributed skill. Consumers (the catalog loader) treat the return
+ * value as a read-only snapshot — mutating it does not mutate the registry.
+ */
+export function getPluginContributedSkillSummaries(): SkillSummary[] {
+  const out: SkillSummary[] = [];
+  for (const stored of pluginSkillsById.values()) {
+    // Strip `body` so we hand out a SkillSummary, not a SkillDefinition —
+    // the catalog merge function in config/skills.ts pushes summaries.
+    const { body: _body, ...summary } = stored.definition;
+    out.push(summary);
+  }
+  return out;
+}
+
+/**
+ * Look up the full {@link SkillDefinition} for a plugin-contributed skill by
+ * id. Used by the catalog loader to satisfy `skill_load` without a disk
+ * read.
+ */
+export function getPluginContributedSkillDefinition(
+  skillId: string,
+): SkillDefinition | undefined {
+  return pluginSkillsById.get(skillId)?.definition;
+}
+
+/**
+ * Return the current ref count for a plugin's skills. Exposed for tests.
+ */
+export function getPluginSkillRefCount(pluginName: string): number {
+  return pluginRefCount.get(pluginName) ?? 0;
+}
+
+/**
+ * Clear every registered plugin skill. Test-only — throws when invoked
+ * outside a test environment. Guard mirrors
+ * {@link resetPluginRegistryForTests}.
+ */
+export function resetPluginSkillContributionsForTests(): void {
+  const isTest =
+    process.env.BUN_TEST === "1" || process.env.NODE_ENV === "test";
+  if (!isTest) {
+    throw new PluginExecutionError(
+      "resetPluginSkillContributionsForTests may only be called in test environments",
+      undefined,
+    );
+  }
+  pluginSkillsById.clear();
+  pluginRefCount.clear();
+  pluginSkillIdsByPlugin.clear();
+}