@vellumai/assistant 0.8.8 → 0.8.9-staging.2

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

@@ -0,0 +1,59 @@
+/**
+ * Default compaction implementation.
+ *
+ * Summarizes conversation history when the context window fills up by
+ * delegating to a {@link ContextWindowManager}. The agent loop calls
+ * {@link defaultCompact} directly with a {@link CompactionContext}; the request
+ * carries the conversational inputs while the manager performs the work.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ */
+
+import type {
+  ContextWindowManager,
+  ContextWindowResult,
+} from "../../../context/window-manager.js";
+import type { Message } from "../../../providers/types.js";
+import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+
+/**
+ * Name under which the default compaction plugin registers. Exposed so call
+ * sites can attribute compaction failures to the default plugin.
+ */
+export const DEFAULT_COMPACTION_PLUGIN_NAME = "default-compaction";
+
+/**
+ * Self-describing compaction request handed to {@link defaultCompact}. Carries
+ * the conversational inputs plus the {@link ContextWindowManager} that runs the
+ * summary, so the request is the part that can grow toward a model-facing
+ * compaction-method shape without coupling callers to the manager's option bag.
+ */
+export interface CompactionContext {
+  /** Context window manager that performs the compaction. */
+  manager: ContextWindowManager;
+  /** Message history to consider for compaction. */
+  messages: Message[];
+  /** Abort signal forwarded to the compaction summary call. */
+  signal?: AbortSignal;
+  /** Skip the auto-threshold check (forced/overflow/emergency compaction). */
+  force?: boolean;
+  /** Per-conversation inference-profile override for the summary call. */
+  overrideProfile?: string | null;
+  /** Pre-computed token estimate from a prior `shouldCompact()` call. */
+  precomputedEstimate?: number;
+  /** Legacy keep-boundary hint forwarded to the compactor. */
+  minKeepRecentUserTurns?: number;
+  /** Trust class of the actor whose turn triggered compaction. */
+  actorTrustClass?: TrustClass;
+}
+
+/**
+ * Run compaction for the turn: delegates to the request's context window
+ * manager and returns the (possibly summarized) message history.
+ */
+export async function defaultCompact(
+  context: CompactionContext,
+): Promise<ContextWindowResult> {
+  const { manager, messages, signal, ...options } = context;
+  return manager.maybeCompact(messages, signal, options);
+}

package/src/{daemon → plugins/defaults/compaction}/context-overflow-reducer.ts

@@ -16,23 +16,23 @@
  *   4. Runtime injection downgrade to minimal mode
  */
 
-import type { ContextWindowConfig } from "../config/types.js";
+import type { ContextWindowConfig } from "../../../config/types.js";
 import {
   estimateContentBlockTokens,
   estimatePromptTokens,
-} from "../context/token-estimator.js";
-import { truncateToolResultsAcrossHistory } from "../context/tool-result-truncation.js";
+} from "../../../context/token-estimator.js";
+import { truncateToolResultsAcrossHistory } from "../../../context/tool-result-truncation.js";
 import type {
   ContextWindowCompactOptions,
   ContextWindowResult,
-} from "../context/window-manager.js";
-import type { Message } from "../providers/types.js";
+} from "../../../context/window-manager.js";
 import {
   countMediaBlocks,
   estimateUnconditionalStubTokens,
   stripMediaPayloadsForRetry,
-} from "./conversation-media-retry.js";
-import type { InjectionMode } from "./conversation-runtime-assembly.js";
+} from "../../../daemon/conversation-media-retry.js";
+import type { InjectionMode } from "../../../daemon/conversation-runtime-assembly.js";
+import type { Message } from "../../../providers/types.js";
 
 /**
  * Identifies which reduction tier was applied in a given step.

package/src/plugins/defaults/compaction/manager-store.ts

@@ -0,0 +1,57 @@
+/**
+ * Per-conversation {@link ContextWindowManager} ownership for the default
+ * compaction module.
+ *
+ * Construction of the manager lives here rather than in the conversation so the
+ * compaction surface owns the manager's lifetime: {@link createContextWindowManager}
+ * builds the instance and records it in a per-conversation store, and
+ * {@link disposeContextWindowManager} drops it when the conversation is torn
+ * down so the store doesn't grow unbounded.
+ *
+ * This module is side-effect free: importing it only initializes an empty
+ * store and registers no plugin.
+ */
+
+import {
+  ContextWindowManager,
+  type ContextWindowManagerOptions,
+} from "../../../context/window-manager.js";
+
+/** Live managers keyed by conversation id. */
+const managersByConversation = new Map<string, ContextWindowManager>();
+
+/**
+ * Build the conversation's {@link ContextWindowManager} and register it under
+ * its conversation id. Construction is owned by the compaction module; the
+ * conversation supplies the provider, prompt/tool resolvers, and initial
+ * config. Replaces any prior manager for the same conversation so each
+ * construction yields a fresh instance, matching a direct `new` call.
+ */
+export function createContextWindowManager(
+  options: ContextWindowManagerOptions & { conversationId: string },
+): ContextWindowManager {
+  const manager = new ContextWindowManager(options);
+  managersByConversation.set(options.conversationId, manager);
+  return manager;
+}
+
+/**
+ * Resolve the manager registered for a conversation, or `undefined` when none
+ * is registered (the conversation was never constructed or has been torn
+ * down). The store is the single owner of the instance; the conversation, its
+ * agent loop, and the compaction surface all read through this lookup rather
+ * than holding their own handle.
+ */
+export function getContextWindowManager(
+  conversationId: string,
+): ContextWindowManager | undefined {
+  return managersByConversation.get(conversationId);
+}
+
+/**
+ * Release the manager registered for a conversation. Called from conversation
+ * teardown so the store releases the instance once the conversation is gone.
+ */
+export function disposeContextWindowManager(conversationId: string): void {
+  managersByConversation.delete(conversationId);
+}

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

