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

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/maintain-job.ts

@@ -25,14 +25,14 @@
  * `assignPages`, and `invalidateLanes` without process-global module mocks.
  */
 
-import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
-import type { AssistantConfig } from "../../../config/types.js";
-import { getMemoryCheckpoint, setMemoryCheckpoint } from "../../../memory/checkpoints.js";
-import type { MemoryJob } from "../../../memory/jobs-store.js";
-import { getPageIndex } from "../../../memory/v2/page-index.js";
-import { listPages, readPage, writePage } from "../../../memory/v2/page-store.js";
-import { getLogger } from "../../../util/logger.js";
-import { getWorkspaceDir } from "../../../util/platform.js";
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import type { AssistantConfig } from "../../config/types.js";
+import { getLogger } from "../../util/logger.js";
+import { getWorkspaceDir } from "../../util/platform.js";
+import { getMemoryCheckpoint, setMemoryCheckpoint } from "../checkpoints.js";
+import type { MemoryJob } from "../jobs-store.js";
+import { getPageIndex } from "../v2/page-index.js";
+import { listPages, readPage, writePage } from "../v2/page-store.js";
 import { assignPages as realAssignPages } from "./assign.js";
 import { invalidateLanes as realInvalidateLanes } from "./shadow-plugin.js";
 import { loadLeafTree as realLoadLeafTree, resolveDataDir } from "./tree.js";

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/page-content.ts

@@ -1,5 +1,5 @@
-import { readPage, renderPageContent } from "../../../memory/v2/page-store.js";
-import { getWorkspaceDir } from "../../../util/platform.js";
+import { getWorkspaceDir } from "../../util/platform.js";
+import { readPage, renderPageContent } from "../v2/page-store.js";
 import { renderCapabilityContent } from "./capabilities.js";
 import type { Slug } from "./types.js";
 

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/provider-blocks.ts

@@ -1,4 +1,4 @@
-import type { ContentBlock } from "../../../providers/types.js";
+import type { ContentBlock } from "../../providers/types.js";
 
 /**
  * Text content block carrying a `cache_control` breakpoint with a 1-hour TTL.

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/reconcile.ts

@@ -38,9 +38,9 @@ import { join, relative, sep } from "node:path";
 
 import { parse as parseYaml } from "yaml";
 
-import { listPages, readPage, writePage } from "../../../memory/v2/page-store.js";
-import type { Provider } from "../../../providers/types.js";
-import { getLogger } from "../../../util/logger.js";
+import type { Provider } from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
+import { listPages, readPage, writePage } from "../v2/page-store.js";
 import { assignPages } from "./assign.js";
 import { loadCore } from "./core.js";
 import { invalidateLanes } from "./shadow-plugin.js";

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/render-injection.ts

@@ -1,4 +1,4 @@
-import { wrapMemoryBlock } from "../../../memory/memory-marker.js";
+import { wrapMemoryBlock } from "../memory-marker.js";
 import { Slug } from "./types.js";
 
 /**

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/router.ts

@@ -33,9 +33,9 @@ import { z } from "zod";
 import {
   extractToolUse,
   getConfiguredProvider,
-} from "../../../providers/provider-send-message.js";
-import type { Message, ToolDefinition } from "../../../providers/types.js";
-import { getLogger } from "../../../util/logger.js";
+} from "../../providers/provider-send-message.js";
+import type { Message, ToolDefinition } from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
 import { retryForResult } from "./llm-retry.js";
 import { cachedTextBlock } from "./provider-blocks.js";
 import type { LeafPath, LeafTree, TurnContext } from "./types.js";

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/selection-log-store.ts

@@ -7,10 +7,10 @@
  * across turns) and can't be reproduced after the fact.
  */
 
