@vellumai/assistant 0.8.7 → 0.8.8-dev.202606052332.17fc8ea

package/src/memory/schedule-attribution-sql.ts

@@ -0,0 +1,104 @@
+export interface ScheduleAttributionFilter {
+  scheduleId?: string;
+}
+
+export type ScheduleAttributionSqlParam = string | number;
+
+export interface ScheduleAttributionSqlFragment {
+  sql: string;
+  params: ScheduleAttributionSqlParam[];
+}
+
+export function normalizeScheduleAttributionFilter(
+  filter?: ScheduleAttributionFilter,
+): ScheduleAttributionFilter {
+  const scheduleId = filter?.scheduleId?.trim();
+  return scheduleId ? { scheduleId } : {};
+}
+
+function usageColumn(column: string, eventAlias: string): string {
+  return `${eventAlias}.${column}`;
+}
+
+function buildScheduleRunWindowPredicate({
+  eventAlias,
+  runAlias,
+  filter,
+}: {
+  eventAlias: string;
+  runAlias: string;
+  filter?: ScheduleAttributionFilter;
+}): string {
+  const normalized = normalizeScheduleAttributionFilter(filter);
+  const scheduleClause = normalized.scheduleId
+    ? `${runAlias}.job_id = ? AND `
+    : "";
+  return `${scheduleClause}${runAlias}.conversation_id = ${usageColumn(
+    "conversation_id",
+    eventAlias,
+  )}
+    AND ${usageColumn("created_at", eventAlias)} >= ${runAlias}.started_at
+    AND ${usageColumn("created_at", eventAlias)} <= COALESCE(${runAlias}.finished_at, ?)`;
+}
+
+function buildScheduleRunWindowParams(
+  filter: ScheduleAttributionFilter | undefined,
+  now: number,
+): ScheduleAttributionSqlParam[] {
+  const normalized = normalizeScheduleAttributionFilter(filter);
+  return normalized.scheduleId ? [normalized.scheduleId, now] : [now];
+}
+
+export function buildScheduleRunWindowExists({
+  eventAlias,
+  filter,
+  now,
+  runAlias = "schedule_filter_runs",
+}: {
+  eventAlias: string;
+  filter?: ScheduleAttributionFilter;
+  now: number;
+  runAlias?: string;
+}): ScheduleAttributionSqlFragment {
+  return {
+    sql: `EXISTS (
+      SELECT 1
+      FROM cron_runs ${runAlias}
+      WHERE ${buildScheduleRunWindowPredicate({
+        eventAlias,
+        runAlias,
+        filter,
+      })}
+    )`,
+    params: buildScheduleRunWindowParams(filter, now),
+  };
+}
+
+export function buildScheduleAttributionSubquery({
+  eventAlias,
+  filter,
+  now,
+  selectExpression,
+  runAlias = "schedule_attr_runs",
+}: {
+  eventAlias: string;
+  filter?: ScheduleAttributionFilter;
+  now: number;
+  selectExpression: string;
+  runAlias?: string;
+}): ScheduleAttributionSqlFragment {
+  return {
+    sql: `(
+    SELECT ${selectExpression}
+    FROM cron_runs ${runAlias}
+    WHERE ${buildScheduleRunWindowPredicate({
+      eventAlias,
+      runAlias,
+      filter,
+    })}
+    ORDER BY ${runAlias}.started_at DESC, ${runAlias}.id DESC
+    LIMIT 1
+  )`,
+    params: buildScheduleRunWindowParams(filter, now),
+  };
+}

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/schema/infrastructure.ts