@@ -1,11 +1,10 @@
 {
   "name": "default-compaction",
   "version": "1.0.0",
-  "description": "First-party default plugin wrapping the assistant's built-in compaction pipeline with a passthrough implementation.",
+  "description": "First-party default plugin providing the assistant's built-in conversation-history compaction.",
   "private": true,
   "license": "MIT",
   "type": "module",
-  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },

package/src/plugins/defaults/empty-response/package.json

@@ -5,7 +5,6 @@
   "private": true,
   "license": "MIT",
   "type": "module",
-  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },

package/src/plugins/defaults/history-repair/package.json

@@ -5,7 +5,6 @@
   "private": true,
   "license": "MIT",
   "type": "module",
-  "main": "./register.ts",
   "engines": {
     "node": ">=20.12.0"
   },

package/src/plugins/defaults/index.ts

@@ -1,9 +1,12 @@
 /**
- * Aggregate export of the first-party default plugins.
+ * First-party default plugins — definitions and centralized registration.
  *
- * Each default wraps one of the assistant's built-in pipelines with a
- * passthrough implementation so the pipeline shape is always explicit at boot
- * and at test time, even when no third-party plugins are loaded.
+ * Each default contributes the hooks for one of the assistant's built-in
+ * behaviors (history repair, title generation, tool-error coaching, …) so the
+ * lifecycle is always populated at boot and at test time, even when no
+ * third-party plugins are loaded. A `Plugin` is the manifest (name/version,
+ * sourced from the sibling `package.json`) plus its hook map; the hook
+ * implementations live in each `defaults/<name>/hooks/` directory.
  *
  * Consumers:
  *
@@ -16,44 +19,150 @@
  *   production-parity state (e.g. `conversation-agent-loop.test.ts`); those
  *   call {@link resetPluginRegistryAndRegisterDefaults}.
  *
- * Each `defaults/<name>/register.ts` module only builds and exports its
- * `Plugin` object; registration is centralized here. The plugin identifiers
- * are dereferenced inside {@link registerDefaultPlugins} at call time, once
- * every module has finished initializing, so importing this aggregator does no
- * registration work.
+ * The plugin definitions below are plain `const`s, so importing this module
+ * does no registration work — registration is driven by
+ * {@link registerDefaultPlugins} at call time.
  */
 
 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 { 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";
+import compactionPkg from "./compaction/package.json" with { type: "json" };
+import emptyResponseStop from "./empty-response/hooks/stop.js";
+import emptyResponsePkg from "./empty-response/package.json" with { type: "json" };
+import historyRepairUserPromptSubmit from "./history-repair/hooks/user-prompt-submit.js";
+import historyRepairPkg from "./history-repair/package.json" with { type: "json" };
+import memoryV3PostCompact from "./memory-v3-shadow/hooks/post-compact.js";
+import memoryV3UserPromptSubmit from "./memory-v3-shadow/hooks/user-prompt-submit.js";
+import memoryV3Pkg from "./memory-v3-shadow/package.json" with { type: "json" };
+import titleGenerateStop from "./title-generate/hooks/stop.js";
+import titleGenerateUserPromptSubmit from "./title-generate/hooks/user-prompt-submit.js";
+import titleGeneratePkg from "./title-generate/package.json" with { type: "json" };
+import toolErrorPostToolUse from "./tool-error/hooks/post-tool-use.js";
+import toolErrorPkg from "./tool-error/package.json" with { type: "json" };
+import toolResultTruncatePostToolUse from "./tool-result-truncate/hooks/post-tool-use.js";
+import toolResultTruncatePkg from "./tool-result-truncate/package.json" with { type: "json" };
+
+/**
+ * `compaction` — compaction is implemented in `compaction/compact.ts` as
+ * `defaultCompact`, which the agent loop calls directly. 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
+ * hooks today.
+ */
+export const defaultCompactionPlugin: Plugin = {
+  manifest: {
+    name: compactionPkg.name,
+    version: compactionPkg.version,
+  },
+};
+
+/**
+ * `empty-response` — a `stop` hook that re-queries the model when a turn
+ * yields with no tool calls but came back empty (or as a provider refusal).
+ */
+export const defaultEmptyResponsePlugin: Plugin = {
+  manifest: {
+    name: emptyResponsePkg.name,
+    version: emptyResponsePkg.version,
+  },
+  hooks: {
+    stop: emptyResponseStop,
+  },
+};
+
+/**
+ * `history-repair` — a `user-prompt-submit` hook that normalizes the working
+ * message history (tool-use/tool-result pairing, role alternation) before the
+ * agent loop hands it to the provider.
+ */
+export const defaultHistoryRepairPlugin: Plugin = {
+  manifest: {
+    name: historyRepairPkg.name,
+    version: historyRepairPkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": historyRepairUserPromptSubmit,
+  },
+};
+
+/**
+ * `memory-v3-shadow` — houses the memory-v3 shadow/live orchestration engine
+ * (`memory-v3-shadow/`) and its injector. The `user-prompt-submit` /
+ * `post-compact` hooks are no-op scaffolding for the eventual convergence,
+ * when v3 injection moves off the loop-driven chain and into these hooks.
+ */
+export const memoryV3ShadowPlugin: Plugin = {
+  manifest: {
+    name: memoryV3Pkg.name,
+    version: memoryV3Pkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": memoryV3UserPromptSubmit,
+    "post-compact": memoryV3PostCompact,
+  },
+};
+
+/**
+ * `title-generate` — two pure-trigger hooks that delegate the title work to
+ * the conversation-title service: `user-prompt-submit` (first-pass title) and
+ * `stop` (second-pass regeneration once the topic is established).
+ */
+export const defaultTitleGeneratePlugin: Plugin = {
+  manifest: {
+    name: titleGeneratePkg.name,
+    version: titleGeneratePkg.version,
+  },
+  hooks: {
+    "user-prompt-submit": titleGenerateUserPromptSubmit,
+    stop: titleGenerateStop,
+  },
+};
+
+/**
+ * `tool-error` — a `post-tool-use` hook that coaches the model to retry or
+ * report a failed tool call, bounded per tool. The coaching is surfaced via
+ * `additionalContext`, leaving the tool result's own content untouched.
+ */
+export const defaultToolErrorPlugin: Plugin = {
+  manifest: {
+    name: toolErrorPkg.name,
+    version: toolErrorPkg.version,
+  },
+  hooks: {
+    "post-tool-use": toolErrorPostToolUse,
+  },
+};
+
+/**
+ * `tool-result-truncate` — a `post-tool-use` hook that tail-drops an oversized
+ * tool result down to a character budget derived from the model's context
+ * window before the result is sent to the provider.
+ */
+export const defaultToolResultTruncatePlugin: Plugin = {
+  manifest: {
+    name: toolResultTruncatePkg.name,
+    version: toolResultTruncatePkg.version,
+  },
+  hooks: {
+    "post-tool-use": toolResultTruncatePostToolUse,
+  },
+};
 
 /**
  * Full set of first-party default plugins. Used by
  * {@link registerDefaultPlugins} to drive the registration loop; the array
- * order is the registration order, which determines onion order for middleware
- * composition (defaults innermost, user plugins outermost).
- *
- * Returned by a function rather than a top-level `const` so the array
- * contents are read at call time, after every imported plugin identifier is
- * guaranteed initialized.
+ * order is the registration order, which fixes hook-chain order (defaults run
+ * ahead of any later-registered user plugins).
  */
 function getAllDefaultPlugins(): readonly Plugin[] {
   return [
     defaultToolResultTruncatePlugin,
     defaultEmptyResponsePlugin,
     defaultToolErrorPlugin,
-    defaultOverflowReducePlugin,
     defaultHistoryRepairPlugin,
     defaultCompactionPlugin,
-    defaultCircuitBreakerPlugin,
     defaultTitleGeneratePlugin,
+    memoryV3ShadowPlugin,
   ];
 }
 
@@ -85,7 +194,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. overflowReduce).
+ * plugin handles every op (e.g. compaction).
  *
  * Tests that specifically need an empty registry (pipeline-unit tests, the
  * plugin-registry tests themselves) should continue to call

