@vellumai/assistant 0.8.6 → 0.8.7

package/src/plugins/defaults/memory-retrieval/middlewares/memoryRetrieval.ts

@@ -0,0 +1,17 @@
+import type { MemoryArgs, MemoryResult, Middleware } from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `memoryRetrieval` pipeline.
+ *
+ * Keeping a real middleware registered (rather than an empty list) makes the
+ * pipeline observable in `plugin.pipeline` logs with a non-empty `chain` field
+ * and lets third-party plugins rely on the default slot being present even
+ * when nothing is overriding it. The work happens in the terminal supplied by
+ * the agent loop, which calls `runDefaultMemoryRetrieval`.
+ */
+const defaultMemoryRetrievalMiddleware: Middleware<MemoryArgs, MemoryResult> =
+  async function defaultMemoryRetrieval(args, next) {
+    return next(args);
+  };
+
+export default defaultMemoryRetrievalMiddleware;

package/src/plugins/defaults/memory-retrieval/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-memory-retrieval",
+  "version": "0.0.1",
+  "description": "First-party default plugin wrapping the assistant's built-in memory-retrieval 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/{memory-retrieval.ts → memory-retrieval/register.ts}

@@ -24,22 +24,21 @@
  * milestone.
  */
 
-import type { AssistantConfig } from "../../config/schema.js";
+import type { AssistantConfig } from "../../../config/schema.js";
 import {
   readNowScratchpad,
   readPkbContext,
-} from "../../daemon/conversation-runtime-assembly.js";
-import type { ServerMessage } from "../../daemon/message-protocol.js";
-import type { ConversationGraphMemory } from "../../memory/graph/conversation-graph-memory.js";
-import type { Message } from "../../providers/types.js";
-import { registerPlugin } from "../registry.js";
+} from "../../../daemon/conversation-runtime-assembly.js";
+import type { ServerMessage } from "../../../daemon/message-protocol.js";
+import type { ConversationGraphMemory } from "../../../memory/graph/conversation-graph-memory.js";
+import type { Message } from "../../../providers/types.js";
 import {
   type MemoryArgs,
   type MemoryResult,
-  type Middleware,
   type Plugin,
-  PluginExecutionError,
-} from "../types.js";
+} from "../../types.js";
+import defaultMemoryRetrievalMiddleware from "./middlewares/memoryRetrieval.js";
+import pkg from "./package.json" with { type: "json" };
 
 /**
  * Discriminator the agent loop uses to narrow `MemoryResult.memoryGraphBlocks`
@@ -166,21 +165,6 @@ export function asDefaultGraphPayload(
   return null;
 }
 
-/**
- * Default `memoryRetrieval` middleware — a pure pass-through.
- *
- * Keeping a real middleware registered (rather than an empty list) makes
- * the pipeline observable in `plugin.pipeline` logs with a non-empty
- * `chain` field and lets third-party plugins rely on the default slot
- * being present even when nothing is overriding it. The work happens in
- * the terminal supplied by the agent loop, which calls
- * {@link runDefaultMemoryRetrieval}.
- */
-const defaultMemoryRetrievalMiddleware: Middleware<MemoryArgs, MemoryResult> =
-  async function defaultMemoryRetrieval(args, next) {
-    return next(args);
-  };
-
 /**
  * Default plugin exposing the `memoryRetrieval` pipeline slot. Registered
  * by {@link registerDefaultMemoryRetrievalPlugin} from the plugin
@@ -188,32 +172,10 @@ const defaultMemoryRetrievalMiddleware: Middleware<MemoryArgs, MemoryResult> =
  */
 export const defaultMemoryRetrievalPlugin: Plugin = {
   manifest: {
-    name: "default-memory-retrieval",
-    version: "0.0.1",
+    name: pkg.name,
+    version: pkg.version,
   },
   middleware: {
     memoryRetrieval: defaultMemoryRetrievalMiddleware,
   },
 };
