@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/plugins/types.ts

@@ -1,55 +1,29 @@
 /**
  * Plugin core types.
  *
- * This file is scaffolding only — it defines the shape of the plugin system
- * without wiring any behavior. Later PRs in the `agent-plugin-system` plan
- * refine per-pipeline argument/result types (currently `unknown`-based
- * 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
- * {@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
- * (`tools`, `routes`, `skills`).
+ * A plugin may contribute lifecycle hooks ({@link PluginHooks}) that the
+ * runtime invokes at named events, and model-visible capabilities (`tools`,
+ * `routes`, `skills`). The registry tracks every registered plugin in
+ * registration order.
  *
  * Design doc: `.private/plans/agent-plugin-system.md`.
  */
 
 import type { CompactionCircuitClosedEvent } from "../api/events/compaction-circuit-closed.js";
 import type { CompactionCircuitOpenEvent } from "../api/events/compaction-circuit-open.js";
-import type { ContextWindowConfig } from "../config/schemas/inference.js";
-import type {
-  ContextWindowManager,
-  ContextWindowResult,
-} from "../context/window-manager.js";
-import type { ReducerState } from "../daemon/context-overflow-reducer.js";
+import type { LLMCallSite } from "../config/schemas/llm.js";
+import type { ContextWindowManager } from "../context/window-manager.js";
 import type {
-  ActiveSurfaceContext,
   ChannelCapabilities,
-  ChannelCommandContext,
   InjectionMode,
 } from "../daemon/conversation-runtime-assembly.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 { ConversationGraphMemory } from "../memory/graph/conversation-graph-memory.js";
 import type { PluginHookFn } from "../plugin-api/types.js";
-import type {
-  ContentBlock,
-  Message,
-  Provider,
-  ProviderResponse,
-  SendMessageOptions,
-  ToolDefinition,
-} from "../providers/types.js";
+import type { Message } from "../providers/types.js";
 import type { SkillRoute } from "../runtime/skill-route-registry.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../tools/types.js";
+import type { Tool } from "../tools/types.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
-import type {
-  ToolResultTruncateArgs,
-  ToolResultTruncateResult,
-} from "./defaults/tool-result-truncate/types.js";
 
 // ─── Manifest ────────────────────────────────────────────────────────────────
 
@@ -100,618 +74,20 @@ export type {
   PluginShutdownContext,
 } from "../plugin-api/types.js";
 
