@vellumai/assistant 0.8.6 → 0.8.7

package/src/permissions/prompter.ts

@@ -104,27 +104,27 @@ export class PermissionPrompter {
       pendingInteractions.register(requestId, {
         conversationId: conversationId ?? "",
         kind: "confirmation",
-          confirmationDetails: {
-            toolName,
-            input: redactSensitiveFields(input),
-            riskLevel,
-            executionTarget,
-            allowlistOptions: allowlistOptions.map((o) => ({
-              label: o.label,
-              description: o.description,
-              pattern: o.pattern,
-            })),
-            scopeOptions: scopeOptions.map((o) => ({
-              label: o.label,
-              scope: o.scope,
-            })),
-            persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
-          },
-          rpcResolve: resolve as (value: unknown) => void,
-          rpcReject: reject,
-          timer,
-          toolUseId,
-        });
+        confirmationDetails: {
+          toolName,
+          input: redactSensitiveFields(input),
+          riskLevel,
+          executionTarget,
+          allowlistOptions: allowlistOptions.map((o) => ({
+            label: o.label,
+            description: o.description,
+            pattern: o.pattern,
+          })),
+          scopeOptions: scopeOptions.map((o) => ({
+            label: o.label,
+            scope: o.scope,
+          })),
+          persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
+        },
+        rpcResolve: resolve as (value: unknown) => void,
+        rpcReject: reject,
+        timer,
+        toolUseId,
+      });
       this.ownedIds.add(requestId);
 
       if (signal) {
@@ -156,7 +156,10 @@ export class PermissionPrompter {
           scope: o.scope,
         })),
         directoryScopeOptions: directoryScopeOptions
-          ? directoryScopeOptions.map((o) => ({ scope: o.scope, label: o.label }))
+          ? directoryScopeOptions.map((o) => ({
+              scope: o.scope,
+              label: o.label,
+            }))
           : undefined,
         diff,
         conversationId,
