@vellumai/assistant 0.8.6 → 0.8.7-dev.202606052118.34cd356

package/src/plugins/types.ts

@@ -7,7 +7,7 @@
  * placeholders) and add the pipeline runner, registry, and bootstrap.
  *
  * The assistant composes behavior around a small set of named pipelines
- * (`turn`, `llmCall`, `toolExecute`, ...). Each plugin may contribute one
+ * (`compaction`). Each plugin may contribute one
  * {@link Middleware} per pipeline; the registry composes them in onion
  * order at runtime. Plugins may also contribute {@link Injector}s that emit
  * system-prompt-time content, as well as model-visible capabilities
@@ -16,38 +16,21 @@
  * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
-import type { ContextWindowConfig } from "../config/schemas/inference.js";
+import type { CompactionCircuitClosedEvent } from "../api/events/compaction-circuit-closed.js";
+import type { CompactionCircuitOpenEvent } from "../api/events/compaction-circuit-open.js";
+import type { LLMCallSite } from "../config/schemas/llm.js";
+import type { ContextWindowManager } from "../context/window-manager.js";
 import type {
-  ContextWindowManager,
-  ContextWindowResult,
-} from "../context/window-manager.js";
-import type { ReducerState } from "../daemon/context-overflow-reducer.js";
-import type {
-  ActiveSurfaceContext,
   ChannelCapabilities,
   ChannelCommandContext,
   InjectionMode,
 } from "../daemon/conversation-runtime-assembly.js";
-import type { RepairResult } from "../daemon/history-repair.js";
-import type { ServerMessage } from "../daemon/message-protocol.js";
-import type { PkbContextConversation } from "../daemon/pkb-context-tracker.js";
 import type { TrustContext } from "../daemon/trust-context.js";
-import type { MessageRole } from "../memory/conversation-crud.js";
-import type { QdrantSparseVector } from "../memory/qdrant-client.js";
-import type {
-  ContentBlock,
-  Message,
-  Provider,
-  ProviderResponse,
-  SendMessageOptions,
-  ToolDefinition,
-} from "../providers/types.js";
+import type { ConversationGraphMemory } from "../memory/graph/conversation-graph-memory.js";
+import type { PluginHookFn } from "../plugin-api/types.js";
+import type { Message } from "../providers/types.js";
 import type { SkillRoute } from "../runtime/skill-route-registry.js";
-import type {
-  LoadedTool,
-  ToolContext,
-  ToolExecutionResult,
-} from "../tools/types.js";
+import type { Tool } from "../tools/types.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
 
 // ─── Manifest ────────────────────────────────────────────────────────────────
@@ -89,11 +72,12 @@ export interface PluginManifest {
   config?: unknown;
 }
 
-// ─── Init / Shutdown context ─────────────────────────────────────────────────
-// Public types — defined in `assistant/src/plugin-api/types.ts` and re-exported
-// here so existing internal call sites keep working. Plugin authors will
-// import these from `@vellumai/plugin-api` once that package is published.
+// ─── Public plugin-API types ─────────────────────────────────────────────────
+// Defined in `assistant/src/plugin-api/types.ts` and re-exported here so
+// existing internal call sites keep working. Plugin authors import these from
+// `@vellumai/plugin-api`.
 export type {
+  PluginHookFn,
   PluginInitContext,
   PluginShutdownContext,
 } from "../plugin-api/types.js";