-import type { MemoryV3SelectionLog } from "../../../api/responses/memory-v3-selection-log.js";
-import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
-import { getConfig } from "../../../config/loader.js";
-import { getDb, getSqliteFrom } from "../../../memory/db-connection.js";
+import type { MemoryV3SelectionLog } from "../../api/responses/memory-v3-selection-log.js";
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import { getConfig } from "../../config/loader.js";
+import { getDb, getSqliteFrom } from "../db-connection.js";
 import { renderV3PageContent } from "./page-content.js";
 import { renderMemoryBlock } from "./render-injection.js";
 import type { Slug } from "./types.js";

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/selector.ts

@@ -33,10 +33,10 @@ import { z } from "zod";
 import {
   extractToolUse,
   getConfiguredProvider,
-} from "../../../providers/provider-send-message.js";
-import type { Message, ToolDefinition } from "../../../providers/types.js";
-import { getLogger } from "../../../util/logger.js";
-import { mapLimit } from "../../../util/map-limit.js";
+} from "../../providers/provider-send-message.js";
+import type { Message, ToolDefinition } from "../../providers/types.js";
+import { getLogger } from "../../util/logger.js";
+import { mapLimit } from "../../util/map-limit.js";
 import { retryForResult } from "./llm-retry.js";
 import { cachedTextBlock } from "./provider-blocks.js";
 import { membersOf } from "./tree.js";

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/shadow-plugin.ts

@@ -1,18 +1,18 @@
 /**
- * Memory v3 — flag-gated shadow/live orchestration engine.
+ * Memory v3 — flag-gated shadow/live injector.
  *
- * Runs the v3 orchestrator each turn and records its selection set to
- * `memory_v3_selections`. Two flags gate behavior:
+ * An {@link Injector} that runs the v3 orchestrator each turn and
+ * records its selection set to `memory_v3_selections`. Two flags gate its
+ * injection behavior:
  *
- *   - `memory-v3-shadow` (live OFF): observation-only. {@link observeTurn}
- *     orchestrates and logs the selection set; no injection is produced, so v2
- *     injection is bit-for-bit identical — the only difference is the
- *     side-effect telemetry write.
- *   - `memory-v3-live`: live injection. The injector (`memoryV3Injector` in
- *     `./injector.ts`) additionally renders the working-set selection into a
- *     `<memory>` block and returns it at v2's dynamic-memory placement
+ *   - `memory-v3-shadow` (and live OFF): observation-only. `produce()` returns
+ *     `null`, so v2 injection is bit-for-bit identical whether the flag is on
+ *     or off — the only difference is the side-effect telemetry write.
+ *   - `memory-v3-live`: live injection. `produce()` additionally renders the
+ *     working-set selection into a `<memory>` block via {@link renderMemoryBlock}
+ *     and returns it as an injection block at v2's dynamic-memory placement
  *     (`after-memory-prefix`). Selections are still logged.
- *   - both OFF: orchestration is skipped entirely.
+ *   - both OFF: `produce()` returns `null` and skips orchestration entirely.
  *
  * On each turn (either flag on):
  *   1. Lazy-init the v3 lanes ONCE across the whole process (leaf tree, core
@@ -22,45 +22,54 @@
  *   3. Run {@link orchestrate} and record its selection set to
  *      `memory_v3_selections` with a best-effort lane attribution.
  *
- * {@link observeTurn} wraps everything after the flag read in try/catch — any
- * failure is logged and swallowed so it can never affect the live turn. The
- * injector treats a `null`/empty result as "no v3 injection", so v2 memory
- * remains the fallback rather than dropping all memory.
+ * Everything after the flag read is wrapped in try/catch — any failure is
+ * logged and swallowed so it can never affect the live turn. In live mode a
+ * failure returns `null` (no v3 injection); v2 suppression keys off BOTH the
+ * flag AND whether `produce()` actually returned a block, so a v3 failure (or
+ * empty selection) falls back to v2 memory rather than dropping all memory.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 
-import { isAssistantFeatureFlagEnabled } from "../../../config/assistant-feature-flags.js";
-import { getConfig } from "../../../config/loader.js";
-import type { AssistantConfig } from "../../../config/schema.js";
-import { getMessages } from "../../../memory/conversation-crud.js";
-import { getDb, getSqliteFrom } from "../../../memory/db-connection.js";
-import { stringifyMessageContent } from "../../../memory/message-content.js";
-import { getPageIndex } from "../../../memory/v2/page-index.js";
-import { getLogger } from "../../../util/logger.js";
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import { getConfig } from "../../config/loader.js";
+import type { AssistantConfig } from "../../config/schema.js";
+import { getMessages } from "../../memory/conversation-crud.js";
+import { getDb, getSqliteFrom } from "../../memory/db-connection.js";
+import { stringifyMessageContent } from "../../memory/message-content.js";
+import {
+  type InjectionBlock,
+  type Injector,
+  type TurnContext as PluginTurnContext,
+} from "../../plugins/types.js";
+import { getLogger } from "../../util/logger.js";
 import {
   getWorkspaceDir,
   getWorkspacePromptPath,
-} from "../../../util/platform.js";
-import { stripCommentLines } from "../../../util/strip-comment-lines.js";
+} from "../../util/platform.js";
+import { stripCommentLines } from "../../util/strip-comment-lines.js";
+import { getPageIndex } from "../v2/page-index.js";
 import { injectCapabilitiesLeaf, isCapabilitySlug } from "./capabilities.js";
 import { loadCore } from "./core.js";
 import type { NeedleIndex } from "./needle.js";
 import { buildNeedleIndex } from "./needle.js";
 import type { OrchestrateResult } from "./orchestrate.js";
 import { orchestrate } from "./orchestrate.js";
+import { renderV3PageContent } from "./page-content.js";
+import { renderMemoryBlock } from "./render-injection.js";
 import { coreSlugs, loadLeafTree, resolveDataDir } from "./tree.js";
 import {
   type LeafPath,
   type LeafTree,
+  MEMORY_V3_BLOCK_ID,
   type SelectionSource,
   type Slug,
   type TurnContext,
 } from "./types.js";
 import { WorkingSet } from "./working-set.js";
 
-export const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
-export const MEMORY_V3_LIVE = "memory-v3-live" as const;
+const MEMORY_V3_SHADOW = "memory-v3-shadow" as const;
+const MEMORY_V3_LIVE = "memory-v3-live" as const;
 
 const log = getLogger("memory-v3-shadow");
 
@@ -301,7 +310,7 @@ function writeSelections(
  * failures are logged and swallowed (returning `null`) so the live turn is
  * unaffected. Returns `null` when there is no user message to route on.
  */
