@vellumai/assistant 0.5.10 → 0.5.12

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

@@ -10,6 +10,8 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { z } from "zod";
+
 import {
   getPlatformBaseUrl,
   setIngressPublicBaseUrl,
@@ -28,10 +30,6 @@ import {
   getMostRecentAppByProvider,
   getProvider,
 } from "../../oauth/oauth-store.js";
-import {
-  getProviderBehavior,
-  resolveService,
-} from "../../oauth/provider-behaviors.js";
 import {
   check,
   classifyRisk,
@@ -168,14 +166,14 @@ async function handleOAuthConnectStart(body: {
     return httpError("BAD_REQUEST", "Missing required field: service", 400);
   }
 
-  const resolvedService = resolveService(body.service);
+  const service = body.service;
 
   // Resolve client_id and client_secret from oauth-store.
   let clientId: string | undefined;
   let clientSecret: string | undefined;
 
   // Try existing connection first (re-auth flow)
-  const conn = getConnectionByProvider(resolvedService);
+  const conn = getConnectionByProvider(service);
   if (conn) {
     const app = getApp(conn.oauthAppId);
     if (app) {
@@ -186,7 +184,7 @@ async function handleOAuthConnectStart(body: {
 
   // Fall back to most recent app for this provider (first-time connect with stored app)
   if (!clientId) {
-    const dbApp = getMostRecentAppByProvider(resolvedService);
+    const dbApp = getMostRecentAppByProvider(service);
     if (dbApp) {
       clientId = dbApp.clientId;
       if (!clientSecret) {
@@ -200,20 +198,17 @@ async function handleOAuthConnectStart(body: {
   if (!clientId) {
     return httpError(
       "BAD_REQUEST",
-      `No client_id found for "${body.service}". Store it first via the credential vault.`,
+      `No client_id found for "${service}". Store it first via the credential vault.`,
       400,
     );
   }
 
-  const behavior = getProviderBehavior(resolvedService);
-  const providerRow = getProvider(resolvedService);
-  const requiresSecret =
-    behavior?.setup?.requiresClientSecret ??
-    !!(providerRow?.tokenEndpointAuthMethod || providerRow?.extraParams);
+  const providerRow = getProvider(service);
+  const requiresSecret = !!providerRow?.requiresClientSecret;
   if (requiresSecret && !clientSecret) {
     return httpError(
       "BAD_REQUEST",
-      `client_secret is required for "${body.service}" but not found in the credential store. Store it first via the credential vault.`,
+      `client_secret is required for "${service}" but not found in the credential store. Store it first via the credential vault.`,
       400,
     );
   }
@@ -224,7 +219,7 @@ async function handleOAuthConnectStart(body: {
     let authUrl: string | undefined;
 
     const result = await orchestrateOAuthConnect({
-      service: body.service,
+      service,
       requestedScopes: body.requestedScopes,
       clientId,
       clientSecret,
@@ -236,7 +231,7 @@ async function handleOAuthConnectStart(body: {
         // Prefer accountInfo from oauth-store when available.
         let accountInfo = deferredResult.accountInfo;
         try {
-          const conn = getConnectionByProvider(resolvedService);
+          const conn = getConnectionByProvider(service);
           if (conn?.accountInfo) accountInfo = conn.accountInfo;
         } catch {
           // DB not ready — use orchestrator value
@@ -275,7 +270,7 @@ async function handleOAuthConnectStart(body: {
 
     if (!result.success) {
       log.error(
-        { err: result.error, service: body.service },
+        { err: result.error, service },
         "OAuth connect orchestrator returned error",
       );
       return httpError(
@@ -296,7 +291,7 @@ async function handleOAuthConnectStart(body: {
     // Prefer accountInfo from oauth-store when available.
     let responseAccountInfo = result.accountInfo;
     try {
-      const conn = getConnectionByProvider(resolvedService);
+      const conn = getConnectionByProvider(service);
       if (conn?.accountInfo) responseAccountInfo = conn.accountInfo;
     } catch {
       // DB not ready — use orchestrator value
@@ -310,7 +305,7 @@ async function handleOAuthConnectStart(body: {
     });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    log.error({ err, service: body.service }, "OAuth connect flow failed");
+    log.error({ err, service }, "OAuth connect flow failed");
     return httpError("INTERNAL_ERROR", sanitizeOAuthError(message), 500);
   }
 }
@@ -612,6 +607,12 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "settings/voice",
       method: "PUT",
       policyKey: "settings/voice",
+      summary: "Update voice activation key",
+      description: "Validate and normalize a voice activation key.",
+      tags: ["settings"],
+      requestBody: z.object({
+        activationKey: z.string(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as { activationKey?: string };
         if (!body.activationKey) {
@@ -626,6 +627,12 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "settings/avatar/generate",
       method: "POST",
       policyKey: "settings/avatar/generate",
+      summary: "Generate avatar",
+      description: "Generate an AI avatar image from a text description.",
+      tags: ["settings"],
+      requestBody: z.object({
+        description: z.string(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as { description?: string };
         return handleGenerateAvatar(body.description ?? "");
@@ -637,6 +644,13 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "settings/client",
       method: "PUT",
       policyKey: "settings/client",
+      summary: "Update client setting",
+      description: "Set a single client-side setting key/value pair.",
+      tags: ["settings"],
+      requestBody: z.object({
+        key: z.string(),
+        value: z.string(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as { key?: string; value?: string };
         if (!body.key || body.value === undefined) {
@@ -651,6 +665,14 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "oauth/start",
       method: "POST",
       policyKey: "oauth/start",
+      summary: "Start OAuth flow",
+      description:
+        "Initiate an OAuth authorization flow for a third-party service.",
+      tags: ["oauth"],
+      requestBody: z.object({
+        service: z.string(),
+        requestedScopes: z.array(z.unknown()),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as {
           service?: string;
@@ -665,6 +687,13 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "integrations/oauth/start",
       method: "POST",
       policyKey: "integrations/oauth/start",
+      summary: "Start OAuth flow (legacy)",
+      description: "Legacy alias for oauth/start.",
+      tags: ["oauth"],
+      requestBody: z.object({
+        service: z.string(),
+        requestedScopes: z.array(z.unknown()),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as {
           service?: string;
@@ -679,12 +708,18 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "workspace-files",
       method: "GET",
       policyKey: "workspace-files",
+      summary: "List workspace files",
+      description: "Return an array of files in the workspace directory.",
+      tags: ["workspace"],
       handler: () => handleWorkspaceFilesList(),
     },
     {
       endpoint: "workspace-files/read",
       method: "GET",
       policyKey: "workspace-files/read",
+      summary: "Read a workspace file",
+      description: "Return the contents of a single file by path.",
+      tags: ["workspace"],
       handler: ({ url }) => {
         const filePath = url.searchParams.get("path") ?? "";
         if (!filePath) {
@@ -703,6 +738,10 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "tools",
       method: "GET",
       policyKey: "tools",
+      summary: "List tools",
+      description:
+        "Return available tool names with their descriptions, risk levels, and categories.",
+      tags: ["tools"],
       handler: () => handleToolNamesList(),
     },
 
@@ -711,6 +750,17 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "tools/simulate-permission",
       method: "POST",
       policyKey: "tools/simulate-permission",
+      summary: "Simulate tool permission check",
+      description:
+        "Dry-run a permission check for a tool invocation without executing it.",
+      tags: ["tools"],
+      requestBody: z.object({
+        toolName: z.string(),
+        input: z.object({}).passthrough(),
+        workingDir: z.string(),
+        forcePromptSideEffects: z.boolean(),
+        isInteractive: z.boolean(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as {
           toolName?: string;
@@ -728,6 +778,10 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "diagnostics/env-vars",
       method: "GET",
       policyKey: "diagnostics/env-vars",
+      summary: "List safe environment variables",
+      description:
+        "Return environment variable names and values that are safe to expose (no secrets).",
+      tags: ["diagnostics"],
       handler: () => handleEnvVars(),
     },
 
@@ -736,6 +790,13 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "config/platform",
       method: "GET",
       policyKey: "config/platform:GET",
+      summary: "Get platform config",
+      description: "Return the platform base URL configuration.",
+      tags: ["config"],
+      responseBody: z.object({
+        baseUrl: z.string(),
+        success: z.boolean(),
+      }),
       handler: () => {
         const raw = loadRawConfig();
         const platform = (raw?.platform ?? {}) as Record<string, unknown>;
@@ -748,6 +809,12 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "config/platform",
       method: "PUT",
       policyKey: "config/platform",
+      summary: "Update platform config",
+      description: "Set the platform base URL.",
+      tags: ["config"],
+      requestBody: z.object({
+        baseUrl: z.string(),
+      }),
       handler: async ({ req }) => {
         try {
           const body = (await req.json()) as { baseUrl?: string };
@@ -773,12 +840,28 @@ export function settingsRouteDefinitions(): RouteDefinition[] {
       endpoint: "integrations/ingress/config",
       method: "GET",
       policyKey: "integrations/ingress/config:GET",
+      summary: "Get ingress config",
+      description: "Return the current ingress tunnel configuration.",
+      tags: ["config"],
       handler: () => Response.json(getIngressConfigResult()),
     },
     {
       endpoint: "integrations/ingress/config",
       method: "PUT",
       policyKey: "integrations/ingress/config",
+      summary: "Update ingress config",
+      description: "Set the ingress public base URL and enabled state.",
+      tags: ["config"],
+      requestBody: z.object({
+        publicBaseUrl: z.string(),
+        enabled: z.boolean(),
+      }),
+      responseBody: z.object({
+        enabled: z.boolean(),
+        publicBaseUrl: z.string(),
+        localGatewayTarget: z.string(),
+        success: z.boolean(),
+      }),
       handler: async ({ req }) => {
         try {
           const body = (await req.json()) as {

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

@@ -5,6 +5,8 @@
  * using the standalone functions extracted in `../../daemon/handlers/skills.ts`.
  */
 
+import { z } from "zod";
+
 import type {
   CreateSkillParams,
   SkillOperationContext,
@@ -21,6 +23,7 @@ import {
   inspectSkill,
   installSkill,
   listSkills,
+  listSkillsWithCatalog,
   searchSkills,
   uninstallSkill,
   updateSkill,
@@ -40,22 +43,69 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
   const ctx = () => deps.getSkillContext();
 
   return [
-    // GET /v1/skills — list all skills
     {
       endpoint: "skills",
       method: "GET",
       policyKey: "skills",
-      handler: () => {
-        const skills = listSkills(ctx());
+      summary: "List all skills",
+      description:
+        "Return all installed skills. Pass ?include=catalog to also include available catalog skills.",
+      tags: ["skills"],
+      queryParams: [
+        {
+          name: "include",
+          schema: { type: "string", enum: ["catalog"] },
+          description:
+            "Optional inclusion flag. Use 'catalog' to merge available Vellum catalog skills into the response.",
+        },
+      ],
+      responseBody: z.object({
+        skills: z
+          .array(
+            z.object({
+              id: z.string(),
+              name: z.string(),
+              description: z.string(),
+              emoji: z.string().optional(),
+              homepage: z.string().optional(),
+              source: z.enum([
+                "bundled",
+                "managed",
+                "workspace",
+                "clawhub",
+                "extra",
+                "catalog",
+              ]),
+              state: z.enum(["enabled", "disabled"]),
+              installStatus: z.enum(["bundled", "installed", "available"]),
+              updateAvailable: z.boolean(),
+              provenance: z.object({
+                kind: z.enum(["first-party", "third-party", "local"]),
+                provider: z.string().optional(),
+                originId: z.string().optional(),
+                sourceUrl: z.string().optional(),
+              }),
+            }),
+          )
+          .describe("Skill objects"),
+      }),
+      handler: async ({ url }) => {
+        const include = url.searchParams.get("include");
+        const skills =
+          include === "catalog"
+            ? await listSkillsWithCatalog(ctx())
+            : listSkills(ctx());
         return Response.json({ skills });
       },
     },
 
-    // GET /v1/skills/:id/files — skill metadata + directory contents
     {
       endpoint: "skills/:id/files",
       method: "GET",
       policyKey: "skills",
+      summary: "Get skill files",
+      description: "Return skill metadata and directory contents.",
+      tags: ["skills"],
       handler: ({ params }) => {
         const result = getSkillFiles(params.id, ctx());
         if ("error" in result) {
@@ -68,11 +118,16 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // POST /v1/skills/:id/enable — enable skill
     {
       endpoint: "skills/:id/enable",
       method: "POST",
       policyKey: "skills",
+      summary: "Enable skill",
+      description: "Enable an installed skill.",
+      tags: ["skills"],
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: ({ params }) => {
         const result = enableSkill(params.id, ctx());
         if (!result.success) {
@@ -82,11 +137,16 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // POST /v1/skills/:id/disable — disable skill
     {
       endpoint: "skills/:id/disable",
       method: "POST",
       policyKey: "skills",
+      summary: "Disable skill",
+      description: "Disable an installed skill.",
+      tags: ["skills"],
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: ({ params }) => {
         const result = disableSkill(params.id, ctx());
         if (!result.success) {
@@ -96,11 +156,21 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // PATCH /v1/skills/:id/config — configure skill
     {
       endpoint: "skills/:id/config",
       method: "PATCH",
       policyKey: "skills",
+      summary: "Configure skill",
+      description: "Update skill configuration (env, apiKey, config).",
+      tags: ["skills"],
+      requestBody: z.object({
+        env: z.object({}).passthrough().describe("Environment variables"),
+        apiKey: z.string(),
+        config: z.object({}).passthrough().describe("Arbitrary config"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req, params }) => {
         const body = (await req.json()) as {
           env?: Record<string, string>;
@@ -119,11 +189,22 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // POST /v1/skills/install — install skill
     {
       endpoint: "skills/install",
       method: "POST",
       policyKey: "skills",
+      summary: "Install skill",
+      description: "Install a skill by slug, URL, or spec.",
+      tags: ["skills"],
+      requestBody: z.object({
+        slug: z.string().describe("Skill slug"),
+        url: z.string().describe("Skill URL"),
+        spec: z.string().describe("Skill spec"),
+        version: z.string(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as {
           slug?: string;
@@ -150,11 +231,16 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // POST /v1/skills/check-updates — check for updates
     {
       endpoint: "skills/check-updates",
       method: "POST",
       policyKey: "skills",
+      summary: "Check skill updates",
+      description: "Check for available updates to installed skills.",
+      tags: ["skills"],
+      responseBody: z.object({
+        data: z.object({}).passthrough().describe("Update availability info"),
+      }),
       handler: async () => {
         const result = await checkSkillUpdates(ctx());
         if (!result.success) {
@@ -164,11 +250,23 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // GET /v1/skills/search — search catalog
     {
       endpoint: "skills/search",
       method: "GET",
       policyKey: "skills",
+      summary: "Search skill catalog",
+      description: "Search the skill catalog by query string.",
+      tags: ["skills"],
+      queryParams: [
+        {
+          name: "q",
+          schema: { type: "string" },
+          description: "Search query (required)",
+        },
+      ],
+      responseBody: z.object({
+        data: z.object({}).passthrough().describe("Search results"),
+      }),
       handler: async ({ url }) => {
         const query = url.searchParams.get("q") ?? "";
         if (!query) {
@@ -182,11 +280,16 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // POST /v1/skills/draft — draft new skill
     {
       endpoint: "skills/draft",
       method: "POST",
       policyKey: "skills",
+      summary: "Draft a skill",
+      description: "Generate a skill draft from source text.",
+      tags: ["skills"],
+      requestBody: z.object({
+        sourceText: z.string().describe("Source text for drafting"),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as { sourceText?: string };
         if (!body.sourceText || typeof body.sourceText !== "string") {
@@ -204,11 +307,22 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // POST /v1/skills — create skill
     {
       endpoint: "skills",
       method: "POST",
       policyKey: "skills",
+      summary: "Create skill",
+      description: "Create a new skill.",
+      tags: ["skills"],
+      requestBody: z.object({
+        skillId: z.string(),
+        name: z.string(),
+        description: z.string(),
+        bodyMarkdown: z.string(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as CreateSkillParams;
         if (
@@ -231,11 +345,16 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // POST /v1/skills/:id/update — update skill
     {
       endpoint: "skills/:id/update",
       method: "POST",
       policyKey: "skills",
+      summary: "Update skill",
+      description: "Update an installed skill to the latest version.",
+      tags: ["skills"],
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ params }) => {
         const result = await updateSkill(params.id, ctx());
         if (!result.success) {
@@ -245,11 +364,13 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // GET /v1/skills/:id/inspect — inspect skill details
     {
       endpoint: "skills/:id/inspect",
       method: "GET",
       policyKey: "skills",
+      summary: "Inspect skill",
+      description: "Return detailed skill information.",
+      tags: ["skills"],
       handler: async ({ params }) => {
         const result = await inspectSkill(params.id, ctx());
         if (result.error && !result.data) {
@@ -269,13 +390,13 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // GET /v1/skills/:id — single skill metadata
-    // Registered after all literal-segment GET routes (search, inspect, files)
-    // to avoid shadowing them with the parametric :id match.
     {
       endpoint: "skills/:id",
       method: "GET",
       policyKey: "skills",
+      summary: "Get skill",
+      description: "Return a single skill by ID.",
+      tags: ["skills"],
       handler: ({ params }) => {
         const result = getSkill(params.id, ctx());
         if ("error" in result) {
@@ -288,11 +409,13 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
       },
     },
 
-    // DELETE /v1/skills/:id — uninstall skill
     {
       endpoint: "skills/:id",
       method: "DELETE",
       policyKey: "skills",
+      summary: "Uninstall skill",
+      description: "Remove an installed skill.",
+      tags: ["skills"],
       handler: async ({ params }) => {
         const result = await uninstallSkill(params.id, ctx());
         if (!result.success) {

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

@@ -5,6 +5,8 @@
  * sharing business logic with the handlers in
  * `daemon/handlers/subagents.ts`.
  */
+import { z } from "zod";
+
 import { getMessages } from "../../memory/conversation-crud.js";
 import { getSubagentManager } from "../../subagent/index.js";
 import { getLogger } from "../../util/logger.js";
@@ -121,11 +123,25 @@ export function getSubagentDetail(
 
 export function subagentRouteDefinitions(): RouteDefinition[] {
   return [
-    // GET /v1/subagents/:id — get subagent detail
     {
       endpoint: "subagents/:id",
       method: "GET",
       policyKey: "subagents",
+      summary: "Get subagent detail",
+      description: "Return subagent objective and event history.",
+      tags: ["subagents"],
+      queryParams: [
+        {
+          name: "conversationId",
+          schema: { type: "string" },
+          description: "Parent conversation ID (required)",
+        },
+      ],
+      responseBody: z.object({
+        subagentId: z.string(),
+        objective: z.string(),
+        events: z.array(z.unknown()).describe("Subagent event objects"),
+      }),
       handler: ({ url, params }) => {
         const conversationId = url.searchParams.get("conversationId");
         if (!conversationId) {
@@ -152,11 +168,20 @@ export function subagentRouteDefinitions(): RouteDefinition[] {
       },
     },
 
-    // POST /v1/subagents/:id/abort — abort subagent
     {
       endpoint: "subagents/:id/abort",
       method: "POST",
       policyKey: "subagents/abort",
+      summary: "Abort subagent",
+      description: "Abort a running subagent.",
+      tags: ["subagents"],
+      requestBody: z.object({
+        conversationId: z.string(),
+      }),
+      responseBody: z.object({
+        subagentId: z.string(),
+        aborted: z.boolean(),
+      }),
       handler: async ({ req, params }) => {
         const body = (await req.json()) as { conversationId?: string };
         const conversationId = body.conversationId;
@@ -187,11 +212,21 @@ export function subagentRouteDefinitions(): RouteDefinition[] {
       },
     },
 
-    // POST /v1/subagents/:id/message — send message to subagent
     {
       endpoint: "subagents/:id/message",
       method: "POST",
       policyKey: "subagents/message",
+      summary: "Send message to subagent",
+      description: "Send a text message to a running subagent.",
+      tags: ["subagents"],
+      requestBody: z.object({
+        conversationId: z.string(),
+        content: z.string(),
+      }),
+      responseBody: z.object({
+        subagentId: z.string(),
+        sent: z.boolean(),
+      }),
       handler: async ({ req, params }) => {
         const body = (await req.json()) as {
           conversationId?: string;