@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091853.fbaa2ae

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

@@ -1,73 +0,0 @@
-/**
- * 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/empty-response/register.ts

@@ -1,23 +0,0 @@
-/**
- * Default `empty-response` plugin.
- *
- * Contributes 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). The decision
- * logic lives in `./hooks/stop.ts`. Defaults register before user plugins, so
- * this runs at the front of the `stop` hook chain.
- */
-
-import { type Plugin } from "../../types.js";
-import stop from "./hooks/stop.js";
-import pkg from "./package.json" with { type: "json" };
-
-/** Singleton plugin — the registry rejects duplicate registrations by name. */
-export const defaultEmptyResponsePlugin: Plugin = {
-  manifest: {
-    name: pkg.name,
-    version: pkg.version,
-  },
-  hooks: {
-    stop,
-  },
-};

package/src/plugins/defaults/history-repair/register.ts

@@ -1,24 +0,0 @@
-/**
- * Default `history-repair` plugin.
- *
- * Contributes 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. The repair implementation lives in
- * `./terminal.ts`; the hook in `./hooks/user-prompt-submit.ts` wires it into
- * the lifecycle. Defaults register before user plugins, so this normalization
- * runs at the front of the hook chain.
- */
-
-import { type Plugin } from "../../types.js";
-import userPromptSubmit from "./hooks/user-prompt-submit.js";
-import pkg from "./package.json" with { type: "json" };
-
-export const defaultHistoryRepairPlugin: Plugin = {
-  manifest: {
-    name: pkg.name,
-    version: pkg.version,
-  },
-  hooks: {
-    "user-prompt-submit": userPromptSubmit,
-  },
-};

package/src/plugins/defaults/memory-retrieval/hooks/user-prompt-submit-temp.ts