package/src/plugins/defaults/memory-retrieval/hooks/post-compact.ts

@@ -10,82 +10,130 @@
  * history (and the blocks it captured), with no dependency on the agent loop's
  * closure state.
  *
- * It re-applies the runtime injections via {@link applyRuntimeInjections},
- * re-tracks the memory graph's cached nodes against the re-injected history,
- * and converts now-historical `web_search_tool_result` blocks to text so their
- * expired `encrypted_content` tokens are not replayed. The remaining
- * orchestrator-side step (the post-injection bookkeeping the loop records) is
- * expected to migrate here as the hook subsumes the loop's re-injection
- * ceremony.
+ * It re-applies the runtime injections via {@link applyRuntimeInjections} and
+ * re-tracks the memory graph's cached nodes against the re-injected history.
+ * The remaining orchestrator-side step (the post-injection bookkeeping the
+ * loop records) is expected to migrate here as the hook subsumes the loop's
+ * re-injection ceremony.
  *
  * The memory graph handle is sourced internally from the plugin's own
  * conversation-keyed registry ({@link getLiveGraphMemory}) rather than being
  * threaded in by the loop — it is memory-retrieval-specific state, not
- * something the generic loop or the shared {@link TurnContext} should carry.
+ * something the generic loop should carry.
  */
 
 import {
   applyRuntimeInjections,
-  type RuntimeInjectionOptions,
+  type InboundActorContext,
+  type InjectionMode,
   type RuntimeInjectionResult,
 } from "../../../../daemon/conversation-runtime-assembly.js";