-// ─── Middleware ──────────────────────────────────────────────────────────────
-
-/**
- * Generic onion-style middleware. Each middleware may observe/modify the
- * arguments, decide whether to call `next` (short-circuit) or return a
- * synthetic result, and observe/modify the downstream result. `ctx` is the
- * immutable per-turn {@link TurnContext}.
- */
-export type Middleware<A, R> = (
-  args: A,
-  next: (args: A) => Promise<R>,
-  ctx: TurnContext,
-) => Promise<R>;
-
-// ─── Pipeline names ──────────────────────────────────────────────────────────
-
-/**
- * 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"
-  | "tokenEstimate"
-  | "compaction"
-  | "overflowReduce"
-  | "persistence"
-  | "titleGenerate"
-  | "toolResultTruncate"
-  | "emptyResponse"
-  | "toolError"
-  | "circuitBreaker";
-
-// ─── 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.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 — `tools`, `systemPrompt`, `config`,
- * `onEvent`, and `signal` — so middleware can substitute streaming handlers,
- * tool sets, or cancellation signals without reconstructing them.
- */
-export type LLMCallArgs = {
-  readonly provider: Provider;
-  readonly messages: Message[];
-  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.
- */
-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>;
-}
-
-/**
- * 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;
-
-/**
- * Pipeline inputs for the `compaction` slot — the arguments the assistant
- * would otherwise have passed to {@link ContextWindowManager.maybeCompact}.
- *
- * Typed via `unknown`-forwarded aliases to keep this module free of runtime
- * imports from `context/window-manager.ts` (which would pull the full
- * compaction machinery into anything that merely imports plugin types).
- * The default compaction plugin re-casts back to the concrete types before
- * delegating to the manager.
- */
-export type CompactionArgs = {
-  /** The message history to consider for compaction. */
-  readonly messages: unknown;
-  /** Abort signal forwarded to the compaction summary call. */
-  readonly signal?: AbortSignal;
-  /** `ContextWindowCompactOptions` — options block forwarded verbatim. */
-  readonly options?: unknown;
-};
-/**
- * Pipeline result for the `compaction` slot — the full
- * {@link import("../context/window-manager.js").ContextWindowResult}
- * object returned by `maybeCompact()`. Kept as `unknown` here for the
- * same decoupling reason as {@link CompactionArgs}; consumers in
- * `daemon/conversation-agent-loop.ts` cast back to the concrete shape.
- */
-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.
- */
-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, options?)`.
- *                     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>>;
+// ─── Memory-graph result ─────────────────────────────────────────────────────
 
 /**
- * @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}.
+ * 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 TitleGenerateResult = TitleResult;
+export type GraphMemoryResult = Awaited<
+  ReturnType<ConversationGraphMemory["prepareMemory"]>
+>;
 
 /**
- * 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;
-  /**
-   * Provider-reported stop reason for the assistant turn being evaluated.
-   * `null`/`undefined` when the provider didn't report one (older
-   * providers, partial responses). The default terminal uses this to
-   * distinguish an explicit safety-classifier refusal (Anthropic's
-   * `"refusal"`) from an organically-empty turn — refusals deserve a
-   * nudge even on the very first model call of the run, whereas an
-   * organically-empty first call usually means the model legitimately
-   * had nothing to say.
-   */
-  readonly stopReason: string | null | undefined;
-}
-
-/**
- * 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. Its parameter is narrowed to {@link CompactionCircuitEvent} (the
- * only two messages this pipeline ever emits) rather than the full
- * `ServerMessage` union, so a caller whose outbound channel can carry just
- * these two events can satisfy it. Callers that only want to query without
- * emitting 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: CompactionCircuitEvent) => void;
-};
-
-/**
- * The complete set of transition events the `circuitBreaker` pipeline emits:
+ * 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
@@ -721,44 +97,6 @@ export type CompactionCircuitEvent =
   | CompactionCircuitOpenEvent
   | CompactionCircuitClosedEvent;
 
-/**
- * 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;
-};
-
-/**
- * Mapping from {@link PipelineName} to the middleware signature the registry
- * expects for that slot. Used both to shape `Plugin.middleware` and to drive
- * `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>;
-  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 ─────────────────────────────────────────────────────────────
 
 /**
@@ -784,49 +122,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. */
@@ -843,18 +140,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. */
-  readonly voiceCallControlPrompt?: string | null;
-  /** Gateway-provided transport hints (e.g. Slack thread context). */
-  readonly transportHints?: string[] | null;
   /**
    * When true, inject the `<non_interactive_context>` block so the model
    * knows no human is present to answer clarification questions.
@@ -880,18 +165,12 @@ 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.
+ * Per-turn execution context threaded to the injector chain and to hook
+ * consumers that need turn-level identity.
  *
  * Combines turn-level identifiers (`requestId`, `conversationId`,
- * `turnIndex`), the optionally-bound `pluginName` (set by the pipeline
- * runner when invoking a specific plugin's middleware, for error
- * attribution), and the canonical {@link TrustContext} that carries trust
+ * `turnIndex`) with the canonical {@link TrustContext} that carries trust
  * class and channel identity for the inbound actor.
  *
  * `TrustContext` is re-exposed here (rather than redefined) so the plugin
@@ -904,39 +183,44 @@ export interface TurnContext {
   conversationId: string;
   /** 0-based turn index within the conversation. */
   turnIndex: number;
