@vellumai/assistant 0.5.9 → 0.5.11

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

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 import {
   setPlatformAssistantId,
   setPlatformBaseUrl,
@@ -532,7 +534,7 @@ export async function handleListSecrets(): Promise<Response> {
       return { type: "api_key" as const, name: account };
     });
 
-    return Response.json({ secrets });
+    return Response.json({ secrets, accounts: secrets });
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return httpError("INTERNAL_ERROR", message, 500);
@@ -556,21 +558,81 @@ export function secretRouteDefinitions(
       endpoint: "secrets",
       method: "POST",
       handler: async ({ req }) => handleAddSecret(req, deps?.getCesClient),
+      summary: "Add a secret",
+      description:
+        "Store a new secret (API key, OAuth token, etc.) in the credential vault.",
+      tags: ["secrets"],
+      requestBody: z.object({
+        type: z.string().describe("Secret type: 'api_key' or 'credential'"),
+        name: z.string().describe("Unique name for the secret"),
+        value: z.string().describe("Secret value to store"),
+      }),
+      responseBody: z.object({
+        success: z.boolean(),
+        type: z.string(),
+        name: z.string(),
+      }),
     },
     {
       endpoint: "secrets",
       method: "DELETE",
       handler: async ({ req }) => handleDeleteSecret(req),
+      summary: "Delete a secret",
+      description: "Remove a secret from the credential vault by name.",
+      tags: ["secrets"],
+      requestBody: z.object({
+        type: z.string().describe("Secret type: 'api_key' or 'credential'"),
+        name: z.string().describe("Name of the secret to delete"),
+      }),
+      responseBody: z.object({
+        success: z.boolean(),
+        type: z.string(),
+        name: z.string(),
+      }),
     },
     {
       endpoint: "secrets",
       method: "GET",
       handler: async () => handleListSecrets(),
+      summary: "List secrets",
+      description: "Return the names (not values) of all stored secrets.",
+      tags: ["secrets"],
+      responseBody: z.object({
+        secrets: z
+          .array(z.unknown())
+          .describe("List of secret metadata entries, each with type and name"),
+        accounts: z
+          .array(z.unknown())
+          .describe("Alias for secrets (same data)"),
+      }),
     },
     {
       endpoint: "secrets/read",
       method: "POST",
       handler: async ({ req }) => handleReadSecret(req),
+      summary: "Read a secret value",
+      description: "Retrieve the decrypted value of a stored secret by name.",
+      tags: ["secrets"],
+      requestBody: z.object({
+        type: z.string().describe("Secret type: 'api_key' or 'credential'"),
+        name: z.string().describe("Name of the secret to read"),
+        reveal: z
+          .boolean()
+          .describe(
+            "If true, return the decrypted value; otherwise return a masked version",
+          )
+          .optional(),
+      }),
+      responseBody: z.object({
+        found: z.boolean(),
+        value: z
+          .string()
+          .describe("Decrypted value (only when reveal=true and found)"),
+        masked: z
+          .string()
+          .describe("Masked value (when reveal=false and found)"),
+        unreachable: z.boolean(),
+      }),
     },
   ];
 }

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,
@@ -213,7 +215,7 @@ async function handleOAuthConnectStart(body: {
   if (requiresSecret && !clientSecret) {
     return httpError(
       "BAD_REQUEST",
-      `client_secret is required for "${body.service}" but not found in the keychain. Store it first via the credential vault.`,
+      `client_secret is required for "${body.service}" but not found in the credential store. Store it first via the credential vault.`,
       400,
     );
   }
@@ -612,6 +614,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 +634,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 +651,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 +672,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 +694,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 +715,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 +745,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 +757,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 +785,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 +797,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 +816,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 +847,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,
@@ -40,22 +42,29 @@ export function skillRouteDefinitions(deps: SkillRouteDeps): RouteDefinition[] {
   const ctx = () => deps.getSkillContext();
 
   return [
-    // GET /v1/skills — list all skills
     {
       endpoint: "skills",
       method: "GET",
       policyKey: "skills",
+      summary: "List all skills",
+      description: "Return all installed skills.",
+      tags: ["skills"],
+      responseBody: z.object({
+        skills: z.array(z.unknown()).describe("Skill objects"),
+      }),
       handler: () => {
         const skills = 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 +77,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 +96,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 +115,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 +148,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 +190,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 +209,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 +239,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 +266,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 +304,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 +323,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 +349,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 +368,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;