-import { stripHistoricalWebSearchResults } from "../../../../daemon/web-search-history.js";
+import {
+  resolveTrustClass,
+  type TrustContext,
+} from "../../../../daemon/trust-context.js";
 import { getLiveGraphMemory } from "../../../../memory/graph/conversation-graph-memory.js";
-import type { PluginLogger } from "../../../../plugin-api/types.js";
 import type { Message } from "../../../../providers/types.js";
-import type { TurnContext } from "../../../types.js";
 
 /**
- * The slice of the hook's context the agent loop supplies from its own working
- * state. Re-injection inputs migrate loop-ward by growing this type; the loop
- * hands the hook an object of this shape via
- * {@link MidLoopCompaction.postCompactionHook}.
+ * Everything the post-compaction hook needs, supplied by the agent loop from
+ * its own working state. Re-injection inputs migrate loop-ward by growing this
+ * type; the loop hands the hook an object of this shape when it calls
+ * {@link postCompact} directly.
+ *
+ * The turn-identity fields are flat here: `conversationId` is the key the
+ * re-injection resolves the live conversation through (and the only one that,
+ * together with `requestId` and `trust`, cannot be recovered from that live
+ * conversation), while `turnIndex` and `callSite` are intentionally omitted so
+ * {@link applyRuntimeInjections} self-resolves them from the live conversation.
+ * The memory graph handle is likewise sourced internally via
+ * {@link getLiveGraphMemory} rather than threaded in.
  */