-
-// Module-load side effect: register this default at import time so
-// downstream consumers (including tests that skip `bootstrapPlugins()`)
-// observe a populated registry by default. Idempotent via the swallowed
-// duplicate-name check. Kept local to this module (rather than iterating
-// an array in `defaults/index.ts`) so the registration only references
-// the already-initialized `defaultMemoryRetrievalPlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultMemoryRetrievalPlugin);
-} catch (err) {
-  if (
-    err instanceof PluginExecutionError &&
-    err.message.includes("already registered")
-  ) {
-    // already registered — expected when both index.ts and the direct
-    // file are imported in the same process
-  } else {
-    throw err;
-  }
-}

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

@@ -1,54 +1,29 @@
-/**
- * Default `overflowReduce` plugin — extracted verbatim from the inline
- * preflight reducer loop that previously lived in
- * `daemon/conversation-agent-loop.ts` (the `while (preflightAttempts < …)`
- * block around lines 1045–1156 before PR 23).
- *
- * The plugin owns the reducer tier-loop (forced compaction, tool-result
- * truncation, media stubbing, injection downgrade) and the post-step
- * re-injection / re-estimation dance. Orchestrator-specific coupling
- * (activity emission, circuit-breaker tracking, compaction-result
- * application, runtime injection reassembly) is threaded in through the
- * callbacks carried on {@link OverflowReduceArgs}; the plugin itself has no
- * access to the agent-loop context object.
- *
- * The forced-compaction tier runs through the orchestrator-supplied
- * `compactFn`, which routes into the `compaction` plugin pipeline so
- * registered compaction middleware observes reducer-initiated invocations
- * alongside the orchestrator-owned call sites. Non-compaction tiers
- * (tool-result truncation, media stubbing, injection downgrade) remain
- * in-process: they mutate message arrays directly without crossing a
- * pipeline boundary. The reducer itself runs under the `overflowReduce`
- * pipeline, so the full layering is `overflowReduce` → reducer tier loop
- * → (for the forced-compaction tier only) nested `compaction` pipeline.
- */
-
-import type { ContextWindowCompactOptions } from "../../context/window-manager.js";
+import type { ContextWindowCompactOptions } from "../../../../context/window-manager.js";
 import {
   createInitialReducerState,
   reduceContextOverflow,
   type ReducerState,
-} from "../../daemon/context-overflow-reducer.js";
-import { registerPlugin } from "../registry.js";
-import {
-  type Middleware,
-  type OverflowReduceArgs,
-  type OverflowReduceResult,
-  type Plugin,
-  PluginExecutionError,
-} from "../types.js";
+} from "../../../../daemon/context-overflow-reducer.js";
+import type {
+  Middleware,
+  OverflowReduceArgs,
+  OverflowReduceResult,
+} from "../../../types.js";
 
 /**
- * Default middleware — implements the historical tier-loop semantics.
+ * Default middleware for the `overflowReduce` pipeline — implements the
+ * historical tier-loop semantics (forced compaction, tool-result truncation,
+ * media stubbing, injection downgrade) plus the post-step re-injection /
+ * re-estimation dance.
  *
  * The middleware intentionally ignores `next`. Overflow reduction is a
- * *terminal* behavior: there is no downstream implementation to defer to
- * when a user-supplied middleware short-circuits. Later plugins may still
- * wrap this one (outer middleware can observe each reduction iteration via
- * their own `next` callback) but the default never delegates to a
- * hypothetical base handler — the inline loop was the base.
+ * *terminal* behavior: there is no downstream implementation to defer to when
+ * a user-supplied middleware short-circuits. Later plugins may still wrap this
+ * one (outer middleware can observe each reduction iteration via their own
+ * `next` callback) but the default never delegates to a hypothetical base
+ * handler — the inline loop was the base.
  */
-export const defaultOverflowReduceMiddleware: Middleware<
+const defaultOverflowReduceMiddleware: Middleware<
   OverflowReduceArgs,
   OverflowReduceResult
 > = async function defaultOverflowReduceMiddleware(args, _next, _ctx) {
@@ -148,38 +123,4 @@ export const defaultOverflowReduceMiddleware: Middleware<
   };
 };
 