@@ -1,216 +0,0 @@
-/**
- * Default `user-prompt-submit-temp` hook: runs the memory-graph retrieval the
- * agent loop needs before building a turn's runtime-injection block.
- *
- * **Memory graph** via {@link ConversationGraphMemory.prepareMemory} —
- * dispatches to context-load or per-turn retrieval depending on initialization
- * state; gated on the actor being trusted (guardian).
- *
- * The hook also owns the retrieval's side effects — persisting the injected
- * block onto the user message's metadata, writing the recall log, and emitting
- * the `memory_recalled` event — so the loop only consumes the turn-scoped
- * `latestMessages` written back onto the context. The PKB query-vector pair is
- * recorded on the conversation's graph handle for the PKB-reminder injector to
- * read back. PKB context and NOW.md are sourced directly by their injectors
- * (gated on block presence), not produced here.
- *
- * This fires at the early "prompt submitted, before context assembly" moment,
- * distinct from the canonical late `user-prompt-submit` hook (history repair,
- * title): memory's outputs feed the injection and overflow-reduction transforms
- * that run between the two moments. The `-temp` suffix marks this as a
- * transitional staging point that folds into `user-prompt-submit` once
- * compaction is cleared from the gap between the two call sites.
- */
-
-import type { PluginHookFn } from "@vellumai/plugin-api";
-import type { Logger } from "pino";
-
-import type { AssistantConfig } from "../../../../config/schema.js";
-import type { ServerMessage } from "../../../../daemon/message-protocol.js";
-import type { MemoryRecalled } from "../../../../daemon/message-types/memory.js";
-import { updateMessageMetadata } from "../../../../memory/conversation-crud.js";
-import type { ConversationGraphMemory } from "../../../../memory/graph/conversation-graph-memory.js";
-import { recordMemoryRecallLog } from "../../../../memory/memory-recall-log-store.js";
-import type { Message } from "../../../../providers/types.js";
-import type { GraphMemoryResult } from "../../../types.js";
-
-/**
- * Context threaded through the `user-prompt-submit-temp` hook. The readonly
- * fields carry the conversation-scoped state the retriever needs (graph
- * handle, event sink, abort signal); the output fields are populated by the
- * hook and read back by the agent loop. `latestMessages` straddles both: the
- * loop seeds it with the pre-injection array and the hook overwrites it with
- * the injected result.
- */
-export interface MemoryRetrievalHookContext {
-  /** Per-conversation memory graph handle. */
-  readonly graphMemory: ConversationGraphMemory;
-  /** Assistant config snapshot. */
-  readonly config: AssistantConfig;
-  /** Event sink used by the graph retriever and `memory_recalled` emission. */
-  readonly onEvent: (msg: ServerMessage) => void;
-  /** True when the actor for this turn is trusted (guardian-class). */
-  readonly isTrustedActor: boolean;
-  /** Conversation the turn belongs to — keys the recall-log row. */
-  readonly conversationId: string;
-  /** User message the injected memory block is persisted onto. */
-  readonly userMessageId: string;
-  /** Turn-scoped logger for non-fatal persistence warnings. */
-  readonly logger: Logger;
-  /**
-   * Per-turn abort signal forwarded to `prepareMemory`. An external cancel
-   * aborts the underlying retrieval instead of letting it run to completion.
-   */
-  readonly signal: AbortSignal;
-  /**
-   * Working message list for the turn. Seeded by the loop with the
-   * pre-injection messages and consumed as the retrieval input; the hook
-   * overwrites it with the memory-graph block injected, or leaves it
-   * unchanged when no graph retrieval ran (untrusted actor, or a no-op
-   * retrieval). Read back by the loop.
-   */
-  latestMessages: Message[];
-}
-
-/**
- * Persist and broadcast the retrieval's side effects: the injected block on
- * the user message's metadata (so it survives reloads), a recall-log row, and
- * the `memory_recalled` debug event. All three are best-effort — a failure to
- * persist must not abort the turn.
- */
-function recordRecallSideEffects(
-  graphResult: GraphMemoryResult,
-  ctx: MemoryRetrievalHookContext,
-): void {
-  // Persist the injected block text in message metadata so it survives
-  // conversation reloads (eviction, restart, fork). loadFromDb re-injects
-  // from metadata.
-  if (graphResult.injectedBlockText) {
-    try {
-      updateMessageMetadata(ctx.userMessageId, {
-        memoryInjectedBlock: graphResult.injectedBlockText,
-      });
-    } catch (err) {
-      ctx.logger.warn(
-        { err },
-        "Failed to persist memory injection to metadata (non-fatal)",
-      );
-    }
-  }
-
-  const m = graphResult.metrics;
-
-  try {
-    recordMemoryRecallLog({
-      conversationId: ctx.conversationId,
-      enabled: true,
-      degraded: false,
-      provider: m?.embeddingProvider ?? undefined,
-      model: m?.embeddingModel ?? undefined,
-      semanticHits: m?.semanticHits ?? 0,
-      mergedCount: m?.mergedCount ?? 0,
-      selectedCount: m?.selectedCount ?? 0,
-      tier1Count: m?.tier1Count ?? 0,
-      tier2Count: m?.tier2Count ?? 0,
-      hybridSearchLatencyMs: m?.hybridSearchLatencyMs ?? 0,
-      sparseVectorUsed: m?.sparseVectorUsed ?? false,
-      injectedTokens: graphResult.injectedTokens,
-      latencyMs: graphResult.latencyMs,
-      topCandidatesJson: (m?.topCandidates ?? []).map((c) => ({
-        key: c.nodeId,
-        type: c.type,
-        kind: "graph",
-        finalScore: c.score,
-        semantic: c.semanticSimilarity,
-        recency: c.recencyBoost,
-      })),
-      injectedText: graphResult.injectedBlockText ?? undefined,
-      reason: `graph:${graphResult.mode}`,
-      queryContext: m?.queryContext ?? undefined,
-    });
-  } catch (err) {
-    ctx.logger.warn({ err }, "Failed to persist memory recall log (non-fatal)");
-  }
-
-  if (m) {
-    const memoryRecalledEvent: MemoryRecalled = {
-      type: "memory_recalled",
-      provider: m.embeddingProvider ?? "unknown",
-      model: m.embeddingModel ?? "unknown",
-      semanticHits: m.semanticHits,
-      mergedCount: m.mergedCount,
-      selectedCount: m.selectedCount,
-      tier1Count: m.tier1Count,
-      tier2Count: m.tier2Count,
-      hybridSearchLatencyMs: m.hybridSearchLatencyMs,
-      sparseVectorUsed: m.sparseVectorUsed,
-      injectedTokens: graphResult.injectedTokens,
-      latencyMs: graphResult.latencyMs,
-      topCandidates: m.topCandidates.map((c) => ({
-        key: c.nodeId,
-        type: c.type,
-        kind: "graph",
-        finalScore: c.score,
-        semantic: c.semanticSimilarity,
-        recency: c.recencyBoost,
-      })),
-    };
-    ctx.onEvent(memoryRecalledEvent);
-  }
-}
-
-/**
- * Run the default retrieval, writing `latestMessages` back onto the context and
- * recording the PKB query-vector pair on the graph handle. Skips the
- * memory-graph call entirely (leaving `latestMessages` as the seeded input
- * messages and no query pair recorded) when the actor is not trusted.
- *
- * Memory retrieval blocks the turn — there is no soft timeout here. Memory is
- * critical context, and silently dropping it produces a worse outcome than a
- * slower turn. Cancellation still works via `ctx.signal`, which is threaded
- * into `prepareMemory`.
- */
-const userPromptSubmitMemoryRetrieval: PluginHookFn<
-  MemoryRetrievalHookContext
-> = async (ctx) => {
-  if (!ctx.isTrustedActor) {
-    // Untrusted actors skip memory-graph retrieval entirely.
-    return;
-  }
-
-  const graphResult = await ctx.graphMemory.prepareMemory(
-    ctx.latestMessages,
-    ctx.config,
-    ctx.signal,
-    ctx.onEvent,
-  );
-
-  recordRecallSideEffects(graphResult, ctx);
-
-  ctx.latestMessages = graphResult.runMessages;
-  // Select dense+sparse as a matched pair so RRF fusion combines two signals
-  // aligned to the same query text:
-  //   1. Context-load with a user query: user-query dense + user-query sparse
-  //      — the cleanest pairing.
-  //   2. Otherwise (context-load without a user query, or per-turn): whatever
-  //      `queryVector` / `sparseVector` the retriever produced, which are
-  //      themselves co-aligned (both summary-derived in context-load, both
-  //      user-last-message-derived in per-turn).
-  // Never pair a user-query dense with a summary-aligned sparse.
-  // The PKB-reminder injector reads this pair back off the same graph handle
-  // (looked up by conversation id) rather than receiving it threaded through
-  // the agent loop.
-  if (graphResult.userQueryVector) {
-    ctx.graphMemory.recordPkbQueryVectors(
-      graphResult.userQueryVector,
-      graphResult.userQuerySparseVector,
-    );
-  } else {
-    ctx.graphMemory.recordPkbQueryVectors(
-      graphResult.queryVector,
-      graphResult.sparseVector,
-    );
-  }
-};
-
-export default userPromptSubmitMemoryRetrieval;

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

