@vellumai/assistant 0.8.4 → 0.8.5

package/src/runtime/routes/plugins-routes.ts

@@ -0,0 +1,337 @@
+/**
+ * Route handlers for the assistant plugins surface.
+ *
+ * GET    /v1/plugins         — list installed plugins under `<workspaceDir>/plugins/`.
+ * GET    /v1/plugins/search  — search the canonical GitHub catalog of installable plugins.
+ * DELETE /v1/plugins/:name   — uninstall a plugin from `<workspaceDir>/plugins/<name>/`.
+ *
+ * The read-only routes are projections over the same library functions
+ * the CLI uses (`assistant plugins list`, `assistant plugins search`).
+ * The DELETE route is symmetric to `assistant plugins uninstall` and
+ * delegates to the same `uninstallPlugin` lib function. CLI / daemon /
+ * web stay aligned on what an installed or available plugin looks like.
+ *
+ * Install is intentionally not exposed here. The CLI remains the
+ * install surface because installation fetches from GitHub, applies
+ * sanitization, and writes to disk — a heavier flow than a single
+ * JSON request justifies right now.
+ *
+ * # Policy gating
+ *
+ * Every route declares `policyKey: "plugins"` + `requirePolicyEnforcement:
+ * true`. The HTTP router enforces via `enforcePolicy()` against the
+ * `plugins:GET` / `plugins/search:GET` / `plugins:DELETE` registry
+ * entries in `runtime/auth/route-policy.ts`. The IPC adapter exposes
+ * the same policies to the gateway IPC proxy, whose own policy table
+ * (`gateway/src/auth/ipc-route-policy.ts`) holds the matching entries
+ * for `plugins_list` / `plugins_search` / `plugins_uninstall`. Reads
+ * require `settings.read`; uninstall requires `settings.write`.
+ */
+
+import { z } from "zod";
+
+import { InvalidPluginNameError } from "../../cli/lib/install-from-github.js";
+import {
+  type InstalledPluginInfo,
+  listInstalledPlugins,
+} from "../../cli/lib/list-installed-plugins.js";
+import {
+  InvalidSearchPatternError,
+  type PluginSearchMatch,
+  searchPlugins,
+} from "../../cli/lib/search-plugins.js";
+import {
+  PluginNotInstalledError,
+  uninstallPlugin,
+} from "../../cli/lib/uninstall-plugin.js";
+import {
+  BadRequestError,
+  InternalError,
+  NotFoundError,
+} from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const pluginInfoSchema = z.object({
+  id: z
+    .string()
+    .describe(
+      "Plugin's directory name (kebab-case). Matches `assistant plugins install <id>`.",
+    ),
+  name: z.string().describe("Display name. Equal to `id` today."),
+  description: z
+    .string()
+    .nullable()
+    .describe("From `package.json#description`; `null` when unknown."),
+  version: z
+    .string()
+    .nullable()
+    .describe("From `package.json#version`; `null` when unknown."),
+  path: z
+    .string()
+    .optional()
+    .describe("Absolute path to the plugin directory on the assistant host."),
+  issues: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Non-fatal issues with this entry (missing `package.json`, malformed JSON, ...). Omitted when clean.",
+    ),
+});
+
+const pluginsListResponseSchema = z.object({
+  plugins: z.array(pluginInfoSchema),
+});
+
+const pluginSearchMatchSchema = z.object({
+  name: z
+    .string()
+    .describe(
+      "Directory name under `experimental/plugins/`. Matches `assistant plugins install <name>`.",
+    ),
+  path: z
+    .string()
+    .describe(
+      "Repo-relative path of the match (e.g. `experimental/plugins/<name>`).",
+    ),
+});
+
+const pluginsSearchResponseSchema = z.object({
+  query: z
+    .string()
+    .describe("Echo of the requested query (ECMAScript regex source)."),
+  ref: z.string().describe("Git ref the catalog was listed at."),
+  matches: z
+    .array(pluginSearchMatchSchema)
+    .describe("Directory matches, sorted alphabetically by name."),
+});
+
+const pluginUninstallResponseSchema = z.object({
+  name: z
+    .string()
+    .describe(
+      "Directory name that was removed. Echoes the request's `:name` path parameter after sanitization.",
+    ),
+  target: z
+    .string()
+    .describe(
+      "Absolute path that was removed on the assistant host. Useful for audit logs and confirmation toasts.",
+    ),
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+interface PluginView {
+  id: string;
+  name: string;
+  description: string | null;
+  version: string | null;
+  path: string;
+  issues?: string[];
+}
+
+function projectPlugin(entry: InstalledPluginInfo): PluginView {
+  // `id` and `name` both track the directory name. `package.json#name` can
+  // be scoped (e.g. `@vendor/plugin-name`) which is fine for npm but not
+  // what the CLI uses to install — so we don't surface it as `name`.
+  const view: PluginView = {
+    id: entry.name,
+    name: entry.name,
+    description: entry.packageJson?.description ?? null,
+    version: entry.packageJson?.version ?? null,
+    path: entry.target,
+  };
+  if (entry.issues.length > 0) {
+    view.issues = [...entry.issues];
+  }
+  return view;
+}
+
+function matchesQuery(plugin: PluginView, needle: string): boolean {
+  const q = needle.toLowerCase();
+  if (plugin.id.toLowerCase().includes(q)) return true;
+  if (plugin.name.toLowerCase().includes(q)) return true;
+  if (plugin.description && plugin.description.toLowerCase().includes(q)) {
+    return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// Handler — list installed
+// ---------------------------------------------------------------------------
+
+function handleListPlugins({
+  queryParams = {},
+}: RouteHandlerArgs): { plugins: PluginView[] } {
+  const q = queryParams.q?.trim();
+  const installed = listInstalledPlugins();
+  const projected = installed.map(projectPlugin);
+  const filtered = q ? projected.filter((p) => matchesQuery(p, q)) : projected;
+  return { plugins: filtered };
+}
+
+// ---------------------------------------------------------------------------
+// Handler — search catalog
+// ---------------------------------------------------------------------------
+
+interface PluginsSearchResponse {
+  query: string;
+  ref: string;
+  matches: PluginSearchMatch[];
+}
+
+async function handleSearchPlugins({
+  queryParams = {},
+}: RouteHandlerArgs): Promise<PluginsSearchResponse> {
+  // Empty string is a legitimate "match everything" query per the lib's
+  // contract — accept it without forcing the caller to pick a sentinel.
+  const query = queryParams.q ?? "";
+  const ref = queryParams.ref?.trim() || undefined;
+
+  try {
+    const result = await searchPlugins(
+      { query, ref },
+      { fetch: globalThis.fetch.bind(globalThis) },
+    );
+    // Re-pack `readonly` lib types into mutable copies so the route
+    // serializer's `Record<string, unknown>` contract holds. The wire
+    // shape is identical.
+    return {
+      query: result.query,
+      ref: result.ref,
+      matches: result.matches.map((m) => ({ name: m.name, path: m.path })),
+    };
+  } catch (err) {
+    if (err instanceof InvalidSearchPatternError) {
+      throw new BadRequestError(err.message);
+    }
+    throw new InternalError(
+      err instanceof Error ? err.message : "plugin catalog search failed",
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Handler — uninstall
+// ---------------------------------------------------------------------------
+
+interface PluginUninstallResponse {
+  name: string;
+  target: string;
+}
+
+function handleUninstallPlugin({
+  pathParams = {},
+}: RouteHandlerArgs): PluginUninstallResponse {
+  // The HTTP router has already URL-decoded `:name` for us; pass it
+  // through verbatim — `uninstallPlugin` runs the same
+  // `sanitizePluginName` check the CLI uses, so attacker-supplied
+  // `../escape` style names get rejected before `rmSync` is reached.
+  const rawName = pathParams.name ?? "";
+
+  try {
+    const result = uninstallPlugin({ name: rawName });
+    return { name: result.name, target: result.target };
+  } catch (err) {
+    if (err instanceof InvalidPluginNameError) {
+      throw new BadRequestError(err.message);
+    }
+    if (err instanceof PluginNotInstalledError) {
+      throw new NotFoundError(err.message);
+    }
+    throw new InternalError(
+      err instanceof Error ? err.message : "plugin uninstall failed",
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "plugins_list",
+    endpoint: "plugins",
+    method: "GET",
+    policyKey: "plugins",
+    requirePolicyEnforcement: true,
+    summary: "List installed plugins",
+    description:
+      "Return one entry per directory under `<workspaceDir>/plugins/`, sorted alphabetically. Matches the CLI's `assistant plugins list`. Supports `?q=<text>` for case-insensitive substring matching across plugin id, name, and description.",
+    tags: ["plugins"],
+    queryParams: [
+      {
+        name: "q",
+        schema: { type: "string" },
+        description:
+          "Optional substring filter applied to plugin id, name, and description.",
+      },
+    ],
+    responseBody: pluginsListResponseSchema,
+    handler: handleListPlugins,
+  },
+  {
+    operationId: "plugins_search",
+    endpoint: "plugins/search",
+    method: "GET",
+    policyKey: "plugins",
+    requirePolicyEnforcement: true,
+    summary: "Search the plugin catalog",
+    description:
+      "List installable plugins from the canonical `vellum-ai/vellum-assistant` catalog at `experimental/plugins/`. The query is an ECMAScript regex matched case-insensitively against the directory name (e.g. `memory`, `^simple`). Empty query returns every entry. Mirrors the CLI's `assistant plugins search`.",
+    tags: ["plugins"],
+    queryParams: [
+      {
+        name: "q",
+        schema: { type: "string" },
+        description:
+          "ECMAScript regex pattern matched case-insensitively against catalog directory names. Empty/missing matches everything.",
+      },
+      {
+        name: "ref",
+        schema: { type: "string" },
+        description:
+          "Optional git ref to list the catalog at. Defaults to the CLI's `DEFAULT_PLUGIN_REF` (typically `main`).",
+      },
+    ],
+    responseBody: pluginsSearchResponseSchema,
+    handler: handleSearchPlugins,
+  },
+  {
+    operationId: "plugins_uninstall",
+    endpoint: "plugins/:name",
+    method: "DELETE",
+    policyKey: "plugins",
+    requirePolicyEnforcement: true,
+    summary: "Uninstall a plugin",
+    description:
+      "Remove the directory at `<workspaceDir>/plugins/<name>/`. Mirrors the CLI's `assistant plugins uninstall <name>` (without the interactive confirmation — the API caller is responsible for any prompt). The plugin name is sanitized by the same regex the CLI uses; `../escape`-style values, hidden names, and absolute paths return 400. Missing plugins return 404. The assistant must be restarted to drop the plugin from the running runtime.",
+    tags: ["plugins"],
+    pathParams: [
+      {
+        name: "name",
+        type: "string",
+        description:
+          "Directory name under `<workspaceDir>/plugins/`. Must match the kebab-case name accepted by `assistant plugins install`.",
+      },
+    ],
+    responseBody: pluginUninstallResponseSchema,
+    additionalResponses: {
+      "400": {
+        description:
+          "The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).",
+      },
+      "404": {
+        description: "No plugin directory exists with the given name.",
+      },
+    },
+    handler: handleUninstallPlugin,
+  },
+];

package/src/runtime/routes/rename-conversation-routes.ts

@@ -31,7 +31,7 @@ export const ROUTES: RouteDefinition[] = [
     description: "Update the display title of a conversation.",
     tags: ["conversations"],
     requestBody: RenameConversationBody,
-    handler: ({ body }) => {
+    handler: ({ body, headers }) => {
       const parsed = RenameConversationBody.safeParse(body);
       if (!parsed.success) {
         throw new BadRequestError("conversationId and title are required");
@@ -46,7 +46,11 @@ export const ROUTES: RouteDefinition[] = [
 
       updateConversationTitle(conversationId, title, 0);
 
-      publishConversationTitleChanged(conversationId, title);
+      publishConversationTitleChanged(
+        conversationId,
+        title,
+        headers?.["x-vellum-client-id"]?.trim() || undefined,
+      );
 
       return { ok: true };
     },

package/src/runtime/routes/secret-routes.ts

@@ -27,6 +27,7 @@ import { clearEmbeddingBackendCache } from "../../memory/embedding-backend.js";
 import { syncManualTokenConnection } from "../../oauth/manual-token-connection.js";
 import { validateAnthropicApiKey } from "../../providers/anthropic/client.js";
 import { validateGeminiApiKey } from "../../providers/gemini/client.js";
+import { validateMinimaxApiKey } from "../../providers/minimax/client.js";
 import { validateOpenAIApiKey } from "../../providers/openai/client.js";
 import { initializeProviders } from "../../providers/registry.js";
 import { credentialKey } from "../../security/credential-key.js";
@@ -195,9 +196,21 @@ async function handleAddSecret({ body }: RouteHandlerArgs) {
           );
           return { success: false, error: validation.reason };
         }
+      } else if (name === "minimax") {
+        const validation = await validateMinimaxApiKey(value);
+        if (!validation.valid) {
+          log.warn(
+            { provider: name, reason: validation.reason },
+            "API key validation failed",
+          );
+          return { success: false, error: validation.reason };
+        }
       }
 
-      const stored = await setSecureKeyAsync(credentialKey(name, "api_key"), value);
+      const stored = await setSecureKeyAsync(
+        credentialKey(name, "api_key"),
+        value,
+      );
       if (!stored) {
         throw new InternalError(
           `Failed to store API key in secure storage (backend: ${getActiveBackendName()})`,
@@ -339,7 +352,9 @@ async function handleReadSecret({ body }: RouteHandlerArgs) {
 
   try {
     let accountKey: string;
-    let prefetchedResult: Awaited<ReturnType<typeof getSecureKeyResultAsync>> | undefined;
+    let prefetchedResult:
+      | Awaited<ReturnType<typeof getSecureKeyResultAsync>>
+      | undefined;
 
     if (type === "api_key") {
       if (
@@ -350,7 +365,9 @@ async function handleReadSecret({ body }: RouteHandlerArgs) {
         );
       }
       // Check credential namespace first; fall back to bare key only if not found and store is reachable.
-      const credResult = await getSecureKeyResultAsync(credentialKey(name, "api_key"));
+      const credResult = await getSecureKeyResultAsync(
+        credentialKey(name, "api_key"),
+      );
       if (credResult.value === undefined && !credResult.unreachable) {
         accountKey = name;
       } else {
@@ -373,7 +390,8 @@ async function handleReadSecret({ body }: RouteHandlerArgs) {
       );
     }
 
-    const { value, unreachable } = prefetchedResult ?? await getSecureKeyResultAsync(accountKey);
+    const { value, unreachable } =
+      prefetchedResult ?? (await getSecureKeyResultAsync(accountKey));
     if (value === undefined) {
       return { found: false, unreachable };
     }
@@ -543,7 +561,9 @@ async function handleListSecrets() {
         const field = rest.slice(slashIdx + 1);
         if (
           field === "api_key" &&
-          API_KEY_PROVIDERS.includes(service as (typeof API_KEY_PROVIDERS)[number])
+          API_KEY_PROVIDERS.includes(
+            service as (typeof API_KEY_PROVIDERS)[number],
+          )
         ) {
           return [service];
         }

package/src/runtime/routes/settings-routes.ts

@@ -78,7 +78,10 @@ function handleVoiceConfigUpdate({ body = {} }: RouteHandlerArgs) {
 // Avatar generation
 // ---------------------------------------------------------------------------
 
-async function handleGenerateAvatar({ body = {} }: RouteHandlerArgs) {
+async function handleGenerateAvatar({
+  body = {},
+  headers,
+}: RouteHandlerArgs) {
   const { description } = body as { description?: string };
   if (!description?.trim()) {
     throw new BadRequestError("Description is required.");
@@ -95,7 +98,7 @@ async function handleGenerateAvatar({ body = {} }: RouteHandlerArgs) {
 
     const avatarPath = getAvatarImagePath();
 
-    publishAvatarChanged();
+    publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
 
     return { ok: true, avatarPath };
   } catch (err) {
@@ -381,14 +384,7 @@ function handleToolNamesList() {
   };
   const schemas: Record<string, SchemaShape> = {};
 
-  const rawDefs: ToolDefinition[] = [];
-  for (const tool of tools) {
-    try {
-      rawDefs.push(tool.getDefinition());
-    } catch {
-      // Skip tools whose definitions can't be resolved
-    }
-  }
+  const rawDefs: ToolDefinition[] = tools;
 
   const transformedDefs = injectActivityField(rawDefs, ACTIVITY_SKIP_SET);
   for (const def of transformedDefs) {
@@ -444,7 +440,12 @@ async function handleToolPermissionSimulate({ body = {} }: RouteHandlerArgs) {
 
   try {
     const manifestOverride = resolveManifestOverride(toolName);
-    const executionTarget = resolveExecutionTarget(toolName, manifestOverride);
+    // Permission Simulator path: registered tool wins, then explicit
+    // manifest override, then the standard inference rules.
+    const executionTarget =
+      getTool(toolName)?.executionTarget ??
+      manifestOverride?.execution_target ??
+      resolveExecutionTarget({ name: toolName });
     const executionContext =
       isInteractive === false ? "headless" : "conversation";
     const policyContext = { executionTarget, executionContext } as const;

package/src/runtime/routes/slack-channel-routes.ts

@@ -93,6 +93,7 @@ function reasonForSlackError(err: unknown): ResolveReason {
 
 async function handleSlackChannelNameResolve({
   pathParams = {},
+  headers,
 }: RouteHandlerArgs): Promise<SlackChannelResolveResponse> {
   const conversationId = pathParams.conversationId?.trim();
   if (!conversationId) {
@@ -152,10 +153,10 @@ async function handleSlackChannelNameResolve({
   }
 
   updateExternalChatName(conversationId, channelName);
-  await publishSyncInvalidation([
-    SYNC_TAGS.conversationsList,
-    conversationMetadataSyncTag(conversationId),
-  ]);
+  await publishSyncInvalidation(
+    [SYNC_TAGS.conversationsList, conversationMetadataSyncTag(conversationId)],
+    headers?.["x-vellum-client-id"]?.trim() || undefined,
+  );
 
   return {
     channelId,

package/src/runtime/routes/workspace-routes.ts

@@ -59,9 +59,12 @@ function isSoundsWorkspacePath(path: string): boolean {
   );
 }
 
-function publishSoundsConfigUpdatedForPaths(paths: string[]): void {
+function publishSoundsConfigUpdatedForPaths(
+  paths: string[],
+  originClientId?: string,
+): void {
   if (paths.some(isSoundsWorkspacePath)) {
-    publishSoundsConfigUpdated();
+    publishSoundsConfigUpdated(originClientId);
   }
 }
 
@@ -263,7 +266,7 @@ function handleWorkspaceFileContent({
 // POST /v1/workspace/write — create or overwrite a file
 // ---------------------------------------------------------------------------
 
-function handleWorkspaceWrite({ body }: RouteHandlerArgs) {
+function handleWorkspaceWrite({ body, headers }: RouteHandlerArgs) {
   const path = body?.path as string | undefined;
   const content = body?.content as string | undefined;
   const encoding = body?.encoding as string | undefined;
@@ -292,7 +295,10 @@ function handleWorkspaceWrite({ body }: RouteHandlerArgs) {
 
   mkdirSync(dirname(resolved), { recursive: true });
   writeFileSync(resolved, buffer);
-  publishSoundsConfigUpdatedForPaths([path]);
+  publishSoundsConfigUpdatedForPaths(
+    [path],
+    headers?.["x-vellum-client-id"]?.trim() || undefined,
+  );
 
   return { path, size: buffer.byteLength };
 }
@@ -301,7 +307,7 @@ function handleWorkspaceWrite({ body }: RouteHandlerArgs) {
 // POST /v1/workspace/mkdir — create directories
 // ---------------------------------------------------------------------------
 
-function handleWorkspaceMkdir({ body }: RouteHandlerArgs) {
+function handleWorkspaceMkdir({ body, headers }: RouteHandlerArgs) {
   const path = body?.path as string | undefined;
   if (!path) {
     throw new BadRequestError("path is required");
@@ -320,7 +326,10 @@ function handleWorkspaceMkdir({ body }: RouteHandlerArgs) {
   }
 
   mkdirSync(resolved, { recursive: true });
-  publishSoundsConfigUpdatedForPaths([path]);
+  publishSoundsConfigUpdatedForPaths(
+    [path],
+    headers?.["x-vellum-client-id"]?.trim() || undefined,
+  );
   return { path };
 }
 
@@ -328,7 +337,7 @@ function handleWorkspaceMkdir({ body }: RouteHandlerArgs) {
 // POST /v1/workspace/rename — rename/move files and directories
 // ---------------------------------------------------------------------------
 
-function handleWorkspaceRename({ body }: RouteHandlerArgs) {
+function handleWorkspaceRename({ body, headers }: RouteHandlerArgs) {
   const oldPath = body?.oldPath as string | undefined;
   const newPath = body?.newPath as string | undefined;
   if (!oldPath || !newPath) {
@@ -360,7 +369,10 @@ function handleWorkspaceRename({ body }: RouteHandlerArgs) {
 
   mkdirSync(dirname(resolvedNew), { recursive: true });
   renameSync(resolvedOld, resolvedNew);
-  publishSoundsConfigUpdatedForPaths([oldPath, newPath]);
+  publishSoundsConfigUpdatedForPaths(
+    [oldPath, newPath],
+    headers?.["x-vellum-client-id"]?.trim() || undefined,
+  );
   return { oldPath, newPath };
 }
 
@@ -368,7 +380,7 @@ function handleWorkspaceRename({ body }: RouteHandlerArgs) {
 // POST /v1/workspace/delete — delete files and directories
 // ---------------------------------------------------------------------------
 
-function handleWorkspaceDelete({ body }: RouteHandlerArgs) {
+function handleWorkspaceDelete({ body, headers }: RouteHandlerArgs) {
   const path = body?.path as string | undefined;
   if (!path) {
     throw new BadRequestError("path is required");
@@ -388,7 +400,10 @@ function handleWorkspaceDelete({ body }: RouteHandlerArgs) {
   }
 
   rmSync(resolved, { recursive: true, force: true });
-  publishSoundsConfigUpdatedForPaths([path]);
+  publishSoundsConfigUpdatedForPaths(
+    [path],
+    headers?.["x-vellum-client-id"]?.trim() || undefined,
+  );
   return { success: true };
 }