-/**
- * The default plugin registered at bootstrap. No `init`/`onShutdown` —
- * registering the middleware is the only behavior.
- */
-export const defaultOverflowReducePlugin: Plugin = {
-  manifest: {
-    name: "default-overflow-reduce",
-    version: "1.0.0",
-  },
-  middleware: {
-    overflowReduce: defaultOverflowReduceMiddleware,
-  },
-};
-
-// Module-load side effect: register this default at import time so
-// downstream consumers (including tests that skip `bootstrapPlugins()`)
-// observe a populated registry by default. Idempotent via the swallowed
-// duplicate-name check. Kept local to this module (rather than iterating
-// an array in `defaults/index.ts`) so the registration only references
-// the already-initialized `defaultOverflowReducePlugin` identifier —
-// avoiding a TDZ crash when tests `mock.module(...)` a dependency of any
-// other default plugin and directly import this file.
-try {
-  registerPlugin(defaultOverflowReducePlugin);
-} catch (err) {
-  if (
-    err instanceof PluginExecutionError &&
-    err.message.includes("already registered")
-  ) {
-    // already registered — expected when both index.ts and the direct
-    // file are imported in the same process
-  } else {
-    throw err;
-  }
-}
+export default defaultOverflowReduceMiddleware;

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

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

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

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

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

@@ -0,0 +1,19 @@
+import type { Middleware, PersistArgs, PersistResult } from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `persistence` pipeline. Forwards to
+ * `next(args)` unchanged; the actual dispatch lives in the terminal handler
+ * (`../terminal.ts`), wired in at the `runPipeline` call sites in
+ * `daemon/conversation-agent-loop.ts` and
+ * `daemon/conversation-agent-loop-handlers.ts`.
+ *
+ * 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 passthrough: Middleware<PersistArgs, PersistResult> = async (
+  args,
+  next,
+) => next(args);
+
+export default passthrough;

package/src/plugins/defaults/persistence/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-persistence",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in persistence 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/persistence/register.ts

@@ -0,0 +1,38 @@
+/**
+ * Default `persistence` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual dispatch lives in the terminal handler in
+ * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
+ * `runPipeline` call sites in `daemon/conversation-agent-loop.ts` and
+ * `daemon/conversation-agent-loop-handlers.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.
+ *
+ * Manifest declares `provides.persistence: "v1"` so other plugins can
+ * negotiate against the pipeline surface and `requires.pluginRuntime: "v1"`
+ * to satisfy the registry's mandatory capability check.
+ *
+ * Registered from `daemon/external-plugins-bootstrap.ts` via a side-effect
+ * import so the plugin is present in the registry before
+ * {@link bootstrapPlugins} walks it.
+ *
+ * Design doc: `.private/plans/agent-plugin-system.md` (PR 27).
+ */
+
+import { type Plugin } from "../../types.js";
+import persistence from "./middlewares/persistence.js";
+import pkg from "./package.json" with { type: "json" };
+
+export const defaultPersistencePlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  middleware: {
+    persistence,
+  },
+};

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

