@vellumai/assistant 0.10.12 → 0.11.0-staging.2

package/src/cli.ts

@@ -11,6 +11,7 @@ import {
 import { dirname, join } from "node:path";
 import * as readline from "node:readline";
 
+import type { AssistantEvent } from "./api/index.js";
 import {
   type MainScreenLayout,
   renderMainScreen,
@@ -18,7 +19,6 @@ import {
   updateStatusText,
 } from "./cli/main-screen.jsx";
 import { renderHistoryContent } from "./daemon/handlers/shared.js";
-import type { ServerMessage } from "./daemon/message-protocol.js";
 import {
   getConversation,
   getMessages,
@@ -64,7 +64,6 @@ export function sanitizeUrlForDisplay(rawUrl: unknown): string {
 export async function startCli(): Promise<void> {
   let conversationKey = CLI_CONVERSATION_KEY;
   let conversationId = "";
-  let pendingUserContent: string | null = null;
   let generating = false;
   let lastUsage: {
     inputTokens: number;
@@ -290,54 +289,8 @@ export async function startCli(): Promise<void> {
     });
   }
 
-  function handleMessage(msg: ServerMessage): void {
+  function handleMessage(msg: AssistantEvent): void {
     switch (msg.type) {
-      case "conversation_info":
-        pendingSessionPick = false;
-        conversationId = msg.conversationId;
-        process.stdout.write(
-          `\n  Conversation: ${msg.title}\n  Type your message. Ctrl+D to detach.\n\n`,
-        );
-        if (pendingUserContent) {
-          const content = pendingUserContent;
-          pendingUserContent = null;
-          sendUserMessage(content).then((result) => {
-            if (result.ok) {
-              generating = true;
-              spinner.start("Thinking...");
-            } else {
-              if (result.error === "secret_blocked" && result.message) {
-                process.stdout.write(`${result.message}\n`);
-                rl.question("Send anyway? (y/N): ", (answer) => {
-                  if (answer.trim().toLowerCase() === "y") {
-                    sendUserMessage(content, {
-                      bypassSecretCheck: true,
-                    }).then((retryResult) => {
-                      if (retryResult.ok) {
-                        generating = true;
-                        spinner.start("Thinking...");
-                      } else {
-                        process.stdout.write(
-                          "[Not connected — message not sent]\n",
-                        );
-                        prompt();
-                      }
-                    });
-                  } else {
-                    prompt();
-                  }
-                });
-              } else {
-                process.stdout.write("[Not connected — message not sent]\n");
-                prompt();
-              }
-            }
-          });
-        } else {
-          prompt();
-        }
-        break;
-
       case "assistant_text_delta":
         spinner.stop();
         process.stdout.write(msg.text);
@@ -507,70 +460,10 @@ export async function startCli(): Promise<void> {
         prompt();
         break;
 
-      case "conversation_list_response":
-        if (pendingSessionPick) {
-          renderConversationPicker(msg.conversations);
-        } else {
-          for (const conversation of msg.conversations) {
-            process.stdout.write(
-              `  ${conversation.id}  ${conversation.title}\n`,
-            );
-          }
-          prompt();
-        }
-        break;
-
       case "model_info":
         process.stdout.write(`\n  Model: ${msg.model} (${msg.provider})\n\n`);
         prompt();
         break;
-
-      case "history_response":
-        process.stdout.write("\n");
-        if (msg.messages.length === 0) {
-          process.stdout.write("  No messages in this conversation.\n");
-        } else {
-          for (const m of msg.messages) {
-            const label = m.role === "user" ? "you" : "assistant";
-            const preview = truncate(m.text, 120);
-            process.stdout.write(
-              `  ${label}> ${preview.replace(/\n/g, " ")}\n`,
-            );
-          }
-        }
-        process.stdout.write("\n");
-        prompt();
-        break;
-
-      case "undo_complete":
-        if (msg.removedCount === 0) {
-          process.stdout.write("\n  Nothing to undo.\n\n");
-        } else {
-          process.stdout.write(
-            `\n  Removed last exchange (${msg.removedCount} messages).\n\n`,
-          );
-        }
-        prompt();
-        break;
-
-      case "usage_response": {
-        process.stdout.write("\n");
-        process.stdout.write(`  Model:          ${msg.model}\n`);
-        process.stdout.write(
-          `  Input tokens:   ${msg.totalInputTokens.toLocaleString()}\n`,
-        );
-        process.stdout.write(
-          `  Output tokens:  ${msg.totalOutputTokens.toLocaleString()}\n`,
-        );
-        const costStr =
-          msg.estimatedCost > 0
-            ? `$${msg.estimatedCost.toFixed(4)}`
-            : "N/A (unknown model pricing)";
-        process.stdout.write(`  Estimated cost: ${costStr}\n`);
-        process.stdout.write("\n");
-        prompt();
-        break;
-      }
     }
   }
 

package/src/config/__tests__/deployment-context-defaults.test.ts

@@ -164,6 +164,15 @@ describe("deployment-context embedding-provider default (via loadConfig)", () =>
     >;
     expect(webSearchRaw.mode).not.toBe("managed");
 
+    // image-generation's managed axis is its provider: the seeded value is
+    // the platform fill "vellum", never an injected managed mode.
+    const imageGenRaw = (servicesRaw["image-generation"] ?? {}) as Record<
+      string,
+      unknown
+    >;
+    expect(imageGenRaw.provider).toBe("vellum");
+    expect(imageGenRaw.mode).not.toBe("managed");
+
     // Regression guard: on the NEXT load (config.json now exists with the
     // provider leaf absent), the platform default re-applies in memory rather
     // than being lost to a persisted "auto" read back as an explicit choice.

package/src/config/__tests__/substrate-twin-shadowing.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, test } from "bun:test";
+
+import { MemorySubstrateConfigSchema } from "../schemas/memory-substrate.js";
+import { MemoryV2ConfigSchema } from "../schemas/memory-v2.js";
+import {
+  describeShadowedConfigGet,
+  describeShadowedConfigSet,
+  findSubstrateShadowing,
+  SUBSTRATE_TWIN_BY_V2_KEY,
+} from "../substrate-twin-shadowing.js";
+
+describe("substrate twin table", () => {
+  test("pairs exactly the memory.substrate schema's keys", () => {
+    // Drift guard: a substrate key with no entry here is a tunable whose
+    // shadowing goes unreported, which is the silent no-op this module exists
+    // to prevent.
+    expect(
+      new Set(
+        Object.values(SUBSTRATE_TWIN_BY_V2_KEY).map((t) => t.substrateKey),
+      ),
+    ).toEqual(new Set(Object.keys(MemorySubstrateConfigSchema.shape)));
+  });
+
+  test("names a real memory.v2 key on every left-hand side", () => {
+    const v2Keys = new Set(Object.keys(MemoryV2ConfigSchema.shape));
+    for (const v2Key of Object.keys(SUBSTRATE_TWIN_BY_V2_KEY)) {
+      expect(v2Keys).toContain(v2Key);
+    }
+  });
+
+  test("flags exactly the three twins the v2 injection engine reads directly", () => {
+    // `v2/injection.ts` destructures `k` / `hops` off `config.memory.v2` (as
+    // does `v2/backfill-jobs.ts`) and `v2/activation.ts` reads
+    // `config.memory.v2.ann_candidate_limit`. Every other twin's only reader
+    // is `resolveSubstrateTuning`. Widening this set without a matching
+    // direct read makes the warnings claim a divergence that cannot happen.
+    const engineRead = Object.entries(SUBSTRATE_TWIN_BY_V2_KEY)
+      .filter(([, twin]) => twin.alsoReadByV2Engine)
+      .map(([v2Key]) => v2Key)
+      .sort();
+    expect(engineRead).toEqual(["ann_candidate_limit", "hops", "k"]);
+  });
+});
+
+describe("findSubstrateShadowing", () => {
+  test("reports the winning substrate twin for a shadowed memory.v2 key", () => {
+    const raw = {
+      memory: {
+        v2: { consolidation_interval_hours: 4 },
+        substrate: { consolidation_interval_hours: 876000 },
+      },
+    };
+
+    expect(
+      findSubstrateShadowing(raw, "memory.v2.consolidation_interval_hours"),
+    ).toEqual({
+      substratePath: "memory.substrate.consolidation_interval_hours",
+      substrateValue: 876000,
+      alsoReadByV2Engine: false,
+    });
+  });
+
+  test("maps the renamed spread keys to their substrate names", () => {
+    const raw = { memory: { v2: {}, substrate: { spread_k: 0.4 } } };
+
+    expect(findSubstrateShadowing(raw, "memory.v2.k")).toEqual({
+      substratePath: "memory.substrate.spread_k",
+      substrateValue: 0.4,
+      alsoReadByV2Engine: true,
+    });
+    // hops has no twin set, so nothing shadows it.
+    expect(findSubstrateShadowing(raw, "memory.v2.hops")).toBeUndefined();
+  });
+
+  test("treats an explicit null twin as set, matching resolveSubstrateTuning", () => {
+    // `orV2` falls back only on `undefined`, so a null substrate value wins —
+    // and it is exactly the value the consolidation freeze writes.
+    const raw = {
+      memory: {
+        v2: { consolidation_max_buffer_lines: 100 },
+        substrate: { consolidation_max_buffer_lines: null },
+      },
+    };
+
+    expect(
+      findSubstrateShadowing(raw, "memory.v2.consolidation_max_buffer_lines"),
+    ).toEqual({
+      substratePath: "memory.substrate.consolidation_max_buffer_lines",
+      substrateValue: null,
+      alsoReadByV2Engine: false,
+    });
+  });
+
+  test("returns nothing for unshadowed paths", () => {
+    const raw = {
+      memory: {
+        v2: { bm25_b: 0.6, enabled: true },
+        substrate: { bm25_b: 0.3 },
+      },
+    };
+
+    // No memory.substrate subtree at all.
+    expect(
+      findSubstrateShadowing(
+        { memory: { v2: { bm25_b: 0.6 } } },
+        "memory.v2.bm25_b",
+      ),
+    ).toBeUndefined();
+    // A v2 key with no substrate twin.
+    expect(findSubstrateShadowing(raw, "memory.v2.enabled")).toBeUndefined();
+    // The substrate key itself is what wins — writing it is never shadowed.
+    expect(
+      findSubstrateShadowing(raw, "memory.substrate.bm25_b"),
+    ).toBeUndefined();
+    // Paths outside the memory namespace, and the wrong depth.
+    expect(findSubstrateShadowing(raw, "memory.v2")).toBeUndefined();
+    expect(findSubstrateShadowing(raw, "llm.v2.bm25_b")).toBeUndefined();
+  });
+});
+
+describe("describeShadowedConfigSet", () => {
+  test("a substrate-only twin reads as the no-op it is", () => {
+    const message = describeShadowedConfigSet(
+      {
+        substratePath: "memory.substrate.consolidation_interval_hours",
+        substrateValue: 876000,
+        alsoReadByV2Engine: false,
+      },
+      "memory.v2.consolidation_interval_hours",
+    );
+
+    expect(message).toContain(
+      "memory.substrate.consolidation_interval_hours is set (876000)",
+    );
+    expect(message).toContain("does not change the effective value");
+    expect(message).toContain(
+      "assistant config set memory.substrate.consolidation_interval_hours",
+    );
+  });
+
+  test("an engine-read twin reports divergence, never inertness", () => {
+    // `memory.v2.k` still tunes the live v2 injection engine, so claiming the
+    // write is inert would send an operator chasing a phantom.
+    const message = describeShadowedConfigSet(
+      {
+        substratePath: "memory.substrate.spread_k",
+        substrateValue: 0.4,
+        alsoReadByV2Engine: true,
+      },
+      "memory.v2.k",
+    );
+
+    expect(message).toContain("does change its behavior");
+    expect(message).toContain("memory.substrate.spread_k (0.4)");
+    expect(message).toContain("diverge");
+    expect(message).not.toContain("does not change the effective value");
+  });
+});
+
+describe("describeShadowedConfigGet", () => {
+  test("a substrate-only twin names the key that is the effective value", () => {
+    const message = describeShadowedConfigGet(
+      {
+        substratePath: "memory.substrate.bm25_b",
+        substrateValue: 0.3,
+        alsoReadByV2Engine: false,
+      },
+      "memory.v2.bm25_b",
+    );
+
+    expect(message).toContain("Shadowed: memory.substrate.bm25_b = 0.3");
+    expect(message).toContain("is the effective value");
+  });
+
+  test("an engine-read twin names both readers", () => {
+    const message = describeShadowedConfigGet(
+      {
+        substratePath: "memory.substrate.ann_candidate_limit",
+        substrateValue: null,
+        alsoReadByV2Engine: true,
+      },
+      "memory.v2.ann_candidate_limit",
+    );
+
+    expect(message).toContain(
+      "Split: memory.substrate.ann_candidate_limit = null",
+    );
+    expect(message).toContain("substrate recall");
+    expect(message).toContain("memory.v2.ann_candidate_limit");
+  });
+});

package/src/config/assistant-feature-flags.ts

@@ -10,7 +10,7 @@
  *   3. `false`                                    (for undeclared keys)
  *
  * Key format:
- *   Canonical:  simple kebab-case string (e.g., "browser", "voice-mode")
+ *   Canonical:  simple kebab-case string (e.g., "browser", "contacts")
  */
 
 import { existsSync, readFileSync } from "node:fs";

package/src/config/bundled-skills/conversation-groups/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: conversation-groups
+description: Organize conversations into custom sidebar groups — list groups, create new ones, and file conversations into them
+compatibility: "Designed for Vellum personal assistants"
+metadata:
+  emoji: "🗂️"
+  vellum:
+    display-name: "Conversation Groups"
+    category: "productivity"
+---
+
+Organize the user's conversations into sidebar groups. Groups are the sections shown in the conversation sidebar; each conversation belongs to exactly one group.
+
+## Groups
+
+- **Custom groups** are user-defined sections (e.g. "Work", "Travel planning"). Create them with `conversation_group_create` and file conversations with `conversation_move_to_group`.
+- **System groups** are built in and cannot be created, renamed, or deleted:
+  - `system:pinned` (Pinned) — moving a conversation here pins it; moving it elsewhere unpins it.
+  - `system:all` (Recents) — the default ungrouped section. Move a conversation here to "remove" it from a custom group.
+  - `system:scheduled` (Scheduled) and `system:background` (Background) — hold automated conversations. Moving a conversation into these demotes it out of the Recents listing; avoid unless the user explicitly asks.
+
+## Usage
+
+- `conversation_move_to_group` defaults to the **current** conversation, so "file this chat under Work" needs no conversation id.
+- Groups can be referenced by name (case-insensitive) or id. Prefer names; fall back to ids when names are ambiguous.
+- When the user asks to organize their conversations, check the existing groups first (`conversation_group_list`) and reuse a fitting group rather than creating near-duplicates ("Work" vs "Work stuff").
+- Creating a group whose name already exists reuses the existing group instead of creating a duplicate.
+- Moves only affect sidebar organization — no conversation content changes, and every move is reversible.
+- Subagent and background conversations are hidden from the sidebar regardless of group; moving them has no visible effect.

package/src/config/bundled-skills/conversation-groups/TOOLS.json

@@ -0,0 +1,58 @@
+{
+  "version": 1,
+  "tools": [
+    {
+      "name": "conversation_group_list",
+      "description": "List all conversation sidebar groups in display order, including built-in system groups (Pinned, Scheduled, Background, Recents) and user-defined custom groups. Use this before creating or moving so you reuse an existing group instead of creating a near-duplicate.",
+      "category": "conversations",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {},
+        "required": []
+      },
+      "executor": "tools/group-list.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "conversation_group_create",
+      "description": "Create a new custom conversation group (a named section in the conversation sidebar). If a group with the same name already exists (case-insensitive), the existing group is reused and no duplicate is created. System group names (Pinned, Scheduled, Background, Recents) are reserved.",
+      "category": "conversations",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Name for the new group as it should appear in the sidebar"
+          }
+        },
+        "required": ["name"]
+      },
+      "executor": "tools/group-create.ts",
+      "execution_target": "host"
+    },
+    {
+      "name": "conversation_move_to_group",
+      "description": "Move a conversation into a sidebar group. Defaults to the current conversation when conversation_id is omitted. The group may be referenced by name (case-insensitive) or id. Moving to Pinned pins the conversation; moving to Recents (system:all) removes it from a custom group. Only sidebar organization changes — reversible, no content is affected.",
+      "category": "conversations",
+      "risk": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "group": {
+            "type": "string",
+            "description": "Target group name or group id"
+          },
+          "conversation_id": {
+            "type": "string",
+            "description": "Conversation to move. Omit to move the current conversation."
+          }
+        },
+        "required": ["group"]
+      },
+      "executor": "tools/move-to-group.ts",
+      "execution_target": "host"
+    }
+  ]
+}

