@vellumai/assistant 0.12.1 → 0.12.2-staging.1

package/src/live-voice/protocol.ts

@@ -627,8 +627,6 @@ export interface LiveVoiceMetricsServerFrame extends LiveVoiceServerFrameBase {
    * condition as the two fields above.
    */
   readonly endpointDecisionSource?: "front-door" | "provider";
-  /** Which floor-holding ack actually spoke during the turn, if any. */
-  readonly ackSpoken?: "first_delta" | "tool_use";
   /**
    * Spoken progress narrations during the turn. Present only when at least
    * one progress update spoke (otherwise the field is absent, keeping frames

package/src/mcp/__tests__/effective-config.test.ts

@@ -4,8 +4,8 @@
  * The properties worth pinning are the ones a refactor could quietly
  * break, each of which fails silently rather than loudly:
  *
- * 1. Plugin servers reach the manager at all. Reading only `config.mcp`
- *    leaves a plugin's tools missing with nothing logged.
+ * 1. Plugin servers reach the manager at all. Reading only the workspace
+ *    `mcp.json` leaves a plugin's tools missing with nothing logged.
  * 2. A workspace entry of the same id wins, so a plugin cannot redirect a
  *    server the user configured by hand.
  * 3. Every server is attributed. `source` is what `McpClient` reads to

package/src/mcp/__tests__/workspace-mcp-config.test.ts

@@ -0,0 +1,135 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import { AGENT_PLUGINS_MCP_SCHEMA_URL } from "../spec-schema.js";
+import {
+  loadWorkspaceMcpConfig,
+  overlayWorkspaceMcpForConfigRead,
+  readWorkspaceMcpFile,
+  saveWorkspaceMcpConfig,
+} from "../workspace-mcp-config.js";
+
+function mcpPath(): string {
+  return join(process.env.VELLUM_WORKSPACE_DIR!, "mcp.json");
+}
+
+describe("workspace mcp.json", () => {
+  beforeEach(() => {
+    mkdirSync(process.env.VELLUM_WORKSPACE_DIR!, { recursive: true });
+    rmSync(mcpPath(), { force: true });
+  });
+
+  test("missing file is an empty server map", () => {
+    expect(loadWorkspaceMcpConfig()).toEqual({ servers: {} });
+    expect(readWorkspaceMcpFile().fileState).toBe("missing");
+  });
+
+  test("round-trips a spec document without wrapping transport", () => {
+    saveWorkspaceMcpConfig({
+      servers: {
+        remote: {
+          transport: {
+            type: "streamable-http",
+            url: "https://example.com/mcp",
+          },
+        },
+        local: {
+          transport: {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "srv"],
+          },
+        },
+      },
+    });
+
+    expect(JSON.parse(readFileSync(mcpPath(), "utf8"))).toEqual({
+      $schema: AGENT_PLUGINS_MCP_SCHEMA_URL,
+      mcpServers: {
+        remote: {
+          type: "streamable-http",
+          url: "https://example.com/mcp",
+        },
+        local: {
+          type: "stdio",
+          command: "npx",
+          args: ["-y", "srv"],
+        },
+      },
+    });
+    expect(loadWorkspaceMcpConfig()).toEqual({
+      servers: {
+        remote: {
+          transport: {
+            type: "streamable-http",
+            url: "https://example.com/mcp",
+          },
+        },
+        local: {
+          transport: {
+            type: "stdio",
+            command: "npx",
+            args: ["-y", "srv"],
+          },
+        },
+      },
+    });
+  });
+
+  test("does not persist transport headers", () => {
+    saveWorkspaceMcpConfig({
+      servers: {
+        remote: {
+          transport: {
+            type: "streamable-http",
+            url: "https://example.com/mcp",
+            headers: { Authorization: "Bearer secret" },
+          },
+        },
+      },
+    });
+
+    const onDisk = readFileSync(mcpPath(), "utf8");
+    expect(onDisk).not.toContain("secret");
+    expect(loadWorkspaceMcpConfig().servers.remote?.transport).toEqual({
+      type: "streamable-http",
+      url: "https://example.com/mcp",
+    });
+  });
+
+  test("invalid file does not throw on read and refuses a later write", () => {
+    mkdirSync(process.env.VELLUM_WORKSPACE_DIR!, { recursive: true });
+    writeFileSync(mcpPath(), "{ not json");
+
+    expect(loadWorkspaceMcpConfig()).toEqual({ servers: {} });
+    expect(readWorkspaceMcpFile().fileState).toBe("invalid");
+    expect(() => saveWorkspaceMcpConfig({ servers: {} })).toThrow(/invalid JSON/);
+  });
+
+  test("overlay projects transport-only servers for config reads", () => {
+    saveWorkspaceMcpConfig({
+      servers: {
+        remote: {
+          transport: {
+            type: "streamable-http",
+            url: "https://example.com/mcp",
+          },
+        },
+      },
+    });
+
+    const config: Record<string, unknown> = { llm: { activeProfile: "balanced" } };
+    overlayWorkspaceMcpForConfigRead(config);
+    expect(config.mcp).toEqual({
+      servers: {
+        remote: {
+          transport: {
+            type: "streamable-http",
+            url: "https://example.com/mcp",
+          },
+        },
+      },
+    });
+  });
+});

package/src/mcp/effective-config.ts

@@ -1,11 +1,11 @@
 /**
  * The MCP configuration the daemon actually runs.
  *
- * Two sources contribute servers: the workspace `config.json`, which the
+ * Two sources contribute servers: the workspace `mcp.json`, which the
  * user owns, and each installed plugin's `mcp.json`, which its author
  * owns. Both must reach the MCP manager, so every consumer that starts
- * servers builds its config through here rather than reading
- * `config.mcp` directly — a path that only reads the workspace half
+ * servers builds its config through here rather than reading the
+ * workspace file directly — a path that only reads the workspace half
  * leaves a plugin's tools silently missing.
  *
  * Every server comes out attributed with its {@link McpServerSource}, so

package/src/mcp/mcp-header-store.ts

@@ -3,18 +3,21 @@
  *
  * Follows the same pattern as mcp-oauth-provider.ts: headers are stored in
  * the secure credential store (CES or encrypted file fallback) rather than
- * in plaintext config.json, keeping secrets out of workspace config files.
+ * in plaintext mcp.json, keeping secrets out of workspace config files.
  *
  * Key format: mcp:{serverId}:headers — stores JSON-serialized Record<string, string>.
  */
 
-import { loadRawConfig, saveRawConfig } from "../config/loader.js";
 import {
   deleteSecureKeyAsync,
   getSecureKeyAsync,
   setSecureKeyAsync,
 } from "../security/secure-keys.js";
 import { getLogger } from "../util/logger.js";
+import {
+  loadWorkspaceMcpConfig,
+  saveWorkspaceMcpConfig,
+} from "./workspace-mcp-config.js";
 
 const log = getLogger("mcp-header-store");
 
@@ -73,64 +76,45 @@ export async function deleteMcpHeaders(serverId: string): Promise<boolean> {
 }
 
 /**
- * One-time lazy migration: move any plaintext headers from config.json
- * transport entries into the credential store and strip them from config.
- * Safe to call on every MCP reload — no-ops when no legacy headers remain.
+ * Move leftover plaintext headers from mcp.json into the credential store
+ * and rewrite the file without them. Safe to call on every MCP reload.
  */
 export async function migrateLegacyMcpHeaders(): Promise<void> {
-  const raw = loadRawConfig();
-  const mcpConfig = raw.mcp as
-    | { servers?: Record<string, Record<string, unknown>> }
-    | undefined;
-  const servers = mcpConfig?.servers;
-  if (!servers) {
-    return;
-  }
+  const config = loadWorkspaceMcpConfig();
+  const servers = config.servers;
+  let dirty = false;
 
-  let configDirty = false;
   for (const [id, server] of Object.entries(servers)) {
-    const transport = server?.transport as Record<string, unknown> | undefined;
-    if (
-      !transport ||
-      (transport.type !== "sse" && transport.type !== "streamable-http")
-    ) {
+    const transport = server.transport;
+    if (transport.type !== "sse" && transport.type !== "streamable-http") {
       continue;
     }
-    const legacyHeaders = transport.headers as
-      | Record<string, string>
-      | undefined;
-    if (!legacyHeaders || Object.keys(legacyHeaders).length === 0) {
+    const leftoverHeaders = transport.headers;
+    if (!leftoverHeaders || Object.keys(leftoverHeaders).length === 0) {
       continue;
     }
 
-    // Only migrate if credential store doesn't already have headers for
-    // this server (idempotent — safe to re-run after partial failure).
     const existing = await getMcpHeaders(id);
-    if (existing) {
-      // Credential store already has headers; just strip the config copy.
-      delete transport.headers;
-      configDirty = true;
-      continue;
-    }
-
-    const ok = await setMcpHeaders(id, legacyHeaders);
-    if (ok) {
-      delete transport.headers;
-      configDirty = true;
+    if (!existing) {
+      const ok = await setMcpHeaders(id, leftoverHeaders);
+      if (!ok) {
+        log.warn(
+          { serverId: id },
+          "Skipping leftover header migration: credential store write failed; will retry on next reload",
+        );
+        continue;
+      }
       log.info(
         { serverId: id },
-        "Migrated legacy MCP headers to credential store",
-      );
-    } else {
-      log.warn(
-        { serverId: id },
-        "Skipping legacy header migration — credential store write failed; will retry on next reload",
+        "Moved leftover MCP headers to credential store",
       );
     }
+    delete transport.headers;
+    dirty = true;
   }
 
-  if (configDirty) {
-    saveRawConfig(raw);
-    log.info("Config updated: legacy MCP headers removed after migration");
+  if (dirty) {
+    saveWorkspaceMcpConfig(config);
+    log.info("mcp.json updated: leftover MCP headers removed after migration");
   }
 }

package/src/mcp/spec-schema.ts

@@ -0,0 +1,111 @@
+/**
+ * Agent Plugins 1.0.0 `mcp.json` wire schema and projections onto the
+ * assistant's in-memory `McpTransport` union.
+ *
+ * Workspace `/workspace/mcp.json` and each plugin's root `mcp.json` share
+ * this document shape. Origin (`workspace` vs `plugin`) is resolved from
+ * which file was read, never from a field in the file.
+ */
+
+import { z } from "zod";
+
+import type { McpTransport } from "../config/schemas/mcp.js";
+
+/** Canonical `$schema` value for an Agent Plugins 1.0.0 MCP document. */
+export const AGENT_PLUGINS_MCP_SCHEMA_URL =
+  "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json";
+
+const SpecStdioServerSchema = z.object({
+  type: z.literal("stdio"),
+  command: z.string().min(1),
+  args: z.array(z.string()).optional(),
+  env: z.record(z.string(), z.string()).optional(),
+  cwd: z.string().optional(),
+});
+
+/**
+ * Remote MCP entry. Agent Plugins 1.0.0 requires `type` and names no
+ * default. MCP's current remote transport is Streamable HTTP, so this
+ * host fills omitted `type` and the Claude-style `http` alias as
+ * `streamable-http`. `sse` stays explicit.
+ */
+const SpecHttpServerSchema = z.object({
+  type: z
+    .union([
+      z.literal("streamable-http"),
+      z.literal("sse"),
+      z.literal("http").transform(() => "streamable-http" as const),
+    ])
+    .default("streamable-http"),
+  url: z.string().min(1),
+  headers: z.record(z.string(), z.string()).optional(),
+});
+
+export const SpecMcpServerSchema = z.union([
+  SpecStdioServerSchema,
+  SpecHttpServerSchema,
+]);
+
+export const SpecMcpDocumentSchema = z.object({
+  $schema: z.string().optional(),
+  mcpServers: z.record(z.string(), z.unknown()),
+});
+
+export type SpecMcpServer = z.infer<typeof SpecMcpServerSchema>;
+export type SpecMcpDocument = z.infer<typeof SpecMcpDocumentSchema>;
+
+/**
+ * Project one spec-shaped entry onto the assistant's transport union. The
+ * two vocabularies already agree on type names and required fields, so this
+ * is a field copy plus an optional expander for plugin path variables.
+ */
+export function projectSpecServerToTransport(
+  entry: SpecMcpServer,
+  expand?: (value: string) => string,
+): McpTransport {
+  if (entry.type === "stdio") {
+    const map = expand ?? ((value: string) => value);
+    return {
+      type: "stdio",
+      command: entry.command,
+      args: (entry.args ?? []).map(map),
+      ...(entry.env && {
+        env: Object.fromEntries(
+          Object.entries(entry.env).map(([key, value]) => [key, map(value)]),
+        ),
+      }),
+    };
+  }
+  return {
+    type: entry.type,
+    url: entry.url,
+    ...(entry.headers && { headers: entry.headers }),
+  };
+}
+
+/**
+ * Project an in-memory transport onto a spec server entry. Headers are
+ * omitted: workspace secrets live in the credential store, and a write
+ * must not copy them into `mcp.json`.
+ */
+export function projectTransportToSpecServer(
+  transport: McpTransport,
+): Record<string, unknown> {
+  if (transport.type === "stdio") {
+    const entry: Record<string, unknown> = {
+      type: "stdio",
+      command: transport.command,
+    };
+    if (transport.args && transport.args.length > 0) {
+      entry.args = transport.args;
+    }
+    if (transport.env) {
+      entry.env = transport.env;
+    }
+    return entry;
+  }
+  return {
+    type: transport.type,
+    url: transport.url,
+  };
+}

package/src/mcp/startup.ts

@@ -13,13 +13,14 @@
  * further process that starts hosting turns has one call to make.
  */
 
-import { getConfig, invalidateConfigCache } from "../config/loader.js";
+import { invalidateConfigCache } from "../config/loader.js";
 import type { McpConfig } from "../config/schemas/mcp.js";
 import { createMcpToolsFromServer } from "../tools/mcp/mcp-tool-factory.js";
 import { registerMcpTools, unregisterAllMcpTools } from "../tools/registry.js";
 import { getLogger } from "../util/logger.js";
 import { buildEffectiveMcpConfig } from "./effective-config.js";
 import { getMcpServerManager, stopMcpServerManager } from "./manager.js";
+import { loadWorkspaceMcpConfig } from "./workspace-mcp-config.js";
 
 const log = getLogger("mcp-startup");
 
@@ -36,7 +37,8 @@ const log = getLogger("mcp-startup");
  * is a startup step in processes whose other work must not be held hostage to
  * a third-party server being up.
  *
- * @param workspaceMcpConfig The `mcp` block of the assistant config, if any.
+ * @param workspaceMcpConfig The projected workspace MCP config. Callers
+ * that omit it read `/workspace/mcp.json`.
  * @returns The number of tools registered across all servers.
  */
 export async function startConfiguredMcpServers(
@@ -44,7 +46,9 @@ export async function startConfiguredMcpServers(
 ): Promise<number> {
   let registered = 0;
   try {
-    const mcpConfig = buildEffectiveMcpConfig(workspaceMcpConfig);
+    const mcpConfig = buildEffectiveMcpConfig(
+      workspaceMcpConfig ?? loadWorkspaceMcpConfig(),
+    );
     if (Object.keys(mcpConfig.servers).length === 0) {
       return 0;
     }
@@ -97,5 +101,5 @@ export async function restartConfiguredMcpServers(): Promise<number> {
   }
   unregisterAllMcpTools();
   invalidateConfigCache();
-  return startConfiguredMcpServers(getConfig().mcp);
+  return startConfiguredMcpServers(loadWorkspaceMcpConfig());
 }

package/src/mcp/workspace-mcp-config.ts

@@ -0,0 +1,188 @@
+/**
+ * User-owned MCP servers in `$VELLUM_WORKSPACE_DIR/mcp.json`.
+ *
+ * The file is an Agent Plugins 1.0.0 document (`$schema` + `mcpServers`).
+ * This module is the only reader and writer of that file. Presence of a
+ * server starts it. Headers are never persisted here.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+
+import type { McpConfig, McpServerConfig } from "../config/schemas/mcp.js";
+import { McpConfigSchema } from "../config/schemas/mcp.js";
+import { getLogger } from "../util/logger.js";
+import { getWorkspaceMcpConfigPath } from "../util/platform.js";
+import {
+  AGENT_PLUGINS_MCP_SCHEMA_URL,
+  projectSpecServerToTransport,
+  projectTransportToSpecServer,
+  SpecMcpDocumentSchema,
+  SpecMcpServerSchema,
+} from "./spec-schema.js";
+
+const log = getLogger("workspace-mcp-config");
+
+export type WorkspaceMcpFileState = "missing" | "ok" | "invalid";
+
+export interface WorkspaceMcpLoadResult {
+  readonly config: McpConfig;
+  readonly issues: readonly string[];
+  readonly fileState: WorkspaceMcpFileState;
+}
+
+/**
+ * Read `/workspace/mcp.json` and project it onto the in-memory MCP config.
+ *
+ * A missing file is an empty server map. An invalid file disables the
+ * workspace half only (plugin servers still load) and is reported so a
+ * write can refuse to overwrite it.
+ */
+export function readWorkspaceMcpFile(
+  path: string = getWorkspaceMcpConfigPath(),
+): WorkspaceMcpLoadResult {
+  if (!existsSync(path)) {
+    return {
+      config: McpConfigSchema.parse({}),
+      issues: [],
+      fileState: "missing",
+    };
+  }
+
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (err) {
+    const message = `mcp.json unreadable: ${err instanceof Error ? err.message : String(err)}`;
+    return {
+      config: McpConfigSchema.parse({}),
+      issues: [message],
+      fileState: "invalid",
+    };
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch (err) {
+    const message = `mcp.json invalid JSON: ${err instanceof Error ? err.message : String(err)}`;
+    return {
+      config: McpConfigSchema.parse({}),
+      issues: [message],
+      fileState: "invalid",
+    };
+  }
+
+  const document = SpecMcpDocumentSchema.safeParse(json);
+  if (!document.success) {
+    return {
+      config: McpConfigSchema.parse({}),
+      issues: ['mcp.json is missing a valid "mcpServers" object'],
+      fileState: "invalid",
+    };
+  }
+
+  const servers: Record<string, McpServerConfig> = {};
+  const issues: string[] = [];
+
+  for (const [serverKey, rawEntry] of Object.entries(document.data.mcpServers)) {
+    if (serverKey.trim().length === 0) {
+      issues.push("server key must be a non-empty string; skipping");
+      continue;
+    }
+
+    const entry = SpecMcpServerSchema.safeParse(rawEntry);
+    if (!entry.success) {
+      issues.push(
+        `invalid server entry "${serverKey}": ${entry.error.issues
+          .map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`)
+          .join("; ")}`,
+      );
+      continue;
+    }
+
+    if (entry.data.type === "stdio" && entry.data.cwd) {
+      issues.push(
+        `"${serverKey}": "cwd" is not supported by this host and was ignored; the server runs in the assistant's working directory`,
+      );
+    }
+
+    servers[serverKey] = {
+      transport: projectSpecServerToTransport(entry.data),
+    };
+  }
+
+  return {
+    config: { servers },
+    issues,
+    fileState: "ok",
+  };
+}
+
+/** Load the workspace MCP config, logging any declaration problems. */
+export function loadWorkspaceMcpConfig(): McpConfig {
+  const result = readWorkspaceMcpFile();
+  for (const issue of result.issues) {
+    log.warn(issue);
+  }
+  return result.config;
+}
+
+/**
+ * Refuse a write when `mcp.json` exists but is not a usable document, so a
+ * later add/remove cannot clobber a hand-edit the user still means to fix.
+ */
+export function assertWorkspaceMcpWritable(): void {
+  const result = readWorkspaceMcpFile();
+  if (result.fileState === "invalid") {
+    throw new Error(result.issues[0] ?? "mcp.json is not a valid document");
+  }
+}
+
+/** Persist the in-memory workspace MCP config as a spec-pure document. */
+export function saveWorkspaceMcpConfig(config: McpConfig): void {
+  assertWorkspaceMcpWritable();
+  const path = getWorkspaceMcpConfigPath();
+  const mcpServers: Record<string, unknown> = {};
+  for (const [id, server] of Object.entries(config.servers)) {
+    mcpServers[id] = projectTransportToSpecServer(server.transport);
+  }
+
+  const document = {
+    $schema: AGENT_PLUGINS_MCP_SCHEMA_URL,
+    mcpServers,
+  };
+
+  mkdirSync(dirname(path), { recursive: true });
+  const tmpPath = `${path}.tmp`;
+  writeFileSync(tmpPath, JSON.stringify(document, null, 2) + "\n");
+  renameSync(tmpPath, path);
+}
+
+/**
+ * Replace `config.mcp` on a settings/export payload with the projected
+ * workspace servers (transport only, headers stripped). Old clients that
+ * still read `mcp.servers` from `/v1/config` keep seeing the same shape.
+ */
+export function overlayWorkspaceMcpForConfigRead(config: unknown): void {
+  if (config === null || typeof config !== "object" || Array.isArray(config)) {
+    return;
+  }
+  const root = config as Record<string, unknown>;
+  const { servers } = loadWorkspaceMcpConfig();
+  const projected: Record<string, unknown> = {};
+  for (const [id, server] of Object.entries(servers)) {
+    const { headers: _headers, ...safeTransport } = server.transport as Record<
+      string,
+      unknown
+    >;
+    projected[id] = { transport: safeTransport };
+  }
+  root.mcp = { servers: projected };
+}

package/src/messaging/provider.ts

@@ -56,15 +56,22 @@ export interface MessagingProvider {
     query: string,
     options?: SearchOptions,
   ): Promise<SearchResult>;
-  sendMessage(
+
+  // ── Optional operations (platforms implement what they support) ───
+
+  /**
+   * Send through the provider's own API. A provider whose channel has a
+   * direct transport omits this: its sends go through the transport, which
+   * is the one send implementation per addressable channel, and the
+   * messaging tool routes there before it looks for this method.
+   */
+  sendMessage?(
     connection: OAuthConnection | undefined,
     conversationId: string,
     text: string,
     options?: SendOptions,
   ): Promise<SendResult>;
 
-  // ── Optional operations (platforms implement what they support) ───
-
   getThreadReplies?(
     connection: OAuthConnection | undefined,
     conversationId: string,