@@ -22,6 +22,7 @@ export const cronJobs = sqliteTable("cron_jobs", {
   maxRetries: integer("max_retries").notNull().default(3),
   retryBackoffMs: integer("retry_backoff_ms").notNull().default(60000),
   timeoutMs: integer("timeout_ms"), // script-mode execution timeout override (ms); null = use default
+  createdFromConversationId: text("created_from_conversation_id"),
   createdBy: text("created_by").notNull(), // 'agent' | 'user'
   mode: text("mode").notNull().default("execute"), // 'notify' | 'execute'
   routingIntent: text("routing_intent").notNull().default("all_channels"), // 'single_channel' | 'multi_channel' | 'all_channels'
@@ -278,6 +279,21 @@ export const onboardingEvents = sqliteTable("onboarding_events", {
   abVariant: text("ab_variant"),
 });
 
+// Aggregated legacy-loopback auth-fallback counts forwarded by the gateway.
+// One row per (guard, path, failure_kind) per flush window; `count` is how many
+// requests fell back to the loopback exemption in that window. Flushed to the
+// platform telemetry endpoint by the usage telemetry reporter.
+export const authFallbackEvents = sqliteTable("auth_fallback_events", {
+  id: text("id").primaryKey(),
+  createdAt: integer("created_at").notNull(),
+  guard: text("guard").notNull(), // 'edge' | 'edge-scoped' | 'edge-guardian'
+  path: text("path").notNull(),
+  failureKind: text("failure_kind").notNull(),
+  count: integer("count").notNull(),
+  windowStart: integer("window_start").notNull(),
+  windowEnd: integer("window_end").notNull(),
+});
+
 export const traceEvents = sqliteTable(
   "trace_events",
   {

package/src/memory/usage-grouped-buckets.ts

@@ -27,6 +27,7 @@ export interface UsageGroupedSeriesBucket extends UsageDayBucket {
 
 export interface UsageGroupedBucketRow extends UsageEventBucketRow {
   group_key: string | null;
+  group_label?: string | null;
 }
 
 const VALUE_GROUP_PREFIX = "value:";
@@ -42,6 +43,9 @@ export function displayUsageGroup(
   if (groupBy === "inference_profile") {
     return groupKey === null ? "Default / Unset" : groupKey;
   }
+  if (groupBy === "schedule") {
+    return groupKey ?? "Other";
+  }
   return groupKey ?? "Other";
 }
 
@@ -102,7 +106,8 @@ export function bucketGroupedUsageEvents(
     let group = groupedBucket.groups[seriesKey];
     if (!group) {
       group = {
-        group: displayUsageGroup(options.groupBy, row.group_key),
+        group:
+          row.group_label ?? displayUsageGroup(options.groupBy, row.group_key),
         groupKey: row.group_key,
         totalInputTokens: 0,
         totalOutputTokens: 0,

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>(),
 }));
 
@@ -279,7 +279,7 @@ describe("memoryV2ConsolidateJob — non-empty buffer", () => {
     expect(runnerLastArgs).not.toBeNull();
     expect(runnerLastArgs?.jobName).toBe("memory.consolidate");
     expect(runnerLastArgs?.source).toBe("memory_v2_consolidation");
-    expect(runnerLastArgs?.callSite).toBe("mainAgent");
+    expect(runnerLastArgs?.callSite).toBe("memoryV2Consolidation");
     expect(runnerLastArgs?.origin).toBe("memory_consolidation");
     // The whole point of this PR: opt out of activity.failed notifications
     // because consolidation runs on tight intervals and transient failures

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";
 
@@ -197,7 +206,7 @@ export async function memoryV2ConsolidateJob(
       source: MEMORY_V2_CONSOLIDATION_SOURCE,
       prompt,
       trustContext: { sourceChannel: "vellum", trustClass: "guardian" },
-      callSite: "mainAgent",
+      callSite: "memoryV2Consolidation",
       timeoutMs: CONSOLIDATION_TIMEOUT_MS,
       origin: "memory_consolidation",
       suppressFailureNotifications: true,

package/src/notifications/conversation-pairing.ts

@@ -21,7 +21,6 @@
 import type { ConversationStrategy } from "../channels/config.js";
 import { getConversationStrategy } from "../channels/config.js";
 import type { ChannelId } from "../channels/types.js";
-import { isHomePageEnabled } from "../home/feature-gate.js";
 import {
   addMessage,
   createConversation,
@@ -120,20 +119,14 @@ export async function pairDeliveryWithConversation(
     // Passive vellum notifications surface via the home feed alone and link
     // back to the originating conversation via `signal.sourceContextId`.
     // Materializing a fresh per-notification conversation just to host the
-    // seed message leaves a graveyard entry in the sidebar; skip it unless
-    // the producer opted in via `requiresConversation` or the decision engine
-    // requested explicit reuse of a target conversation.
-    //
-    // Gated on `home-page`: the home feed is the surface that hosts passive
-    // notifications, so when the flag is off there is nowhere for them to
-    // land — fall through and create a conversation (the pre-home-feed
-    // behavior) to preserve the notification's only surface.
-    if (
-      strategy === "start_new_conversation" &&
-      !signal.requiresConversation &&
-      conversationAction?.action !== "reuse_existing" &&
-      isHomePageEnabled()
-    ) {
+    // seed message leaves a graveyard entry in the sidebar; skip it
+    // unconditionally when the producer did not opt in via
+    // `requiresConversation`. The decision engine's `reuse_existing` hint is
+    // also ignored here: even a successful reuse would append a seed message
+    // to a conversation that the user didn't ask for, and a failed reuse
+    // (stale target / source mismatch) falls through to `createConversation`
+    // — producing exactly the graveyard entry we want to avoid.
+    if (strategy === "start_new_conversation" && !signal.requiresConversation) {
       return {
         conversationId: null,
         messageId: null,

package/src/notifications/decision-engine.ts

@@ -149,8 +149,8 @@ function buildSystemPrompt(
     `  - Avoid meta-send phrasing (e.g. "I'd like to send a notification", "May I go ahead with that?"). Write the recipient-facing message directly.`,
     `  - Avoid intermediary-instruction phrasing like "consider telling the guardian", "ask the recipient to", or "the assistant should remind them". Rewrite it as final copy the recipient can act on directly.`,
     `  - For telegram: 1-2 concise sentences.`,
-    `- \`conversationSeedMessage\` is the opening message in the internal notification conversation — it can be richer and more contextual.`,
-    `  - For vellum (desktop): 2-4 short sentences with useful context and clear next step if action is required.`,
+    `- \`conversationSeedMessage\` is the opening message in the internal notification conversation and also the expanded detail shown in the home feed. It should be richer and more contextual than the popup body.`,
+    `  - For vellum (desktop): use structured markdown for readability. Break content into bullet points, numbered lists, or short sections with **bold** labels. Avoid long unbroken paragraphs — scan-friendly formatting is preferred.`,
     `  - Never dump raw JSON. Include only human-readable context.`,
     ``,
     `Conversation reuse guidelines:`,
@@ -838,7 +838,10 @@ export async function evaluateSignal(
       selectedChannels,
       reasoningSummary: "assistant_tool pass-through",
       renderedCopy: Object.fromEntries(
-        availableChannels.map((ch) => [ch, { title, body }]),
+        availableChannels.map((ch) => [
+          ch,
+          { title, body, conversationSeedMessage: body },
+        ]),
       ) as NotificationDecision["renderedCopy"],
       conversationActions: Object.fromEntries(
         availableChannels.map((ch) => [ch, { action: "start_new" as const }]),

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

@@ -21,6 +21,7 @@ import { appendFeedItem } from "../home/feed-writer.js";
 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 type { NotificationSignal } from "./signal.js";
 import type { NotificationDecision, RenderedChannelCopy } from "./types.js";
 
@@ -77,8 +78,18 @@ export async function writeHomeFeedItemForSignal(
   // against `summary` in the row. Leave undefined when absent; renderers
   // fall back to `summary`.
   const resolvedTitle = payloadTitle?.trim() || undefined;
+  // Prefer conversationSeedMessage over body for the home feed: the seed
+  // message is richer and may contain structured markdown (lists, headers,
+  // bold) that the detail panel renders. The popup-oriented `body` is
+  // intentionally short (≤ 2 sentences) and loses formatting.
+  const seedCandidate = renderedCopy?.conversationSeedMessage;
   const resolvedSummary =
-    renderedCopy?.body?.trim() || payloadBody?.trim() || "";
+    (isConversationSeedSane(seedCandidate)
+      ? seedCandidate.trim()
+      : undefined) ||
+    renderedCopy?.body?.trim() ||
+    payloadBody?.trim() ||
+    "";
   if (!resolvedSummary) {
     log.warn(
       { signalId: signal.signalId, sourceEventName: signal.sourceEventName },

package/src/permissions/prompter.ts

@@ -118,6 +118,10 @@ export class PermissionPrompter {
             label: o.label,
             scope: o.scope,
           })),
+          directoryScopeOptions: directoryScopeOptions?.map((o) => ({
+            label: o.label,
+            scope: o.scope,
+          })),
           persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
         },
         rpcResolve: resolve as (value: unknown) => void,

package/src/plugin-api/constants.ts

@@ -20,6 +20,10 @@ export const HOOKS = {
   SHUTDOWN: "shutdown",
   /** Fires once per user turn, immediately before the agent loop receives `runMessages`. */
   USER_PROMPT_SUBMIT: "user-prompt-submit",
+  /** 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",
 } as const;
 
 /** Union of every hook name declared in {@link HOOKS}. */

package/src/plugin-api/index.ts

@@ -24,17 +24,16 @@
  * - {@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 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 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 (`LLMCallArgs`, `MemoryArgs`, 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";
@@ -44,6 +43,9 @@ export type {
   PluginInitContext,
   PluginLogger,
   PluginShutdownContext,
+  PostToolUseContext,
+  StopContext,
+  StopDecision,
   ToolContext,
   ToolDefinition,
   ToolExecutionResult,

package/src/plugin-api/types.ts

@@ -4,7 +4,11 @@
  * removing is breaking and gated on a major bump.
  */
 
-import type { Message } from "../providers/types.js";
+import type {
+  ContentBlock,
+  Message,
+  ToolResultContent,
+} from "../providers/types.js";
 
 export type {
   ToolContext,
@@ -47,6 +51,8 @@ export interface PluginLogger {
  *   - `init` — {@link PluginInitContext}
  *   - `shutdown` — {@link PluginShutdownContext}
  *   - `user-prompt-submit` — {@link UserPromptSubmitContext}
+ *   - `post-tool-use` — {@link PostToolUseContext}
+ *   - `stop` — {@link StopContext}
  */
 export type PluginHookFn<TCtx = unknown> = (ctx: TCtx) => Promise<TCtx | void>;
 
@@ -121,6 +127,16 @@ export interface PluginShutdownContext {
 export interface UserPromptSubmitContext {
   /** Conversation ID the user prompt was submitted on. */
   readonly conversationId: string;
+  /**
+   * The text of the user prompt that triggered this turn — the resolved
+   * user message (after slash-command expansion), independent of any
+   * internal rewriting applied to the message that flows into the model.
+   * Mirrors the `prompt` field Claude Code / Codex pass to their
+   * `UserPromptSubmit` hooks, so hooks that key off the submitted text
+   * (e.g. title generation) read it directly rather than reconstructing
+   * it from the message arrays.
+   */
+  readonly prompt: string;
   /**
    * The user's original message list, immutable for the hook. Plugins
    * may snapshot or compare against this but MUST NOT mutate it.
@@ -138,3 +154,137 @@ export interface UserPromptSubmitContext {
    */
   readonly logger: PluginLogger;
 }
+
+// ─── Post-tool-use hook context ──────────────────────────────────────────────
+
+/**
+ * Context passed to the `post-tool-use` hook. Fires once per tool result —
+ * after the tool returns and before the result is appended to the message
+ * history sent to the provider. With several tools dispatched in a single
+ * turn, the hook fires once per result, in tool-use order.
+ *
+ * The hook may transform the result either by mutating `toolResponse` in
+ * place (e.g. reassigning `toolResponse.content`) or by returning a new
+ * context with a fresh `toolResponse` — see {@link PluginHookFn}'s
+ * polymorphic return shape. The daemon threads the final `toolResponse`
+ * into the provider-bound history.
+ *
+ * Multiple plugins' hooks chain in registration order — each plugin's hook
+ * sees the previous plugin's mutations. The default tool-result-truncate
+ * plugin contributes a hook here that tail-drops oversized output to fit the
+ * model's context window; the default tool-error plugin sets
+ * {@link additionalContext} with retry coaching for failed results. User hooks
+ * can swap in a smarter strategy (e.g. a summarizer) or observe results for
+ * side effects.
+ */
+export interface PostToolUseContext {
+  /** Conversation ID the tool ran on. */
+  readonly conversationId: string;
+  /**
+   * The tool result block. Plugins may mutate its `content` in place or
+   * replace the block by returning a new context.
+   */
+  toolResponse: ToolResultContent;
+  /**
+   * Conversation history up to and including the assistant turn that issued
+   * this tool call. The current result is not in it yet — it lives in
+   * {@link toolResponse}. A hook reasoning about prior tool outcomes (e.g.
+   * how many times a tool has failed in a row) derives that from the history
+   * content rather than a precomputed counter, so the signal survives mid-run
+   * compaction rewriting the array. Read-only: hooks transform the result via
+   * {@link toolResponse}, not by mutating history.
+   */
+  readonly messages: ReadonlyArray<Message>;
+  /**
+   * Extra guidance for the model that is not part of the tool's output. A hook
+   * sets this to surface provider-only context — e.g. retry coaching for a
+   * failed result — and the daemon appends it to the provider-bound history as
+   * a separate block *after* emitting the tool_result, so it reaches the model
+   * without polluting the client-facing or persisted tool output. Mirrors
+   * Claude Code's PostToolUse `hookSpecificOutput.additionalContext` and the
+   * singular of Codex's `additional_contexts`. Unset means no extra context.
+   */
+  additionalContext?: string;
+  /**
+   * The model's context-window size in tokens. Plugins derive their own
+   * character budget from this (e.g. a share of the window) rather than
+   * receiving a precomputed limit.
+   */
+  readonly maxInputTokens: number;
+  /**
+   * Logger scoped to the current turn. The same instance is shared by
+   * every hook in the chain, so plugins should tag their structured log
+   * fields (e.g. `{ plugin: "<name>" }`) for attribution.
+   */
+  readonly logger: PluginLogger;
+}
+
+// ─── Stop hook context ───────────────────────────────────────────────────────
+
+/**
+ * Binary outcome of the `stop` hook. The agent loop seeds it to `"stop"`
+ * and acts on the value the chain settles on:
+ *
+ * - `"stop"`     — let the turn end; the loop yields the assistant response
+ *                  to the user. This is the default.
+ * - `"continue"` — re-query the model. The hook is responsible for appending
+ *                  the follow-up turn it wants the model to see to
+ *                  {@link StopContext.messages} before returning.
+ *
+ * To abort with an error a hook should throw — the loop's error handler
+ * surfaces it. There is intentionally no error decision value.
+ */
+export type StopDecision = "continue" | "stop";
+
+/**
+ * Context passed to the `stop` hook. Fires when the model yields a response
+ * with no tool calls — the run's stop boundary, where the loop is about to
+ * hand the turn back to the user. The default empty-response plugin uses it
+ * to re-query the model when a turn came back empty or as a provider refusal.
+ *
+ * The hook decides the outcome by setting {@link decision}. When it sets
+ * `"continue"` it must also append the follow-up turn (e.g. a nudge `user`
+ * message) to {@link messages}; the loop threads those messages into the next
+ * iteration. {@link messages} is the full conversation history, carried back
+ * verbatim. A hook that needs to reason about just the current response cycle
+ * (e.g. whether an earlier turn already delivered visible text) derives that
+ * boundary from the history itself — the messages after the last genuine user
+ * prompt — rather than an index, since mid-run compaction can rewrite the
+ * array.
+ *
+ * Multiple plugins' hooks chain in registration order — each sees the
+ * previous hook's `decision` and `messages` mutations.
+ */
+export interface StopContext {
+  /** Conversation ID the run belongs to. */
+  readonly conversationId: string;
+  /**
+   * Full conversation history: the inbound conversation followed by every
+   * message produced this run. A hook that sets `decision` to `"continue"`
+   * appends its follow-up turn here; the loop carries the result into the
+   * next iteration.
+   */
+  messages: Message[];
+  /**
+   * Content blocks of the assistant turn that triggered the stop. Guaranteed
+   * to contain no `tool_use` blocks — the hook only fires at the boundary
+   * where the model stopped requesting tools.
+   */
+  readonly responseContent: ReadonlyArray<ContentBlock>;
+  /**
+   * Provider-reported stop reason for the assistant turn (e.g. `"refusal"`,
+   * `"end_turn"`). `null`/`undefined` when the provider didn't report one.
+   */
+  readonly stopReason: string | null | undefined;
+  /**
+   * Seeded to `"stop"`. A hook sets it to `"continue"` to force another loop
+   * iteration; later hooks in the chain may override it.
+   */
+  decision: StopDecision;
+  /**
+   * Logger scoped to the current turn. The same instance is shared by
+   * every hook in the chain, so plugins should tag their structured log
+   * fields (e.g. `{ plugin: "<name>" }`) for attribution.
+   */
+  readonly logger: PluginLogger;
+}

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/plugins/defaults/compaction/package.json

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