package/src/config/bundled-skills/conversation-groups/tools/group-create.ts

@@ -0,0 +1,12 @@
+import { executeConversationGroupCreate } from "../../../../tools/conversation-groups/group_create.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeConversationGroupCreate(input, context);
+}

package/src/config/bundled-skills/conversation-groups/tools/group-list.ts

@@ -0,0 +1,12 @@
+import { executeConversationGroupList } from "../../../../tools/conversation-groups/group_list.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeConversationGroupList(input, context);
+}

package/src/config/bundled-skills/conversation-groups/tools/move-to-group.ts

@@ -0,0 +1,12 @@
+import { executeConversationMoveToGroup } from "../../../../tools/conversation-groups/move_to_group.js";
+import type {
+  ToolContext,
+  ToolExecutionResult,
+} from "../../../../tools/types.js";
+
+export async function run(
+  input: Record<string, unknown>,
+  context: ToolContext,
+): Promise<ToolExecutionResult> {
+  return executeConversationMoveToGroup(input, context);
+}

package/src/config/bundled-skills/image-studio/tools/media-generate-image.ts

@@ -1,4 +1,7 @@
-import { resolveImageGenCredentials } from "../../../../media/image-credentials.js";
+import {
+  resolveImageGenCredentials,
+  resolveImageGenRouting,
+} from "../../../../media/image-credentials.js";
 import {
   describeImageModels,
   resolveImageModel,
@@ -6,7 +9,6 @@ import {
 import {
   generateImage,
   mapImageGenError,
-  providerForModel,
 } from "../../../../media/image-service.js";
 import { getFilePathBySourcePath } from "../../../../persistence/attachments-store.js";
 import type { ImageContent } from "../../../../providers/types.js";
@@ -37,13 +39,17 @@ export async function run(
     }
     modelOverride = entry.id;
   }
-  // Derive provider from the explicit model when supplied so that requesting
-  // e.g. `gpt-image-2` while config.provider === "gemini" routes to OpenAI
-  // instead of silently falling back to the Gemini default model.
-  const provider = providerForModel(modelOverride, svc.provider);
+  // Backend and managed-ness resolve together: an explicit model re-routes
+  // to the model's backend (e.g. `gpt-image-2` under a gemini config routes
+  // to OpenAI), and provider "vellum" runs managed with a model-derived
+  // backend.
+  const { backendProvider: provider, managed } = resolveImageGenRouting(
+    svc,
+    modelOverride,
+  );
   const { credentials, errorHint } = await resolveImageGenCredentials({
     provider,
-    mode: svc.mode,
+    managed,
   });
   if (!credentials) {
     return {

package/src/config/bundled-skills/schedule/SKILL.md

@@ -104,6 +104,8 @@ Use `notify` for simple reminders ("remind me to take medicine at 9am"), `execut
 
 Script commands run with the workspace root as the working directory. The assistant injects `__SCHEDULE_ID` (stable across runs of one schedule) and `__SCHEDULE_RUN_ID` (unique per firing) into the environment; `VELLUM_WORKSPACE_DIR` is also set. There is no schedule-name variable — the id is how a command finds anything keyed to its schedule.
 
+**Check for an existing skill before writing one.** An installed skill may already do the work the script is about to reimplement. Search the installed skills first, and follow that skill's own instructions for using it from a schedule. Where it gives none, `assistant skills inspect <id> --json` reports where it is installed — resolve that when the schedule runs rather than baking the path in, since a skill's directory varies by source and moves when a workspace is restored elsewhere.
+
 **Files on disk.** A self-contained command can live directly in the `script` field. A schedule that needs files on disk — a script too large to inline, or state that carries across runs — has a conventional home at `$VELLUM_WORKSPACE_DIR/schedules/$__SCHEDULE_ID/`. The assistant does not create or manage this directory. Because it is keyed by the schedule id, create the schedule first, read the id from the result, then create and populate `schedules/<id>/`: script files at the top level, run-managed state under `state/`, and a `.gitignore` covering `state/`. At runtime the command may reference the directory by absolute path or `cd` into it — either works. Deleting a schedule does not remove its directory; clean it up separately.
 
 **Handing off to the agent loop.** A script can wake the assistant when it finds something worth acting on:

package/src/config/feature-flag-cache.ts

@@ -12,10 +12,10 @@
  *
  * State is held on `globalThis.vellumAssistant.featureFlagCache` so test
  * helpers in `__tests__/` can read/write it WITHOUT importing this
- * module — they declare the same slot shape locally and access the
- * globalThis namespace directly. See
- * `__tests__/feature-flag-test-helpers.ts` for the test-side mirror;
- * the slot shape MUST stay in sync between the two.
+ * module. Both sides reference the shared ambient `VellumFeatureFlagCache`
+ * type (declared in `src/vellum-assistant-namespace.d.ts`), which types the
+ * slot without adding a runtime import between them. See
+ * `__tests__/feature-flag-test-helpers.ts` for the test-side writer.
  *
  * Both `overrides` and `fromGateway` were previously module-level `let`
  * bindings inside `assistant-feature-flags.ts`. The semantics are
@@ -28,18 +28,8 @@
  *   - `__tests__/feature-flag-test-helpers.ts` (seeds for tests, via globalThis)
  */
 
-type FlagSlot = {
-  overrides: Record<string, boolean | string> | null;
-  fromGateway: boolean;
-};
-
-type VellumAssistantNamespace = {
-  featureFlagCache?: FlagSlot;
-};
-
-function slot(): FlagSlot {
-  const g = globalThis as { vellumAssistant?: VellumAssistantNamespace };
-  const ns = (g.vellumAssistant ??= {});
+function slot(): VellumFeatureFlagCache {
+  const ns = (globalThis.vellumAssistant ??= {});
   return (ns.featureFlagCache ??= { overrides: null, fromGateway: false });
 }