@@ -1,126 +0,0 @@
-import type { ContextWindowCompactOptions } from "../../../../context/window-manager.js";
-import {
-  createInitialReducerState,
-  reduceContextOverflow,
-  type ReducerState,
-} from "../../../../daemon/context-overflow-reducer.js";
-import type {
-  Middleware,
-  OverflowReduceArgs,
-  OverflowReduceResult,
-} from "../../../types.js";
-
-/**
- * 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.
- */
-const defaultOverflowReduceMiddleware: Middleware<
-  OverflowReduceArgs,
-  OverflowReduceResult
-> = async function defaultOverflowReduceMiddleware(args, _next, _ctx) {
-  let messages = args.messages;
-  let runMessages = args.runMessages;
-  let injectionMode: "full" | "minimal" = "full";
-  let reducerState: ReducerState = createInitialReducerState();
-  let reducerCompacted = false;
-  let attempts = 0;
-
-  while (attempts < args.maxAttempts && !reducerState.exhausted) {
-    // Abort check at the top of every iteration. When the pipeline runner
-    // arms a timeout (or the caller aborts externally), `args.abortSignal`
-    // is linked to that trigger via `linkAbortSignal`, so this check lets
-    // us bail out BETWEEN iterations rather than letting another round of
-    // compaction / re-injection mutate `ctx.messages` after the turn has
-    // already failed. Individual `reduceContextOverflow` calls also honor
-    // the signal, but without this gate a fresh iteration could still
-    // start after the signal fires, since the previous one returned
-    // normally before the abort propagated.
-    args.abortSignal?.throwIfAborted();
-
-    attempts++;
-    args.emitActivityState();
-
-    const basisMessages = messages;
-    const step = await reduceContextOverflow(
-      basisMessages,
-      {
-        providerName: args.providerName,
-        systemPrompt: args.systemPrompt,
-        contextWindow: args.contextWindow,
-        targetTokens: args.preflightBudget,
-        toolTokenBudget: args.toolTokenBudget,
-      },
-      reducerState,
-      (msgs, signal, opts: ContextWindowCompactOptions) =>
-        args.compactFn(msgs, signal, opts),
-      args.abortSignal,
-    );
-
-    reducerState = step.state;
-    messages = step.messages;
-    injectionMode = step.state.injectionMode;
-
-    // Per-iteration compaction flag: whether THIS step just produced a
-    // fresh compaction. PKB / NOW re-injection is gated on this — see the
-    // reinjectForMode JSDoc for why the two signals differ.
-    const stepCompacted = step.compactionResult?.compacted === true;
-
-    // Let the orchestrator apply compaction side effects (circuit-breaker
-    // tracking, event emission, ctx mutation) before we re-inject.
-    if (step.compactionResult) {
-      await args.onCompactionResult(step.compactionResult, basisMessages);
-      if (stepCompacted) {
-        reducerCompacted = true;
-      }
-    }
-
-    // Second abort gate — if the side effects or the step itself took us
-    // past the deadline, don't rebuild runMessages or iterate again.
-    args.abortSignal?.throwIfAborted();
-
-    // Rebuild runMessages via the orchestrator-supplied helper (which
-    // re-runs `applyRuntimeInjections` with potentially downgraded mode
-    // and freshly re-hydrated PKB/NOW blocks after compaction). We pass
-    // the current reduced `messages` explicitly so the orchestrator never
-    // has to read from mutable shared state to rebuild runMessages — a
-    // tier that doesn't trigger compaction (tool-result truncation, media
-    // stubbing) won't update `ctx.messages` on its own.
-    //
-    // `stepCompacted` and `reducerCompacted` are both passed so the
-    // orchestrator can gate PKB / NOW re-injection per-iteration while
-    // keeping `slackChronologicalMessages` suppressed once any iteration
-    // has compacted.
-    runMessages = await args.reinjectForMode(
-      messages,
-      injectionMode,
-      stepCompacted,
-      reducerCompacted,
-    );
-
-    // Re-estimate with injections included — `step.estimatedTokens` was
-    // computed on bare history and doesn't account for tokens added by
-    // runtime injections.
-    const postInjectionTokens = args.estimatePostInjection(runMessages);
-    if (postInjectionTokens <= args.preflightBudget) break;
-  }
-
-  return {
-    messages,
-    runMessages,
-    injectionMode,
-    reducerState,
-    reducerCompacted,
-    attempts,
-  };
-};
-
-export default defaultOverflowReduceMiddleware;

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

