@vellumai/assistant 0.8.5 → 0.8.6

package/src/oauth/connection-resolver.ts

@@ -9,6 +9,7 @@ import { getLogger } from "../util/logger.js";
 import { BYOOAuthConnection } from "./byo-connection.js";
 import type { OAuthConnection } from "./connection.js";
 import { getConnectionAccessTokenResult } from "./credential-token-resolver.js";
+import { syncManualTokenConnection } from "./manual-token-connection.js";
 import { getActiveConnection, getProvider } from "./oauth-store.js";
 import { PlatformOAuthConnection } from "./platform-connection.js";
 
@@ -82,6 +83,10 @@ export async function resolveOAuthConnection(
   }
 
   // BYO path — requires a local connection row, access token, and base URL.
+  if (providerRow?.authorizeUrl === "urn:manual-token") {
+    await syncManualTokenConnection(provider);
+  }
+
   const conn = getActiveConnection(provider, { clientId, account });
   if (!conn) {
     const filters = [
@@ -185,20 +190,26 @@ interface ResolvePlatformConnectionIdOptions {
   account?: string;
 }
 
+interface PlatformConnectionEntry {
+  id: string;
+  account_label?: string | null;
+}
+
 /**
- * Fetch the platform-side connection ID for a managed provider by calling
- * the List Connections endpoint.
+ * Fetch active platform connections for a managed provider by calling the
+ * List Connections endpoint.
  */
-async function resolvePlatformConnectionId(
-  options: ResolvePlatformConnectionIdOptions,
-): Promise<string> {
-  const { client, provider, account } = options;
-
+async function fetchPlatformConnections(options: {
+  client: VellumPlatformClient;
+  provider: string;
+  accountIdentifier?: string;
+}): Promise<PlatformConnectionEntry[]> {
+  const { client, provider, accountIdentifier } = options;
   const params = new URLSearchParams();
   params.set("provider", provider);
   params.set("status", "ACTIVE");
-  if (account) {
-    params.set("account_identifier", account);
+  if (accountIdentifier) {
+    params.set("account_identifier", accountIdentifier);
   }
 
   const path = `/v1/assistants/${client.platformAssistantId}/oauth/connections/?${params.toString()}`;
@@ -219,7 +230,35 @@ async function resolvePlatformConnectionId(
     Array.isArray(body)
       ? body
       : ((body as Record<string, unknown>).results ?? [])
-  ) as Array<{ id: string; account_label?: string }>;
+  ) as PlatformConnectionEntry[];
+  return connections;
+}
+
+/**
+ * Fetch the platform-side connection ID for a managed provider by calling
+ * the List Connections endpoint.
+ */
+async function resolvePlatformConnectionId(
+  options: ResolvePlatformConnectionIdOptions,
+): Promise<string> {
+  const { client, provider, account } = options;
+
+  let connections = await fetchPlatformConnections({
+    client,
+    provider,
+    accountIdentifier: account,
+  });
+
+  if (account && connections.length === 0) {
+    const unfilteredConnections = await fetchPlatformConnections({
+      client,
+      provider,
+    });
+    connections = unfilteredConnections.filter(
+      (connection) =>
+        connection.account_label === account || connection.id === account,
+    );
+  }
 
   if (connections.length === 0) {
     throw new Error(

package/src/oauth/manual-token-connection.ts

@@ -10,6 +10,7 @@
 
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyResultAsync } from "../security/secure-keys.js";
+import { getTelegramBotUsername } from "../telegram/bot-username.js";
 import { getLogger } from "../util/logger.js";
 import {
   createConnection,
@@ -24,6 +25,44 @@ const log = getLogger("manual-token-connection");
 /** Sentinel client_id used for non-OAuth providers that don't have a real app. */
 const MANUAL_TOKEN_CLIENT_ID = "manual-config";
 
+type ResolvedAccountInfoSource = "provided" | "derived" | "none";
+
+interface ResolvedAccountInfo {
+  value?: string;
+  source: ResolvedAccountInfoSource;
+}
+
+function resolveManualTokenAccountInfo(
+  provider: string,
+  accountInfo?: string,
+): ResolvedAccountInfo {
+  if (accountInfo !== undefined) {
+    return { value: accountInfo, source: "provided" };
+  }
+
+  if (provider === "telegram") {
+    const botUsername = getTelegramBotUsername();
+    if (!botUsername) return { source: "none" };
+    return {
+      value: botUsername.startsWith("@") ? botUsername : `@${botUsername}`,
+      source: "derived",
+    };
+  }
+
+  return { source: "none" };
+}
+
+function accountInfoForManualTokenSync(
+  provider: string,
+  resolved: ResolvedAccountInfo,
+): string | undefined {
+  if (resolved.source !== "derived") return resolved.value;
+
+  const existing = getConnectionByProvider(provider);
+  if (existing?.accountInfo) return undefined;
+  return resolved.value;
+}
+
 /**
  * Ensure an active oauth_connection row exists for the given manual-token
  * provider. Creates the synthetic oauth_app row on first use.
@@ -79,6 +118,15 @@ export async function syncManualTokenConnection(
   provider: string,
   accountInfo?: string,
 ): Promise<void> {
+  const resolvedAccountInfo = resolveManualTokenAccountInfo(
+    provider,
+    accountInfo,
+  );
+  const accountInfoToStore = accountInfoForManualTokenSync(
+    provider,
+    resolvedAccountInfo,
+  );
+
   switch (provider) {
     case "telegram": {
       const botTokenResult = await getSecureKeyResultAsync(
@@ -94,7 +142,7 @@ export async function syncManualTokenConnection(
         return;
       }
       if (botTokenResult.value && webhookSecretResult.value) {
-        await ensureManualTokenConnection(provider, accountInfo);
+        await ensureManualTokenConnection(provider, accountInfoToStore);
       } else {
         removeManualTokenConnection(provider);
       }
@@ -115,7 +163,7 @@ export async function syncManualTokenConnection(
         return;
       }
       if (botTokenResult.value && appTokenResult.value) {
-        await ensureManualTokenConnection(provider, accountInfo);
+        await ensureManualTokenConnection(provider, accountInfoToStore);
       } else {
         removeManualTokenConnection(provider);
       }
@@ -133,7 +181,7 @@ export async function syncManualTokenConnection(
         return;
       }
       if (tokenResult.value) {
-        await ensureManualTokenConnection(provider, accountInfo);
+        await ensureManualTokenConnection(provider, accountInfoToStore);
       } else {
         removeManualTokenConnection(provider);
       }

package/src/oauth/seed-providers.ts

@@ -199,6 +199,9 @@ export const PROVIDER_SEED_DATA: Record<
       },
     ],
     appType: "Public integration",
+    setupNotes: [
+      "Enable Token Rotation on your Notion integration (developer dashboard → your integration → Configuration → Token rotation). Without it, Notion does not issue a refresh token and the connection cannot auto-recover if Notion revokes the access token server-side — you will silently lose access and need to reconnect manually.",
+    ],
     identityUrl: "https://api.notion.com/v1/users/me",
     identityHeaders: { "Notion-Version": "2022-06-28" },
     identityResponsePaths: ["name", "person.email"],

package/src/permissions/approval-policy.test.ts

@@ -334,6 +334,19 @@ describe("no rule — third-party skill tool", () => {
     expect(result.reason).toContain("Skill tool");
   });
 
+  test("plugin origin → treated as extension-owned (prompt at strict threshold)", () => {
+    // Plugins join skills in the "extension-owned" bucket — both prompt by
+    // default. `isSkillBundled` is irrelevant for plugins (always false).
+    const result = evaluate({
+      riskLevel: RiskLevel.Low,
+      toolName: "custom_plugin_tool",
+      toolOrigin: "plugin",
+      autoApproveUpTo: "none",
+    });
+    expect(result.decision).toBe("prompt");
+    expect(result.reason).toContain("Skill tool");
+  });
+
   test("no tool origin but hasManifestOverride, strict threshold → prompt (unregistered skill tool)", () => {
     const result = evaluate({
       riskLevel: RiskLevel.Low,
@@ -699,16 +712,17 @@ describe("edge cases", () => {
     expect(result.reason).toContain("Skill tool");
   });
 
-  test("hasManifestOverride with toolOrigin set to builtin — falls through (not a skill)", () => {
+  test("hasManifestOverride with toolOrigin=mcp — falls through (not extension-owned)", () => {
     const result = evaluate({
       riskLevel: RiskLevel.Low,
       toolName: "manifest_tool",
-      toolOrigin: "builtin",
+      toolOrigin: "mcp",
       hasManifestOverride: true,
     });
-    // toolOrigin is "builtin", so the third-party skill check doesn't trigger.
-    // The hasManifestOverride check requires !toolOrigin, but toolOrigin is set.
-    // Falls through to risk-based: Low → allow (within default "low" threshold).
+    // toolOrigin is "mcp", which is not extension-class (skill/plugin), so
+    // the third-party skill check doesn't trigger. The hasManifestOverride
+    // sub-check requires !toolOrigin, but toolOrigin is set. Falls through
+    // to risk-based: Low → allow (within default "low" threshold).
     expect(result.decision).toBe("allow");
     expect(result.reason).toContain("low risk");
   });

package/src/permissions/approval-policy.ts

@@ -1,3 +1,4 @@
+import type { OwnerKind } from "../tools/types.js";
 import type { TrustRule } from "./types.js";
 import { RiskLevel } from "./types.js";
 
@@ -13,8 +14,13 @@ export interface ApprovalContext {
   matchedRule?: TrustRule;
   isContainerized: boolean;
   isWorkspaceScoped: boolean;
-  /** Where the tool originates from — "skill" for skill-provided tools, "builtin" for core tools. */
-  toolOrigin?: "skill" | "builtin";
+  /**
+   * Owner kind of the tool, as recorded by the tool registry — "skill" /
+   * "plugin" / "mcp" for extension-owned tools, `undefined` for core tools
+   * (and for tools that aren't registered, e.g. unregistered skill tools
+   * matched only via `hasManifestOverride`).
+   */
+  toolOrigin?: OwnerKind;
   /** Whether the tool's owning skill is a first-party bundled skill. */
   isSkillBundled?: boolean;
   /** Whether the tool has a manifest override (unregistered skill tool). */
@@ -173,8 +179,13 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
 
     // ── 6. No rule + third-party skill tool → prompt (unless threshold covers it)
     if (!matchedRule) {
+      // Plugin- and skill-owned tools are both treated as extension-class
+      // for approval purposes: external by default, prompt unless bundled.
+      // MCP-owned tools fall through to the core risk-based path.
+      const isExtensionOwned =
+        toolOrigin === "skill" || toolOrigin === "plugin";
       const isThirdPartySkill =
-        (toolOrigin === "skill" && !isSkillBundled) ||
+        (isExtensionOwned && !isSkillBundled) ||
         (hasManifestOverride && !toolOrigin);
       if (isThirdPartySkill) {
         if (isRiskWithinThreshold(riskLevel, context.autoApproveUpTo)) {

package/src/permissions/checker.ts

@@ -15,7 +15,8 @@ import {
   looksLikeHostPortShorthand,
   looksLikePathOnlyInput,
 } from "../tools/network/url-safety.js";
-import { getTool } from "../tools/registry.js";
+import { getTool, getToolOwner } from "../tools/registry.js";
+import type { Tool } from "../tools/types.js";
 import {
   getDeprecatedDir,
   getProtectedDir,
@@ -150,6 +151,23 @@ function resolveSkillIdAndHash(
   }
 }
 
+/**
+ * Resolve whether the skill that owns this tool is bundled (first-party).
+ * Returns false when the tool has no owning skill or the skill is not in
+ * the catalog. Derived from `loadSkillCatalog()` at check time so the
+ * answer reflects current catalog truth (managed overrides flip the bit
+ * without needing to re-register tools). Owner is looked up from the tool
+ * registry (`getToolOwner(name)`) rather than read from the `Tool` object,
+ * since ownership lives on the registry, not on the tool itself.
+ */
+function isToolOwnerSkillBundled(tool: Tool | undefined): boolean {
+  if (!tool) return false;
+  const owner = getToolOwner(tool.name);
+  if (owner?.kind !== "skill") return false;
+  const skill = loadSkillCatalog().find((s) => s.id === owner.id);
+  return skill?.bundled ?? false;
+}
+
 /**
  * Check whether a skill (by id) has parsed inline command expansions.
  * Returns false when the skill is not found in the catalog.
@@ -529,13 +547,8 @@ export async function check(
       risk === RiskLevel.Low
         ? isWorkspaceScopedInvocation(toolName, input, workingDir)
         : false,
-    toolOrigin:
-      tool?.origin === "skill" || tool?.origin === "plugin"
-        ? "skill"
-        : tool
-          ? "builtin"
-          : undefined,
-    isSkillBundled: tool?.ownerSkillBundled ?? false,
+    toolOrigin: getToolOwner(toolName)?.kind,
+    isSkillBundled: isToolOwnerSkillBundled(tool),
     hasManifestOverride: !!manifestOverride,
     autoApproveUpTo: threshold,
     hasSandboxAutoApprove,

package/src/platform/client.test.ts

@@ -10,6 +10,7 @@ let mockManagedProxyCtx = {
   assistantApiKey: "",
 };
 let mockAssistantId = "";
+let mockSecureKeys: Record<string, string | null | undefined> = {};
 
 // ---------------------------------------------------------------------------
 // Module mocks
@@ -26,7 +27,7 @@ mock.module("../config/env.js", () => ({
 // Stub the credential-store fallback so tests stay hermetic and do not
 // read real values from the host credential backend.
 mock.module("../security/secure-keys.js", () => ({
-  getSecureKeyAsync: async () => null,
+  getSecureKeyAsync: async (key: string) => mockSecureKeys[key] ?? null,
 }));
 
 mock.module("../security/credential-key.js", () => ({
@@ -54,6 +55,7 @@ describe("VellumPlatformClient", () => {
       assistantApiKey: "sk-test-key",
     };
     mockAssistantId = "asst-123";
+    mockSecureKeys = {};
   });
 
   afterEach(() => {
@@ -94,6 +96,27 @@ describe("VellumPlatformClient", () => {
       const client = await VellumPlatformClient.create();
       expect(client!.baseUrl).toBe("https://platform.example.com");
     });
+
+    test("falls back to credential store values when managed context is not rehydrated", async () => {
+      mockManagedProxyCtx = {
+        enabled: false,
+        platformBaseUrl: "",
+        assistantApiKey: "",
+      };
+      mockAssistantId = "";
+      mockSecureKeys = {
+        "vellum:platform_base_url": "https://stored-platform.example.com/",
+        "vellum:assistant_api_key": "stored-api-key",
+        "vellum:platform_assistant_id": " stored-assistant-id ",
+      };
+
+      const client = await VellumPlatformClient.create();
+
+      expect(client).not.toBeNull();
+      expect(client!.baseUrl).toBe("https://stored-platform.example.com");
+      expect(client!.assistantApiKey).toBe("stored-api-key");
+      expect(client!.platformAssistantId).toBe("stored-assistant-id");
+    });
   });
 
   describe("fetch()", () => {

package/src/platform/client.ts

@@ -10,6 +10,7 @@ import { resolveManagedProxyContext } from "../providers/platform-proxy/context.
 import { credentialKey } from "../security/credential-key.js";
 import { getSecureKeyAsync } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
+import { arePlatformFeaturesEnabled } from "./feature-gate.js";
 
 const log = getLogger("platform-client");
 
@@ -43,6 +44,13 @@ export class VellumPlatformClient {
    * should check `platformAssistantId` themselves.
    */
   static async create(): Promise<VellumPlatformClient | null> {
+    if (!arePlatformFeaturesEnabled()) {
+      log.debug(
+        "platform-features-in-local-mode is disabled — returning null",
+      );
+      return null;
+    }
+
     const ctx = await resolveManagedProxyContext();
 
     let baseUrl = ctx.enabled ? ctx.platformBaseUrl : "";

package/src/platform/feature-gate.ts

@@ -0,0 +1,15 @@
+import { isAssistantFeatureFlagEnabled } from "../config/assistant-feature-flags.js";
+import { getIsPlatform } from "../config/env-registry.js";
+import type { AssistantConfig } from "../config/schema.js";
+
+const FLAG_KEY = "platform-features-in-local-mode" as const;
+
+export function arePlatformFeaturesEnabled(
+  config?: AssistantConfig,
+): boolean {
+  if (getIsPlatform()) return true;
+  return isAssistantFeatureFlagEnabled(
+    FLAG_KEY,
+    (config ?? {}) as AssistantConfig,
+  );
+}

package/src/plugins/defaults/injectors.ts

@@ -48,7 +48,6 @@
 
 import { resolve } from "node:path";
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import { getInContextPkbPaths } from "../../daemon/pkb-context-tracker.js";
 import { buildPkbReminder } from "../../daemon/pkb-reminder-builder.js";
@@ -107,24 +106,19 @@ function readInjectionInputs(ctx: TurnContext): TurnInjectionInputs {
 }
 
 export const DISK_PRESSURE_WARNING_PROMPT = `<disk_pressure_warning>
-Disk usage is critically low: this assistant is in storage cleanup mode because the workspace volume is at least 95% full.
+Disk usage is critically low: this assistant is in storage cleanup mode because the workspace volume is critically full.
 
 In your first paragraph, warn the user that storage is critically low and that normal work is suspended until space is freed.
 
 Then help the user clean up storage. Prefer safe inspection steps first, such as checking available space and finding large directories. Ask before deleting files or caches unless the user has already clearly approved the specific cleanup action.
 
-Do not work on unrelated tasks until disk usage drops below the critical threshold or the user explicitly overrides the lock. Background processes and messages from trusted contacts are blocked while this cleanup mode is active.
+Do not work on unrelated tasks until enough space is freed to clear the lock or the user explicitly overrides it. Background processes and messages from trusted contacts are blocked while this cleanup mode is active.
 </disk_pressure_warning>`;
 
-function isSafeStorageLimitsEnabled(): boolean {
-  return isAssistantFeatureFlagEnabled("safe-storage-limits", getConfig());
-}
-
 const diskPressureWarningInjector: Injector = {
   name: "disk-pressure-warning",
   order: DEFAULT_INJECTOR_ORDER.diskPressureWarning,
   async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
-    if (!isSafeStorageLimitsEnabled()) return null;
     const inputs = readInjectionInputs(ctx);
     if (!inputs.diskPressureContext?.cleanupModeActive) return null;
     return {

package/src/plugins/defaults/persistence.ts

@@ -15,12 +15,17 @@
  *
  * The terminal dispatches on the discriminated {@link PersistArgs.op} field:
  *
- * - `add`    → {@link addMessage}, optionally followed by
- *              {@link syncMessageToDisk} when `args.syncToDisk` is true.
- * - `update` → {@link updateMessageMetadata} (returns `void`, wrapped as
- *              `{ op: "update" }`).
- * - `delete` → {@link deleteMessageById} (returns the segment/summary IDs
- *              the caller must clean up out-of-band).
+ * - `add`           → {@link addMessage}, optionally followed by
+ *                     {@link syncMessageToDisk} when `args.syncToDisk` is true.
+ * - `reserve`       → {@link reserveMessage} — pre-allocates an empty row
+ *                     for assistant anchor stamping.
+ * - `updateContent` → {@link updateMessageContent} — overwrites an existing
+ *                     row's content (returns `void`, wrapped as
+ *                     `{ op: "updateContent" }`).
+ * - `update`        → {@link updateMessageMetadata} (returns `void`, wrapped
+ *                     as `{ op: "update" }`).
+ * - `delete`        → {@link deleteMessageById} (returns the segment/summary
+ *                     IDs the caller must clean up out-of-band).
  *
  * Manifest declares `provides.persistence: "v1"` so other plugins can
  * negotiate against the pipeline surface and `requires.pluginRuntime: "v1"`
@@ -36,6 +41,8 @@
 import {
   addMessage,
   deleteMessageById,
+  reserveMessage,
+  updateMessageContent,
   updateMessageMetadata,
 } from "../../memory/conversation-crud.js";
 import { syncMessageToDisk } from "../../memory/conversation-disk-view.js";
@@ -74,6 +81,18 @@ export async function defaultPersistenceTerminal(
       }
       return { op: "add", message };
     }
+    case "reserve": {
+      const message = await reserveMessage(
+        args.conversationId,
+        args.role,
+        args.metadata,
+      );
+      return { op: "reserve", message };
+    }
+    case "updateContent": {
+      updateMessageContent(args.messageId, args.content);
+      return { op: "updateContent" };
+    }
     case "update": {
       updateMessageMetadata(args.messageId, args.updates);
       return { op: "update" };

package/src/plugins/types.ts

@@ -32,6 +32,7 @@ import type { RepairResult } from "../daemon/history-repair.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
 import type { PkbContextConversation } from "../daemon/pkb-context-tracker.js";
 import type { TrustContext } from "../daemon/trust-context.js";
+import type { MessageRole } from "../memory/conversation-crud.js";
 import type { QdrantSparseVector } from "../memory/qdrant-client.js";
 import type {
   ContentBlock,
@@ -439,18 +440,25 @@ export interface OverflowReduceResult {
  * Pipeline arguments for `persistence` — a discriminated union over the
  * message-CRUD operations plugins may observe, redirect, or short-circuit:
  *
- * - `add`    — append a new message (`addMessage`). Mirrors
- *              `addMessage(conversationId, role, content, metadata?, opts?)`.
- *              When `syncToDisk` is set, the default plugin also runs
- *              {@link syncMessageToDisk} against the just-persisted row so
- *              the JSONL disk view stays consistent. The `createdAtMs` field
- *              carries the conversation's creation timestamp — needed to
- *              resolve the disk-view directory path.
- * - `update` — shallow-merge metadata into an existing message
- *              (`updateMessageMetadata`). Returns `void`.
- * - `delete` — remove a single message (`deleteMessageById`). Returns the
- *              {@link DeletedMemoryIds}-shaped segment/summary IDs the caller
- *              must clean up out-of-band.
+ * - `add`           — append a new message (`addMessage`). Mirrors
+ *                     `addMessage(conversationId, role, content, metadata?, opts?)`.
+ *                     When `syncToDisk` is set, the default plugin also runs
+ *                     {@link syncMessageToDisk} against the just-persisted row
+ *                     so the JSONL disk view stays consistent. The
+ *                     `createdAtMs` field carries the conversation's creation
+ *                     timestamp — needed to resolve the disk-view directory.
+ * - `reserve`       — pre-allocate an empty assistant anchor row
+ *                     (`reserveMessage`) so the agent loop can stamp streaming
+ *                     events with stable identity before any content is
+ *                     produced. Returns the same row shape as `add`.
+ * - `updateContent` — overwrite the content of an existing message
+ *                     (`updateMessageContent`). Used to finalize a previously
+ *                     reserved row, and by consolidation paths.
+ * - `update`        — shallow-merge metadata into an existing message
+ *                     (`updateMessageMetadata`). Returns `void`.
+ * - `delete`        — remove a single message (`deleteMessageById`). Returns
+ *                     the {@link DeletedMemoryIds}-shaped segment/summary IDs
+ *                     the caller must clean up out-of-band.
  *
  * The discriminated `op` field lets plugin middleware narrow the union and
  * tailor behavior per-operation (e.g. "only observe deletes", "redirect
@@ -459,7 +467,7 @@ export interface OverflowReduceResult {
 export type PersistAddArgs = {
   readonly op: "add";
   readonly conversationId: string;
-  readonly role: string;
+  readonly role: MessageRole;
   readonly content: string;
   readonly metadata?: Record<string, unknown>;
   readonly addOptions?: { readonly skipIndexing?: boolean };
@@ -473,6 +481,19 @@ export type PersistAddArgs = {
   readonly createdAtMs?: number;
 };
 
+export type PersistReserveArgs = {
+  readonly op: "reserve";
+  readonly conversationId: string;
+  readonly role: MessageRole;
+  readonly metadata?: Record<string, unknown>;
+};
+
+export type PersistUpdateContentArgs = {
+  readonly op: "updateContent";
+  readonly messageId: string;
+  readonly content: string;
+};
+
 export type PersistUpdateArgs = {
   readonly op: "update";
   readonly messageId: string;
@@ -486,6 +507,8 @@ export type PersistDeleteArgs = {
 
 export type PersistArgs =
   | PersistAddArgs
+  | PersistReserveArgs
+  | PersistUpdateContentArgs
   | PersistUpdateArgs
   | PersistDeleteArgs;
 
@@ -506,6 +529,25 @@ export type PersistAddResult = {
   };
 };
 
+/**
+ * Result row returned by a `reserve` op — same row shape as `add` but with
+ * empty `content` (`"[]"`) and tagged distinctly so middleware can branch
+ * on intent.
+ */
+export type PersistReserveResult = {
+  readonly op: "reserve";
+  readonly message: {
+    readonly id: string;
+    readonly conversationId: string;
+    readonly role: string;
+    readonly content: string;
+    readonly createdAt: number;
+    readonly metadata?: string;
+  };
+};
+
+export type PersistUpdateContentResult = { readonly op: "updateContent" };
+
 export type PersistUpdateResult = { readonly op: "update" };
 
 /** IDs of segments/summaries the caller must remove from Qdrant. */
@@ -517,6 +559,8 @@ export type PersistDeleteResult = {
 
 export type PersistResult =
   | PersistAddResult
+  | PersistReserveResult
+  | PersistUpdateContentResult
   | PersistUpdateResult
   | PersistDeleteResult;
 

package/src/proactive-artifact/job.test.ts

@@ -163,6 +163,7 @@ mock.module("../memory/conversation-crud.js", () => ({
     addMessageCalls.push({ conversationId, role, content, metadata, opts });
     return { id: `msg-${addMessageCalls.length}` };
   },
+  reserveMessage: mock(async () => ({ id: "msg-reserve" })),
 }));
 
 // emitNotificationSignal mock

package/src/prompts/__tests__/system-prompt.test.ts

@@ -58,7 +58,7 @@ mock.module("../../config/loader.js", () => ({
   setNestedValue: () => {},
 }));
 
-const { buildSystemPrompt, maybeReseedBootstrapForCohort } =
+const { buildSystemPrompt, maybeReseedBootstrap } =
   await import("../system-prompt.js");
 
 describe("buildSystemPrompt — tool routing guidance", () => {
@@ -73,12 +73,12 @@ describe("buildSystemPrompt — tool routing guidance", () => {
   });
 });
 
-describe("maybeReseedBootstrapForCohort — content-automation template", () => {
+describe("maybeReseedBootstrap — content-automation template", () => {
   const templatesDir = join(import.meta.dirname!, "..", "templates");
 
   beforeEach(() => {
     mkdirSync(TEST_DIR, { recursive: true });
-    // Seed the workspace with the generic BOOTSTRAP.md so the cohort
+    // Seed the workspace with the generic BOOTSTRAP.md so the bootstrap
     // reseed detects it as an unmodified template and overwrites it.
     copyFileSync(
       join(templatesDir, "BOOTSTRAP.md"),
@@ -87,7 +87,7 @@ describe("maybeReseedBootstrapForCohort — content-automation template", () =>
   });
 
   function reseedAndRead(): string {
-    maybeReseedBootstrapForCohort("content-automation");
+    maybeReseedBootstrap("BOOTSTRAP-CONTENT-AUTOMATION.md");
     return readFileSync(join(TEST_DIR, "BOOTSTRAP.md"), "utf-8");
   }