@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/plugins/defaults/memory/substrate/page-index.ts

@@ -19,6 +19,7 @@
  * concept pages or seeded skill entries change.
  */
 
+import { safeStringSlice } from "../host-utils.js";
 import { getLogger } from "../logging.js";
 import {
   CLI_COMMAND_SLUG_PREFIX,
@@ -51,7 +52,11 @@ const SUMMARY_MAX_LENGTH = 200;
  * and corrupt the format the router parses.
  */
 function normalizeSummary(raw: string): string {
-  return raw.replace(/\s+/g, " ").trim().slice(0, SUMMARY_MAX_LENGTH);
+  return safeStringSlice(
+    raw.replace(/\s+/g, " ").trim(),
+    0,
+    SUMMARY_MAX_LENGTH,
+  );
 }
 
 /**

package/src/plugins/defaults/memory/substrate/skill-content.ts

@@ -1,4 +1,4 @@
-import { getConfig } from "../../../../config/loader.js";
+import { loadWorkspaceMcpConfig } from "../../../../mcp/workspace-mcp-config.js";
 
 /**
  * Generic input for building capability statements: the capability fields of
@@ -92,7 +92,7 @@ export function augmentMcpSetupDescription(
   if (input.id !== "mcp-setup") {
     return input;
   }
-  const servers = getConfig().mcp?.servers;
+  const servers = loadWorkspaceMcpConfig().servers;
   if (!servers) {
     return input;
   }

package/src/plugins/defaults/memory/v1/graph/consolidation.ts

@@ -26,7 +26,7 @@ import {
 } from "../../graph/store.js";
 import type { MemoryNode } from "../../graph/types.js";
 import { isCapabilityNode } from "../../graph/types.js";
-import { BackendUnavailableError } from "../../host-utils.js";
+import { BackendUnavailableError, safeStringSlice } from "../../host-utils.js";
 import { extractToolUse, userMessage } from "../../llm-helpers.js";
 import { getLogger } from "../../logging.js";
 import {
@@ -268,7 +268,9 @@ async function identifyDuplicateGroups(
   const listing = nodes
     .map((n) => {
       const preview =
-        n.content.length > 100 ? n.content.slice(0, 100) + "…" : n.content;
+        n.content.length > 100
+          ? safeStringSlice(n.content, 0, 100) + "…"
+          : n.content;
       return `[${n.id}] ${preview}`;
     })
     .join("\n");

package/src/plugins/defaults/memory/v1/graph/extraction.ts

@@ -46,7 +46,7 @@ import type {
   SourceType,
   TriggerType,
 } from "../../graph/types.js";
-import { BackendUnavailableError } from "../../host-utils.js";
+import { BackendUnavailableError, safeStringSlice } from "../../host-utils.js";
 import { extractToolUse, userMessage } from "../../llm-helpers.js";
 import { getLogger } from "../../logging.js";
 import { buildIdentityContext } from "../identity-context.js";
@@ -1617,7 +1617,9 @@ async function findCandidateNodes(
       await import("../../../../../persistence/embeddings/embed.js");
     const searchText =
       transcript.length > 3000
-        ? transcript.slice(0, 1500) + "\n...\n" + transcript.slice(-1500)
+        ? safeStringSlice(transcript, 0, 1500) +
+          "\n...\n" +
+          safeStringSlice(transcript, transcript.length - 1500)
         : transcript;
 
     try {

package/src/plugins/defaults/memory/v1/graph/retriever.ts

@@ -33,6 +33,7 @@ import type {
   ScoredNode,
 } from "../../graph/types.js";
 import { isCapabilityNode } from "../../graph/types.js";
+import { safeStringSlice } from "../../host-utils.js";
 import { extractToolUse, userMessage } from "../../llm-helpers.js";
 import { getLogger } from "../../logging.js";
 import { searchGraphNodes } from "./graph-search.js";
@@ -491,7 +492,9 @@ export async function loadContextMemory(
     try {
       const queryText = opts.recentSummaries.join("\n\n");
       const truncated =
-        queryText.length > 3000 ? queryText.slice(0, 3000) : queryText;
+        queryText.length > 3000
+          ? safeStringSlice(queryText, 0, 3000)
+          : queryText;
       contextQueryText = truncated;
       const result = await embedWithRetry(opts.config, [truncated], {
         signal: opts.signal,

package/src/plugins/defaults/memory/v2/reranker.ts

@@ -3,6 +3,7 @@
 import { createHash } from "node:crypto";
 
 import type { AssistantConfig } from "../../../../config/types.js";
+import { safeStringSlice } from "../host-utils.js";
 import { getLogger } from "../logging.js";
 import { getWorkspaceDir } from "../paths.js";
 import { readPage } from "../substrate/page-store.js";
@@ -57,7 +58,11 @@ function buildPassage(slug: string, body: string): string {
   const blank = trimmed.search(/\n\s*\n/);
   const para = blank === -1 ? trimmed : trimmed.slice(0, blank);
   const stripped = para.replace(/^#+\s.*\n/, "").trim();
-  const compact = stripped.replace(/\s+/g, " ").slice(0, PASSAGE_CHAR_CAP);
+  const compact = safeStringSlice(
+    stripped.replace(/\s+/g, " "),
+    0,
+    PASSAGE_CHAR_CAP,
+  );
   return `${slug}\n${compact}`;
 }
 

package/src/plugins/defaults/memory/v3/__tests__/card.test.ts

@@ -6,6 +6,8 @@
 
 import { describe, expect, test } from "bun:test";
 
+import { stripOrphanedSurrogates } from "../../../../../util/unicode.js";
+import { LINK_SEPARATOR } from "../../substrate/page-links.js";
 import { renderCard } from "../card.js";
 
 const PAGE = `---
@@ -73,6 +75,28 @@ Lead paragraph for page a.
     expect(line.length).toBeLessThan(300);
   });
 
+  test("capping a `current:` value never splits an emoji at the cap", () => {
+    // 279 BMP characters put the 280-character cap inside the emoji's pair.
+    const current = `${"x".repeat(279)}🎉 trailing`;
+    const card = renderCard(
+      "page-a",
+      `---\ncurrent: "${current}"\n---\n\nLead.\n`,
+    );
+    const line = card.split("\n")[1]!;
+    expect(stripOrphanedSurrogates(line)).toBe(line);
+    expect(line).toBe(`[current: ${"x".repeat(279)}…]`);
+  });
+
+  test("capping a link note never splits an emoji at the cap", () => {
+    const note = `${"n".repeat(79)}🎉 trailing`;
+    const card = renderCard(
+      "page-a",
+      `---\nkind: index\nlinks:\n  - "other${LINK_SEPARATOR}${note}"\n---\n\nLead.\n`,
+    );
+    expect(stripOrphanedSurrogates(card)).toBe(card);
+    expect(card).toContain(`other${LINK_SEPARATOR}${"n".repeat(79)}…`);
+  });
+
   test("the `status:` draft marker does NOT render as a card line", () => {
     const card = renderCard("page-a", `---\nstatus: cc-draft\n---\n\nLead.\n`);
     expect(card).not.toContain("cc-draft");

package/src/plugins/defaults/memory/v3/__tests__/pool-select.test.ts

@@ -39,7 +39,9 @@ import type {
   SendMessageOptions,
 } from "@vellumai/plugin-api";
 
+import { OpenRouterProvider } from "../../../../../providers/openrouter/client.js";
 import { ProviderError } from "../../../../../util/errors.js";
+import { stripOrphanedSurrogates } from "../../../../../util/unicode.js";
 import { sectionHeadLine } from "../sections.js";
 import type { MemoryRoutingTurn, Section } from "../types.js";
 
@@ -842,4 +844,127 @@ describe("selectPool: sections and keyword-in-context snippets", () => {
       true,
     );
   });
+  test("a window whose edges land inside an emoji keeps both pairs whole and the request well-formed", async () => {
+    providerStub = makeProvider(toolUseResponse({ ids: [] }));
+    // 200 emoji (400 code units) on each side of the term, offset so that a
+    // code-unit window centered on the term starts and ends mid-pair. A
+    // window cut there carries half a pair on each edge, which strict
+    // provider parsers reject once JSON.stringify escapes each orphan.
+    const emoji = "😀".repeat(200);
+    const body = `${emoji}y turnip  ${emoji}`;
+    const term = body.indexOf("turnip");
+    const naiveStart = term + 3 - 150;
+    const naive = body.slice(naiveStart, naiveStart + 300);
+    expect(stripOrphanedSurrogates(naive)).not.toBe(naive);
+    const section = sectionOf("page-a", "Rollout", body);
+    await selectPool(
+      finderOnly({
+        slug: "page-a",
+        descriptor: section.text,
+        section,
+        terms: ["turnip"],
+      }),
+      makeTurn("turnip?"),
+    );
+    const [block] = sentBlocks();
+    expect(stripOrphanedSurrogates(block.text)).toBe(block.text);
+    const line = block.text
+      .split("\n")
+      .find((l) => l.startsWith("[1] page-a "))!;
+    expect(line).toContain("§Rollout: … ");
+    expect(line).toContain("turnip");
+    expect(line.endsWith(" …")).toBe(true);
+    // The window stays bounded: at most one code unit shorter on each edge.
+    const windowStart = line.indexOf("… ") + "… ".length;
+    expect(line.length - windowStart).toBeLessThanOrEqual(300 + " …".length);
+    expect(line.length - windowStart).toBeGreaterThanOrEqual(298 + " …".length);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// selectPool: cataloged thinking and forced-tool compatibility.
+// ---------------------------------------------------------------------------
+
+describe("selectPool: cataloged thinking and forced-tool compatibility", () => {
+  test("OpenRouter Kimi K2.6 omits the forced choice and yields a structured selection", async () => {
+    // A real OpenAI chat-completions provider stands in for the cataloged
+    // OpenRouter Kimi profile. The request succeeds without a reactive retry
+    // because the forced select_pages choice is omitted before dispatch.
+    const wireRequests: unknown[] = [];
+    const kimi = new OpenRouterProvider(
+      "test-key",
+      "moonshotai/kimi-k2.6-20260420",
+    );
+    (kimi as unknown as { client: unknown }).client = {
+      chat: {
+        completions: {
+          create: async (params: unknown) => {
+            wireRequests.push(JSON.parse(JSON.stringify(params)));
+            return {
+              async *[Symbol.asyncIterator]() {
+                yield {
+                  choices: [
+                    {
+                      delta: {
+                        tool_calls: [
+                          {
+                            index: 0,
+                            id: "call-1",
+                            function: {
+                              name: "select_pages",
+                              arguments: '{"ids":[3]}',
+                            },
+                          },
+                        ],
+                      },
+                      finish_reason: "tool_calls",
+                    },
+                  ],
+                  usage: { prompt_tokens: 10, completion_tokens: 2 },
+                };
+              },
+            };
+          },
+        },
+      },
+    };
+
+    // The profile layer injects the thinking effort onto the call config in
+    // production; emulate that here so the forced tool_choice rides alongside
+    // reasoning on the wire.
+    providerStub = {
+      name: "kimi-openai-compat",
+      sendMessage: (messages: Message[], options?: SendMessageOptions) =>
+        kimi.sendMessage(messages, {
+          ...options,
+          config: {
+            ...options?.config,
+            effort: "high",
+            thinking: { enabled: true },
+          },
+        }),
+    };
+
+    const selection = await selectPool(makePool(), makeTurn("rollout?"));
+
+    // The preflight path avoids an incompatible first request, and the
+    // pool-level re-prompt loop never engages.
+    expect(wireRequests).toHaveLength(1);
+    const first = wireRequests[0] as {
+      tool_choice?: unknown;
+      reasoning?: { effort?: string; summary?: string };
+    };
+    expect(first.tool_choice).toBeUndefined();
+    expect(first.reasoning).toMatchObject({
+      effort: "high",
+      summary: "detailed",
+    });
+    expect(warnPayloads().filter((p) => p.reason === "provider_error")).toEqual(
+      [],
+    );
+
+    // Structured selection survived: ids [3] is the topic-x finder line.
+    expect(selection.keptAll).toBe(false);
+    expect(selection.pages).toEqual([{ slug: "topic-x", sections: [] }]);
+  });
 });

package/src/plugins/defaults/memory/v3/__tests__/sections.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
+import { stripOrphanedSurrogates } from "../../../../../util/unicode.js";
 import {
   buildSectionIndex,
   leadSectionOfBody,
@@ -108,6 +109,31 @@ describe("buildSectionIndex", () => {
     }
   });
 
+  test("a hard split never lands inside a surrogate pair and loses no text", async () => {
+    // One unbroken line of emoji longer than the window, offset by one BMP
+    // character so the window boundary falls between a pair's halves.
+    const unbroken = `y${"😀".repeat(SECTION_CHUNK_CHARS)}`;
+    const index = await buildSectionIndex(
+      ["page-a"],
+      reader({ "page-a": `## Big\n${unbroken}` }),
+    );
+
+    const big = index.sections.filter((s) => s.title === "Big");
+    expect(big.length).toBeGreaterThan(1);
+    for (const chunk of big) {
+      expect(chunk.text.length).toBeLessThanOrEqual(SECTION_CHUNK_CHARS);
+      expect(stripOrphanedSurrogates(chunk.text)).toBe(chunk.text);
+    }
+    expect(big.map(sectionBody).join("")).toBe(unbroken);
+  });
+
+  test("a capped head-line title never ends in half an emoji", () => {
+    const title = `${"t".repeat(199)}🎉 more`;
+    const head = sectionHeadLine("page-a", title);
+    expect(stripOrphanedSurrogates(head)).toBe(head);
+    expect(head).toBe(`page-a - ${"t".repeat(199)}`);
+  });
+
   test("a heading longer than the window still chunks by near-window bodies; the key keeps the full title", async () => {
     const title = "H".repeat(SECTION_CHUNK_CHARS + 100);
     const body = "b".repeat(SECTION_CHUNK_CHARS * 2);

package/src/plugins/defaults/memory/v3/__tests__/shadow-plugin.test.ts

@@ -38,6 +38,7 @@ import { ESCALATION_CONTINUATION_CONTENT } from "../../../../../calls/voice-tria
 import { MemoryV3GateSchema } from "../../../../../config/schemas/memory-v3.js";
 import { ensureMemoryV3SelectionsSchema } from "../../../../../persistence/migrations/338-move-memory-v3-selections-to-memory-db.js";
 import * as schema from "../../../../../persistence/schema/index.js";
+import { stripOrphanedSurrogates } from "../../../../../util/unicode.js";
 import type { HotSetEntry, HotSetOptions } from "../hot-set.js";
 import type { OrchestrateResult } from "../orchestrate.js";
 import {
@@ -1083,6 +1084,35 @@ describe("memory-v3 engine", () => {
     expect(turn.previousAssistantMessage).toBeUndefined();
   });
 
+  test("the reply tail never starts inside a surrogate pair", async () => {
+    // 1300 emoji then one BMP character: the 2500-code-unit tail would start
+    // on a low surrogate, an orphan the embedding request's parser rejects.
+    const reply = `${"😀".repeat(1300)}a`;
+    messages = [
+      {
+        role: "user",
+        content: JSON.stringify([{ type: "text", text: "first question" }]),
+      },
+      {
+        role: "assistant",
+        content: JSON.stringify([{ type: "text", text: reply }]),
+      },
+      {
+        role: "user",
+        content: JSON.stringify([{ type: "text", text: "and now this" }]),
+      },
+    ];
+    await observeTurn("conv-1", 1);
+
+    const turn = (
+      orchestrateSpy.mock.calls as unknown as unknown[][]
+    )[0]![0] as MemoryRoutingTurn;
+    const tail = turn.previousAssistantMessage!;
+    expect(stripOrphanedSurrogates(tail)).toBe(tail);
+    expect(tail.length).toBeLessThanOrEqual(2500);
+    expect(reply.endsWith(tail)).toBe(true);
+  });
+
   test("a page with lines from two lanes is attributed the lane of the line whose section was selected", () => {
     const bulk: Section = {
       article: "page-two",

package/src/plugins/defaults/memory/v3/card.ts

@@ -1,4 +1,5 @@
 import { FRONTMATTER_REGEX, parseFrontmatterFields } from "../frontmatter.js";
+import { safeStringSlice } from "../host-utils.js";
 import { injectedConceptHeader } from "../substrate/injected-block-slugs.js";
 import { LINK_SEPARATOR, parseLinkEntry } from "../substrate/page-links.js";
 import type { Slug } from "./types.js";
@@ -38,7 +39,7 @@ function renderLinkEntry(entry: string): string {
   }
   const note =
     description.length > LINK_NOTE_MAX_CHARS
-      ? `${description.slice(0, LINK_NOTE_MAX_CHARS).trimEnd()}…`
+      ? `${safeStringSlice(description, 0, LINK_NOTE_MAX_CHARS).trimEnd()}…`
       : description;
   return `${target}${LINK_SEPARATOR}${note}`;
 }
@@ -103,7 +104,7 @@ export function renderCurrentLine(
   }
   const capped =
     collapsed.length > CURRENT_MAX_CHARS
-      ? `${collapsed.slice(0, CURRENT_MAX_CHARS).trimEnd()}…`
+      ? `${safeStringSlice(collapsed, 0, CURRENT_MAX_CHARS).trimEnd()}…`
       : collapsed;
   return `[current: ${capped}]`;
 }

package/src/plugins/defaults/memory/v3/pool-select.ts

@@ -57,7 +57,7 @@ import { z } from "zod";
 
 import { classifyConversationError } from "../../../../daemon/conversation-error.js";
 import type { PendingConversationNotice } from "../../../../daemon/conversation-notices.js";
-import { redactLogString, truncate } from "../host-utils.js";
+import { redactLogString, safeStringSlice, truncate } from "../host-utils.js";
 import {
   cachedTextBlock,
   extractToolUse,
@@ -276,7 +276,9 @@ function oneLine(text: string): string {
  * `§<title>: … <window> …`, the window being up to {@link SNIPPET_MAX_CHARS}
  * of the one-line section body centered on the first occurrence of the
  * best-contributing query term that occurs in it (the lead, titled `""`,
- * renders the window alone). `undefined` when no term occurs in the body.
+ * renders the window alone). The window edges never split a surrogate pair:
+ * an orphaned half is invalid UTF-16 and strict provider parsers reject the
+ * whole request. `undefined` when no term occurs in the body.
  */
 function renderKeywordInContext(
   section: Section,
@@ -299,7 +301,7 @@ function renderKeywordInContext(
     const end = Math.min(body.length, start + SNIPPET_MAX_CHARS);
     const window = [
       start > 0 ? "… " : "",
-      body.slice(start, end).trim(),
+      safeStringSlice(body, start, end).trim(),
       end < body.length ? " …" : "",
     ].join("");
     const title = section.title.trim();

package/src/plugins/defaults/memory/v3/sections.ts

@@ -1,3 +1,4 @@
+import { safeStringSlice } from "../host-utils.js";
 import type { Section, SectionIndex, Slug } from "./types.js";
 
 /**
@@ -44,7 +45,7 @@ function lastSlugSegment(slug: Slug): string {
  * {@link sectionBody}.
  */
 export function sectionHeadLine(article: Slug, title: string): string {
-  return `${lastSlugSegment(article)} - ${title.slice(0, SECTION_HEAD_TITLE_CHARS)}`;
+  return `${lastSlugSegment(article)} - ${safeStringSlice(title, 0, SECTION_HEAD_TITLE_CHARS)}`;
 }
 
 /**
@@ -95,7 +96,9 @@ export function splitIntoRawSections(body: string): RawSection[] {
 /**
  * Split `text` into chunks no longer than `limit`, preferring to break on
  * newlines so chunks stay readable. A single line longer than the limit is
- * hard-split at the limit. Order is preserved.
+ * hard-split at the limit, backed off one code unit when the limit would cut
+ * a surrogate pair (an orphaned half is invalid UTF-16 that strict provider
+ * parsers reject). Order is preserved.
  */
 function chunkText(text: string, limit: number): string[] {
   if (text.length <= limit) {
@@ -109,7 +112,10 @@ function chunkText(text: string, limit: number): string[] {
     const newlineBreak = window.lastIndexOf("\n");
     // Only break on a newline if it leaves a non-trivial chunk; otherwise hard
     // split at the window boundary to guarantee forward progress.
-    const breakAt = newlineBreak > 0 ? newlineBreak : limit;
+    const breakAt =
+      newlineBreak > 0
+        ? newlineBreak
+        : Math.max(1, safeStringSlice(remaining, 0, limit).length);
     chunks.push(remaining.slice(0, breakAt));
     remaining = remaining.slice(breakAt).replace(/^\n/, "");
   }

package/src/plugins/defaults/memory/v3/shadow-plugin.ts

@@ -44,7 +44,7 @@ import {
   timeLatencySubSpan,
 } from "../../../../daemon/turn-latency-sub-spans.js";
 import { enqueueMemoryJob } from "../../../../persistence/jobs-store.js";
-import { stripCommentLines } from "../host-utils.js";
+import { safeStringSlice, stripCommentLines } from "../host-utils.js";
 import { getLogger } from "../logging.js";
 import { type MemorySqlite, memorySqliteOrNull } from "../memory-db.js";
 import { getWorkspaceDir, getWorkspacePromptPath } from "../paths.js";
@@ -578,7 +578,10 @@ async function buildShadowTurn(
     }
     const text = stringifyMessageContent(rows[i]!.content);
     if (text.length > 0) {
-      previousAssistantMessage = text.slice(-REPLY_QUERY_TAIL_CHARS);
+      previousAssistantMessage = safeStringSlice(
+        text,
+        Math.max(0, text.length - REPLY_QUERY_TAIL_CHARS),
+      );
       break;
     }
   }

package/src/plugins/defaults/memory/worker.ts

@@ -16,6 +16,10 @@ import { getConfig } from "../../../config/loader.js";
 import { isMemoryEnabled } from "../../../config/memory-v3-gate.js";
 import { rehydratePlatformCredentials } from "../../../config/platform-rehydration.js";
 import { startConversationEvictor } from "../../../daemon/conversation-evictor.js";
+import {
+  startWorkspaceSkillMdMtimePoll,
+  stopWorkspaceSkillMdMtimePoll,
+} from "../../../daemon/skill-memory-refresh.js";
 import { resetDb } from "../../../persistence/db-connection.js";
 import {
   EMBEDDING_SHUTDOWN_BUDGET_MS,
@@ -108,6 +112,7 @@ async function main(): Promise<void> {
     shuttingDown = true;
     log.info({ signal }, "Memory worker process shutting down");
     worker?.stop();
+    stopWorkspaceSkillMdMtimePoll();
     if (keepAlive != null) {
       clearInterval(keepAlive);
     }
@@ -161,6 +166,7 @@ async function main(): Promise<void> {
   }
 
   worker = startMemoryJobsWorkerLoop();
+  startWorkspaceSkillMdMtimePoll();
 
   // Keep-alive: the worker's setTimeout timers are unref'd, so without
   // this interval the process would exit immediately.

package/src/plugins/mcp-servers.ts

@@ -14,7 +14,7 @@
  * This module reads those files and projects each entry onto the
  * assistant's own `McpServerConfig` shape, so a plugin-declared server can
  * flow through the same surfaces as one configured in the workspace
- * `config.json`.
+ * `mcp.json`.
  *
  * Failure isolation follows the spec: an invalid top-level `mcp.json`
  * disables MCP for that plugin only, and an invalid individual server
@@ -39,17 +39,17 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { z } from "zod";
-
 import {
   type AllPluginInfo,
   listAllPlugins,
   type ListInstalledPluginsOptions,
 } from "../cli/lib/list-installed-plugins.js";
-import type {
-  McpTransport,
-  ResolvedMcpServerConfig,
-} from "../config/schemas/mcp.js";
+import type { ResolvedMcpServerConfig } from "../config/schemas/mcp.js";
+import {
+  projectSpecServerToTransport,
+  SpecMcpDocumentSchema,
+  SpecMcpServerSchema,
+} from "../mcp/spec-schema.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("plugin-mcp-servers");
@@ -77,45 +77,6 @@ export const PLUGIN_MCP_MANIFEST = "mcp.json";
  * origin risk.
  */
 
-// ---------------------------------------------------------------------------
-// Wire schema (Agent Plugins 1.0.0)
-// ---------------------------------------------------------------------------
-
-const PluginStdioServerSchema = 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 PluginHttpServerSchema = 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(),
-});
-
-const PluginMcpServerSchema = z.union([
-  PluginStdioServerSchema,
-  PluginHttpServerSchema,
-]);
-
-const PluginMcpManifestSchema = z.object({
-  mcpServers: z.record(z.string(), z.unknown()),
-});
-
 // ---------------------------------------------------------------------------
 // Public shape
 // ---------------------------------------------------------------------------
@@ -251,7 +212,7 @@ export function readPluginMcpServers(
         continue;
       }
 
-      const entry = PluginMcpServerSchema.safeParse(raw);
+      const entry = SpecMcpServerSchema.safeParse(raw);
       if (!entry.success) {
         issues.push({
           pluginName: plugin.name,
@@ -325,7 +286,7 @@ function parseManifest(
     };
   }
 
-  const manifest = PluginMcpManifestSchema.safeParse(json);
+  const manifest = SpecMcpDocumentSchema.safeParse(json);
   if (!manifest.success) {
     return {
       error: `${PLUGIN_MCP_MANIFEST} is missing a valid "mcpServers" object`,
@@ -334,33 +295,12 @@ function parseManifest(
   return { mcpServers: manifest.data.mcpServers };
 }
 
-/**
- * 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 path interpolation for the stdio case.
- */
 function projectTransport(
-  entry: z.infer<typeof PluginMcpServerSchema>,
+  entry: Parameters<typeof projectSpecServerToTransport>[0],
   pluginRoot: string,
-): McpTransport {
-  if (entry.type === "stdio") {
-    const pluginData = join(pluginRoot, "data");
-    const expand = (v: string): string =>
-      interpolatePluginPaths(v, pluginRoot, pluginData);
-    return {
-      type: "stdio",
-      command: entry.command,
-      args: (entry.args ?? []).map(expand),
-      ...(entry.env && {
-        env: Object.fromEntries(
-          Object.entries(entry.env).map(([k, v]) => [k, expand(v)]),
-        ),
-      }),
-    };
-  }
-  return {
-    type: entry.type,
-    url: entry.url,
-    ...(entry.headers && { headers: entry.headers }),
-  };
+) {
+  const pluginData = join(pluginRoot, "data");
+  return projectSpecServerToTransport(entry, (value) =>
+    interpolatePluginPaths(value, pluginRoot, pluginData),
+  );
 }