@vellumai/assistant 0.8.8 → 0.8.9-staging.2

package/src/ipc/skill-routes/memory.ts

@@ -17,7 +17,9 @@ import type { SkillIpcRoute } from "../skill-ipc-types.js";
 
 /**
  * IPC params for `addMessage()`. `role` is constrained to the
- * `MessageRole` union. `metadata` is a free-form record (validated
+ * renderable conversation roles (`user`/`assistant`): the messages store
+ * is UI-facing (`ConversationMessage`), so agent-context `system` rows are
+ * not accepted here. `metadata` is a free-form record (validated
  * downstream by `messageMetadataSchema` with a warn-and-store fallback).
  * `skipIndexing` and `clientMessageId` mirror `AddMessageOptions`.
  *
@@ -28,7 +30,7 @@ import type { SkillIpcRoute } from "../skill-ipc-types.js";
  */
 const MemoryAddMessageParams = z.object({
   conversationId: z.string().min(1),
-  role: z.enum(["user", "assistant", "system"]),
+  role: z.enum(["user", "assistant"]),
   content: z.string(),
   metadata: z.record(z.string(), z.unknown()).optional(),
   skipIndexing: z.boolean().optional(),

package/src/memory/__tests__/jobs-worker-v2-schedule.test.ts

@@ -151,6 +151,7 @@ describe("maybeEnqueueGraphMaintenanceJobs — memory v2 consolidation", () => {
 
   test("enqueues consolidate when v2 is on and no checkpoint exists", () => {
     const config = buildConfig({ v2Enabled: true, intervalHours: 1 });
+    writeBuffer(15);
 
     maybeEnqueueGraphMaintenanceJobs(config, Date.now());
 
@@ -177,6 +178,7 @@ describe("maybeEnqueueGraphMaintenanceJobs — memory v2 consolidation", () => {
 
   test("enqueues consolidate again once the interval elapses", () => {
     const config = buildConfig({ v2Enabled: true, intervalHours: 1 });
+    writeBuffer(15);
 
     const now = Date.now();
     // Stamp checkpoint to >1h ago.
@@ -193,6 +195,7 @@ describe("maybeEnqueueGraphMaintenanceJobs — memory v2 consolidation", () => {
 
   test("respects a custom consolidation_interval_hours value", () => {
     const config = buildConfig({ v2Enabled: true, intervalHours: 6 });
+    writeBuffer(15);
 
     const now = Date.now();
     // 4h elapsed — under the configured 6h interval.
@@ -216,6 +219,7 @@ describe("maybeEnqueueGraphMaintenanceJobs — memory v2 consolidation", () => {
 
   test("v1 maintenance entries are suppressed when v2 is active", () => {
     const config = buildConfig({ v2Enabled: true, intervalHours: 1 });
+    writeBuffer(15);
 
     // No checkpoints set — every entry would be due if it were scheduled.
     deleteMemoryCheckpoint("graph_maintenance:decay:last_run");
@@ -426,3 +430,86 @@ describe("maybeEnqueueGraphMaintenanceJobs — buffer-size trigger", () => {
     expect(countPendingJobs("memory_v2_consolidate")).toBe(0);
   });
 });
+
+describe("maybeEnqueueGraphMaintenanceJobs — min buffer lines noop", () => {
+  test("skips scheduled consolidation when buffer is under 10 lines", () => {
+    // GIVEN v2 consolidation is enabled and the interval has elapsed
+    const config = buildConfig({ v2Enabled: true, intervalHours: 1 });
+    const now = Date.now();
+    setMemoryCheckpoint(
+      CONSOLIDATE_CHECKPOINT_KEY,
+      String(now - 2 * 60 * 60 * 1000),
+    );
+    // AND the buffer has fewer than 10 lines
+    writeBuffer(5);
+
+    // WHEN the schedule runs
+    maybeEnqueueGraphMaintenanceJobs(config, now);
+
+    // THEN no consolidation job is enqueued
+    expect(countPendingJobs("memory_v2_consolidate")).toBe(0);
+    // AND the checkpoint advances so the skip doesn't re-fire next tick
+    expect(getMemoryCheckpoint(CONSOLIDATE_CHECKPOINT_KEY)).toBe(String(now));
+  });
+
+  test("allows scheduled consolidation when buffer has exactly 10 lines", () => {
+    // GIVEN v2 consolidation is enabled and the interval has elapsed
+    const config = buildConfig({ v2Enabled: true, intervalHours: 1 });
+    const now = Date.now();
+    setMemoryCheckpoint(
+      CONSOLIDATE_CHECKPOINT_KEY,
+      String(now - 2 * 60 * 60 * 1000),
+    );
+    // AND the buffer has exactly 10 lines
+    writeBuffer(10);
+
+    // WHEN the schedule runs
+    maybeEnqueueGraphMaintenanceJobs(config, now);
+
+    // THEN consolidation is enqueued
+    expect(countPendingJobs("memory_v2_consolidate")).toBe(1);
+  });
+
+  test("skips scheduled consolidation when buffer file is missing", () => {
+    // GIVEN v2 consolidation is enabled and the interval has elapsed
+    const config = buildConfig({ v2Enabled: true, intervalHours: 1 });
+    const now = Date.now();
+    setMemoryCheckpoint(
+      CONSOLIDATE_CHECKPOINT_KEY,
+      String(now - 2 * 60 * 60 * 1000),
+    );
+    // AND no buffer file exists (0 lines)
+    removeBuffer();
+
+    // WHEN the schedule runs
+    maybeEnqueueGraphMaintenanceJobs(config, now);
+
+    // THEN no consolidation job is enqueued
+    expect(countPendingJobs("memory_v2_consolidate")).toBe(0);
+    // AND the checkpoint advances
+    expect(getMemoryCheckpoint(CONSOLIDATE_CHECKPOINT_KEY)).toBe(String(now));
+  });
+
+  test("size-based trigger is independent of the min-lines noop", () => {
+    // GIVEN the time-based interval has elapsed but the buffer has fewer
+    // than 10 lines, while exceeding the configured maxBufferLines threshold
+    const config = buildConfig({
+      v2Enabled: true,
+      intervalHours: 1,
+      maxBufferLines: 5,
+    });
+    const now = Date.now();
+    setMemoryCheckpoint(
+      CONSOLIDATE_CHECKPOINT_KEY,
+      String(now - 2 * 60 * 60 * 1000),
+    );
+    writeBuffer(8);
+
+    // WHEN the schedule runs
+    maybeEnqueueGraphMaintenanceJobs(config, now);
+
+    // THEN consolidation is enqueued via the size trigger despite the
+    // time-based schedule being nooped (8 < 10 min lines, but 8 >= 5 max)
+    expect(countPendingJobs("memory_v2_consolidate")).toBe(1);
+  });
+});

package/src/memory/conversation-crud.ts

@@ -277,6 +277,7 @@ export interface MessageRow {
   content: string;
   createdAt: number;
   metadata: string | null;
+  clientMessageId: string | null;
 }
 
 const parseMessage = createRowMapper<typeof messages.$inferSelect, MessageRow>({
@@ -286,6 +287,7 @@ const parseMessage = createRowMapper<typeof messages.$inferSelect, MessageRow>({
   content: "content",
   createdAt: "createdAt",
   metadata: "metadata",
+  clientMessageId: "clientMessageId",
 });
 
 export type ConversationCreateType = "standard" | "background" | "scheduled";
@@ -1903,21 +1905,30 @@ export function listActiveInferenceProfileSessions(
 }
 
 /**
- * Resolve the per-turn inference-profile override from an already-loaded
- * conversation row. Returns the row's `inferenceProfile` for interactive
- * conversations, `undefined` for automation threads (subagent fan-out,
- * scheduled tasks, update bulletins) so they run on the workspace defaults
- * rather than inheriting an interactive override.
- *
- * Prefer this row-based form when the caller already needs to read the
- * conversation row for other reasons (e.g. the agent loop's title check).
+ * The conversation fields needed to resolve a per-turn inference-profile
+ * override. Satisfied by both the DB {@link ConversationRow} and the live
+ * in-memory `Conversation`, so callers can derive the override from whichever
+ * representation they already hold without a redundant row fetch.
+ */
+export interface OverrideProfileFields {
+  conversationType?: string | null;
+  inferenceProfile?: string | null;
+  inferenceProfileExpiresAt?: number | null;
+}
+
+/**
+ * Resolve the per-turn inference-profile override from a conversation's
+ * fields. Returns the `inferenceProfile` for interactive conversations,
+ * `undefined` for automation threads (subagent fan-out, scheduled tasks,
+ * update bulletins) so they run on the workspace defaults rather than
+ * inheriting an interactive override.
  */
-export function getConversationOverrideProfileFromRow(
-  conv: ConversationRow | null,
+export function resolveOverrideProfile(
+  fields: OverrideProfileFields | null,
 ): string | undefined {
   if (
-    conv?.conversationType === "background" ||
-    conv?.conversationType === "scheduled"
+    fields?.conversationType === "background" ||
+    fields?.conversationType === "scheduled"
   ) {
     return undefined;
   }
@@ -1931,24 +1942,23 @@ export function getConversationOverrideProfileFromRow(
   // Without this, a session at the exact-expiry millisecond would be served
   // for one extra turn here while being cleared by the reaper.
   if (
-    conv?.inferenceProfileExpiresAt != null &&
-    conv.inferenceProfileExpiresAt <= Date.now()
+    fields?.inferenceProfileExpiresAt != null &&
+    fields.inferenceProfileExpiresAt <= Date.now()
   ) {
     return undefined;
   }
-  return conv?.inferenceProfile ?? undefined;
+  return fields?.inferenceProfile ?? undefined;
 }
 
 /**
  * Resolve the per-turn inference-profile override by conversation id.
- * Convenience wrapper around `getConversationOverrideProfileFromRow` for
- * standalone callers (e.g. subagent spawn, opportunity-wake) that don't
- * already have the row in hand.
+ * Convenience wrapper for standalone callers (e.g. subagent spawn,
+ * opportunity-wake) that don't already have the conversation in hand.
  */
 export function getConversationOverrideProfile(
   conversationId: string,
 ): string | undefined {
-  return getConversationOverrideProfileFromRow(getConversation(conversationId));
+  return resolveOverrideProfile(getConversation(conversationId));
 }
 
 export function setLastNotifiedInferenceProfile(

package/src/memory/conversation-starter-checkpoints.ts

@@ -15,6 +15,7 @@ import { memoryCheckpoints } from "./schema.js";
 export const CK_ITEM_COUNT = "conversation_starters:item_count_at_last_gen";
 export const CK_BATCH = "conversation_starters:generation_batch";
 export const CK_LAST_GEN_AT = "conversation_starters:last_gen_at";
+export const CK_LAST_ATTEMPT_AT = "conversation_starters:last_attempt_at";
 
 export function checkpointKey(base: string, scopeId: string): string {
   return `${base}:${scopeId}`;

package/src/memory/db-init.ts

@@ -41,6 +41,7 @@ import {
   migrate230AcpSessionHistory,
   migrate231RepairMemoryGraphEventDates,
   migrateA2ATasks,
+  migrateAcpSessionHistoryCwd,
   migrateActivationState,
   migrateActivationStateFkCascade,
   migrateAddConversationInferenceProfile,
@@ -478,6 +479,7 @@ export function initializeDb(): void {
     migrateScheduleSourceConversation,
     migrateMessagesRoleCreatedAtIndex,
     createAuthFallbackEventsTable,
+    migrateAcpSessionHistoryCwd,
   ];
 
   // Run each migration step, catching and logging individual failures so one

package/src/memory/job-handlers/conversation-starters.ts

@@ -22,6 +22,7 @@ import {
   checkpointKey,
   CK_BATCH,
   CK_ITEM_COUNT,
+  CK_LAST_ATTEMPT_AT,
   CK_LAST_GEN_AT,
   countActiveMemoryNodes,
   getCheckpointValue,
@@ -336,6 +337,7 @@ Bad → Good (incomplete phrase → complete):
         config: {
           callSite: "conversationStarters" as const,
           max_tokens: 2048,
+          temperature: 0.7,
           tool_choice: {
             type: "tool" as const,
             name: "store_conversation_starters",
@@ -395,18 +397,27 @@ export async function generateConversationStartersJob(
   const db = getDb();
   const now = Date.now();
 
+  // Record attempt time so the route handler's cooldown prevents rapid retries
+  // even when generation produces 0 valid starters.
+  upsertCheckpoint(
+    checkpointKey(CK_LAST_ATTEMPT_AT, scopeId),
+    String(now),
+    now,
+  );
+
   const starters = await generateStarters(scopeId);
   if (starters.length === 0) {
     log.info({ scopeId }, "No conversation starters generated");
 
-    // Sync checkpoints so both `staleByAge` and `checkpointAhead` clear.
+    // Sync the item count checkpoint so `checkpointAhead` clears, but do NOT
+    // update `CK_LAST_GEN_AT` — the stale TTL should trigger a retry on the
+    // next GET rather than blocking retries for the full TTL window.
     const totalActive = countActiveMemoryNodes(scopeId);
     upsertCheckpoint(
       checkpointKey(CK_ITEM_COUNT, scopeId),
       String(totalActive),
       now,
     );
-    upsertCheckpoint(checkpointKey(CK_LAST_GEN_AT, scopeId), String(now), now);
     return;
   }
 

package/src/memory/jobs/__tests__/embed-concept-page.test.ts

@@ -143,9 +143,8 @@ afterAll(() => {
 // `getWorkspaceDir()` resolves to the tmpdir.
 const { DEFAULT_CONFIG } = await import("../../../config/defaults.js");
 const { getDb } = await import("../../db-connection.js");
-const { resetDbForTesting } = await import(
-  "../../../__tests__/db-test-helpers.js"
-);
+const { resetDbForTesting } =
+  await import("../../../__tests__/db-test-helpers.js");
 const { initializeDb } = await import("../../db-init.js");
 const { memoryEmbeddings, memoryJobs } = await import("../../schema.js");
 const { claimMemoryJobs } = await import("../../jobs-store.js");
@@ -187,12 +186,14 @@ function makeJob(payload: Record<string, unknown>): MemoryJob {
 
 beforeEach(() => {
   resetDbForTesting();
+  // The first run pays the full cold-start migration chain; bump the hook
+  // timeout above bun's 5s default so the leading test doesn't flake in CI.
   initializeDb();
   embedWithBackendCalls.length = 0;
   upsertCalls.length = 0;
   deleteCalls.length = 0;
   _resetQdrantBreaker();
-});
+}, 30_000);
 
 afterEach(() => {
   // Clean up any pages written between tests so each scenario starts fresh.

package/src/memory/jobs-worker.ts

@@ -8,6 +8,7 @@ import {
   diskPressureBackgroundSkipLogFields,
   shouldLogDiskPressureBackgroundSkip,
 } from "../daemon/disk-pressure-background-gate.js";
+import { maintainJob as memoryV3MaintainJob } from "../plugins/defaults/memory-v3-shadow/maintain-job.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir } from "../util/platform.js";
 import { getMemoryCheckpoint, setMemoryCheckpoint } from "./checkpoints.js";
@@ -87,7 +88,6 @@ import {
   memoryV2ConsolidateJob,
 } from "./v2/consolidation-job.js";
 import { memoryV2SweepJob } from "./v2/sweep-job.js";
-import { maintainJob as memoryV3MaintainJob } from "./v3/maintain-job.js";
 
 const log = getLogger("memory-jobs-worker");
 
@@ -95,6 +95,16 @@ const AUTOMATIC_CONSOLIDATION_JOB_PAYLOAD = {
   trigger: MEMORY_V2_CONSOLIDATION_JOB_TRIGGERS.automatic,
 } as const;
 
+/**
+ * Minimum buffer entries required for a scheduled consolidation run. The
+ * time-based schedule noops when `memory/buffer.md` has fewer non-empty lines
+ * than this threshold — the LLM cost of a full consolidation pass outweighs
+ * the benefit when the buffer is nearly empty. Mirrors the heartbeat
+ * max-consecutive-runs skip pattern. Manual "Run now" and the size-based
+ * trigger are not affected.
+ */
+export const MIN_BUFFER_LINES_FOR_CONSOLIDATION = 10;
+
 /**
  * V1 job types that read or write the v1 Qdrant collection via
  * `getQdrantClient()`. When `memory.v2.enabled` is true, the v1 client is
@@ -815,6 +825,20 @@ export function maybeEnqueueGraphMaintenanceJobs(
   for (const { key, intervalMs, jobType } of schedule) {
     const lastRun = parseInt(getMemoryCheckpoint(key) ?? "0", 10);
     if (nowMs - lastRun >= intervalMs) {
+      // Noop scheduled consolidation when the buffer has too few entries to
+      // justify an LLM run — mirrors the heartbeat max-consecutive-runs skip.
+      // The checkpoint advances so the next check fires after the regular
+      // interval. Manual "Run now" is unaffected (routes layer, not schedule).
+      if (jobType === consolidateEntry.jobType) {
+        const bufferPath = join(getWorkspaceDir(), "memory", "buffer.md");
+        if (countBufferLines(bufferPath) < MIN_BUFFER_LINES_FOR_CONSOLIDATION) {
+          log.debug(
+            "Scheduled consolidation skipped: buffer under minimum line threshold",
+          );
+          setMemoryCheckpoint(key, String(nowMs));
+          continue;
+        }
+      }
       const payload =
         jobType === consolidateEntry.jobType
           ? AUTOMATIC_CONSOLIDATION_JOB_PAYLOAD

package/src/memory/migrations/272-acp-session-history-cwd.ts

@@ -0,0 +1,36 @@
+import type { DrizzleDb } from "../db-connection.js";
+import { getSqliteFrom } from "../db-connection.js";
+import { withCrashRecovery } from "./validate-migration-state.js";
+
+const CHECKPOINT_KEY = "migration_acp_session_history_cwd_v1";
+
+const TABLE = "acp_session_history";
+const COLUMN = "cwd";
+
+/**
+ * Add a nullable `cwd TEXT` column to `acp_session_history`.
+ *
+ * Records the working directory the ACP agent process was spawned with so
+ * that a persisted session can later be resumed (`session/load` /
+ * `session/resume` both require the original cwd to reconstruct params).
+ *
+ * `NULL` for rows persisted before this migration ran — legacy sessions
+ * simply are not resumable.
+ *
+ * Idempotent — the PRAGMA guard makes re-running a no-op once the column
+ * exists.
+ */
+export function migrateAcpSessionHistoryCwd(database: DrizzleDb): void {
+  withCrashRecovery(database, CHECKPOINT_KEY, () => {
+    const raw = getSqliteFrom(database);
+
+    const columns = raw.query(`PRAGMA table_info(${TABLE})`).all() as Array<{
+      name: string;
+    }>;
+    const columnNames = new Set(columns.map((c) => c.name));
+
+    if (!columnNames.has(COLUMN)) {
+      raw.exec(`ALTER TABLE ${TABLE} ADD COLUMN ${COLUMN} TEXT`);
+    }
+  });
+}

package/src/memory/migrations/index.ts

@@ -259,6 +259,7 @@ export { migrateScheduleScriptTimeout } from "./269-schedule-script-timeout.js";
 export { migrateMessagesRoleCreatedAtIndex } from "./270-messages-role-created-at-index.js";
 export { migrateScheduleSourceConversation } from "./270-schedule-source-conversation.js";
 export { createAuthFallbackEventsTable } from "./271-create-auth-fallback-events.js";
+export { migrateAcpSessionHistoryCwd } from "./272-acp-session-history-cwd.js";
 export {
   MIGRATION_REGISTRY,
   type MigrationRegistryEntry,

package/src/memory/schema/acp.ts

@@ -20,6 +20,10 @@ export const acpSessionHistory = sqliteTable(
     stopReason: text("stop_reason"),
     error: text("error"),
     eventLogJson: text("event_log_json").notNull().default("[]"),
+    // Working directory the agent process was spawned with. Required to
+    // resume a persisted session; null for rows written before migration
+    // 272 (those sessions are not resumable).
+    cwd: text("cwd"),
   },
   (table) => [
     index("idx_acp_session_history_started_at").on(table.startedAt),

package/src/memory/v2/__tests__/consolidation-job.test.ts

@@ -121,7 +121,7 @@ mock.module("../../../config/assistant-feature-flags.js", () => ({
 
 let renderedHealth = "";
 let computeThrows = false;
-mock.module("../../v3/health.js", () => ({
+mock.module("../../../plugins/defaults/memory-v3-shadow/health.js", () => ({
   computeV3Health: () => {
     if (computeThrows) throw new Error("simulated health compute failure");
     return {};
@@ -129,12 +129,12 @@ mock.module("../../v3/health.js", () => ({
   renderV3Health: () => renderedHealth,
 }));
 
-mock.module("../../v3/tree.js", () => ({
+mock.module("../../../plugins/defaults/memory-v3-shadow/tree.js", () => ({
   loadLeafTree: async () => ({ leaves: new Map(), byPage: new Map() }),
   resolveDataDir: () => "/tmp/v3-data-stub",
 }));
 
-mock.module("../../v3/core.js", () => ({
+mock.module("../../../plugins/defaults/memory-v3-shadow/core.js", () => ({
   loadCore: async () => new Set<string>(),
 }));
 

package/src/memory/v2/consolidation-job.ts

@@ -63,6 +63,19 @@ import { dirname, join } from "node:path";
 
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import type { AssistantConfig } from "../../config/types.js";
+import { loadCore } from "../../plugins/defaults/memory-v3-shadow/core.js";
+import {
+  computeV3Health,
+  renderV3Health,
+} from "../../plugins/defaults/memory-v3-shadow/health.js";
+import {
+  loadLeafTree,
+  resolveDataDir,
+} from "../../plugins/defaults/memory-v3-shadow/tree.js";
+import type {
+  LeafPath,
+  Slug,
+} from "../../plugins/defaults/memory-v3-shadow/types.js";
 import { runBackgroundJob } from "../../runtime/background-job-runner.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
@@ -74,10 +87,6 @@ import {
   type MemoryJobType,
 } from "../jobs-store.js";
 import { getPageIndex } from "../v2/page-index.js";
-import { loadCore } from "../v3/core.js";
-import { computeV3Health, renderV3Health } from "../v3/health.js";
-import { loadLeafTree, resolveDataDir } from "../v3/tree.js";
-import type { LeafPath, Slug } from "../v3/types.js";
 import { MEMORY_V2_CONSOLIDATION_SOURCE } from "./constants.js";
 import { resolveConsolidationPrompt } from "./prompts/consolidation.js";
 

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, before it is persisted/streamed-final. A hook may transform the message content. */
+  ASSISTANT_MESSAGE: "assistant-message",
 } as const;
 
 /** Union of every hook name declared in {@link HOOKS}. */

package/src/plugin-api/index.ts

@@ -24,31 +24,32 @@
  * - {@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 AssistantMessageContext} — passed to `assistant-message` 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";
 export { HOOKS } from "./constants.js";
 export type {
+  AssistantMessageContext,
   PluginHookFn,
   PluginInitContext,
   PluginLogger,
   PluginShutdownContext,
   PostToolUseContext,
+  PreModelCallContext,
   StopContext,
   StopDecision,
   ToolContext,

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}
+ *   - `assistant-message` — {@link AssistantMessageContext}
  */
 export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
 
@@ -288,3 +291,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; an `assistant-message` 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;
+}
+
+// ─── Assistant-message hook context ──────────────────────────────────────────
+
+/**
+ * Context passed to the `assistant-message` 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 AssistantMessageContext {
+  /** 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;
+}