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

package/src/plugins/defaults/{memory-retrieval/injectors.ts → injectors/register.ts}

@@ -47,8 +47,6 @@ import { resolve } from "node:path";
 
 import { getConfig } from "../../../config/loader.js";
 import type { InjectionMatcher } from "../../../context/strip-injections.js";
-import { findConversationOrSubagent } from "../../../daemon/conversation-registry.js";
-import { resolveWorkspaceTopLevelContext } from "../../../daemon/conversation-workspace.js";
 import { readNowScratchpad } from "../../../daemon/now-scratchpad.js";
 import { getInContextPkbPaths } from "../../../daemon/pkb-context-tracker.js";
 import { buildPkbReminder } from "../../../daemon/pkb-reminder-builder.js";
@@ -127,22 +125,12 @@ Then help the user clean up storage. Prefer safe inspection steps first, such as
 Do not work on unrelated tasks until enough space is freed to clear the lock or the user explicitly overrides it. Background processes and messages from trusted contacts are blocked while this cleanup mode is active.
 </disk_pressure_warning>`;
 
-/**
- * `disk-pressure-warning` injector — order 5, prepend-user-tail.
- *
- * Emits the storage cleanup-mode warning at the very top of the user tail when
- * the turn is restricted to disk-pressure cleanup. Reads the cleanup-mode flag
- * off the live `Conversation` looked up by conversation id — the agent loop
- * sets `diskPressureCleanupModeActive` when it classifies the turn's
- * disk-pressure policy — rather than having the loop thread it as an injection
- * input.
- */
 const diskPressureWarningInjector: Injector = {
   name: "disk-pressure-warning",
   order: DEFAULT_INJECTOR_ORDER.diskPressureWarning,
   async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
-    const conversation = findConversationOrSubagent(ctx.conversationId);
-    if (!conversation?.diskPressureCleanupModeActive) return null;
+    const inputs = readInjectionInputs(ctx);
+    if (!inputs.diskPressureContext?.cleanupModeActive) return null;
     return {
       id: "disk-pressure-warning",
       text: DISK_PRESSURE_WARNING_PROMPT,
@@ -162,52 +150,26 @@ function isPkbInjectionSilencedByV2(): boolean {
   return getConfig().memory.v2.enabled;
 }
 
-/**
- * Matchers that mark a persisted `<workspace>` top-level injection. Uses the
- * `{ prefix, suffix }` wrapper shape so user-authored text merely starting with
- * `<workspace>\n` is never mistaken for an injection — matching the full-wrapper
- * requirement the compaction strip uses for this block. The legacy
- * `<workspace_top_level>` tag (pre-rename history) counts as present too.
- */
-const WORKSPACE_BLOCK_MATCHERS: readonly InjectionMatcher[] = [
-  { prefix: "<workspace>\n", suffix: "\n</workspace>" },
-  "<workspace_top_level>",
-];
-
 /**
  * `workspace-context` injector — order 10, prepend-user-tail.
  *
  * Injects the workspace top-level directory context at the very top of the
- * user tail's content so the assistant sees a workspace grounding block before
- * any other per-turn context.
- *
- * Sources the dirty-guarded top-level cache itself via
- * {@link resolveWorkspaceTopLevelContext} (keyed by conversation id) rather than
- * having the agent loop compute and thread it. Decides inject/skip by presence
- * detection: the block is (re)injected only when it is absent from the working
- * messages — true on the first turn and right after compaction strips it — and
- * skipped on normal cached turns where it already persists in history. This
- * keeps the conversation prefix stable for Anthropic's prefix caching.
+ * user tail's content so the assistant sees a workspace grounding block
+ * before any other per-turn context.
  *
  * Gating:
  *  - `mode === "full"` (skipped in minimal mode).
- *  - the rendered workspace context is a non-null, non-empty string.
- *  - no `<workspace>` block is already present in `runMessages`.
+ *  - `workspaceTopLevelContext` is a non-null, non-empty string.
  */
 const workspaceContextInjector: Injector = {
   name: "workspace-context",
   order: DEFAULT_INJECTOR_ORDER.workspaceContext,
-  async produce(
-    ctx: TurnContext,
-    runMessages?: Message[],
-  ): Promise<InjectionBlock | null> {
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
     const inputs = readInjectionInputs(ctx);
     const mode = inputs.mode ?? "full";
     if (mode !== "full") return null;
-    const text = resolveWorkspaceTopLevelContext(ctx.conversationId);
+    const text = inputs.workspaceTopLevelContext;
     if (!text) return null;
-    if (hasInjectedUserTextBlock(runMessages, WORKSPACE_BLOCK_MATCHERS))
-      return null;
     return {
       id: "workspace-context",
       text,

package/src/plugins/defaults/memory-retrieval/hooks/post-compact.ts

@@ -29,7 +29,6 @@ import {
   type RuntimeInjectionOptions,
   type RuntimeInjectionResult,
 } from "../../../../daemon/conversation-runtime-assembly.js";
-import { resolveTrustClass } from "../../../../daemon/trust-context.js";
 import { stripHistoricalWebSearchResults } from "../../../../daemon/web-search-history.js";
 import { getLiveGraphMemory } from "../../../../memory/graph/conversation-graph-memory.js";
 import type { PluginLogger } from "../../../../plugin-api/types.js";
@@ -52,14 +51,15 @@ export interface PostCompactionHookInput {
 /**
  * Everything the hook needs in a single context: the loop-supplied
  * {@link PostCompactionHookInput}, the resolved {@link RuntimeInjectionOptions}
- * (spread top-level so each field stays individually addressable), and a
- * turn-scoped logger. The memory graph handle is not part of this context —
- * the hook sources it internally via {@link getLiveGraphMemory} — and the
- * actor's trust class is derived from {@link PostCompactionHookInput.turnContext}
- * rather than threaded in.
+ * (spread top-level so each field stays individually addressable), and the
+ * conversation-scoped state the options bag cannot carry (actor trust and a
+ * turn-scoped logger). The memory graph handle is not part of this context —
+ * the hook sources it internally via {@link getLiveGraphMemory}.
  */
 export interface PostCompactContext
   extends RuntimeInjectionOptions, PostCompactionHookInput {
+  /** True when the actor for this turn is trusted (guardian-class). */
+  isTrustedActor: boolean;
   /** Turn-scoped logger for diagnostics emitted while re-injecting. */
   logger: PluginLogger;
 }
@@ -67,18 +67,14 @@ export interface PostCompactContext
 export default async function postCompactReinject(
   ctx: PostCompactContext,
 ): Promise<RuntimeInjectionResult> {
-  const { history, logger, ...options } = ctx;
+  const { history, isTrustedActor, logger, ...options } = ctx;
   const result = await applyRuntimeInjections(history, options);
   // Re-track the nodes the memory graph last injected so they survive against
   // the re-injected history. Untrusted actors and minimal-mode turns never
   // received a memory-graph injection, so there is nothing to re-track. The
-  // actor's trust class is derived from the turn's own trust context (the same
-  // value the injector chain resolves), not threaded in from the loop. The
   // live graph handle is looked up from the plugin's own registry by the
   // turn's conversation id — the same instance the turn's retrieval mutated,
   // so re-tracking sees the real cached-node state.
-  const isTrustedActor =
-    resolveTrustClass(options.turnContext?.trust) === "guardian";
   if (isTrustedActor && options.mode !== "minimal") {
     getLiveGraphMemory(
       options.turnContext?.conversationId,

package/src/plugins/defaults/memory-retrieval/injector-chain.ts

@@ -18,9 +18,9 @@
  * ordering assumptions about when `defaultInjectors` finishes initializing.
  */
 
+import { memoryV3Injector } from "../../../memory/v3/shadow-plugin.js";
 import type { Injector } from "../../types.js";
-import { memoryV3Injector } from "../memory-v3-shadow/injector.js";
-import { defaultInjectors } from "./injectors.js";
+import { defaultInjectors } from "../injectors/register.js";
 
 let cachedChain: Injector[] | null = null;
 

package/src/plugins/defaults/overflow-reduce/middlewares/overflowReduce.ts

@@ -0,0 +1,126 @@
+import type { ContextWindowCompactOptions } from "../../../../context/window-manager.js";
+import {
+  createInitialReducerState,
+  reduceContextOverflow,
+  type ReducerState,
+} from "../../../../daemon/context-overflow-reducer.js";
+import type {
+  Middleware,
+  OverflowReduceArgs,
+  OverflowReduceResult,
+} from "../../../types.js";
+
+/**
+ * Default middleware for the `overflowReduce` pipeline — implements the
+ * historical tier-loop semantics (forced compaction, tool-result truncation,
+ * media stubbing, injection downgrade) plus the post-step re-injection /
+ * re-estimation dance.
+ *
+ * The middleware intentionally ignores `next`. Overflow reduction is a
+ * *terminal* behavior: there is no downstream implementation to defer to when
+ * a user-supplied middleware short-circuits. Later plugins may still wrap this
+ * one (outer middleware can observe each reduction iteration via their own
+ * `next` callback) but the default never delegates to a hypothetical base
+ * handler — the inline loop was the base.
+ */
+const defaultOverflowReduceMiddleware: Middleware<
+  OverflowReduceArgs,
+  OverflowReduceResult
+> = async function defaultOverflowReduceMiddleware(args, _next, _ctx) {
+  let messages = args.messages;
+  let runMessages = args.runMessages;
+  let injectionMode: "full" | "minimal" = "full";
+  let reducerState: ReducerState = createInitialReducerState();
+  let reducerCompacted = false;
+  let attempts = 0;
+
+  while (attempts < args.maxAttempts && !reducerState.exhausted) {
+    // Abort check at the top of every iteration. When the pipeline runner
+    // arms a timeout (or the caller aborts externally), `args.abortSignal`
+    // is linked to that trigger via `linkAbortSignal`, so this check lets
+    // us bail out BETWEEN iterations rather than letting another round of
+    // compaction / re-injection mutate `ctx.messages` after the turn has
+    // already failed. Individual `reduceContextOverflow` calls also honor
+    // the signal, but without this gate a fresh iteration could still
+    // start after the signal fires, since the previous one returned
+    // normally before the abort propagated.
+    args.abortSignal?.throwIfAborted();
+
+    attempts++;
+    args.emitActivityState();
+
+    const basisMessages = messages;
+    const step = await reduceContextOverflow(
+      basisMessages,
+      {
+        providerName: args.providerName,
+        systemPrompt: args.systemPrompt,
+        contextWindow: args.contextWindow,
+        targetTokens: args.preflightBudget,
+        toolTokenBudget: args.toolTokenBudget,
+      },
+      reducerState,
+      (msgs, signal, opts: ContextWindowCompactOptions) =>
+        args.compactFn(msgs, signal, opts),
+      args.abortSignal,
+    );
+
+    reducerState = step.state;
+    messages = step.messages;
+    injectionMode = step.state.injectionMode;
+
+    // Per-iteration compaction flag: whether THIS step just produced a
+    // fresh compaction. PKB / NOW re-injection is gated on this — see the
+    // reinjectForMode JSDoc for why the two signals differ.
+    const stepCompacted = step.compactionResult?.compacted === true;
+
+    // Let the orchestrator apply compaction side effects (circuit-breaker
+    // tracking, event emission, ctx mutation) before we re-inject.
+    if (step.compactionResult) {
+      await args.onCompactionResult(step.compactionResult, basisMessages);
+      if (stepCompacted) {
+        reducerCompacted = true;
+      }
+    }
+
+    // Second abort gate — if the side effects or the step itself took us
+    // past the deadline, don't rebuild runMessages or iterate again.
+    args.abortSignal?.throwIfAborted();
+
+    // Rebuild runMessages via the orchestrator-supplied helper (which
+    // re-runs `applyRuntimeInjections` with potentially downgraded mode
+    // and freshly re-hydrated PKB/NOW blocks after compaction). We pass
+    // the current reduced `messages` explicitly so the orchestrator never
+    // has to read from mutable shared state to rebuild runMessages — a
+    // tier that doesn't trigger compaction (tool-result truncation, media
+    // stubbing) won't update `ctx.messages` on its own.
+    //
+    // `stepCompacted` and `reducerCompacted` are both passed so the
+    // orchestrator can gate PKB / NOW re-injection per-iteration while
+    // keeping `slackChronologicalMessages` suppressed once any iteration
+    // has compacted.
+    runMessages = await args.reinjectForMode(
+      messages,
+      injectionMode,
+      stepCompacted,
+      reducerCompacted,
+    );
+
+    // Re-estimate with injections included — `step.estimatedTokens` was
+    // computed on bare history and doesn't account for tokens added by
+    // runtime injections.
+    const postInjectionTokens = args.estimatePostInjection(runMessages);
+    if (postInjectionTokens <= args.preflightBudget) break;
+  }
+
+  return {
+    messages,
+    runMessages,
+    injectionMode,
+    reducerState,
+    reducerCompacted,
+    attempts,
+  };
+};
+
+export default defaultOverflowReduceMiddleware;

package/src/plugins/defaults/overflow-reduce/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-overflow-reduce",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in overflow-reduce pipeline with a passthrough implementation.",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "./register.ts",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "peerDependencies": {
+    "@vellumai/plugin-api": "^0.8.0"
+  }
+}

package/src/plugins/defaults/overflow-reduce/register.ts

@@ -0,0 +1,42 @@
+/**
+ * Default `overflowReduce` plugin — extracted verbatim from the inline
+ * preflight reducer loop that previously lived in
+ * `daemon/conversation-agent-loop.ts` (the `while (preflightAttempts < …)`
+ * block around lines 1045–1156 before PR 23).
+ *
+ * The plugin owns the reducer tier-loop (forced compaction, tool-result
+ * truncation, media stubbing, injection downgrade) and the post-step
+ * re-injection / re-estimation dance. Orchestrator-specific coupling
+ * (activity emission, circuit-breaker tracking, compaction-result
+ * application, runtime injection reassembly) is threaded in through the
+ * callbacks carried on {@link OverflowReduceArgs}; the plugin itself has no
+ * access to the agent-loop context object.
+ *
+ * The forced-compaction tier runs through the orchestrator-supplied
+ * `compactFn`, which routes into the `compaction` plugin pipeline so
+ * registered compaction middleware observes reducer-initiated invocations
+ * alongside the orchestrator-owned call sites. Non-compaction tiers
+ * (tool-result truncation, media stubbing, injection downgrade) remain
+ * in-process: they mutate message arrays directly without crossing a
+ * pipeline boundary. The reducer itself runs under the `overflowReduce`
+ * pipeline, so the full layering is `overflowReduce` → reducer tier loop
+ * → (for the forced-compaction tier only) nested `compaction` pipeline.
+ */
+
+import { type Plugin } from "../../types.js";
+import defaultOverflowReduceMiddleware from "./middlewares/overflowReduce.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * The default plugin registered at bootstrap. No `init`/`onShutdown` —
+ * registering the middleware is the only behavior.
+ */
+export const defaultOverflowReducePlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  middleware: {
+    overflowReduce: defaultOverflowReduceMiddleware,
+  },
+};

package/src/plugins/external-api.ts

@@ -31,8 +31,8 @@
  * absolute paths or workspace-local copies — the TypeScript compiler erases
  * them and they have no module-identity effect at runtime.
  *
- * See `experimental/plugins/README.md` for the full authoring contract and
- * `assistant/examples/plugins/echo/` for a worked example.
+ * See `assistant/docs/plugins.md` for the full authoring contract and
+ * `assistant/examples/plugins/echo/register.ts` for a worked example.
  */
 
 import { assistantEventHub } from "../runtime/assistant-event-hub.js";

package/src/plugins/pipeline.ts

@@ -1,16 +1,297 @@
 /**
- * Plugin hook runner.
+ * Plugin pipeline runner.
  *
- * 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.
+ * 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`.
+ * 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.
  */
 
+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 ────────────────────────────────────────────────────────────
 
@@ -21,6 +302,12 @@ import { getHooksFor } from "./registry.js";
  * 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