@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091853.fbaa2ae

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

@@ -1,51 +1,66 @@
 /**
  * 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>/`.
+ * GET    /v1/plugins          — list installed plugins under `<workspaceDir>/plugins/`.
+ * GET    /v1/plugins/search   — search the canonical GitHub catalog of installable plugins.
+ * GET    /v1/plugins/:name    — resolve a single plugin's detail view (metadata + README).
+ * POST   /v1/plugins/install  — install a plugin by name from the canonical source.
+ * 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.
+ * The install / uninstall routes are symmetric to `assistant plugins
+ * install` / `uninstall` and delegate to the same `installPlugin` /
+ * `uninstallPlugin` lib functions. CLI / daemon / web stay aligned on
+ * what an installed or available plugin looks like — mirroring the
+ * skills surface, which already exposes detail + install over HTTP.
  *
  * # 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 same registry is the
- * source of truth for the IPC path too: the IPC route adapter resolves
- * each route's policy and ships it in `get_route_schema`, which the
- * gateway's IPC proxy reads from its in-memory cache. Reads require
- * `settings.read`; uninstall requires `settings.write`.
+ * Reads require `settings.read`; install and uninstall require
+ * `settings.write`. The HTTP router enforces the per-route `policy`
+ * block below, and the IPC route adapter ships the same policy in
+ * `get_route_schema` so the gateway's IPC proxy stays in sync.
  */
 
 import { z } from "zod";
 
-import { InvalidPluginNameError } from "../../cli/lib/install-from-github.js";
+import {
+  DEFAULT_PLUGIN_REF,
+  installPlugin,
+  InvalidPluginNameError,
+  PluginAlreadyInstalledError,
+  PluginNotFoundError,
+  PluginSourceUnavailableError,
+} from "../../cli/lib/install-from-github.js";
 import {
   type InstalledPluginInfo,
   listInstalledPlugins,
 } from "../../cli/lib/list-installed-plugins.js";
+import { getPluginCatalog } from "../../cli/lib/plugin-catalog-cache.js";
+import {
+  getPluginDetails,
+  PluginDetailsNotFoundError,
+} from "../../cli/lib/plugin-details.js";
 import {
+  assertValidSearchPattern,
+  filterPluginCatalog,
   InvalidSearchPatternError,
+  PluginCatalogUnavailableError,
   type PluginSearchMatch,
-  searchPlugins,
 } from "../../cli/lib/search-plugins.js";
 import {
   PluginNotInstalledError,
   uninstallPlugin,
 } from "../../cli/lib/uninstall-plugin.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
-import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
+import {
+  BadRequestError,
+  ConflictError,
+  InternalError,
+  NotFoundError,
+  ServiceUnavailableError,
+} from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -83,17 +98,43 @@ const pluginsListResponseSchema = z.object({
   plugins: z.array(pluginInfoSchema),
 });
 
