@vellumai/assistant 0.8.3 → 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/question-routes.ts

@@ -148,7 +148,10 @@ function handleQuestionResponse({ body }: RouteHandlerArgs) {
 
   // Validation passed — deregister now to clear the prompter timer, then
   // hand the result to the prompter's caller via rpcResolve.
-  pendingInteractions.resolve(requestId);
+  pendingInteractions.resolve(
+    requestId,
+    response.kind === "close" ? "cancelled" : "answered",
+  );
 
   log.info(
     {

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/sanity-routes.ts

@@ -0,0 +1,159 @@
+/**
+ * Route definitions for Sanity CMS connection management.
+ *
+ * POST /v1/sanity/discover — project/dataset discovery using the stored API token
+ * POST /v1/sanity/connect  — finalise connection by writing the sidecar file
+ *
+ * Both routes use policyKey: "secrets" — they read credentials and write
+ * workspace data, the same policy tier as the existing secrets routes.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { z } from "zod";
+
+import { credentialKey } from "../../security/credential-key.js";
+import { getSecureKeyAsync } from "../../security/secure-keys.js";
+import { getWorkspaceDir } from "../../util/platform.js";
+import { BadRequestError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+async function getStoredToken(): Promise<string | undefined> {
+  return getSecureKeyAsync(credentialKey("sanity", "api_token"));
+}
+
+function writeSidecar(relPath: string, data: Record<string, unknown>): void {
+  const workspaceDir = getWorkspaceDir();
+  const absPath = join(workspaceDir, relPath);
+  mkdirSync(dirname(absPath), { recursive: true });
+  writeFileSync(absPath, JSON.stringify(data, null, 2), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/sanity/discover
+// ---------------------------------------------------------------------------
+
+async function handleDiscover(
+  args: RouteHandlerArgs,
+): Promise<Record<string, unknown>> {
+  const token = await getStoredToken();
+  if (!token) {
+    return { error: "no_token" };
+  }
+
+  const projectId =
+    typeof args.body?.projectId === "string" ? args.body.projectId : undefined;
+
+  if (!projectId) {
+    // List all projects this token has access to
+    const response = await fetch("https://api.sanity.io/v2021-06-07/projects", {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (response.status === 401 || response.status === 403) {
+      return { error: "token_scope_limited" };
+    }
+
+    if (!response.ok) {
+      return { error: "discovery_failed" };
+    }
+
+    const raw = (await response.json()) as Array<{
+      id: string;
+      displayName?: string;
+    }>;
+    const projects = raw.map((p) => ({
+      id: p.id,
+      displayName: p.displayName ?? p.id,
+    }));
+    return { projects };
+  }
+
+  // List datasets for a specific project
+  const response = await fetch(
+    `https://api.sanity.io/v2021-06-07/projects/${projectId}/datasets`,
+    {
+      headers: { Authorization: `Bearer ${token}` },
+    },
+  );
+
+  if (response.status === 401 || response.status === 403) {
+    return { error: "token_scope_limited" };
+  }
+
+  if (!response.ok) {
+    return { error: "discovery_failed" };
+  }
+
+  const raw = (await response.json()) as Array<{ name: string }>;
+  const datasets = raw.map((d) => d.name);
+  return { projectId, datasets };
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/sanity/connect
+// ---------------------------------------------------------------------------
+
+async function handleConnect(
+  args: RouteHandlerArgs,
+): Promise<Record<string, unknown>> {
+  const token = await getStoredToken();
+  if (!token) {
+    throw new BadRequestError(
+      "Sanity API token not found. Store it first via POST /v1/secrets.",
+    );
+  }
+
+  const projectId =
+    typeof args.body?.projectId === "string" ? args.body.projectId.trim() : "";
+  const dataset =
+    typeof args.body?.dataset === "string" ? args.body.dataset.trim() : "";
+
+  if (!projectId) {
+    throw new BadRequestError(
+      "projectId is required and must be a non-empty string",
+    );
+  }
+  if (!dataset) {
+    throw new BadRequestError(
+      "dataset is required and must be a non-empty string",
+    );
+  }
+
+  writeSidecar("data/sanity-connection.json", { projectId, dataset });
+
+  return { ok: true };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "sanity_discover",
+    endpoint: "sanity/discover",
+    method: "POST",
+    policyKey: "secrets",
+    summary: "Discover Sanity projects and datasets using the stored API token",
+    requestBody: z.object({ projectId: z.string().optional() }).optional(),
+    handler: handleDiscover,
+  },
+  {
+    operationId: "sanity_connect",
+    endpoint: "sanity/connect",
+    method: "POST",
+    policyKey: "secrets",
+    summary: "Finalise Sanity connection and write sidecar file",
+    requestBody: z.object({
+      projectId: z.string(),
+      dataset: z.string(),
+    }),
+    handler: handleConnect,
+  },
+];

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;