@@ -0,0 +1,83 @@
+/**
+ * Default `persistence` behavior: writes conversation messages to the database
+ * (and optionally the JSONL disk view).
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * The handler dispatches on the discriminated {@link PersistArgs.op} field:
+ *
+ * - `add`           → {@link addMessage}, optionally followed by
+ *                     {@link syncMessageToDisk} when `args.syncToDisk` is true.
+ * - `reserve`       → {@link reserveMessage} — pre-allocates an empty row
+ *                     for assistant anchor stamping.
+ * - `updateContent` → {@link updateMessageContent} — overwrites an existing
+ *                     row's content (returns `void`, wrapped as
+ *                     `{ op: "updateContent" }`).
+ * - `update`        → {@link updateMessageMetadata} (returns `void`, wrapped
+ *                     as `{ op: "update" }`).
+ * - `delete`        → {@link deleteMessageById} (returns the segment/summary
+ *                     IDs the caller must clean up out-of-band).
+ */
+
+import {
+  addMessage,
+  deleteMessageById,
+  reserveMessage,
+  updateMessageContent,
+  updateMessageMetadata,
+} from "../../../memory/conversation-crud.js";
+import { syncMessageToDisk } from "../../../memory/conversation-disk-view.js";
+import type { PersistArgs, PersistResult } from "../../types.js";
+
+/**
+ * Persist a message according to `args.op`. Exported so the agent-loop call
+ * sites can invoke it directly and tests can verify each op in isolation.
+ */
+export async function defaultPersistenceTerminal(
+  args: PersistArgs,
+): Promise<PersistResult> {
+  switch (args.op) {
+    case "add": {
+      const message = await addMessage(
+        args.conversationId,
+        args.role,
+        args.content,
+        {
+          metadata: args.metadata,
+          ...args.addOptions,
+        },
+      );
+      // Sync the just-persisted row to the JSONL disk view when the caller
+      // opted in. The handler that emits tool-result rows sets
+      // `syncToDisk: true` so the disk view stays in lockstep with the DB.
+      if (args.syncToDisk && args.createdAtMs !== undefined) {
+        syncMessageToDisk(args.conversationId, message.id, args.createdAtMs);
+      }
+      return { op: "add", message };
+    }
+    case "reserve": {
+      const message = await reserveMessage(
+        args.conversationId,
+        args.role,
+        args.metadata,
+      );
+      return { op: "reserve", message };
+    }
+    case "updateContent": {
+      updateMessageContent(args.messageId, args.content);
+      return { op: "updateContent" };
+    }
+    case "update": {
+      updateMessageMetadata(args.messageId, args.updates);
+      return { op: "update" };
+    }
+    case "delete": {
+      const deleted = deleteMessageById(args.messageId);
+      return {
+        op: "delete",
+        segmentIds: deleted.segmentIds,
+        deletedSummaryIds: deleted.deletedSummaryIds,
+      };
+    }
+  }
+}

package/src/plugins/defaults/title-generate/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-title-generate",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in title-generate 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/title-generate/register.ts

@@ -0,0 +1,35 @@
+/**
+ * Default `titleGenerate` pipeline plugin.
+ *
+ * Declares no middleware — the terminal handler in `./terminal.ts` is wired in
+ * as the pipeline's `terminal` argument by the `runPipeline` call site in
+ * `daemon/conversation-agent-loop.ts`. This plugin exists purely to negotiate
+ * the `titleGenerateApi` capability so bootstrap has a record that the
+ * assistant runtime exposes this pipeline.
+ *
+ * Registered via a side-effect import from
+ * `daemon/external-plugins-bootstrap.ts` so it is present in the registry
+ * by the time {@link bootstrapPlugins} runs.
+ */
+
+import { type Plugin } from "../../types.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * Default titleGenerate plugin. Declares no middleware — it exists purely
+ * to negotiate the `titleGenerateApi` capability so bootstrap has a record
+ * that the assistant runtime exposes this pipeline.
+ *
+ * The terminal handler (`./terminal.ts`) is supplied at the call site in
+ * `conversation-agent-loop.ts` rather than through `middleware.titleGenerate`,
+ * because a default middleware would short-circuit user-registered middleware
+ * by always running first in onion order. Keeping the terminal outside the
+ * middleware chain lets user plugins observe/transform/short-circuit the
+ * call without competing with an assistant-owned default middleware.
+ */
+export const defaultTitleGeneratePlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+};

package/src/plugins/defaults/title-generate/terminal.ts

@@ -0,0 +1,31 @@
+/**
+ * Default `titleGenerate` behavior: kicks off conversation-title generation.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * Delegates to {@link queueGenerateConversationTitle}, which schedules title
+ * generation as fire-and-forget background work and falls back to a
+ * deterministic placeholder on failure.
+ */
+
+import { queueGenerateConversationTitle } from "../../../memory/conversation-title-service.js";
+import type { TitleArgs, TitleResult } from "../../types.js";
+
+/**
+ * Invoke the title-generation service with the provided arguments. Exported
+ * for tests that want to exercise the default directly.
+ *
+ * Returns an empty result — the service is fire-and-forget and surfaces its
+ * output through `onTitleUpdated`.
+ */
+export async function defaultTitleGenerateTerminal(
+  args: TitleArgs,
+): Promise<TitleResult> {
+  queueGenerateConversationTitle({
+    conversationId: args.conversationId,
+    provider: args.provider,
+    userMessage: args.userMessage,
+    onTitleUpdated: args.onTitleUpdated,
+  });
+  return {};
+}