@@ -1,15 +0,0 @@
-{
-  "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

@@ -1,42 +0,0 @@
-/**
- * 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/title-generate/register.ts

@@ -1,35 +0,0 @@
-/**
- * Default `title-generate` plugin.
- *
- * Contributes two hooks, both pure triggers that delegate the title work to
- * the service (`memory/conversation-title-service.ts`):
- *
- * - `user-prompt-submit` (`./hooks/user-prompt-submit.ts`) — first-pass title
- *   generation from the submitted prompt.
- * - `stop` (`./hooks/stop.ts`) — second-pass regeneration once the
- *   conversation reaches its third user turn, for a title that reflects the
- *   established topic.
- *
- * Persistence and the resulting `conversation_title_updated` / `sync_changed`
- * broadcast are owned by the title service.
- *
- * 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 stop from "./hooks/stop.js";
-import userPromptSubmit from "./hooks/user-prompt-submit.js";
-import pkg from "./package.json" with { type: "json" };
-
-export const defaultTitleGeneratePlugin: Plugin = {
-  manifest: {
-    name: pkg.name,
-    version: pkg.version,
-  },
-  hooks: {
-    "user-prompt-submit": userPromptSubmit,
-    stop,
-  },
-};

package/src/plugins/defaults/tool-error/register.ts

@@ -1,23 +0,0 @@
-/**
- * Default `tool-error` plugin.
- *
- * Contributes a `post-tool-use` hook that coaches the model to retry or report
- * a failed tool call, bounded per tool so an unrecoverable error doesn't churn.
- * The coaching is surfaced via `additionalContext` (a separate provider-only
- * block), leaving the tool result's own content untouched. The decision logic
- * lives in `./hooks/post-tool-use.ts`.
- */
-
-import { type Plugin } from "../../types.js";
-import postToolUse from "./hooks/post-tool-use.js";
-import pkg from "./package.json" with { type: "json" };
-
-export const defaultToolErrorPlugin: Plugin = {
-  manifest: {
-    name: pkg.name,
-    version: pkg.version,
-  },
-  hooks: {
-    "post-tool-use": postToolUse,
-  },
-};

package/src/plugins/defaults/tool-result-truncate/register.ts

@@ -1,24 +0,0 @@
-/**
- * Default `tool-result-truncate` plugin.
- *
- * Contributes 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. The truncation implementation lives in
- * `./terminal.ts`; the hook in `./hooks/post-tool-use.ts` wires it into the
- * lifecycle. Defaults register before user plugins, so this runs at the front
- * of the hook chain.
- */
-
-import { type Plugin } from "../../types.js";
-import postToolUse from "./hooks/post-tool-use.js";
-import pkg from "./package.json" with { type: "json" };
-
-export const defaultToolResultTruncatePlugin: Plugin = {
-  manifest: {
-    name: pkg.name,
-    version: pkg.version,
-  },
-  hooks: {
-    "post-tool-use": postToolUse,
-  },
-};