-  /**
-   * When the pipeline runner is executing a specific plugin's middleware,
-   * this is set to that plugin's name so downstream code (error wrapping,
-   * telemetry) can attribute work accurately.
-   */
-  pluginName?: string;
   /** Trust classification and channel identity for the inbound actor. */
   trust: TrustContext;
   /**
    * Optional handle to the conversation's {@link ContextWindowManager}.
    *
-   * Attached by the orchestrator when building the per-turn context for
-   * pipeline invocations that need to defer to the real compaction machinery
-   * (notably the default `compaction` plugin). Pipelines that never touch
-   * compaction can ignore this field; the default compaction plugin throws
-   * a {@link PluginExecutionError} if it is missing, which keeps the failure
-   * attributed to the plugin rather than surfacing as a late NPE downstream.
+   * Attached by the orchestrator so the default compaction implementation can
+   * defer to the real compaction machinery via `context.manager`. Call sites
+   * that never touch compaction may omit it.
    *
    * Declared as an optional typed field so plugin code can read it without a
-   * lenient cast. The optional shape is load-bearing: pipeline runner tests,
-   * synthesized handler contexts, and other non-compaction call sites still
-   * construct valid `TurnContext` literals without attaching a manager.
+   * lenient cast. The optional shape is load-bearing: synthesized handler
+   * contexts and other non-compaction call sites still construct valid
+   * `TurnContext` literals without attaching a manager.
    */
   contextWindowManager?: ContextWindowManager;
   /**
    * Per-turn injection inputs consumed by the default injector chain.
    *
-   * Omitted for call sites that don't drive runtime injection (pipeline-runner
-   * tests, synthesized handler contexts, some background jobs). Each default
-   * injector treats missing/absent fields as "no injection on this turn", so
-   * a context without `injectionInputs` produces an empty injection chain.
+   * Omitted for call sites that don't drive runtime injection (synthesized
+   * handler contexts, some background jobs). Each default injector treats
+   * missing/absent fields as "no injection on this turn", so a context
+   * without `injectionInputs` produces an empty injection chain.
    */
   injectionInputs?: TurnInjectionInputs;
+  /**
+   * The {@link LLMCallSite} this turn 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 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 ───────────────────────────────────────────────────────────────
@@ -1016,8 +300,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 ──────────────────────────────────────────
@@ -1104,7 +401,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 lifecycle hooks and model-visible
  * capabilities. Lifecycle hooks live under `hooks`.
  */
 export interface Plugin {
@@ -1126,45 +423,13 @@ export interface Plugin {
   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
-   * registration order (outermost first).
-   */
-  middleware?: Partial<PipelineMiddlewareMap>;
 }
 
 // ─── Errors ──────────────────────────────────────────────────────────────────
 
-/**
- * Thrown by the pipeline runner when a plugin's middleware exceeds the
- * pipeline's configured timeout. Carries the pipeline name, the offending
- * plugin (if known), and the elapsed-milliseconds budget that was breached.
- */
-export class PluginTimeoutError extends AssistantError {
-  constructor(
-    public readonly pipeline: PipelineName,
-    public readonly pluginName: string | undefined,
-    public readonly elapsedMs: number,
-    options?: { cause?: unknown },
-  ) {
-    super(
-      `Plugin pipeline '${pipeline}' timed out after ${elapsedMs}ms${
-        pluginName ? ` (offending plugin: ${pluginName})` : ""
-      }`,
-      ErrorCode.INTERNAL_ERROR,
-      options,
-    );
-    this.name = "PluginTimeoutError";
-  }
-}
-
 /**
  * Thrown by registry and bootstrap for plugin lifecycle errors — registration
- * validation failures, API-version mismatches, init throw-outs. Distinct from
- * {@link PluginTimeoutError} so callers can discriminate.
+ * validation failures, API-version mismatches, init throw-outs.
  */
 export class PluginExecutionError extends AssistantError {
   constructor(