package/src/plugins/defaults/token-estimate/middlewares/tokenEstimate.ts

@@ -0,0 +1,23 @@
+import type {
+  EstimateArgs,
+  EstimateResult,
+  Middleware,
+} from "../../../types.js";
+
+/**
+ * Passthrough middleware for the `tokenEstimate` pipeline. Forwards to
+ * `next(args)` unchanged; the actual estimate lives in the terminal handler
+ * (`../terminal.ts`), wired in at the `runPipeline` call sites in
+ * `daemon/conversation-agent-loop.ts`.
+ *
+ * Defaults register at the OUTERMOST onion position, so deciding here without
+ * calling `next` would shadow every later-registered plugin. The passthrough
+ * lets user middleware that wraps the default (e.g. a doubler, a
+ * provider-native `countTokens` override) participate normally.
+ */
+const passthrough: Middleware<EstimateArgs, EstimateResult> = async (
+  args,
+  next,
+) => next(args);
+
+export default passthrough;

package/src/plugins/defaults/token-estimate/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "default-token-estimate",
+  "version": "1.0.0",
+  "description": "First-party default plugin wrapping the assistant's built-in token-estimate 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/token-estimate/register.ts

@@ -0,0 +1,34 @@
+/**
+ * Default `tokenEstimate` plugin.
+ *
+ * The plugin's middleware is a passthrough — it calls `next(args)` and returns
+ * the result unchanged. The actual estimate lives in the terminal handler in
+ * `./terminal.ts`, which is wired in as the pipeline's `terminal` argument by
+ * `runPipeline` call sites 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. The passthrough lets user middleware that wraps the
+ * default (e.g. a doubler, a provider-native `countTokens` override)
+ * participate normally.
+ */
+
+import { type Plugin } from "../../types.js";
+import tokenEstimate from "./middlewares/tokenEstimate.js";
+import pkg from "./package.json" with { type: "json" };
+
+/**
+ * Default `tokenEstimate` plugin. Registered by
+ * {@link bootstrapPlugins} on daemon startup so the pipeline always has a
+ * terminal handler even when no other plugin contributes one.
+ */
+export const defaultTokenEstimatePlugin: Plugin = {
+  manifest: {
+    name: pkg.name,
+    version: pkg.version,
+  },
+  middleware: {
+    tokenEstimate,
+  },
+};

package/src/plugins/defaults/token-estimate/terminal.ts

@@ -0,0 +1,40 @@
+/**
+ * Default `tokenEstimate` behavior: estimates the prompt token count used by
+ * the overflow gate.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ *
+ * Delegates to
+ * {@link estimatePromptTokens}, which applies the EWMA calibration correction
+ * recorded from past provider responses. Preflight + mid-loop checks must use
+ * the calibrated estimate — the calibrated value keeps the overflow gate
+ * consistent with the convergence path in the reducer. The pre-send
+ * calibration capture in `agent/loop.ts` still uses `estimatePromptTokensRaw`
+ * on purpose — the calibrator must learn against the raw estimate so the EWMA
+ * converges against provider ground truth rather than chasing its own
+ * corrected output. This path produces the user-facing estimate; calibration
+ * capture stays separate.
+ */
+
+import {
+  estimatePromptTokens,
+  estimateToolsTokens,
+} from "../../../context/token-estimator.js";
+import type { EstimateArgs, EstimateResult } from "../../types.js";
+
+/**
+ * Compute the tool token budget from `args.tools` and delegate to
+ * {@link estimatePromptTokens} with the canonical provider key, applying the
+ * EWMA calibration correction. Exported so the agent loop can call it directly
+ * and tests can verify the default behavior.
+ */
+export const defaultTokenEstimateTerminal = async (
+  args: EstimateArgs,
+): Promise<EstimateResult> => {
+  const toolTokenBudget =
+    args.tools.length > 0 ? estimateToolsTokens(args.tools) : 0;
+  return estimatePromptTokens(args.history, args.systemPrompt, {
+    providerName: args.providerName,
+    toolTokenBudget,
+  });
+};