-export interface PostCompactionHookInput {
+export interface PostCompactContext {
   /** Compacted message history to re-inject onto. */
   history: Message[];
-  /** Per-turn conversation context forwarded to the injector chain. */
-  turnContext?: TurnContext;
+  /**
+   * Stable ID for the current request, forwarded onto the injector turn
+   * context. The one turn-identity field that cannot be recovered from the
+   * live conversation, so the loop supplies it.
+   */
+  requestId: string | undefined;
+  /**
+   * Conversation the turn is scoped to. The key the re-injection resolves the
+   * live conversation (and its channel/trust/transcript state) through, so the
+   * loop always supplies it.
+   */
+  conversationId: string;
+  /**
+   * Trust classification and channel identity for the inbound actor, forwarded
+   * onto the injector turn context and used to gate the memory-graph re-track.
+   * Supplied by the loop as the turn-start snapshot rather than re-resolved
+   * mid-turn.
+   */
+  trust: TrustContext;
+  /**
+   * Whether the in-flight turn has no human present to answer clarification
+   * questions. Resolved once by the agent loop at turn start (from its
+   * `isInteractive` option, which can fall back to mutable client/headless
+   * state that flips mid-turn on SSE reconnect) and handed to the hook here, so
+   * re-injection uses the loop's turn-start snapshot rather than re-reading
+   * live conversation state.
+   */
+  isNonInteractive: boolean;
+  /**
+   * Injection volume for the re-applied blocks. Owned by the agent loop, which
+   * drops to `"minimal"` when overflow reduction trims the prompt; handed to
+   * the hook here so re-injection matches the loop's committed decision instead
+   * of re-deriving it.
+   */
+  mode: InjectionMode;
+  /**
+   * The `model_profile:` turn-context label, or `null` when the active
+   * inference profile is unchanged since the last notified one. The agent loop
+   * resolves it once at turn start from config and the turn's profile override,
+   * and notifies the model only on change — a decision that flips mid-turn once
+   * the notification is persisted, so it cannot be re-derived. Handed to the
+   * hook here so re-injection re-emits the loop's turn-start value.
+   */
+  modelProfile: string | null;
+  /**
+   * Inbound actor identity and trust fields for the unified `<turn_context>`
+   * block, or `null` on guardian turns (which suppress the actor section). The
+   * agent loop resolves it once at turn start via the actor-trust resolver,
+   * whose contact/member registry inputs can be mutated mid-turn by contact
+   * tools, so it cannot be re-derived. Handed to the hook here so re-injection
+   * re-emits the loop's turn-start value.
+   */
+  actorContext: InboundActorContext | null;
 }
 
-/**
- * Everything the hook needs in a single context: the loop-supplied
- * {@link PostCompactionHookInput}, the resolved {@link RuntimeInjectionOptions}
- * (spread top-level so each field stays individually addressable), and the
- * conversation-scoped state the options bag cannot carry (actor trust and a
- * turn-scoped logger). The memory graph handle is not part of this context —
- * the hook sources it internally via {@link getLiveGraphMemory}.
- */
-export interface PostCompactContext
-  extends RuntimeInjectionOptions, PostCompactionHookInput {
-  /** True when the actor for this turn is trusted (guardian-class). */
-  isTrustedActor: boolean;
-  /** Turn-scoped logger for diagnostics emitted while re-injecting. */
-  logger: PluginLogger;
-}
-
-export default async function postCompactReinject(
+export default async function postCompact(
   ctx: PostCompactContext,
 ): Promise<RuntimeInjectionResult> {
-  const { history, isTrustedActor, logger, ...options } = ctx;
-  const result = await applyRuntimeInjections(history, options);
+  const { history, requestId, conversationId, trust, ...options } = ctx;
+  // The remaining `options` carry the non-identity injection inputs
+  // (`isNonInteractive`, `mode`, `modelProfile`, `actorContext`). Forward the
+  // turn-identity fields the live conversation can't supply (`requestId`,
+  // `conversationId`, `trust`); `turnIndex` and `callSite` self-resolve from
+  // the live conversation so the re-injection matches the turn's initial
+  // assembly.
+  const result = await applyRuntimeInjections(history, {
+    ...options,
+    requestId,
+    conversationId,
+    trust,
+  });
   // Re-track the nodes the memory graph last injected so they survive against
   // the re-injected history. Untrusted actors and minimal-mode turns never
   // received a memory-graph injection, so there is nothing to re-track. The
-  // live graph handle is looked up from the plugin's own registry by the
-  // turn's conversation id — the same instance the turn's retrieval mutated,
-  // so re-tracking sees the real cached-node state.
+  // actor's trust class is derived from the turn's own trust context (the same
+  // value the injector chain resolves). The live graph handle is looked up
+  // from the plugin's own registry by the turn's conversation id — the same
+  // instance the turn's retrieval mutated, so re-tracking sees the real
+  // cached-node state.
+  const isTrustedActor = resolveTrustClass(trust) === "guardian";
   if (isTrustedActor && options.mode !== "minimal") {
-    getLiveGraphMemory(
-      options.turnContext?.conversationId,
-    )?.retrackCachedNodes();
-  }
-  const strip = stripHistoricalWebSearchResults(result.messages);
-  if (strip.stats.blocksStripped > 0) {
-    logger.info(
-      { phase: "mid-loop-compact", ...strip.stats },
-      "Converted historical web_search_tool_result blocks to text summaries",
-    );
+    getLiveGraphMemory(conversationId)?.retrackCachedNodes();
   }
-  return { ...result, messages: strip.messages };
+  return result;
 }