+const pluginMatchSourceSchema = z
+  .discriminatedUnion("kind", [
+    z.object({
+      kind: z.literal("first-party"),
+    }),
+    z.object({
+      kind: z.literal("github"),
+      repo: z
+        .string()
+        .describe("`owner/repo` of the external plugin repository."),
+      path: z
+        .string()
+        .optional()
+        .describe(
+          "Directory within the repo, when the plugin is not at the root.",
+        ),
+      ref: z.string().describe("Pinned git ref the plugin is fetched from."),
+    }),
+  ])
+  .describe(
+    "Origin of the match: a first-party in-repo plugin or a whitelisted external one.",
+  );
+
 const pluginSearchMatchSchema = z.object({
   name: z
     .string()
-    .describe(
-      "Directory name under `experimental/plugins/`. Matches `assistant plugins install <name>`.",
-    ),
+    .describe("Install name. Matches `assistant plugins install <name>`."),
   path: z
     .string()
     .describe(
-      "Repo-relative path of the match (e.g. `experimental/plugins/<name>`).",
+      "Human-readable origin: a repo-relative path (`experimental/plugins/<name>`) for first-party plugins or a `github:owner/repo@ref` locator for external ones.",
     ),
+  description: z
+    .string()
+    .optional()
+    .describe("Short description, when known (external entries only today)."),
+  source: pluginMatchSourceSchema,
 });
 
 const pluginsSearchResponseSchema = z.object({
@@ -119,6 +160,66 @@ const pluginUninstallResponseSchema = z.object({
     ),
 });
 
+const pluginDetailsResponseSchema = z.object({
+  name: z
+    .string()
+    .describe("Install name. Matches `assistant plugins install <name>`."),
+  installed: z
+    .boolean()
+    .describe(
+      "Whether a copy is materialized under `<workspaceDir>/plugins/<name>/`.",
+    ),
+  description: z
+    .string()
+    .nullable()
+    .describe(
+      "Short description, best-effort across disk, manifest, and repo.",
+    ),
+  homepage: z.string().nullable().describe("Project homepage URL, when known."),
+  license: z
+    .string()
+    .nullable()
+    .describe("SPDX license expression, when known."),
+  version: z
+    .string()
+    .nullable()
+    .describe(
+      "Resolved version (installed copy first, then repo `package.json`).",
+    ),
+  source: pluginMatchSourceSchema,
+  readme: z
+    .string()
+    .nullable()
+    .describe("README markdown, or null when the plugin ships none."),
+  ref: z
+    .string()
+    .describe("Git ref the catalog metadata / README were resolved at."),
+});
+
+const pluginInstallRequestSchema = z.object({
+  name: z
+    .string()
+    .describe(
+      "Install name to resolve against the catalog (first-party directory or marketplace entry).",
+    ),
+  force: z
+    .boolean()
+    .optional()
+    .describe("Overwrite an existing install in place. Defaults to false."),
+});
+
+const pluginInstallResponseSchema = z.object({
+  ok: z.literal(true),
+  name: z.string().describe("Install name that was materialized."),
+  target: z
+    .string()
+    .describe("Absolute path the plugin was materialized into on the host."),
+  fileCount: z
+    .number()
+    .describe("Number of files written for the installed plugin."),
+  ref: z.string().describe("Git ref the plugin was fetched from."),
+});
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -149,6 +250,41 @@ function projectPlugin(entry: InstalledPluginInfo): PluginView {
   return view;
 }
 
+/** Wire shape for a catalog match. Mirrors {@link pluginSearchMatchSchema}. */
+interface PluginMatchView {
+  name: string;
+  path: string;
+  description?: string;
+  source:
+    | { kind: "first-party" }
+    | { kind: "github"; repo: string; path?: string; ref: string };
+}
+
+/**
+ * Re-pack a `readonly` lib match into a mutable wire object so the route
+ * serializer's `Record<string, unknown>` contract holds. The wire shape is
+ * identical to {@link PluginSearchMatch}.
+ */
+function projectMatch(m: PluginSearchMatch): PluginMatchView {
+  const view: PluginMatchView = {
+    name: m.name,
+    path: m.path,
+    source:
+      m.source.kind === "github"
+        ? {
+            kind: "github",
+            repo: m.source.repo,
+            ref: m.source.ref,
+            ...(m.source.path !== undefined ? { path: m.source.path } : {}),
+          }
+        : { kind: "first-party" },
+  };
+  if (m.description !== undefined) {
+    view.description = m.description;
+  }
+  return view;
+}
+
 function matchesQuery(plugin: PluginView, needle: string): boolean {
   const q = needle.toLowerCase();
   if (plugin.id.toLowerCase().includes(q)) return true;
@@ -180,7 +316,7 @@ function handleListPlugins({ queryParams = {} }: RouteHandlerArgs): {
 interface PluginsSearchResponse {
   query: string;
   ref: string;
-  matches: PluginSearchMatch[];
+  matches: PluginMatchView[];
 }
 
 async function handleSearchPlugins({
@@ -189,25 +325,39 @@ async function handleSearchPlugins({
   // 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;
+  const ref = queryParams.ref?.trim() || DEFAULT_PLUGIN_REF;
 
   try {
-    const result = await searchPlugins(
-      { query, ref },
-      { fetch: globalThis.fetch.bind(globalThis) },
-    );
+    // Reject a malformed regex before any network I/O so a user typo is a
+    // cheap deterministic 400 — never a wasted GitHub request that could
+    // surface as 503 on a cold cache when upstream is rate-limited.
+    assertValidSearchPattern(query);
+    // The catalog is cached per ref (and served stale on upstream failure),
+    // so repeated searches don't re-hit GitHub's unauthenticated rate limit.
+    // Filtering by the query is an in-memory operation over that catalog.
+    const catalog = await getPluginCatalog(ref, {
+      fetch: globalThis.fetch.bind(globalThis),
+    });
+    const matches = filterPluginCatalog(catalog, query);
     // 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 })),
+      query,
+      ref: catalog.ref,
+      matches: matches.map(projectMatch),
     };
   } catch (err) {
     if (err instanceof InvalidSearchPatternError) {
       throw new BadRequestError(err.message);
     }
+    // A rate-limited or unavailable upstream (with no cache to fall back on)
+    // is transient and retryable — surface it as 503 rather than a
+    // misleading 500 so the client can show a "temporarily unavailable"
+    // state and retry later.
+    if (err instanceof PluginCatalogUnavailableError) {
+      throw new ServiceUnavailableError(err.message);
+    }
     throw new InternalError(
       err instanceof Error ? err.message : "plugin catalog search failed",
     );
@@ -248,6 +398,87 @@ function handleUninstallPlugin({
   }
 }
 
+// ---------------------------------------------------------------------------
+// Handler — detail view
+// ---------------------------------------------------------------------------
+
+async function handleGetPluginDetails({
+  pathParams = {},
+  queryParams = {},
+}: RouteHandlerArgs) {
+  const rawName = pathParams.name ?? "";
+  const ref = queryParams.ref?.trim() || undefined;
+
+  try {
+    return await getPluginDetails(
+      { name: rawName, ref },
+      { fetch: globalThis.fetch.bind(globalThis) },
+    );
+  } catch (err) {
+    if (err instanceof InvalidPluginNameError) {
+      throw new BadRequestError(err.message);
+    }
+    if (err instanceof PluginDetailsNotFoundError) {
+      throw new NotFoundError(err.message);
+    }
+    throw new InternalError(
+      err instanceof Error ? err.message : "plugin detail lookup failed",
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Handler — install
+// ---------------------------------------------------------------------------
+
+async function handleInstallPlugin({ body = {} }: RouteHandlerArgs) {
+  const name = typeof body.name === "string" ? body.name : "";
+  if (!name) {
+    throw new BadRequestError("`name` is required");
+  }
+  const force = typeof body.force === "boolean" ? body.force : undefined;
+
+  // The ref is pinned to the curated `DEFAULT_PLUGIN_REF` rather than taken
+  // from the request: a caller-supplied ref would let any `settings.write`
+  // principal install from an unreviewed revision (a PR branch, fork ref,
+  // ...) whose marketplace manifest or first-party plugin directory could
+  // carry attacker code that the loader then dynamically imports. Installs
+  // over HTTP therefore only ever resolve against the reviewed catalog on
+  // the default ref. Operators who need another ref use the local CLI's
+  // `assistant plugins install --ref`.
+  try {
+    const result = await installPlugin(
+      { name, ref: DEFAULT_PLUGIN_REF, force },
+      { fetch: globalThis.fetch.bind(globalThis) },
+    );
+    return {
+      ok: true as const,
+      name: result.name,
+      target: result.target,
+      fileCount: result.fileCount,
+      ref: result.ref,
+    };
+  } catch (err) {
+    if (err instanceof InvalidPluginNameError) {
+      throw new BadRequestError(err.message);
+    }
+    if (err instanceof PluginAlreadyInstalledError) {
+      throw new ConflictError(err.message);
+    }
+    if (err instanceof PluginNotFoundError) {
+      throw new NotFoundError(err.message);
+    }
+    // A rate-limited or otherwise temporarily-down GitHub source is
+    // retryable, so surface 503 rather than a misleading 500.
+    if (err instanceof PluginSourceUnavailableError) {
+      throw new ServiceUnavailableError(err.message);
+    }
+    throw new InternalError(
+      err instanceof Error ? err.message : "plugin install failed",
+    );
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -305,6 +536,77 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: pluginsSearchResponseSchema,
     handler: handleSearchPlugins,
   },
+  {
+    operationId: "plugins_install",
+    endpoint: "plugins/install",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Install a plugin",
+    description:
+      "Install a plugin by name from the canonical source — a whitelisted `experimental/plugins/marketplace.json` entry, else the first-party `experimental/plugins/<name>/` convention. Always resolves against the curated default git ref (no caller-supplied ref): installing from an unreviewed revision would bypass the marketplace/first-party curation boundary and let attacker-controlled code be loaded. Materializes the plugin under `<workspaceDir>/plugins/<name>/`; the assistant must be restarted to load it. Mirrors the CLI's `assistant plugins install <name>`. An already-installed name without `force` returns 409; a name that resolves to nothing returns 404. Sibling to `POST /v1/skills/install`.",
+    tags: ["plugins"],
+    requestBody: pluginInstallRequestSchema,
+    responseBody: pluginInstallResponseSchema,
+    additionalResponses: {
+      "400": {
+        description:
+          "The request body was missing `name` or the name failed sanitization.",
+      },
+      "404": {
+        description:
+          "No plugin resolves to the given name at the requested ref.",
+      },
+      "409": {
+        description:
+          "A plugin with the same name is already installed and `force` was not set.",
+      },
+    },
+    handler: handleInstallPlugin,
+  },
+  {
+    operationId: "plugins_get",
+    endpoint: "plugins/:name",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get a plugin's detail view",
+    description:
+      "Resolve a single plugin's tracked metadata (description, homepage, license, version, source) plus its README markdown. Unions the locally installed copy, the marketplace manifest, and the plugin's repository at the pinned ref — preferring the installed copy. Names that are neither installed nor present in the catalog return 404. Powers the web plugin detail page; mirrors `GET /v1/skills/:id`.",
+    tags: ["plugins"],
+    pathParams: [
+      {
+        name: "name",
+        type: "string",
+        description:
+          "Install name. Must match the kebab-case name accepted by `assistant plugins install`.",
+      },
+    ],
+    queryParams: [
+      {
+        name: "ref",
+        schema: { type: "string" },
+        description:
+          "Optional git ref to read catalog metadata / README at. Defaults to the CLI's `DEFAULT_PLUGIN_REF`.",
+      },
+    ],
+    responseBody: pluginDetailsResponseSchema,
+    additionalResponses: {
+      "400": {
+        description:
+          "The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).",
+      },
+      "404": {
+        description:
+          "No installed copy and no catalog entry claims the given name.",
+      },
+    },
+    handler: handleGetPluginDetails,
+  },
   {
     operationId: "plugins_uninstall",
     endpoint: "plugins/:name",

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

@@ -17,6 +17,7 @@ import { listProviderEntries } from "../../providers/speech-to-text/provider-cat
 import { resolveBatchTranscriber } from "../../providers/speech-to-text/resolve.js";
 import { normalizeSttError } from "../../stt/daemon-batch-transcriber.js";
 import type { BatchTranscriber, SttErrorCategory } from "../../stt/types.js";
+import { SttError } from "../../stt/types.js";
 import { getLogger } from "../../util/logger.js";
 import {
   FFMPEG_TRANSCODE_TIMEOUT_MS,
@@ -141,6 +142,27 @@ async function toWav(inputPath: string, isVideo: boolean): Promise<string> {
   return wavPath;
 }
 
+/**
+ * Call the provider and tag any failure as an {@link SttError} so callers can
+ * distinguish provider failures (categorized HTTP statuses) from local
+ * preprocessing failures (ffmpeg/ffprobe), which stay on the bad-gateway path.
+ */
+async function transcribeChunk(
+  transcriber: BatchTranscriber,
+  audioBuffer: Buffer,
+): Promise<string> {
+  try {
+    const result = await transcriber.transcribe({
+      audio: audioBuffer,
+      mimeType: "audio/wav",
+      signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
+    });
+    return result.text;
+  } catch (err) {
+    throw normalizeSttError(err);
+  }
+}
+
 async function transcribeWithProvider(
   audioPath: string,
   transcriber: BatchTranscriber,
@@ -151,12 +173,7 @@ async function transcribeWithProvider(
   // If small enough, send directly
   if (fileSize <= STT_CHUNK_MAX_BYTES) {
     const audioBuffer = await readFile(audioPath);
-    const result = await transcriber.transcribe({
-      audio: audioBuffer,
-      mimeType: "audio/wav",
-      signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
-    });
-    return result.text;
+    return transcribeChunk(transcriber, audioBuffer);
   }
 
   // Split into chunks for large files
@@ -175,12 +192,8 @@ async function transcribeWithProvider(
         `  Transcribing chunk ${i + 1}/${chunks.length}...\n`,
       );
       const audioBuffer = await readFile(chunks[i]);
-      const result = await transcriber.transcribe({
-        audio: audioBuffer,
-        mimeType: "audio/wav",
-        signal: AbortSignal.timeout(STT_REQUEST_TIMEOUT_MS),
-      });
-      if (result.text) parts.push(result.text);
+      const text = await transcribeChunk(transcriber, audioBuffer);
+      if (text) parts.push(text);
     }
 
     return parts.join(" ");
@@ -363,6 +376,26 @@ async function handleTranscribeFile({ body }: RouteHandlerArgs) {
       durationSeconds,
     };
   } catch (err) {
+    // Only provider failures (tagged as SttError by transcribeChunk) are
+    // categorized into HTTP statuses. Local preprocessing failures (ffmpeg/
+    // ffprobe) stay on the bad-gateway path so their stderr never decides the
+    // category (e.g. a path under a dir named "403" must not become a 401).
+    if (err instanceof SttError) {
+      // Auth/rate-limit/timeout/invalid-audio are user-config or transient
+      // conditions, not daemon defects, so log them at warn to keep them out
+      // of error telemetry. Reserve error level (with the raw err for a Sentry
+      // stack) for genuine provider/unexpected failures.
+      if (err.category === "provider-error") {
+        log.error({ err, filePath }, "File transcription failed");
+      } else {
+        log.warn(
+          { category: err.category, message: err.message, filePath },
+          "File transcription failed",
+        );
+      }
+      throw STT_ERROR_MAP[err.category]();
+    }
+
     log.error({ err, filePath }, "File transcription failed");
     throw new BadGatewayError(
       err instanceof Error ? err.message : "Transcription failed",

package/src/runtime/routes/surface-conversation-resolver.ts

@@ -18,8 +18,8 @@ import type { Conversation } from "../../daemon/conversation.js";
 import {
   findConversation,
   findConversationBySurfaceId,
-  getOrCreateConversation,
-} from "../../daemon/conversation-store.js";
+} from "../../daemon/conversation-registry.js";
+import { getOrCreateConversation } from "../../daemon/conversation-store.js";
 import { rawGet } from "../../memory/raw-query.js";
 
 /**
@@ -60,6 +60,7 @@ export async function resolveSurfaceConversation(
     `%"surfaceId":"${escaped}"%`,
   );
   if (!row) return undefined;
-  if (conversationId && conversationId !== row.conversation_id) return undefined;
+  if (conversationId && conversationId !== row.conversation_id)
+    return undefined;
   return await getOrCreateConversation(row.conversation_id);
 }

package/src/runtime/routes/work-items-routes.ts

@@ -8,10 +8,8 @@
 import { z } from "zod";
 
 import type { Conversation } from "../../daemon/conversation.js";
-import {
-  findConversation,
-  getOrCreateConversation,
-} from "../../daemon/conversation-store.js";
+import { findConversation } from "../../daemon/conversation-registry.js";
+import { getOrCreateConversation } from "../../daemon/conversation-store.js";
 import type { ServerMessage } from "../../daemon/message-protocol.js";
 import { getMessages } from "../../memory/conversation-crud.js";
 import { check, classifyRisk } from "../../permissions/checker.js";