@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/notifications/decision-engine.ts

@@ -23,17 +23,22 @@ import {
 import type { Provider } from "../providers/types.js";
 import { getLogger } from "../util/logger.js";
 import { truncate } from "../util/truncate.js";
+import {
+  buildAccessRequestContractText,
+  buildAccessRequestInviteDirective,
+  hasAccessRequestInstructions,
+  hasInviteFlowDirective,
+} from "./access-request-copy.js";
 import {
   buildConversationCandidates,
   type ConversationCandidateSet,
   serializeCandidatesForPrompt,
 } from "./conversation-candidates.js";
 import {
-  buildAccessRequestContractText,
-  buildAccessRequestInviteDirective,
   composeFallbackCopy,
-  hasAccessRequestInstructions,
-  hasInviteFlowDirective,
+  deriveTitle,
+  nonEmpty,
+  readPayloadString,
 } from "./copy-composer.js";
 import { createDecision } from "./decisions-store.js";
 import {
@@ -56,21 +61,6 @@ const log = getLogger("notification-decision-engine");
 const DECISION_TIMEOUT_MS = 15_000;
 const PROMPT_VERSION = "v4";
 
-/**
- * Derive a short notification title from a message body. Used when an
- * assistant_tool-sourced signal supplies `requestedMessage` without an
- * explicit `requestedTitle`: trims to the first sentence terminator when
- * present, then caps the result at 60 characters with an ellipsis.
- */
-function deriveTitle(body: string): string {
-  const firstSentenceEnd = body.search(/[.!?](\s|$)/);
-  const candidate =
-    firstSentenceEnd > 0 ? body.slice(0, firstSentenceEnd + 1) : body;
-  return candidate.length > 60
-    ? candidate.slice(0, 60).trim() + "…"
-    : candidate.trim();
-}
-
 /**
  * Maximum character budget for identity context injected into the notification
  * decision prompt. We truncate to prevent oversized prompts when SOUL.md /
@@ -768,24 +758,15 @@ export async function evaluateSignal(
   // classifier entirely. The producer has already done the routing and
   // copy decisions — we just enforce the standard post-decision guards
   // and persist the result.
-  if (
-    signal.sourceChannel === "assistant_tool" &&
-    typeof signal.contextPayload === "object" &&
-    signal.contextPayload != null &&
-    typeof (signal.contextPayload as Record<string, unknown>)
-      .requestedMessage === "string" &&
-    (
-      (signal.contextPayload as Record<string, unknown>)
-        .requestedMessage as string
-    ).trim().length > 0
-  ) {
+  const requestedBody = nonEmpty(
+    readPayloadString(signal.contextPayload, "requestedMessage"),
+  );
+  if (signal.sourceChannel === "assistant_tool" && requestedBody) {
     const payload = signal.contextPayload as Record<string, unknown>;
-    const body = (payload.requestedMessage as string).trim();
+    const body = requestedBody;
     const title =
-      typeof payload.requestedTitle === "string" &&
-      payload.requestedTitle.trim().length > 0
-        ? (payload.requestedTitle as string).trim()
-        : deriveTitle(body);
+      nonEmpty(readPayloadString(signal.contextPayload, "requestedTitle")) ??
+      deriveTitle(body);
     const isUrgent =
       signal.attentionHints.urgency === "critical" ||
       signal.attentionHints.urgency === "high";

package/src/notifications/home-feed-side-effect.ts

@@ -22,6 +22,7 @@ import { getConversation } from "../memory/conversation-crud.js";
 import { isBackgroundConversationType } from "../memory/conversation-types.js";
 import { getLogger } from "../util/logger.js";
 import { isConversationSeedSane } from "./conversation-seed-composer.js";
+import { readPayloadString } from "./copy-composer.js";
 import type { NotificationSignal } from "./signal.js";
 import type { NotificationDecision, RenderedChannelCopy } from "./types.js";
 
@@ -231,12 +232,6 @@ function resolveHomeFeedMirror(
   return { mirror: false };
 }
 
-function readPayloadString(payload: unknown, key: string): string | undefined {
-  if (!payload || typeof payload !== "object") return undefined;
-  const value = (payload as Record<string, unknown>)[key];
-  return typeof value === "string" ? value : undefined;
-}
-
 /**
  * Routing-intent enforcement can prune `selectedChannels` without also
  * pruning `renderedCopy`, so iterating `renderedCopy` directly risks

package/src/plugin-api/constants.ts

@@ -20,10 +20,14 @@ export const HOOKS = {
   SHUTDOWN: "shutdown",
   /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
   USER_PROMPT_SUBMIT: "user-prompt-submit",
+  /** Fires immediately before each provider call. A hook may edit the outbound request (e.g. the system prompt) and opt the turn into deferred output streaming. */
+  PRE_MODEL_CALL: "pre-model-call",
   /** Fires once per tool result, after the tool returns and before the result is sent to the provider. */
   POST_TOOL_USE: "post-tool-use",
   /** Fires when the model yields a response with no tool calls — the run's stop boundary. Decides whether to stop or continue with a follow-up turn. */
   STOP: "stop",
+  /** Fires for each finalized assistant message, once per model call, before it is persisted/streamed-final. A hook may transform the message content. */
+  POST_MODEL_CALL: "post-model-call",
 } as const;
 
 /** Union of every hook name declared in {@link HOOKS}. */

package/src/plugin-api/index.ts

@@ -11,34 +11,46 @@
  *
  * ## Surface today
  *
- * The public package is intentionally **declarative**: a plugin is a
- * directory whose `package.json` is the manifest and whose `hooks/` /
- * `tools/` / `skills/` / `routes/` subdirectories are the contributions.
- * The host introspects the directory at load time and wires it into the
- * runtime — plugin authors never call a runtime registration function.
+ * The primary authoring model is **declarative**: a plugin is a directory
+ * whose `package.json` is the manifest and whose `hooks/` / `tools/` /
+ * `skills/` / `routes/` subdirectories are the contributions. The host
+ * introspects the directory at load time and wires it into the runtime.
  *
- * What this module exposes is therefore types-only: the context shapes
+ * Most of what this module exposes is therefore types: the context shapes
  * the host hands to plugin hooks, and the logger shape they include.
  *
+ * Alongside those types, the module exposes a small set of **runtime
+ * handles** for plugins that need to reach the assistant's live singletons
+ * (subscribe to runtime events, read secrets). These resolve to the
+ * assistant's own instances: the host parks the loaded plugin-api namespace
+ * on `globalThis` at boot, and the workspace-level shim re-binds each
+ * runtime export from there — so a plugin's
+ * `import { assistantEventHub } from "@vellumai/plugin-api"` lands on the
+ * same singleton the assistant uses, even when the daemon is a
+ * `bun --compile` binary where an absolute-path import would load a
+ * disjoint module copy.
+ *
+ * - {@link assistantEventHub} — the assistant's pub/sub hub for runtime events
+ * - {@link getSecureKeyAsync} — read a secret from secure storage
+ *
  * - {@link PluginInitContext} — passed to `init` hook at bootstrap
  * - {@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 PreModelCallContext} — passed to `pre-model-call` hook, fired
+ *   before each provider call to edit the request / defer output streaming
  * - {@link PostToolUseContext} — passed to `post-tool-use` hook, fired once
  *   per tool result before it joins the provider-bound history
  * - {@link StopContext} — passed to `stop` hook, fired when the model yields
  *   a response with no tool calls
+ * - {@link PostModelCallContext} — passed to `post-model-call` hook,
+ *   fired for each finalized assistant message to transform its content
  * - {@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)
  * - {@link ToolContext} — passed to a plugin tool's `execute` method
  * - {@link ToolExecutionResult} — return shape of a plugin tool's `execute`
- *
- * Pipeline-argument types (`MemoryArgs`, `CompactionArgs`, etc.) currently
- * live in `assistant/src/plugins/types.ts` and have not yet migrated into
- * this package. A follow-up PR will move them into this surface as the
- * per-pipeline schemas stabilize.
  */
 
 export type { HookName } from "./constants.js";
@@ -48,7 +60,9 @@ export type {
   PluginInitContext,
   PluginLogger,
   PluginShutdownContext,
+  PostModelCallContext,
   PostToolUseContext,
+  PreModelCallContext,
   StopContext,
   StopDecision,
   ToolContext,
@@ -57,3 +71,18 @@ export type {
   UserPromptSubmitContext,
 } from "./types.js";
 export { RiskLevel } from "./types.js";
+
+// ─── Runtime handles ─────────────────────────────────────────────────────────
+// Values (not just types) that plugins consume at module-load / init time.
+// Workspace-local plugins resolve these via the boot-time shim, which
+// re-binds each from the assistant's globalThis-parked namespace so they
+// share module identity with the assistant's own singletons.
+export type { AssistantEvent } from "../runtime/assistant-event.js";
+export type {
+  AssistantEventCallback,
+  AssistantEventFilter,
+  AssistantEventHub,
+  AssistantEventSubscription,
+} from "../runtime/assistant-event-hub.js";
+export { assistantEventHub } from "../runtime/assistant-event-hub.js";
+export { getSecureKeyAsync } from "../security/secure-keys.js";

package/src/plugin-api/types.ts

@@ -4,6 +4,7 @@
  * removing is breaking and gated on a major bump.
  */
 
+import type { LLMCallSite } from "../config/schemas/llm.js";
 import type {
   ContentBlock,
   Message,
@@ -51,8 +52,10 @@ export interface PluginLogger {
  *   - `init` — {@link PluginInitContext}
  *   - `shutdown` — {@link PluginShutdownContext}
  *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
+ *   - `pre-model-call` — {@link PreModelCallContext}
  *   - `post-tool-use` — {@link PostToolUseContext}
  *   - `stop` — {@link StopContext}
+ *   - `post-model-call` — {@link PostModelCallContext}
  */
 export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
 
@@ -127,6 +130,39 @@ export interface PluginShutdownContext {
 export interface UserPromptSubmitContext {
   /** Conversation ID the user prompt was submitted on. */
   readonly conversationId: string;
+  /**
+   * Persisted ID of the user message that triggered this turn. Hooks that
+   * attach turn-scoped metadata to the originating message (e.g. recording an
+   * injected memory block so it survives a conversation reload) key off this
+   * row id rather than the in-memory message arrays, whose entries carry no id.
+   */
+  readonly userMessageId: string;
+  /**
+   * Stable ID for the request that drives this turn. Hooks that perform
+   * runtime injection forward it onto the injector turn context so the
+   * assembled blocks are attributed to the originating request; it is fixed
+   * for the turn and cannot be recovered from the message arrays.
+   */
+  readonly requestId: string;
+  /**
+   * Active inference profile key to surface in this turn's context, or `null`
+   * when the profile is unchanged since the one last announced to the model.
+   * Hooks that emit the `model_profile` grounding line resolve the
+   * human-readable label (and model id) from this key via the workspace LLM
+   * config rather than receiving the rendered string — the key is the minimal
+   * turn input the message arrays cannot carry.
+   */
+  readonly modelProfileKey: string | null;
+  /**
+   * Whether the turn has no human present to answer clarification questions
+   * (e.g. a scheduled, background, or headless run). Resolved once at turn
+   * start from the run's interactivity option, falling back to live client
+   * presence — a single value the hook reads rather than re-deriving from
+   * mutable conversation state that can flip mid-turn. Hooks that assemble the
+   * turn's runtime injections forward it so the assembled context reflects the
+   * turn's interactivity.
+   */
+  readonly isNonInteractive: boolean;
   /**
    * The text of the user prompt that triggered this turn — the resolved
    * user message (after slash-command expansion), independent of any
@@ -288,3 +324,75 @@ export interface StopContext {
    */
   readonly logger: PluginLogger;
 }
+
+// ─── Pre-model-call hook context ─────────────────────────────────────────────
+
+/**
+ * Context passed to the `pre-model-call` hook. Fires immediately before each
+ * provider call — once per model call within a turn, including tool-result
+ * follow-up calls. Because it runs for every provider call (background, subagent,
+ * and compaction work can share a conversation), hooks MUST self-gate on
+ * {@link callSite} / {@link conversationId} before acting.
+ *
+ * A hook may edit the outbound request by replacing {@link systemPrompt}, and may
+ * opt this turn into deferred output streaming via {@link deferAssistantOutput}.
+ * Mutate the context in place or return a new one; throwing is contained by the
+ * loop (the call proceeds with the original request).
+ */
+export interface PreModelCallContext {
+  /** Conversation ID the call belongs to. */
+  readonly conversationId: string;
+  /**
+   * The call site this provider call serves — `"mainAgent"` for the user-facing
+   * reply, or a background/utility site. Omitted by call sites that don't tag one.
+   */
+  readonly callSite?: LLMCallSite;
+  /**
+   * The system prompt about to be sent. A hook may replace it (e.g. strip or
+   * append a section); the loop sends the resulting value.
+   */
+  systemPrompt: string | undefined;
+  /**
+   * Seeded `false`. When a hook sets it `true`, the loop suppresses this turn's
+   * live assistant `text_delta` stream; a `post-model-call` hook is then
+   * expected to produce the text the client sees (emitted once, after the reply
+   * is finalized). Lets a plugin replace streamed output wholesale — e.g.
+   * redaction that needs the full message — instead of leaking the raw stream.
+   */
+  deferAssistantOutput: boolean;
+  /** Logger scoped to the current turn (tag structured fields with `{ plugin }`). */
+  readonly logger: PluginLogger;
+}
+
+// ─── Post-model-call hook context ────────────────────────────────────────────
+
+/**
+ * Context passed to the `post-model-call` hook. Fires for each finalized
+ * assistant message — once per model call, at the message-complete boundary —
+ * before the message is persisted and (if deferred) streamed-final. Unlike
+ * {@link StopContext}'s read-only `responseContent` (which exists for the stop
+ * decision), {@link content} is mutable: the loop adopts the hook's result as the
+ * persisted and streamed message.
+ *
+ * Fires on tool-bearing turns too (a reply can carry both text and `tool_use`),
+ * so a hook should transform only the blocks it owns and leave others — notably
+ * `tool_use` — intact. Runs for every finalized message regardless of call site;
+ * hooks MUST self-gate on {@link callSite} / {@link conversationId}. Mutate in
+ * place or return a new context; throwing is contained by the loop (the original
+ * content is kept).
+ */
+export interface PostModelCallContext {
+  /** Conversation ID the message belongs to. */
+  readonly conversationId: string;
+  /** The call site this message serves — `"mainAgent"` for the user-facing reply. */
+  readonly callSite?: LLMCallSite;
+  /**
+   * The finalized message content. Mutable — transform the text blocks and leave
+   * `tool_use` (and other non-text blocks) intact.
+   */
+  content: ContentBlock[];
+  /** Provider-reported stop reason for the turn, when reported. */
+  readonly stopReason: string | null | undefined;
+  /** Logger scoped to the current turn (tag structured fields with `{ plugin }`). */
+  readonly logger: PluginLogger;
+}

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

@@ -0,0 +1,106 @@
+/**
+ * Default compaction implementation.
+ *
+ * Summarizes conversation history when the context window fills up by
+ * delegating to the conversation's {@link ContextWindowManager}. The agent loop
+ * calls {@link defaultCompact} directly with a {@link CompactionContext}; the
+ * request carries the conversational inputs while the compaction module resolves
+ * (and, if needed, builds) the manager from its per-conversation store.
+ *
+ * This module is side-effect free: importing it does not register any plugin.
+ */
+
+import type { Message } from "../../../providers/types.js";
+import type { TrustClass } from "../../../runtime/actor-trust-resolver.js";
+import { PluginExecutionError } from "../../types.js";
+import { getContextWindowManager } from "./manager-store.js";
+import type {
+  ContextWindowResult,
+  EmergencyCompactOptions,
+} from "./window-manager.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 `conversationId` the compaction module
+ * resolves its manager from, so callers never hold or pass a manager handle and
+ * the request can grow toward a model-facing compaction-method shape without
+ * coupling callers to the manager's option bag.
+ */
+export interface CompactionContext {
+  /** Conversation whose manager performs the compaction. */
+  conversationId: string;
+  /** 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: resolves the conversation's context window
+ * manager from the compaction store (building it on first access) and returns
+ * the (possibly summarized) message history.
+ */
+export async function defaultCompact(
+  context: CompactionContext,
+): Promise<ContextWindowResult> {
+  const { conversationId, messages, signal, ...options } = context;
+  const manager = getContextWindowManager(conversationId);
+  if (manager == null) {
+    throw new PluginExecutionError(
+      `default-compaction: no ContextWindowManager registered for conversation ${conversationId} — the conversation must register one before compaction runs`,
+      DEFAULT_COMPACTION_PLUGIN_NAME,
+    );
+  }
+  return manager.maybeCompact(messages, signal, options);
+}
+
+/**
+ * Self-describing emergency-compaction request handed to
+ * {@link defaultEmergencyCompact}. Mirrors {@link CompactionContext} but
+ * carries the provider-reported token estimate at the overflow that triggered
+ * recovery, which sizes the summarize-around-last-tool-pair cut.
+ */
+export interface EmergencyCompactionContext extends EmergencyCompactOptions {
+  /** Conversation whose manager performs the emergency compaction. */
+  conversationId: string;
+  /** Message history to summarize around the last tool_use/tool_result pair. */
+  messages: Message[];
+  /** Abort signal forwarded to the compaction summary call. */
+  signal?: AbortSignal;
+}
+
+/**
+ * Run emergency mid-turn compaction for the turn: resolves the conversation's
+ * context window manager from the compaction store and summarizes everything
+ * before the last tool_use/tool_result pair, preserving the agent's most recent
+ * action context while aggressively compressing earlier history.
+ */
+export async function defaultEmergencyCompact(
+  context: EmergencyCompactionContext,
+): Promise<ContextWindowResult> {
+  const { conversationId, messages, signal, ...options } = context;
+  const manager = getContextWindowManager(conversationId);
+  if (manager == null) {
+    throw new PluginExecutionError(
+      `default-compaction: no ContextWindowManager registered for conversation ${conversationId} — the conversation must register one before emergency compaction runs`,
+      DEFAULT_COMPACTION_PLUGIN_NAME,
+    );
+  }
+  return manager.emergencyCompact(messages, options, signal);
+}