-export async function observeTurn(
+async function observeTurn(
   conversationId: string,
   turnIndex: number,
 ): Promise<OrchestrateResult | null> {
@@ -347,3 +356,56 @@ export async function runShadowObservation(
   if (!isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, getConfig())) return;
   await observeTurn(conversationId, turnIndex);
 }
+
+/**
+ * The v3 injector. Reads both flags:
+ *   - `memory-v3-live` on → orchestrate, log, render the working-set selection
+ *     into a `<memory>` block, and return it at v2's dynamic-memory placement.
+ *   - `memory-v3-shadow` on (live off) → orchestrate + log only, return `null`.
+ *   - both off → return `null` (no orchestration).
+ *
+ * Empty selection and any failure return `null` (no v3 injection). v2
+ * suppression keys off BOTH the flag AND this return value, so a `null` here
+ * (failure or empty selection) falls back to v2 memory rather than dropping all
+ * memory.
+ */
+export const memoryV3Injector: Injector = {
+  name: "memory-v3-shadow",
+  // High order so it sorts last; the live `<memory>` block uses the
+  // after-memory-prefix placement so it lands at the memory boundary regardless
+  // of this sort key, which only orders content-producing injectors.
+  order: 1000,
+  async produce(ctx: PluginTurnContext): Promise<InjectionBlock | null> {
+    const config = getConfig();
+    const live = isAssistantFeatureFlagEnabled(MEMORY_V3_LIVE, config);
+    const shadow = isAssistantFeatureFlagEnabled(MEMORY_V3_SHADOW, config);
+    if (!live && !shadow) return null;
+
+    const result = await observeTurn(ctx.conversationId, ctx.turnIndex);
+    if (!live || !result) return null;
+
+    try {
+      // `renderMemoryBlock` returns "" for an empty selection; inject nothing.
+      const text = await renderMemoryBlock(
+        result.finalInjection,
+        renderV3PageContent,
+      );
+      if (text.length === 0) return null;
+      return {
+        id: MEMORY_V3_BLOCK_ID,
+        text,
+        // Mirror v2's dynamic `<memory>` block placement.
+        placement: "after-memory-prefix",
+      };
+    } catch (err) {
+      log.warn(
+        {
+          err: err instanceof Error ? err.message : String(err),
+          conversationId: ctx.conversationId,
+        },
+        "memory-v3 live render failed (non-fatal) — falling back to v2",
+      );
+      return null;
+    }
+  },
+};

package/src/{plugins/defaults/memory-v3-shadow → memory/v3}/tree.ts

@@ -5,7 +5,7 @@ import { fileURLToPath } from "node:url";
 
 import { parse as parseYaml } from "yaml";
 
-import { getWorkspaceDir } from "../../../util/platform.js";
+import { getWorkspaceDir } from "../../util/platform.js";
 import type {
   LeafFrontmatter,
   LeafNode,

package/src/plugin-api/index.ts

@@ -34,6 +34,11 @@
  *   for both plugin tool files and workspace tool files)
  * - {@link ToolContext} — passed to a plugin tool's `execute` method
  * - {@link ToolExecutionResult} — return shape of a plugin tool's `execute`
+ *
+ * Pipeline-argument types (`MemoryArgs`, `CompactionArgs`, etc.) currently
+ * live in `assistant/src/plugins/types.ts` and have not yet migrated into
+ * this package. A follow-up PR will move them into this surface as the
+ * per-pipeline schemas stabilize.
  */
 
 export type { HookName } from "./constants.js";

package/src/plugins/defaults/circuit-breaker/middlewares/circuitBreaker.ts

@@ -0,0 +1,93 @@
+import type {
+  CircuitBreakerArgs,
+  CircuitBreakerResult,
+  Middleware,
+} from "../../../types.js";
+
+/**
+ * Consecutive failures required to trip the breaker. Matches the legacy
+ * `COMPACTION_CIRCUIT_FAILURE_THRESHOLD` in `conversation-agent-loop.ts`.
+ */
+export const COMPACTION_CIRCUIT_FAILURE_THRESHOLD = 3;
+
+/**
+ * Cooldown window after the breaker trips, during which auto-compaction is
+ * suspended. Matches the legacy `COMPACTION_CIRCUIT_COOLDOWN_MS`.
+ */
+export const COMPACTION_CIRCUIT_COOLDOWN_MS = 60 * 60 * 1000;
+
+/**
+ * Default middleware for the `circuitBreaker` pipeline. A thin wrapper over the
+ * state container passed in `CircuitBreakerArgs.state`:
+ *
+ * - `{ key }` — query. Defers to `next` for the current
+ *   `{ open, cooldownRemainingMs? }`.
+ * - `{ key, outcome }` — update state based on outcome, then defer to `next`
+ *   for the post-update decision. A run of three failures trips the breaker;
+ *   any non-failure outcome resets both the counter and the cooldown timestamp.
+ *
+ * Event emission preserves the existing `trackCompactionOutcome` behavior:
+ * `compaction_circuit_open` fires once when the counter first reaches the
+ * threshold while the circuit is dormant; `compaction_circuit_closed` fires
+ * only on the open→closed transition.
+ */
+const circuitBreaker: Middleware<CircuitBreakerArgs, CircuitBreakerResult> =
+  async function circuitBreaker(args, next) {
+    const { outcome, state, onEvent } = args;
+
+    // Update branch — mutate state first, then defer to the downstream
+    // chain (or terminal) for the decision so outer observers still see
+    // the fully-processed outcome. Separating state mutation from
+    // decision computation also keeps this middleware composable: an
+    // outer plugin may wrap the invocation to observe both the pre-update
+    // args and the post-update result.
+    if (outcome !== undefined) {
+      if (outcome === "failure") {
+        state.consecutiveCompactionFailures += 1;
+        // Treat a stale/expired open-until timestamp the same as null so
+        // a new 3-strike window can re-open the circuit after the prior
+        // cooldown elapses. Without this, subsequent trips would no-op
+        // because `compactionCircuitOpenUntil` remains set to a past
+        // timestamp even though the breaker is effectively closed.
+        const circuitDormant =
+          state.compactionCircuitOpenUntil === null ||
+          Date.now() >= state.compactionCircuitOpenUntil;
+        if (
+          state.consecutiveCompactionFailures >=
+            COMPACTION_CIRCUIT_FAILURE_THRESHOLD &&
+          circuitDormant
+        ) {
+          const openUntil = Date.now() + COMPACTION_CIRCUIT_COOLDOWN_MS;
+          state.compactionCircuitOpenUntil = openUntil;
+          if (onEvent) {
+            onEvent({
+              type: "compaction_circuit_open",
+              conversationId: state.conversationId,
+              reason: "3_consecutive_failures",
+              openUntil,
+            });
+          }
+        }
+      } else {
+        // Emit only on the open→closed transition; firing on the common
+        // closed→closed case would be noise.
+        const wasOpen = state.compactionCircuitOpenUntil !== null;
+        state.consecutiveCompactionFailures = 0;
+        state.compactionCircuitOpenUntil = null;
+        if (wasOpen && onEvent) {
+          onEvent({
+            type: "compaction_circuit_closed",
+            conversationId: state.conversationId,
+          });
+        }
+      }
+    }
+
+    // Defer to downstream (the terminal, in the default registration, but
+    // potentially another plugin in a customized chain) for the final
+    // decision. The terminal's implementation is the canonical read of
+    // the (now-updated) state container.
+    return next(args);
+  };
+
+export default circuitBreaker;

package/src/plugins/defaults/{memory-v3-shadow → circuit-breaker}/package.json

@@ -1,7 +1,7 @@
 {
-  "name": "default-memory-v3-shadow",
+  "name": "default-circuit-breaker",
   "version": "1.0.0",
-  "description": "First-party default plugin housing the memory-v3 shadow/live orchestration engine and its injector.",
+  "description": "First-party default plugin wrapping the assistant's built-in circuit-breaker pipeline with a passthrough implementation.",
   "private": true,
   "license": "MIT",
   "type": "module",

package/src/plugins/defaults/circuit-breaker/register.ts

@@ -0,0 +1,39 @@
+/**
+ * Default `circuitBreaker` plugin.
+ *
+ * Replicates the inline compaction circuit-breaker logic that previously
+ * lived in `daemon/conversation-agent-loop.ts`: three consecutive summary-LLM
+ * failures open the circuit for a one-hour cooldown, and any successful
+ * compaction resets the counter.
+ *
+ * The plugin is a thin wrapper over the state container passed in
+ * `CircuitBreakerArgs.state`. The {@link Conversation} owns the underlying
+ * fields (`consecutiveCompactionFailures`, `compactionCircuitOpenUntil`)
+ * because dev-only playground routes (`POST /playground/reset-compaction-circuit`,
+ * `POST /playground/inject-compaction-failures`) read and mutate them
+ * directly. Keeping ownership on the conversation lets this plugin stay a
+ * pure wrapper while preserving those hatches.
+ *
+ * The `key` parameter is carried through for multi-circuit futures but the
+ * default plugin currently bundles all circuit state into the `state`
+ * container; the key is attached to the log record via the pipeline runner.
+ */
+
+import { type Plugin } from "../../types.js";
+import circuitBreaker from "./middlewares/circuitBreaker.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * Default plugin registered at daemon startup. Consumers negotiate against
+ * `circuitBreakerApi@v1` via the registry's capability table.
+ */
+export const defaultCircuitBreakerPlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+
+  middleware: {
+    circuitBreaker,
+  },
+};

package/src/plugins/defaults/compaction/middlewares/compaction.ts

@@ -0,0 +1,25 @@
+import type {
+  CompactionArgs,
+  CompactionResult,
+  Middleware,
+} from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `compaction` pipeline. Forwards to
+ * `next(args)` so any custom plugins layered outside still run; when this is
+ * the only middleware, `next` is the terminal handler (`../terminal.ts`) and
+ * returns the real compaction output.
+ *
+ * Defaults register at the OUTERMOST onion position, so deciding here without
+ * calling `next` would shadow every later-registered plugin. Routing through
+ * `next(args)` lets user middleware participate normally.
+ */
+const defaultCompactionMiddleware: Middleware<
+  CompactionArgs,
+  CompactionResult
+> = async function defaultCompaction(args, next, ctx) {
+  void ctx;
+  return next(args);
+};
+
+export default defaultCompactionMiddleware;

package/src/plugins/defaults/compaction/package.json

@@ -1,7 +1,7 @@
 {
   "name": "default-compaction",
   "version": "1.0.0",
-  "description": "First-party default plugin providing the assistant's built-in conversation-history compaction.",
+  "description": "First-party default plugin wrapping the assistant's built-in compaction pipeline with a passthrough implementation.",
   "private": true,
   "license": "MIT",
   "type": "module",

package/src/plugins/defaults/compaction/register.ts

@@ -1,24 +1,35 @@
 /**
  * Default `compaction` plugin.
  *
- * Compaction is implemented in `./compact.ts` as {@link defaultCompact}, which
- * the agent loop calls directly with a {@link CompactionContext}. The plugin
- * stays registered as a placeholder so it keeps a presence in the defaults
- * list while we decide how plugins should surface compaction; it contributes
- * no contract slot today.
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual compaction lives in the terminal handler in
+ * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
+ * the `runPipeline` call site in `daemon/conversation-agent-loop.ts`. This
+ * separation matters: the default plugin is registered before any user plugin
+ * (defaults load first in `bootstrapPlugins()`), which puts it at the
+ * OUTERMOST position of the onion chain. If the default middleware were to
+ * invoke the terminal directly without calling `next`, it would shadow every
+ * later-registered plugin. Routing through `next(args)` lets user middleware
+ * participate normally.
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 25).
  */
 
 import { type Plugin } from "../../types.js";
+import defaultCompactionMiddleware from "./middlewares/compaction.js";
 import pkg from "./package.json" with { type: "json" };
 
 /**
- * Manifest for the default compaction plugin. The registration happens in
- * `daemon/external-plugins-bootstrap.ts` before {@link bootstrapPlugins} fires
- * plugin `init()` hooks.
+ * Manifest + middleware wiring for the default compaction plugin. The
+ * registration happens in `daemon/external-plugins-bootstrap.ts` before
+ * {@link bootstrapPlugins} fires plugin `init()` hooks.
  */
 export const defaultCompactionPlugin: Plugin = {
   manifest: {
     name: pkg.name,
     version: pkg.version,
   },
+  middleware: {
+    compaction: defaultCompactionMiddleware,
+  },
 };

package/src/plugins/defaults/compaction/terminal.ts

@@ -0,0 +1,73 @@
+/**
+ * Default `compaction` behavior: summarizes conversation history when the
+ * context window fills up.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * Delegates to the orchestrator's existing {@link ContextWindowManager}
+ * instance, read from `ctx.contextWindowManager` on the {@link TurnContext} as
+ * a typed optional field. The orchestrator is responsible for attaching that
+ * handle to the per-turn context. If the handle is missing, this throws a
+ * {@link PluginExecutionError} so the bug surfaces with clear attribution
+ * instead of a late `undefined.maybeCompact is not a function`.
+ */
+
+import type {
+  ContextWindowCompactOptions,
+  ContextWindowManager,
+  ContextWindowResult,
+} from "../../../context/window-manager.js";
+import type { Message } from "../../../providers/types.js";
+import {
+  type CompactionArgs,
+  type CompactionResult,
+  PluginExecutionError,
+  type TurnContext,
+} from "../../types.js";
+
+/**
+ * Name under which the default plugin registers. Exposed so tests and later
+ * plugins can assert registration order or override the default via
+ * composition.
+ */
+export const DEFAULT_COMPACTION_PLUGIN_NAME = "default-compaction";
+
+/**
+ * Read `contextWindowManager` off the turn context. Throws
+ * {@link PluginExecutionError} when absent so the failure attributes cleanly
+ * to the default plugin instead of manifesting as a later NPE.
+ */
+function extractManager(ctx: TurnContext): ContextWindowManager {
+  const manager = ctx.contextWindowManager;
+  if (
+    manager == null ||
+    typeof manager !== "object" ||
+    typeof (manager as { maybeCompact?: unknown }).maybeCompact !== "function"
+  ) {
+    throw new PluginExecutionError(
+      "default-compaction: ctx.contextWindowManager is missing — orchestrator must attach it before invoking compaction",
+      DEFAULT_COMPACTION_PLUGIN_NAME,
+    );
+  }
+  return manager;
+}
+
+/**
+ * Run compaction for the turn: reads the context window manager off the turn
+ * context and returns the (possibly summarized) message history from
+ * `maybeCompact`.
+ */
+export async function defaultCompactionTerminal(
+  args: CompactionArgs,
+  ctx: TurnContext,
+): Promise<CompactionResult> {
+  const manager = extractManager(ctx);
+  const messages = args.messages as Message[];
+  const options = args.options as ContextWindowCompactOptions | undefined;
+  const result: ContextWindowResult = await manager.maybeCompact(
+    messages,
+    args.signal,
+    options,
+  );
+  return result;
+}

package/src/plugins/defaults/index.ts

@@ -25,10 +25,11 @@
 
 import { registerPlugin, resetPluginRegistryForTests } from "../registry.js";
 import { type Plugin, PluginExecutionError } from "../types.js";
+import { defaultCircuitBreakerPlugin } from "./circuit-breaker/register.js";
 import { defaultCompactionPlugin } from "./compaction/register.js";
 import { defaultEmptyResponsePlugin } from "./empty-response/register.js";
 import { defaultHistoryRepairPlugin } from "./history-repair/register.js";
-import { memoryV3ShadowPlugin } from "./memory-v3-shadow/register.js";
+import { defaultOverflowReducePlugin } from "./overflow-reduce/register.js";
 import { defaultTitleGeneratePlugin } from "./title-generate/register.js";
 import { defaultToolErrorPlugin } from "./tool-error/register.js";
 import { defaultToolResultTruncatePlugin } from "./tool-result-truncate/register.js";
@@ -48,10 +49,11 @@ function getAllDefaultPlugins(): readonly Plugin[] {
     defaultToolResultTruncatePlugin,
     defaultEmptyResponsePlugin,
     defaultToolErrorPlugin,
+    defaultOverflowReducePlugin,
     defaultHistoryRepairPlugin,
     defaultCompactionPlugin,
+    defaultCircuitBreakerPlugin,
     defaultTitleGeneratePlugin,
-    memoryV3ShadowPlugin,
   ];
 }
 
@@ -83,7 +85,7 @@ export function registerDefaultPlugins(): void {
  * so integration tests that exercise the full agent loop have a
  * production-parity plugin stack. Use this in `beforeEach` of tests that
  * dispatch through pipelines with a terminal that assumes the default
- * plugin handles every op (e.g. compaction).
+ * plugin handles every op (e.g. overflowReduce).
  *
  * Tests that specifically need an empty registry (pipeline-unit tests, the
  * plugin-registry tests themselves) should continue to call