@@ -118,181 +102,22 @@ export type Middleware<A, R> = (
  * Exhaustive list of pipeline slot names. New pipelines must be added here
  * and in `DEFAULT_TIMEOUTS` (PR 12). The registry only understands these.
  */
-export type PipelineName =
-  | "turn"
-  | "llmCall"
-  | "toolExecute"
-  | "memoryRetrieval"
-  | "historyRepair"
-  | "tokenEstimate"
-  | "compaction"
-  | "overflowReduce"
-  | "persistence"
-  | "titleGenerate"
-  | "toolResultTruncate"
-  | "emptyResponse"
-  | "toolError"
-  | "circuitBreaker";
+export type PipelineName = "compaction";
 
 // ─── Per-pipeline args / results (placeholder shapes) ────────────────────────
 // Concrete field-level types land in M2/M3 PRs as each pipeline is wrapped.
 // Until then we expose `unknown`-tagged aliases so downstream code can name
 // the types without depending on unstable internal shapes.
 
-export type TurnArgs = { readonly input: unknown };
-export type TurnResult = { readonly output: unknown };
-
-/**
- * Pipeline arguments for `llmCall` — mirrors the inputs to
- * {@link Provider.sendMessage}. The terminal handler (the default plugin)
- * delegates straight to `args.provider.sendMessage(args.messages, args.tools,
- * args.systemPrompt, args.options)`; middleware may observe or rewrite any
- * field before that call, short-circuit with a synthetic {@link LLMCallResult},
- * or post-process the response on the way out.
- *
- * `provider` is passed in `args` (rather than resolved from the runtime) so
- * middleware can swap it deterministically per-call. `options` carries the
- * full `SendMessageOptions` bag — `config`, `onEvent`, and `signal` — so
- * middleware can substitute streaming handlers or cancellation signals
- * without reconstructing them.
- */
-export type LLMCallArgs = {
-  readonly provider: Provider;
-  readonly messages: Message[];
-  readonly tools?: ToolDefinition[];
-  readonly systemPrompt?: string;
-  readonly options?: SendMessageOptions;
-};
-export type LLMCallResult = ProviderResponse;
-
-/**
- * Arguments passed to the `toolExecute` pipeline — mirrors the public
- * {@link ToolExecutor.execute} signature so middleware can observe (and
- * mutate) the tool name, input payload, and the full {@link ToolContext}
- * before the terminal runs the actual execution.
- */
-export interface ToolExecuteArgs {
-  readonly name: string;
-  readonly input: Record<string, unknown>;
-  readonly context: ToolContext;
-}
-
-/**
- * Result returned from the `toolExecute` pipeline — identical to
- * {@link ToolExecutionResult} so short-circuit middleware can supply a
- * synthetic result without invoking the terminal.
- */
-export type ToolExecuteResult = ToolExecutionResult;
-
 /**
- * A single retrieved memory artifact.
- *
- * The memory-graph retriever emits complex, tightly-coupled state (content
- * blocks, query vectors, metrics, events, etc.) that downstream code in the
- * agent loop consumes holistically. Representing each memory-graph output as
- * an opaque `MemoryBlock` lets plugins swap in completely different shapes
- * (custom retrievers, mocks for testing) without requiring the plugin surface
- * to re-declare the graph result schema here. Refined by consumers via
- * runtime narrowing — the default retriever attaches a structural marker so
- * the agent loop can safely unwrap its own output.
+ * Full output of a single memory-graph retrieval — the object returned by
+ * {@link ConversationGraphMemory.prepareMemory} (injected messages, query
+ * vectors, metrics). The agent loop consumes these fields directly to drive
+ * PKB hint search and runtime injection.
  */
-export type MemoryBlock = unknown;
-
-/**
- * Inputs to the memory-retrieval pipeline. The pipeline takes only
- * identifiers and the trust context — the actual data sources (PKB files,
- * NOW.md, memory graph) are side-effectful and read by the terminal.
- *
- * `signal` is the per-turn abort signal forwarded to the memory graph's
- * `prepareMemory` call. Carrying it on `args` (rather than on the
- * `DefaultMemoryRetrievalDeps` extra-state bundle) is load-bearing: the
- * pipeline runner's `linkAbortSignal` swaps any `AbortSignal`-typed
- * property on top-level args for an internal linked signal, so a plugin
- * timeout (or external cancel) actually reaches `prepareMemory` and cancels
- * the underlying retrieval instead of letting it run to completion after
- * the pipeline has already errored.
- */
-export interface MemoryArgs {
-  readonly conversationId: string;
-  readonly trustContext: TrustContext | undefined;
-  readonly turnIndex: number;
-  readonly signal: AbortSignal;
-}
-
-/**
- * Outputs of the memory-retrieval pipeline.
- *
- * - `pkbContent` / `nowContent`: trimmed file contents ready for injection,
- *   or `null` when the file is missing/empty.
- * - `memoryGraphBlocks`: zero or one memory-graph retrievals (the default
- *   retriever yields exactly one when the actor is trusted and the graph
- *   produced output, zero otherwise). Multi-entry arrays are reserved for
- *   future multi-source retrievers; the current agent loop consumes only
- *   the first entry.
- */
-export interface MemoryResult {
-  readonly pkbContent: string | null;
-  readonly nowContent: string | null;
-  readonly memoryGraphBlocks: ReadonlyArray<MemoryBlock>;
-}
-
-/**
- * Arguments for the `historyRepair` pipeline. `history` is the pre-repair
- * message list scheduled for the next provider call; `provider` is the
- * downstream provider key (`ctx.provider.name`) so plugins that want to
- * special-case repair per provider can discriminate without looking up the
- * ambient provider from `TurnContext`.
- *
- * The pipeline currently wraps only the standard pre-run repair pass
- * (`repairHistory`). The orchestrator's one-shot deep-repair fallback
- * (`deepRepairHistory`), invoked only after a provider ordering error,
- * remains a direct call. Adding a `mode` discriminator here would be
- * premature — deep-repair has no known plugin-level consumer yet.
- */
-export type HistoryRepairArgs = {
-  readonly history: Message[];
-  readonly provider: string;
-};
-
-/**
- * Result of the `historyRepair` pipeline. Carries both the repaired message
- * list and the `RepairStats` record the orchestrator logs when any repair
- * happened — the default plugin forwards the shape unchanged from
- * {@link repairHistory}.
- */
-export type HistoryRepairResult = RepairResult;
-
-/**
- * Inputs to the `tokenEstimate` pipeline. The default middleware delegates
- * these straight to {@link estimatePromptTokensRaw}; custom plugins may
- * substitute an alternate estimator (e.g. provider-native tokenization) by
- * short-circuiting the pipeline with their own {@link EstimateResult}.
- *
- * Fields:
- * - `history` — current message list to estimate over.
- * - `systemPrompt` — system prompt string, or `undefined` when absent.
- * - `tools` — tool definitions visible on this turn. The default plugin
- *   sums their token budget via `estimateToolsTokens(tools)` and hands the
- *   result to the raw estimator via `toolTokenBudget`. Plugins that want to
- *   ignore tool cost can skip that term.
- * - `providerName` — canonical calibration provider key (the value returned
- *   by `getCalibrationProviderKey(provider)`). Drives provider-specific
- *   heuristics inside the raw estimator (e.g. Anthropic image sizing).
- */
-export type EstimateArgs = {
-  readonly history: Message[];
-  readonly systemPrompt: string | undefined;
-  readonly tools: ToolDefinition[];
-  readonly providerName: string | undefined;
-};
-
-/** Result of the `tokenEstimate` pipeline — total estimated prompt tokens. */
-export type EstimateResult = number;
-
-/** Alias retained for symmetry with the rest of the pipeline-name family. */
-export type TokenEstimateArgs = EstimateArgs;
-/** Alias retained for symmetry with the rest of the pipeline-name family. */
-export type TokenEstimateResult = EstimateResult;
+export type GraphMemoryResult = Awaited<
+  ReturnType<ConversationGraphMemory["prepareMemory"]>
+>;
 
 /**
  * Pipeline inputs for the `compaction` slot — the arguments the assistant
@@ -322,440 +147,15 @@ export type CompactionArgs = {
 export type CompactionResult = unknown;
 
 /**
- * Input to the `overflowReduce` pipeline. Captures everything the reducer
- * tier loop needs, including the message history, reducer configuration,
- * and side-effect callbacks that bridge the pipeline back to the orchestrator's
- * mutable per-turn state (context-window manager, activity emitter, runtime
- * injection reassembly, memory reinjection).
- *
- * The callbacks are supplied by the orchestrator because the reducer loop
- * needs to coordinate with state that lives on the `AgentLoopConversationContext`
- * (message mutation, compaction event emission, circuit breaker tracking,
- * injection block reassembly). Keeping them as explicit callbacks — rather
- * than pulling the whole context into the pipeline — preserves the rule that
- * `TurnContext` stays minimal and pipeline-agnostic.
+ * The complete set of compaction circuit-breaker transition events:
+ * `compaction_circuit_open` when the breaker trips and `compaction_circuit_closed`
+ * on the open→closed transition. Both are a subset of `ServerMessage`, so any
+ * existing `ServerMessage` sink remains assignable to a
+ * `(msg: CompactionCircuitEvent) => void` parameter.
  */
-export interface OverflowReduceArgs {
-  /** Bare persisted message history (mutable copy — the default middleware
-   *  applies reducer results in-place via the `applyMessages` callback). */
-  readonly messages: Message[];
-  /** Current run-time message array with runtime injections applied. */
-  readonly runMessages: Message[];
-  /** System prompt used for post-step token estimation. */
-  readonly systemPrompt: string;
-  /** Provider name used for token estimation (calibration provider key). */
-  readonly providerName: string;
-  /** Context window config (drives compaction behavior). */
-  readonly contextWindow: ContextWindowConfig;
-  /** Token budget the reducer must get below (preflight budget). */
-  readonly preflightBudget: number;
-  /** Tool-token overhead included in every estimation call. */
-  readonly toolTokenBudget?: number;
-  /** Maximum reducer iterations before the loop exits unconditionally. */
-  readonly maxAttempts: number;
-  /** Abort signal threaded through compaction calls. */
-  readonly abortSignal?: AbortSignal;
-  /**
-   * Compaction callback — the reducer never owns the ContextWindowManager
-   * instance. The orchestrator supplies this closure so the default plugin
-   * can delegate the forced-compaction tier without crossing the
-   * pipeline/infra boundary on its own.
-   */
-  readonly compactFn: (
-    messages: Message[],
-    signal: AbortSignal | undefined,
-    options: unknown,
-  ) => Promise<ContextWindowResult>;
-  /**
-   * Invoked before each reducer iteration to emit the `context_compacting`
-   * activity state. The orchestrator owns activity emission because the
-   * signal is trust/channel aware.
-   */
-  readonly emitActivityState: () => void;
-  /**
-   * Invoked after each reducer step that produced a successful compaction.
-   * Handles circuit-breaker tracking, event emission, and context mutation.
-   * The pipeline passes back `didCompact` so the orchestrator can flip its
-   * `reducerCompacted` / `shouldInjectWorkspace` flags and the next
-   * re-injection uses the fresh messages.
-   */
-  readonly onCompactionResult: (
-    result: ContextWindowResult,
-    compactedBasis?: Message[],
-  ) => void | Promise<void>;
-  /**
-   * Invoked after each step to rebuild `runMessages` from the step's
-   * reduced history with the requested injection mode. The orchestrator
-   * owns this helper so the full per-turn injection options object doesn't
-   * leak into the pipeline surface. The plugin passes the current reduced
-   * messages array explicitly so the orchestrator doesn't need to read
-   * mutable shared state. Returns the new `runMessages`.
-   *
-   * Two distinct "did compact" signals are passed so the orchestrator can
-   * apply the correct per-iteration vs sticky gating:
-   * - `stepCompacted` — whether THIS iteration's reducer step produced a
-   *   fresh compaction. Gates PKB / NOW re-injection: compaction strips the
-   *   existing blocks, so only iterations that just compacted need the
-   *   content re-threaded. Iterations that only truncated tool results or
-   *   downgraded injections must NOT force a re-injection or the token
-   *   count grows each round.
-   * - `accumulatedCompacted` — whether ANY iteration in this pipeline
-   *   invocation has compacted. Gates `slackChronologicalMessages`
-   *   suppression: once compaction has run, the captured Slack transcript
-   *   snapshot would overwrite the compacted history, so it must stay
-   *   suppressed for every subsequent iteration even if that iteration
-   *   didn't re-compact.
-   */
-  readonly reinjectForMode: (
-    messages: Message[],
-    mode: InjectionMode,
-    stepCompacted: boolean,
-    accumulatedCompacted: boolean,
-  ) => Promise<Message[]>;
-  /**
-   * Invoked after each step to post-estimate the rebuilt `runMessages`.
-   * Pulled out so the orchestrator controls how estimation is performed
-   * (and which fields feed it) without the pipeline reimplementing it.
-   */
-  readonly estimatePostInjection: (runMessages: Message[]) => number;
-}
-
-/** Output of the `overflowReduce` pipeline. */
-export interface OverflowReduceResult {
-  /** Final reduced `ctx.messages` value (mutated in place by the reducer). */
-  readonly messages: Message[];
-  /** Final `runMessages` with re-applied runtime injections. */
-  readonly runMessages: Message[];
-  /** Final injection mode (may be `"minimal"` if the downgrade tier fired). */
-  readonly injectionMode: InjectionMode;
-  /** Accumulated reducer state at exit. */
-  readonly reducerState: ReducerState;
-  /** True if any step successfully compacted history. */
-  readonly reducerCompacted: boolean;
-  /** How many iterations of the tier loop executed. */
-  readonly attempts: number;
-}
-
-/**
- * Pipeline arguments for `persistence` — a discriminated union over the
- * message-CRUD operations plugins may observe, redirect, or short-circuit:
- *
- * - `add`           — append a new message (`addMessage`). Mirrors
- *                     `addMessage(conversationId, role, content, metadata?, opts?)`.
- *                     When `syncToDisk` is set, the default plugin also runs
- *                     {@link syncMessageToDisk} against the just-persisted row
- *                     so the JSONL disk view stays consistent. The
- *                     `createdAtMs` field carries the conversation's creation
- *                     timestamp — needed to resolve the disk-view directory.
- * - `reserve`       — pre-allocate an empty assistant anchor row
- *                     (`reserveMessage`) so the agent loop can stamp streaming
- *                     events with stable identity before any content is
- *                     produced. Returns the same row shape as `add`.
- * - `updateContent` — overwrite the content of an existing message
- *                     (`updateMessageContent`). Used to finalize a previously
- *                     reserved row, and by consolidation paths.
- * - `update`        — shallow-merge metadata into an existing message
- *                     (`updateMessageMetadata`). Returns `void`.
- * - `delete`        — remove a single message (`deleteMessageById`). Returns
- *                     the {@link DeletedMemoryIds}-shaped segment/summary IDs
- *                     the caller must clean up out-of-band.
- *
- * The discriminated `op` field lets plugin middleware narrow the union and
- * tailor behavior per-operation (e.g. "only observe deletes", "redirect
- * adds to a mock store").
- */
-export type PersistAddArgs = {
-  readonly op: "add";
-  readonly conversationId: string;
-  readonly role: MessageRole;
-  readonly content: string;
-  readonly metadata?: Record<string, unknown>;
-  readonly addOptions?: { readonly skipIndexing?: boolean };
-  /**
-   * When `true`, the default plugin additionally invokes
-   * {@link syncMessageToDisk} with the returned message's id. Requires
-   * {@link createdAtMs} to resolve the conversation's disk-view directory.
-   */
-  readonly syncToDisk?: boolean;
-  /** Conversation creation timestamp — only read when `syncToDisk` is true. */
-  readonly createdAtMs?: number;
-};
-
-export type PersistReserveArgs = {
-  readonly op: "reserve";
-  readonly conversationId: string;
-  readonly role: MessageRole;
-  readonly metadata?: Record<string, unknown>;
-};
-
-export type PersistUpdateContentArgs = {
-  readonly op: "updateContent";
-  readonly messageId: string;
-  readonly content: string;
-};
-
-export type PersistUpdateArgs = {
-  readonly op: "update";
-  readonly messageId: string;
-  readonly updates: Record<string, unknown>;
-};
-
-export type PersistDeleteArgs = {
-  readonly op: "delete";
-  readonly messageId: string;
-};
-
-export type PersistArgs =
-  | PersistAddArgs
-  | PersistReserveArgs
-  | PersistUpdateContentArgs
-  | PersistUpdateArgs
-  | PersistDeleteArgs;
-
-/**
- * Result row returned by an `add` op — matches the shape produced by
- * {@link addMessage}. Kept structural (not imported from `memory/`) so the
- * plugin types module stays decoupled from the storage layer.
- */
-export type PersistAddResult = {
-  readonly op: "add";
-  readonly message: {
-    readonly id: string;
-    readonly conversationId: string;
-    readonly role: string;
-    readonly content: string;
-    readonly createdAt: number;
-    readonly metadata?: string;
-  };
-};
-
-/**
- * Result row returned by a `reserve` op — same row shape as `add` but with
- * empty `content` (`"[]"`) and tagged distinctly so middleware can branch
- * on intent.
- */
-export type PersistReserveResult = {
-  readonly op: "reserve";
-  readonly message: {
-    readonly id: string;
-    readonly conversationId: string;
-    readonly role: string;
-    readonly content: string;
-    readonly createdAt: number;
-    readonly metadata?: string;
-  };
-};
-
-export type PersistUpdateContentResult = { readonly op: "updateContent" };
-
-export type PersistUpdateResult = { readonly op: "update" };
-
-/** IDs of segments/summaries the caller must remove from Qdrant. */
-export type PersistDeleteResult = {
-  readonly op: "delete";
-  readonly segmentIds: string[];
-  readonly deletedSummaryIds: string[];
-};
-
-export type PersistResult =
-  | PersistAddResult
-  | PersistReserveResult
-  | PersistUpdateContentResult
-  | PersistUpdateResult
-  | PersistDeleteResult;
-
-/**
- * Arguments for the `titleGenerate` pipeline. Mirrors the parameters of
- * `queueGenerateConversationTitle` in `memory/conversation-title-service.ts`
- * so the default plugin can delegate verbatim.
- *
- * `provider` is optional because the underlying service falls back to
- * `getConfiguredProvider("conversationTitle")` when absent. `userMessage`
- * carries the first turn's text — the service uses it as LLM context and
- * also to derive a deterministic fallback title if the call fails.
- *
- * `onTitleUpdated` is a fire-and-forget callback the pipeline invokes when
- * the title is finally persisted. The default implementation is
- * fire-and-forget overall, so the pipeline result (`TitleResult`) carries no
- * payload — callers that need the title must use the callback.
- */
-export type TitleArgs = {
-  readonly conversationId: string;
-  readonly provider?: Provider;
-  readonly userMessage: string;
-  readonly onTitleUpdated?: (title: string) => void;
-};
-/**
- * Result of the `titleGenerate` pipeline. The default implementation is
- * fire-and-forget (it schedules background work and returns immediately),
- * so there is nothing meaningful to return. Defined as an empty object so
- * custom plugins can opt into richer payloads later.
- */
-export type TitleResult = Readonly<Record<string, never>>;
-
-/**
- * @deprecated Alias kept for the M1 scaffolding era. Prefer {@link TitleArgs}.
- */
-export type TitleGenerateArgs = TitleArgs;
-/**
- * @deprecated Alias kept for the M1 scaffolding era. Prefer {@link TitleResult}.
- */
-export type TitleGenerateResult = TitleResult;
-
-/**
- * Input to the `toolResultTruncate` pipeline: the raw tool-result text and
- * the character budget the caller computed from the context-window share
- * (see `calculateMaxToolResultChars` in `context/tool-result-truncation.ts`).
- */
-export type ToolResultTruncateArgs = {
-  readonly content: string;
-  readonly maxChars: number;
-};
-
-/**
- * Output of the `toolResultTruncate` pipeline: the (possibly truncated)
- * content and a boolean flag indicating whether the pipeline actually
- * shortened the input. Callers use `truncated` for telemetry / warnings.
- */
-export type ToolResultTruncateResult = {
-  readonly content: string;
-  readonly truncated: boolean;
-};
-
-/**
- * Snapshot of the just-completed assistant turn plus retry/context counters
- * the `emptyResponse` pipeline needs to decide whether to nudge, accept, or
- * surface an error.
- *
- * `emptyResponseRetries` is the *current* retry counter — the pipeline may
- * compare it to `maxEmptyResponseRetries` to implement a retry cap. The loop
- * increments the counter only after a `"nudge"` decision; the pipeline is
- * stateless across turns.
- *
- * `priorAssistantHadVisibleText` signals that an earlier turn in the current
- * `run()` invocation already delivered user-visible text. When true, an
- * empty follow-up is the model correctly ending its turn and nudging would
- * mislead it into resending text the user already saw.
- */
-export interface EmptyResponseArgs {
-  /** Content blocks produced by the assistant on this turn. */
-  readonly responseContent: ReadonlyArray<ContentBlock>;
-  /**
-   * Number of `tool_use` blocks in `responseContent`. Mirrors the loop's own
-   * count so middleware doesn't have to recompute it. When > 0 the turn is
-   * not empty — the model issued tool calls.
-   */
-  readonly toolUseBlocksLength: number;
-  /** 0-based index of the tool-use turn being evaluated. */
-  readonly toolUseTurns: number;
-  /** How many empty-response nudges the loop has already issued this run. */
-  readonly emptyResponseRetries: number;
-  /** Upper bound for `emptyResponseRetries`. The default is 1. */
-  readonly maxEmptyResponseRetries: number;
-  /**
-   * Whether ANY prior assistant turn in the current `run()` call carried
-   * visible text. See `agent/loop.ts` for why the whole-run scan matters.
-   */
-  readonly priorAssistantHadVisibleText: boolean;
-}
-
-/**
- * Decision produced by the `emptyResponse` pipeline.
- *
- * - `"nudge"`  — loop appends `nudgeText` as a `user` message and retries.
- *                `nudgeText` MUST be present; it is what the model will see.
- * - `"accept"` — loop treats the turn as complete (pushes the assistant
- *                message to history and exits the tool-use chain normally).
- * - `"error"`  — loop surfaces a clear error. Reserved for middleware that
- *                wants to escalate an empty response rather than absorb it.
- */
-export interface EmptyResponseDecision {
-  readonly action: "nudge" | "accept" | "error";
-  /** Nudge text the loop will push to history. Required when `action === "nudge"`. */
-  readonly nudgeText?: string;
-}
-
-/** Alias so the {@link PipelineMiddlewareMap} entry names its own result shape. */
-export type EmptyResponseResult = EmptyResponseDecision;
-
-/**
- * Arguments to the `toolError` pipeline — invoked by the agent loop once per
- * turn that produced tool results, BEFORE the turn's tool-result user message
- * is pushed into history.
- *
- * `hasToolError` is true when at least one tool in the current turn returned
- * `isError: true`. `consecutiveErrorTurns` is the running count of
- * back-to-back error turns (reset to 0 on a clean turn, incremented on each
- * error turn). `maxConsecutiveErrorNudges` is the default cap the agent loop
- * currently applies; plugins receive it so they can match the default
- * threshold exactly or compute a relative offset.
- */
-export type ToolErrorArgs = {
-  readonly hasToolError: boolean;
-  readonly consecutiveErrorTurns: number;
-  readonly maxConsecutiveErrorNudges: number;
-};
-
-/**
- * Decision returned by the `toolError` pipeline. When `action` is `"nudge"`,
- * the agent loop appends a text block with `nudgeText` to the turn's tool
- * results so the next LLM turn sees the nudge. When `action` is `"skip"`, no
- * nudge is injected and the tool results pass through unchanged.
- */
-export type ToolErrorDecision =
-  | { readonly action: "nudge"; readonly nudgeText: string }
-  | { readonly action: "skip" };
-
-/** Alias kept so `PipelineMiddlewareMap.toolError` reads result-shaped. */
-export type ToolErrorResult = ToolErrorDecision;
-
-/**
- * Arguments for the `circuitBreaker` pipeline.
- *
- * A single call pattern handles both querying and updating the breaker:
- * - `{ key }` — query-only. Returns the current `{ open, cooldownRemainingMs? }`.
- * - `{ key, outcome }` — update state, then return the post-update decision.
- *
- * `key` identifies the circuit bucket so independent circuits (e.g. per
- * conversation, per provider) can coexist. The default compaction plugin
- * uses `"compaction:<conversationId>"`.
- *
- * `state` is a pragmatic extension beyond the minimal `{ key, outcome? }`
- * shape: the `Conversation` owns `consecutiveCompactionFailures` and
- * `compactionCircuitOpenUntil` because dev-only playground routes read and
- * mutate those fields directly. The default plugin reads/updates the same
- * container so the pipeline stays a pure wrapper rather than forking state
- * ownership.
- *
- * `onEvent` is optional — when provided, the default plugin emits
- * `compaction_circuit_open` / `compaction_circuit_closed` transition events
- * through it. Callers that just want to query without emitting (or without
- * a `ServerMessage` sink handy) can omit it.
- */
-export type CircuitBreakerArgs = {
-  readonly key: string;
-  readonly outcome?: "success" | "failure";
-  readonly state: {
-    readonly conversationId: string;
-    consecutiveCompactionFailures: number;
-    compactionCircuitOpenUntil: number | null;
-  };
-  readonly onEvent?: (msg: ServerMessage) => void;
-};
-
-/**
- * Result of a `circuitBreaker` pipeline invocation.
- *
- * - `open` — `true` when the breaker is currently tripped (auto paths must
- *   skip). `false` when closed (auto paths may proceed).
- * - `cooldownRemainingMs` — when `open` is `true`, the number of ms until
- *   the breaker auto-closes (for informational display). Omitted when the
- *   breaker is closed.
- */
-export type CircuitBreakerResult = {
-  readonly open: boolean;
-  readonly cooldownRemainingMs?: number;
-};
+export type CompactionCircuitEvent =
+  | CompactionCircuitOpenEvent
+  | CompactionCircuitClosedEvent;
 
 /**
  * Mapping from {@link PipelineName} to the middleware signature the registry
@@ -763,23 +163,7 @@ export type CircuitBreakerResult = {
  * `getMiddlewaresFor<P>()` type narrowing in PR 13.
  */
 export interface PipelineMiddlewareMap {
-  turn: Middleware<TurnArgs, TurnResult>;
-  llmCall: Middleware<LLMCallArgs, LLMCallResult>;
-  toolExecute: Middleware<ToolExecuteArgs, ToolExecuteResult>;
-  memoryRetrieval: Middleware<MemoryArgs, MemoryResult>;
-  historyRepair: Middleware<HistoryRepairArgs, HistoryRepairResult>;
-  tokenEstimate: Middleware<TokenEstimateArgs, TokenEstimateResult>;
   compaction: Middleware<CompactionArgs, CompactionResult>;
-  overflowReduce: Middleware<OverflowReduceArgs, OverflowReduceResult>;
-  persistence: Middleware<PersistArgs, PersistResult>;
-  titleGenerate: Middleware<TitleArgs, TitleResult>;
-  toolResultTruncate: Middleware<
-    ToolResultTruncateArgs,
-    ToolResultTruncateResult
-  >;
-  emptyResponse: Middleware<EmptyResponseArgs, EmptyResponseResult>;
-  toolError: Middleware<ToolErrorArgs, ToolErrorResult>;
-  circuitBreaker: Middleware<CircuitBreakerArgs, CircuitBreakerResult>;
 }
 
 // ─── TurnContext ─────────────────────────────────────────────────────────────
@@ -807,49 +191,8 @@ export interface TurnInjectionInputs {
    * context (unified turn context, etc.). Drives per-injector gating.
    */
   readonly mode?: InjectionMode;
-  /** Disk-pressure cleanup-mode context or null to skip the warning. */
-  readonly diskPressureContext?: DiskPressureInjectionContext | null;
-  /** Workspace top-level context text (`<workspace>...`) or null to skip. */
-  readonly workspaceTopLevelContext?: string | null;
   /** Pre-built unified-turn-context text (`<turn_context>...`) or null to skip. */
   readonly unifiedTurnContext?: string | null;
-  /** PKB auto-injected content (`<knowledge_base>...`) or null to skip. */
-  readonly pkbContext?: string | null;
-  /**
-   * Whether PKB is active for this turn — drives the `<system_reminder>` /
-   * hybrid-search relevance-hint branch.
-   */
-  readonly pkbActive?: boolean;
-  /** Dense query vector surfaced from the graph memory retriever for PKB hints. */
-  readonly pkbQueryVector?: number[];
-  /** Optional sparse vector accompanying `pkbQueryVector`. */
-  readonly pkbSparseVector?: QdrantSparseVector;
-  /** Memory scope id used to filter PKB search results. */
-  readonly pkbScopeId?: string;
-  /**
-   * Live conversation (or a minimal shape containing `messages`) used to
-   * compute which PKB paths are already "in context" and therefore suppressed
-   * from hint suggestions.
-   */
-  readonly pkbConversation?: PkbContextConversation;
-  /** Auto-injected PKB filenames resolved relative to `pkbRoot`. */
-  readonly pkbAutoInjectList?: string[];
-  /** Absolute path to the PKB directory (e.g. `<workspace>/pkb`). */
-  readonly pkbRoot?: string;
-  /**
-   * Working directory against which relative `file_read` paths resolve.
-   * Falls back to `pkbRoot` when omitted.
-   */
-  readonly pkbWorkingDir?: string;
-  /**
-   * Pre-rendered v2 static memory content (essentials/threads/recent/buffer
-   * concatenated, header-wrapped) or null to skip. The agent loop only
-   * passes this on full-mode turns; the injector wraps it in `<memory>` for
-   * the user message.
-   */
-  readonly memoryV2Static?: string | null;
-  /** NOW.md scratchpad content or null to skip. */
-  readonly nowScratchpad?: string | null;
   /** Pre-built `<active_subagents>` block or null to skip. */
   readonly subagentStatusBlock?: string | null;
   /** Channel capabilities — drives slack gating. */
@@ -866,12 +209,6 @@ export interface TurnInjectionInputs {
    * no focus block is appended.
    */
   readonly slackActiveThreadFocusBlock?: string | null;
-  /**
-   * Active dashboard-surface context (read from `<active_workspace>`). Kept
-   * on the injection inputs bag (not its own injector) because it is
-   * orchestrator-owned surface state, not a default-chain element.
-   */
-  readonly activeSurface?: ActiveSurfaceContext | null;
   /** Channel command context (e.g. Telegram /start) or null to skip. */
   readonly channelCommandContext?: ChannelCommandContext | null;
   /** Voice call-control prompt or null to skip. */
@@ -903,11 +240,6 @@ export interface TurnInjectionInputs {
   }> | null;
 }
 
-export interface DiskPressureInjectionContext {
-  /** True when the current turn is allowed to run only for storage cleanup. */
-  readonly cleanupModeActive: boolean;
-}
-
 /**
  * Per-turn execution context threaded through every middleware invocation.
  *
@@ -960,6 +292,20 @@ export interface TurnContext {
    * a context without `injectionInputs` produces an empty injection chain.
    */
   injectionInputs?: TurnInjectionInputs;
+  /**
+   * The {@link LLMCallSite} this turn's pipeline work belongs to —
+   * `"mainAgent"` for the user-facing conversational reply, or the specific
+   * background/utility site (`"compactionAgent"`, `"subagentSpawn"`,
+   * `"memoryConsolidation"`, `"conversationTitle"`, …) when the agent loop is
+   * driving non-main work that happens to share the same `conversationId`.
+   *
+   * Lets {@link Injector}s and pipeline middleware scope their behaviour to
+   * the main reply and stay out of background turns, which `onEvent` presence
+   * alone cannot distinguish (compaction and subagent loops also stream).
+   * Omitted by call sites that don't tag a site (synthesized test contexts);
+   * consumers should treat absence conservatively.
+   */
+  callSite?: LLMCallSite;
 }
 
 // ─── Injectors ───────────────────────────────────────────────────────────────
@@ -1039,8 +385,21 @@ export interface Injector {
   name: string;
   /** Ascending sort key — lower runs first. */
   order: number;
-  /** Produce a block, or `null` to contribute nothing on this turn. */
-  produce(ctx: TurnContext): Promise<InjectionBlock | null>;
+  /**
+   * Produce a block, or `null` to contribute nothing on this turn.
+   *
+   * `runMessages` is the turn's working message array — the same array the
+   * chain's blocks are spliced onto — passed explicitly so injectors that
+   * need the current prompt contents (e.g. the PKB reminder, which scans for
+   * already-loaded `file_read` paths) read it from a parameter rather than a
+   * field on the shared {@link TurnContext}. Absent for text-only chain
+   * consumers ({@link composeInjectorChain}) that drive injectors without a
+   * message array.
+   */
+  produce(
+    ctx: TurnContext,
+    runMessages?: Message[],
+  ): Promise<InjectionBlock | null>;
 }
 
 // ─── Model-visible capability slots ──────────────────────────────────────────
@@ -1108,22 +467,6 @@ export interface PluginSkillRegistration {
 
 // ─── Plugin ──────────────────────────────────────────────────────────────────
 
-/**
- * A plugin lifecycle hook. Receives a per-lifecycle context shape and
- * may return either a transformed context or `void`. Today's runtime
- * consumes only the resolved-or-rejected nature of the promise; the
- * `TCtx` return is reserved for future hooks that fan a transformed
- * context out to downstream plugins.
- *
- * Each known hook key has a documented context shape:
- *   - `init` — {@link PluginInitContext}
- *   - `shutdown` — {@link PluginShutdownContext}
- *
- * Unknown keys are populated by the loader for forward compatibility
- * but are not invoked by today's runtime.
- */
-export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
-
 /**
  * Map of lifecycle hooks contributed by a plugin. Keys match file
  * basenames under `<plugin>/hooks/` — the external loader populates one
@@ -1143,7 +486,7 @@ export type PluginHooks = Record<string, PluginHookFn<any>>;
 
 /**
  * A registered plugin. Every field besides `manifest` is optional — a plugin
- * may contribute any combination of middleware, injectors, and model-visible
+ * may contribute any combination of middleware and model-visible
  * capabilities. Lifecycle hooks live under `hooks`.
  */
 export interface Plugin {
@@ -1157,16 +500,14 @@ export interface Plugin {
    * `@vellumai/plugin-api`); the loader derives `name` from the
    * `tools/<name>.ts` basename and runs the definition through
    * `finalizeTool` to fill omitted required fields, producing the
-   * `LoadedTool` values stored here. Category / ownership metadata is
+   * `Tool` values stored here. Category / ownership metadata is
    * stamped by `registerPluginTools` at registration time.
    */
-  tools?: LoadedTool[];
+  tools?: Tool[];
   /** HTTP route registrations served by the assistant. */
   routes?: PluginRouteRegistration[];
   /** Skill registrations loaded at startup. */
   skills?: PluginSkillRegistration[];
-  /** Prompt-time injectors contributed by this plugin. */
-  injectors?: Injector[];
   /**
    * Named middleware slots. At most one middleware per slot per plugin.
    * The registry composes multiple plugins' middleware for a slot in