@@ -186,9 +189,11 @@ export class PermissionPrompter {
   resolveConfirmation(
     requestId: string,
     decision: UserDecision,
-    selectedPattern?: string,
-    selectedScope?: string,
-    decisionContext?: string,
+    options?: {
+      selectedPattern?: string;
+      selectedScope?: string;
+      decisionContext?: string;
+    },
   ): void {
     if (!this.ownedIds.has(requestId)) {
       log.warn({ requestId }, "No pending prompt for confirmation response");
@@ -201,9 +206,12 @@ export class PermissionPrompter {
       decision === "allow" ? "approved" : "rejected",
     );
     this.ownedIds.delete(requestId);
-    (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
-      { decision, selectedPattern, selectedScope, decisionContext },
-    );
+    (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.({
+      decision,
+      selectedPattern: options?.selectedPattern,
+      selectedScope: options?.selectedScope,
+      decisionContext: options?.decisionContext,
+    });
   }
 
   /**
@@ -215,14 +223,12 @@ export class PermissionPrompter {
     for (const requestId of [...this.ownedIds]) {
       const interaction = pendingInteractions.resolve(requestId, "superseded");
       this.ownedIds.delete(requestId);
-      (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.(
-        {
-          decision: "deny",
-          wasSystemCancel: true,
-          decisionContext:
-            "The user sent a new message instead of responding to this permission prompt. Stop what you are doing and respond to the user's new message. Do NOT retry this tool or request permission again until the user asks you to.",
-        },
-      );
+      (interaction?.rpcResolve as ((v: ConfirmResult) => void) | undefined)?.({
+        decision: "deny",
+        wasSystemCancel: true,
+        decisionContext:
+          "The user sent a new message instead of responding to this permission prompt. Stop what you are doing and respond to the user's new message. Do NOT retry this tool or request permission again until the user asks you to.",
+      });
     }
   }
 

package/src/permissions/question-prompter.test.ts

@@ -1,9 +1,7 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
-import type {
-  QuestionRequest,
-  ServerMessage,
-} from "../daemon/message-protocol.js";
+import type { QuestionRequestEvent } from "../api/events/question-request.js";
+import type { ServerMessage } from "../daemon/message-protocol.js";
 import type {
   QuestionBatchSubmission,
   QuestionPromptResult,
@@ -13,7 +11,12 @@ import type {
 const mockConfig = {
   timeouts: { permissionTimeoutSec: 0.05 },
 };
+// Preserve every other export from the real config/loader so other
+// tests in the same `bun test` run (which share module-level mocks)
+// don't lose access to e.g. `setNestedValue`.
+const realConfigLoader = await import("../config/loader.js");
 mock.module("../config/loader.js", () => ({
+  ...realConfigLoader,
   getConfig: () => mockConfig,
   loadConfig: () => mockConfig,
   invalidateConfigCache: () => {},
@@ -63,17 +66,26 @@ mock.module("../runtime/pending-interactions.js", () => ({
   clear: () => _piStore.clear(),
 }));
 
-const {
-  QuestionPrompter,
-  QuestionBatchValidationError,
-  buildBatchEntries,
-} = await import("./question-prompter.js");
+// `QuestionPrompter` imports `broadcastMessage` directly from
+// assistant-event-hub now (the constructor-injection seam was removed).
+// Intercept that one export so each test instance can observe what the
+// prompter would have broadcast — but preserve every other export from
+// the real module so other tests in the same `bun test` run (which
+// share module-level mocks) still see e.g. `assistantEventHub`.
+let _sentBuffer: ServerMessage[] = [];
+const realEventHub = await import("../runtime/assistant-event-hub.js");
+mock.module("../runtime/assistant-event-hub.js", () => ({
+  ...realEventHub,
+  broadcastMessage: (msg: ServerMessage) => _sentBuffer.push(msg),
+}));
+
+const { QuestionPrompter, QuestionBatchValidationError, buildBatchEntries } =
+  await import("./question-prompter.js");
 
 function makePrompter() {
   const sent: ServerMessage[] = [];
-  const prompter = new QuestionPrompter({
-    broadcastMessage: (msg) => sent.push(msg),
-  });
+  _sentBuffer = sent;
+  const prompter = new QuestionPrompter();
   return { prompter, sent };
 }
 
@@ -176,7 +188,7 @@ describe("QuestionPrompter", () => {
     const promise = prompter.prompt(singleQuestionParams);
 
     expect(sent).toHaveLength(1);
-    const req = sent[0] as QuestionRequest;
+    const req = sent[0] as QuestionRequestEvent;
     expect(req.type).toBe("question_request");
     expect(req.questions).toHaveLength(1);
     expect(req.questions[0]?.id).toBe("q1");
@@ -207,7 +219,7 @@ describe("QuestionPrompter", () => {
       ],
     });
 
-    const req = sent[0] as QuestionRequest;
+    const req = sent[0] as QuestionRequestEvent;
     expect(req.freeTextPlaceholder).toBe("Type a fruit");
     expect(req.questions[0]?.freeTextPlaceholder).toBe("Type a fruit");
 
@@ -228,7 +240,7 @@ describe("QuestionPrompter", () => {
     void prompter.prompt(threeQuestionParams);
 
     expect(sent).toHaveLength(1);
-    const req = sent[0] as QuestionRequest;
+    const req = sent[0] as QuestionRequestEvent;
     expect(req.questions.map((q) => q.id)).toEqual(["q1", "q2", "q3"]);
     // Flat fields mirror the first entry for backwards compat.
     expect(req.question).toBe("Q1?");
@@ -239,7 +251,7 @@ describe("QuestionPrompter", () => {
     const { prompter, sent } = makePrompter();
 
     const promise = prompter.prompt(threeQuestionParams);
-    const req = sent[0] as QuestionRequest;
+    const req = sent[0] as QuestionRequestEvent;
 
     resolveBatch(req.requestId, [
       { questionId: "q2", kind: "option", optionId: "y" },
@@ -262,7 +274,7 @@ describe("QuestionPrompter", () => {
     const { prompter, sent } = makePrompter();
 
     const promise = prompter.prompt(threeQuestionParams);
-    const req = sent[0] as QuestionRequest;
+    const req = sent[0] as QuestionRequestEvent;
 
     resolveBatch(req.requestId, [
       { questionId: "q1", kind: "skip" },
@@ -279,7 +291,7 @@ describe("QuestionPrompter", () => {
     const { prompter, sent } = makePrompter();
 
     const promise = prompter.prompt(threeQuestionParams);
-    const req = sent[0] as QuestionRequest;
+    const req = sent[0] as QuestionRequestEvent;
 
     closeBatch(req.requestId);
 
@@ -294,12 +306,9 @@ describe("QuestionPrompter", () => {
 
   test("buildBatchEntries rejects unknown questionId", () => {
     expect(() =>
-      buildBatchEntries(
-        ["q1"],
-        () => true,
-        new Set(["q1"]),
-        [{ questionId: "qX", kind: "option", optionId: "a" }],
-      ),
+      buildBatchEntries(["q1"], () => true, new Set(["q1"]), [
+        { questionId: "qX", kind: "option", optionId: "a" },
+      ]),
     ).toThrow(QuestionBatchValidationError);
   });
 
@@ -347,7 +356,7 @@ describe("QuestionPrompter", () => {
       ...threeQuestionParams,
       signal: ac.signal,
     });
-    const req = sent[0] as QuestionRequest;
+    const req = sent[0] as QuestionRequestEvent;
     expect(_piStore.has(req.requestId)).toBe(true);
 
     ac.abort();
@@ -377,7 +386,7 @@ describe("QuestionPrompter", () => {
       ...threeQuestionParams,
       signal: ac.signal,
     });
-    const req = sent[0] as QuestionRequest;
+    const req = sent[0] as QuestionRequestEvent;
     expect(_piStore.has(req.requestId)).toBe(true);
 
     // Simulate `removeByConversation` clearing the registry entry before

package/src/permissions/question-prompter.ts

@@ -1,11 +1,11 @@
 import { v4 as uuid } from "uuid";
 
-import { getConfig } from "../config/loader.js";
 import type {
   QuestionOption,
-  QuestionRequest,
-  ServerMessage,
-} from "../daemon/message-protocol.js";
+  QuestionRequestEvent,
+} from "../api/events/question-request.js";
+import { getConfig } from "../config/loader.js";
+import { broadcastMessage } from "../runtime/assistant-event-hub.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
 import { getLogger } from "../util/logger.js";
@@ -161,10 +161,6 @@ export interface QuestionBatchMetadata {
  * secret prompts, so they share the same idle-timeout knob.
  */
 export class QuestionPrompter {
-  constructor(
-    private deps: { broadcastMessage(msg: ServerMessage): void },
-  ) {}
-
   async prompt(params: QuestionPromptParams): Promise<QuestionPromptResult> {
     const { conversationId, questions, toolUseId, signal } = params;
 
@@ -279,7 +275,7 @@ export class QuestionPrompter {
       // batched payload, and the flat fields mirror `questions[0]` for
       // backwards compat with clients that haven't adopted `questions[]`.
       const head = entries[0]!;
-      const msg: QuestionRequest = {
+      const msg: QuestionRequestEvent = {
         type: "question_request",
         requestId,
         questions: entries,
@@ -291,7 +287,7 @@ export class QuestionPrompter {
         toolUseId,
       };
 
-      this.deps.broadcastMessage(msg);
+      broadcastMessage(msg);
     });
   }
 }

package/src/plugin-api/index.ts

@@ -24,6 +24,7 @@
  * - {@link PluginShutdownContext} — passed to `shutdown` hook at teardown
  * - {@link UserPromptSubmitContext} — passed to `user-prompt-submit` hook,
  *   fired immediately before the agent loop receives a user's prompt
+ * - {@link PluginHookFn} — signature every lifecycle hook implements
  * - {@link PluginLogger} — pino-compatible logger shape on the contexts
  * - {@link ToolDefinition} — author-facing tool spec (default-export shape
  *   for both plugin tool files and workspace tool files)
@@ -39,6 +40,7 @@
 export type { HookName } from "./constants.js";
 export { HOOKS } from "./constants.js";
 export type {
+  PluginHookFn,
   PluginInitContext,
   PluginLogger,
   PluginShutdownContext,

package/src/plugin-api/types.ts

@@ -34,6 +34,22 @@ export interface PluginLogger {
   debug(obj: Record<string, unknown>, msg?: string): void;
 }
 
+// ─── Hook function ───────────────────────────────────────────────────────────
+
+/**
+ * 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 hooks that fan a transformed context out
+ * to downstream plugins (e.g. `user-prompt-submit`).
+ *
+ * Each known hook key has a documented context shape:
+ *   - `init` — {@link PluginInitContext}
+ *   - `shutdown` — {@link PluginShutdownContext}
+ *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
+ */
+export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
+
 // ─── Init context ────────────────────────────────────────────────────────────
 
 /**
@@ -83,9 +99,9 @@ export interface PluginShutdownContext {
 /**
  * Context passed to the `user-prompt-submit` hook. Fires once per user
  * turn, after the agent loop has prepared the message list (PKB / NOW /
- * memory-graph injections, history repair, overflow reduction all already
- * applied) and immediately before the messages are handed to the agent
- * loop's tool/LLM iteration.
+ * memory-graph injections, overflow reduction all already applied) and
+ * immediately before the messages are handed to the agent loop's tool/LLM
+ * iteration.
  *
  * The hook may transform `latestMessages` either by mutating it in place
  * (`push` / `splice` / `length = 0`) or by returning a new context with
@@ -115,4 +131,10 @@ export interface UserPromptSubmitContext {
    * may mutate this in place or replace it by returning a new context.
    */
   latestMessages: Message[];
+  /**
+   * Logger scoped to the current turn. The same instance is shared by
+   * every hook in the chain, so plugins should tag their structured log
+   * fields (e.g. `{ plugin: "<name>" }`) for attribution.
+   */
+  readonly logger: PluginLogger;
 }

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/circuit-breaker/package.json

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

package/src/plugins/defaults/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

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

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

@@ -0,0 +1,35 @@
+/**
+ * Default `compaction` plugin.
+ *
+ * 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 + 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;
+}