@vellumai/assistant 0.12.2-staging.2 → 0.12.2-staging.3

package/src/plugins/external-plugin-loader.ts

@@ -10,12 +10,12 @@
  * need to be renamed when the convention shifts.
  *
  *     <pluginDir>/
- *       package.json              ← manifest.name comes from `name`
- *                                   (npm scope stripped);
+ *       package.json              ← legacy Vellum manifest, selected first;
  *                                   peerDependencies["@vellumai/plugin-api"]
  *                                   semver range is checked against the
  *                                   running assistant version and rejects
  *                                   the plugin if unsatisfied
+ *       plugin.json               ← standard fallback when package.json is absent
  *       hooks/
  *         <name>.ts               ← default export → plugin.hooks[<name>]
  *                                   (today the runtime invokes "init" at
@@ -41,7 +41,6 @@
  */
 
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -53,6 +52,10 @@ import { PLUGIN_SECRET_PATTERN_LIMITS } from "../security/plugin-secret-patterns
 import { finalizeTool } from "../tools/tool-defaults.js";
 import type { Tool, ToolDefinition } from "../tools/types.js";
 import { getLogger } from "../util/logger.js";
+import {
+  LEGACY_PLUGIN_MANIFEST,
+  readPluginManifest,
+} from "../util/plugin-manifest.js";
 import { registerPlugin } from "./registry.js";
 import type {
   HookFunction,
@@ -69,39 +72,12 @@ const log = getLogger("external-plugin-loader");
 /** Default upper bound on how long a single plugin load may take. */
 const DEFAULT_IMPORT_TIMEOUT_MS = 10_000;
 
-/**
- * Zod schema for the subset of `package.json` the external loader reads.
- *
- * - `name` is the only required field; everything else is best-effort.
- * - `peerDependencies["@vellumai/plugin-api"]` is the canonical host-compat
- *   declaration. If present, the loader checks `semver.satisfies(host, range)`
- *   against the running assistant version and rejects the plugin on
- *   mismatch. If absent, the plugin loads without a host-compat claim
- *   (with a warning).
- * - `credentialKeyPatterns` is typed `unknown` here and shape-validated
- *   separately ({@link parseCredentialKeyPatterns}) so a malformed
- *   declaration degrades to `undefined` instead of failing the whole
- *   `safeParse` and blocking plugin load.
- * - Unknown fields pass through (`passthrough`) so the loader does not
- *   destructively reshape the file when the rest of the npm ecosystem
- *   writes to it.
- */
-const PluginPackageJsonSchema = z
-  .object({
-    name: z.string().min(1, "package.json `name` must be a non-empty string"),
-    version: z.string().optional(),
-    peerDependencies: z.record(z.string(), z.string()).optional(),
-    credentialKeyPatterns: z.unknown().optional(),
-    /** Human title, when the package name is not one ("@vellumai/imessage"). */
-    displayName: z.string().min(1).optional(),
-    /** Standard npm field, reused as the one-line description clients show. */
-    description: z.string().min(1).optional(),
-    /** Lucide icon name without the `lucide-` prefix, matching `ChannelInfo`. */
-    icon: z.string().min(1).optional(),
-  })
-  .passthrough();
-
-type PluginPackageJson = z.infer<typeof PluginPackageJsonSchema>;
+interface LegacyPluginFields extends Record<string, unknown> {
+  readonly peerDependencies?: Record<string, string>;
+  readonly credentialKeyPatterns?: unknown;
+  readonly displayName?: string;
+  readonly icon?: string;
+}
 
 /**
  * Shape-level caps for the `credentialKeyPatterns` manifest field. The
@@ -270,23 +246,8 @@ async function loadHooks(
  * timeout/try-catch/register triple.
  */
 async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
-  const pkgPath = join(pluginDir, "package.json");
-  let rawPkg: unknown;
-  try {
-    rawPkg = JSON.parse(await readFile(pkgPath, "utf8"));
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    throw new Error(
-      `package.json at ${pluginDir} could not be read or parsed: ${reason}`,
-    );
-  }
-  const parsed = PluginPackageJsonSchema.safeParse(rawPkg);
-  if (!parsed.success) {
-    throw new Error(
-      `package.json at ${pluginDir} failed schema validation: ${parsed.error.message}`,
-    );
-  }
-  const pkg: PluginPackageJson = parsed.data;
+  const resolvedManifest = readPluginManifest(pluginDir);
+  const legacyFields = resolvedManifest.raw as LegacyPluginFields;
   // A plugin's identity is its install directory name — the slug the plugin
   // was installed under (a marketplace slug or a GitHub path leaf). This is
   // the identity every other surface uses: `plugins list`, enable/disable,
@@ -296,7 +257,10 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
   // registry from the identity the user toggles and the scope filters match.
   // The manifest is still required (schema-validated above) as the load gate.
   const name = basename(pluginDir);
-  const version = pkg.version && pkg.version.length > 0 ? pkg.version : "0.0.0";
+  const version =
+    resolvedManifest.version && resolvedManifest.version.length > 0
+      ? resolvedManifest.version
+      : "0.0.0";
 
   // Host-compat negotiation: plugins declare their plugin-api version
   // range via standard `peerDependencies["@vellumai/plugin-api"]`. We
@@ -310,7 +274,7 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
   //
   // If the peerDep is absent, the plugin loads without a host-compat
   // claim; we log a warning so the omission is visible at boot.
-  const range = pkg.peerDependencies?.[PLUGIN_API_PEER_DEP];
+  const range = legacyFields.peerDependencies?.[PLUGIN_API_PEER_DEP];
   if (range !== undefined) {
     if (!semver.validRange(range)) {
       log.error(
@@ -333,7 +297,7 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
         `external plugin ${name}: peerDependencies["${PLUGIN_API_PEER_DEP}"] requires "${range}" but assistant is ${assistantPkg.version} — loading anyway`,
       );
     }
-  } else {
+  } else if (resolvedManifest.source === LEGACY_PLUGIN_MANIFEST) {
     log.warn(
       { pluginDir, plugin: name, peerDep: PLUGIN_API_PEER_DEP },
       "external plugin missing plugin-api peerDependency — loading without host-compat claim",
@@ -342,7 +306,9 @@ async function buildPluginFromDir(pluginDir: string): Promise<Plugin> {
 
   const manifest: PluginManifest = { name, version };
   const credentialKeyPatterns = parseCredentialKeyPatterns(
-    pkg.credentialKeyPatterns,
+    resolvedManifest.source === LEGACY_PLUGIN_MANIFEST
+      ? legacyFields.credentialKeyPatterns
+      : undefined,
     pluginDir,
   );
   if (credentialKeyPatterns !== undefined) {
@@ -459,9 +425,9 @@ export async function loadExternalPlugin(
 }
 
 /**
- * Parse a plugin's `package.json` manifest from disk. Returns the plugin
+ * Parse a plugin's selected manifest from disk. Returns the plugin
  * identity (its install directory name), version, and any declared
- * `credentialKeyPatterns`, or `undefined` when the `package.json` is
+ * legacy `credentialKeyPatterns`, or `undefined` when the manifest is
  * missing, unparseable, or fails schema validation.
  *
  * Exported so the mtime cache can discover plugin identity without going
@@ -497,20 +463,23 @@ export interface PluginPresentation {
 export async function parsePluginPresentation(
   pluginDir: string,
 ): Promise<PluginPresentation | undefined> {
-  let rawPkg: unknown;
   try {
-    rawPkg = JSON.parse(
-      await readFile(join(pluginDir, "package.json"), "utf8"),
-    );
+    const manifest = readPluginManifest(pluginDir);
+    const legacyFields = manifest.raw as LegacyPluginFields;
+    return {
+      displayName:
+        manifest.source === LEGACY_PLUGIN_MANIFEST
+          ? legacyFields.displayName
+          : manifest.name,
+      description: manifest.description,
+      icon:
+        manifest.source === LEGACY_PLUGIN_MANIFEST
+          ? legacyFields.icon
+          : undefined,
+    };
   } catch {
     return undefined;
   }
-  const parsed = PluginPackageJsonSchema.safeParse(rawPkg);
-  if (!parsed.success) {
-    return undefined;
-  }
-  const { displayName, description, icon } = parsed.data;
-  return { displayName, description, icon };
 }
 
 export async function parsePluginManifest(
@@ -519,35 +488,29 @@ export async function parsePluginManifest(
 ): Promise<
   Pick<PluginManifest, "name" | "version" | "credentialKeyPatterns"> | undefined
 > {
-  const pkgPath = join(pluginDir, "package.json");
-  let rawPkg: unknown;
+  let resolvedManifest: ReturnType<typeof readPluginManifest>;
   try {
-    rawPkg = JSON.parse(await readFile(pkgPath, "utf8"));
+    resolvedManifest = readPluginManifest(pluginDir);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     if (!opts.quiet) {
       log.error(
         { err, pluginDir },
-        `package.json at ${pluginDir} could not be read or parsed: ${reason}`,
-      );
-    }
-    return undefined;
-  }
-  const parsed = PluginPackageJsonSchema.safeParse(rawPkg);
-  if (!parsed.success) {
-    if (!opts.quiet) {
-      log.error(
-        { err: parsed.error, pluginDir },
-        `package.json at ${pluginDir} failed schema validation: ${parsed.error.message}`,
+        `Plugin manifest at ${pluginDir} could not be read or validated: ${reason}`,
       );
     }
     return undefined;
   }
-  const pkg: PluginPackageJson = parsed.data;
+  const legacyFields = resolvedManifest.raw as LegacyPluginFields;
   const name = basename(pluginDir);
-  const version = pkg.version && pkg.version.length > 0 ? pkg.version : "0.0.0";
+  const version =
+    resolvedManifest.version && resolvedManifest.version.length > 0
+      ? resolvedManifest.version
+      : "0.0.0";
   const credentialKeyPatterns = parseCredentialKeyPatterns(
-    pkg.credentialKeyPatterns,
+    resolvedManifest.source === LEGACY_PLUGIN_MANIFEST
+      ? legacyFields.credentialKeyPatterns
+      : undefined,
     pluginDir,
   );
   if (credentialKeyPatterns !== undefined) {

package/src/plugins/installed-plugin-dirs.ts

@@ -1,8 +1,9 @@
 /**
  * Enumerate installed plugin directories under the workspace plugins dir.
  *
- * An installed plugin is a non-hidden directory carrying a `package.json`,
- * whose realpath stays under the realpath of the plugins directory. This walk
+ * An installed plugin is a non-hidden directory carrying a `package.json` or
+ * root `plugin.json` whose realpath stays under the realpath of the plugins
+ * directory. This walk
  * is shared by the plugin source-version collector
  * (`./collect-source-versions.ts`) and the schedule reconciler
  * (`../schedule/plugin-schedule-reconciler.ts`) so both agree on what counts
@@ -17,10 +18,11 @@
  * declaration is available to run.
  */
 
-import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { readdirSync, realpathSync, statSync } from "node:fs";
 import { join, sep } from "node:path";
 
 import { getWorkspacePluginsDir } from "../util/platform.js";
+import { hasPluginManifest } from "../util/plugin-manifest.js";
 
 export interface InstalledPluginDir {
   /** Directory basename: the plugin's install identity. */
@@ -92,7 +94,7 @@ export function listInstalledPluginDirs(): InstalledPluginDir[] {
     if (!isInsidePluginRoot(dir, pluginsDir)) {
       continue;
     }
-    if (!existsSync(join(dir, "package.json"))) {
+    if (!hasPluginManifest(dir)) {
       continue;
     }
     out.push({ name: entry, dir });

package/src/plugins/mcp-servers.ts

@@ -21,19 +21,11 @@
  * disables only that entry. Neither ever throws, because a malformed file
  * in one plugin must not remove another plugin's servers from a listing.
  *
- * Authentication is deliberately absent. Agent Plugins 1.0.0 defines no
- * portable OAuth or credential-reference fields; authentication is
- * client-managed, and any `headers` in the file are literal package data.
- * A plugin therefore cannot ship a credential, and the assistant's own
- * credential store stays the only place secrets live.
- *
- * Consumers must not resolve a plugin server's id against the
- * `mcp:<serverId>:*` credential namespace. Those keys belong to
- * workspace-configured servers, and a plugin controls both its server key
- * and its URL, so honoring them for a plugin-declared server would send a
- * workspace credential to an endpoint the plugin chose. Every config built
- * here carries `source: "plugin"`, which is what `McpClient` reads to
- * decide, so the rule travels with the server rather than with the caller.
+ * Authentication is client-managed. Agent Plugins 1.0.0 defines no portable
+ * OAuth or credential-reference fields, and any `headers` in the file are
+ * literal package data. Runtime configs carry the declaring plugin directory
+ * name and original server key so OAuth credentials can be isolated from the
+ * public server id and from workspace credentials.
  */
 
 import { existsSync, readFileSync } from "node:fs";
@@ -141,7 +133,7 @@ export function interpolatePluginPaths(
  *
  * `listAllPlugins` is an inventory of directories and reports a malformed
  * entry rather than dropping it, so it happily returns a directory with no
- * usable `package.json`. The runtime loader rejects those in
+ * usable selected manifest. The runtime loader rejects those in
  * `parsePluginManifest`: the manifest must parse and carry a non-empty
  * `name`. Applying the same gate here keeps `mcp.json` from being honored
  * for a directory that will never load as a plugin.
@@ -192,7 +184,7 @@ export function readPluginMcpServers(
     if (!hasLoadableManifest(plugin)) {
       issues.push({
         pluginName: plugin.name,
-        message: `${PLUGIN_MCP_MANIFEST} ignored: package.json is missing, unparseable, or has no name, so the runtime will not load this directory as a plugin`,
+        message: `${PLUGIN_MCP_MANIFEST} ignored: the selected plugin manifest is missing or invalid, so the runtime will not load this directory as a plugin`,
       });
       continue;
     }
@@ -257,6 +249,8 @@ export function readPluginMcpServers(
         config: {
           transport: projectTransport(entry.data, plugin.target),
           source: "plugin",
+          pluginName: plugin.name,
+          serverKey,
         },
       });
     }

package/src/plugins/mtime-cache.ts

@@ -59,6 +59,7 @@ import {
   getWorkspaceHooksDir,
   getWorkspacePluginsDir,
 } from "../util/platform.js";
+import { hasPluginManifest } from "../util/plugin-manifest.js";
 import { collectSourceVersions } from "./collect-source-versions.js";
 import {
   deriveToolName,
@@ -768,7 +769,7 @@ async function scanPlugins(): Promise<void> {
       );
       continue;
     }
-    if (!existsSync(join(pluginDir, "package.json"))) {
+    if (!hasPluginManifest(pluginDir)) {
       continue;
     }
 

package/src/plugins/user-loader.ts

@@ -2,7 +2,8 @@
  * User plugin loader — discovers plugins under `<workspaceDir>/plugins/*` and
  * populates the mtime cache.
  *
- * A plugin directory is recognized by a `package.json` manifest. The loader
+ * A plugin directory is recognized by a legacy `package.json` or standard
+ * `plugin.json` manifest. The loader
  * delegates to the mtime cache's `populateCacheAtBoot`, which builds each
  * plugin via `buildExternalPlugin` and stores it keyed by mtime. The cache
  * is the single source of truth for user plugin state — the registry is no

package/src/providers/inference/__tests__/endpoint-probe.test.ts

@@ -107,6 +107,51 @@ describe("testInferenceConnection", () => {
     expect(calls[0].body).not.toHaveProperty(OPENCODE_SESSION_HEADER);
   });
 
+  test("probes /responses for an OpenCode responses-only model", async () => {
+    const calls: ProbeCall[] = [];
+    const result = await testInferenceConnection(
+      {
+        provider: "opencode",
+        auth: { type: "none" },
+        baseUrl: "https://opencode.ai/zen/v1",
+        models: [{ id: "muse-spark-1.2-contributor-free" }],
+      },
+      stubFetch(200, calls),
+    );
+
+    expect(result).toMatchObject({
+      ok: true,
+      resolved_url: "https://opencode.ai/zen/v1/responses",
+    });
+    expect(calls[0].body).toMatchObject({
+      model: "muse-spark-1.2-contributor-free",
+      input: "ping",
+      max_output_tokens: 16,
+    });
+    expect(calls[0].headers[OPENCODE_SESSION_HEADER]).toBeTruthy();
+  });
+
+  test("keeps other OpenCode models on /chat/completions", async () => {
+    const calls: ProbeCall[] = [];
+    const result = await testInferenceConnection(
+      {
+        provider: "opencode",
+        auth: { type: "none" },
+        baseUrl: "https://opencode.ai/zen/v1",
+        models: [{ id: "mimo-v2.5-free" }],
+      },
+      stubFetch(200, calls),
+    );
+
+    expect(result?.resolved_url).toBe(
+      "https://opencode.ai/zen/v1/chat/completions",
+    );
+    expect(calls[0].body).toMatchObject({
+      model: "mimo-v2.5-free",
+      max_tokens: 1,
+    });
+  });
+
   test("does not send OpenCode headers to other providers", async () => {
     const calls: ProbeCall[] = [];
     await testInferenceConnection(CONNECTION, stubFetch(200, calls));

package/src/providers/inference/endpoint-probe.ts

@@ -10,7 +10,10 @@
 import { z } from "zod";
 
 import { getLogger } from "../../util/logger.js";
-import { resolveOpenCodeRequestHeaders } from "../opencode/client.js";
+import {
+  OPENCODE_RESPONSES_ONLY_MODELS,
+  resolveOpenCodeRequestHeaders,
+} from "../opencode/client.js";
 import type { Auth, ConnectionModel } from "./auth.js";
 import { resolveAuth } from "./resolve-auth.js";
 
@@ -46,10 +49,12 @@ function hintForStatus(status: number): string {
 }
 
 /**
- * Probe a connection's custom endpoint with a minimal chat-completions
- * request (`max_tokens: 1`). Returns `null` when there is nothing to probe:
- * no custom base URL, no model id to send, or auth that cannot be resolved
- * (a missing credential surfaces through its own error path).
+ * Probe a connection's custom endpoint with a minimal request on the wire
+ * its first model is served over: chat completions (`max_tokens: 1`), or
+ * the Responses API for OpenCode's responses-only models, which answer
+ * `/chat/completions` with HTTP 500. Returns `null` when there is nothing
+ * to probe: no custom base URL, no model id to send, or auth that cannot be
+ * resolved (a missing credential surfaces through its own error path).
  */
 export async function testInferenceConnection(
   connection: {
@@ -78,7 +83,12 @@ export async function testInferenceConnection(
   const providerHeaders =
     connection.provider === "opencode" ? resolveOpenCodeRequestHeaders() : {};
 
-  const url = `${connection.baseUrl.replace(/\/+$/, "")}/chat/completions`;
+  const useResponses =
+    connection.provider === "opencode" &&
+    OPENCODE_RESPONSES_ONLY_MODELS.has(model);
+  const url = `${connection.baseUrl.replace(/\/+$/, "")}${
+    useResponses ? "/responses" : "/chat/completions"
+  }`;
   try {
     const res = await fetchImpl(url, {
       method: "POST",
@@ -87,12 +97,17 @@ export async function testInferenceConnection(
         ...providerHeaders,
         "Content-Type": "application/json",
       },
-      body: JSON.stringify({
-        model,
-        messages: [{ role: "user", content: "ping" }],
-        max_tokens: 1,
-        stream: false,
-      }),
+      body: JSON.stringify(
+        useResponses
+          ? // The Responses API rejects output budgets below 16 tokens.
+            { model, input: "ping", max_output_tokens: 16, stream: false }
+          : {
+              model,
+              messages: [{ role: "user", content: "ping" }],
+              max_tokens: 1,
+              stream: false,
+            },
+      ),
       signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
     });
     void res.body?.cancel();

package/src/providers/openai/responses-provider.ts

@@ -109,7 +109,9 @@ function mapResponsesReasoningEffort(
     return "none";
   }
   const clamped = clampReasoningEffort(raw, effortCeilingForModel(model));
-  return supported ? snapReasoningEffortToSupported(clamped, supported) : clamped;
+  return supported
+    ? snapReasoningEffortToSupported(clamped, supported)
+    : clamped;
 }
 
 /** Values accepted by the Responses API `text.verbosity` parameter. */
@@ -280,7 +282,11 @@ export class OpenAIResponsesProvider implements Provider {
     const effort = configObj?.effort as string | undefined;
     const verbosity = configObj?.verbosity as string | undefined;
     const usageAttributionHeaders = configObj?.usageAttributionHeaders as
-      Record<string, string> | undefined;
+      | Record<string, string>
+      | undefined;
+    const perRequestHeaders = configObj?.requestHeaders as
+      | Record<string, string>
+      | undefined;
     const disableCache = configObj?.disableCache === true;
     const disableTurnStartCache = configObj?.disableTurnStartCache === true;
     const promptCacheKey =
@@ -463,6 +469,7 @@ export class OpenAIResponsesProvider implements Provider {
         const requestHeaders = {
           ...this.requestHeaders,
           ...(usageAttributionHeaders ?? {}),
+          ...(perRequestHeaders ?? {}),
         };
         const stream = await responsesApi.create(
           { ...params, stream: true },