@vellumai/assistant 0.5.9 → 0.5.11

package/src/runtime/routes/app-management-routes.ts

@@ -18,6 +18,8 @@ import { stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
+import { z } from "zod";
+
 import { packageApp } from "../../bundler/app-bundler.js";
 import { compileApp } from "../../bundler/app-compiler.js";
 import { scanBundle } from "../../bundler/bundle-scanner.js";
@@ -378,6 +380,12 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps",
       method: "GET",
       policyKey: "apps",
+      summary: "List apps",
+      description: "Return all locally installed apps.",
+      tags: ["apps"],
+      responseBody: z.object({
+        apps: z.array(z.unknown()).describe("Array of app summary objects"),
+      }),
       handler: () => {
         try {
           const apps = listAppsFiltered();
@@ -400,6 +408,13 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/open-bundle",
       method: "POST",
       policyKey: "apps/open-bundle",
+      summary: "Open a .vbundle file",
+      description:
+        "Scan and validate a .vbundle file from disk and return its manifest.",
+      tags: ["apps"],
+      requestBody: z.object({
+        filePath: z.string().describe("Absolute path to the .vbundle file"),
+      }),
       handler: async ({ req }) => {
         try {
           const body = (await req.json()) as { filePath?: string };
@@ -429,6 +444,12 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/shared",
       method: "GET",
       policyKey: "apps/shared-list",
+      summary: "List shared apps",
+      description: "Return all apps available via cloud share links.",
+      tags: ["apps"],
+      responseBody: z.object({
+        apps: z.array(z.unknown()).describe("Array of shared app objects"),
+      }),
       handler: () => {
         try {
           const apps = listSharedApps();
@@ -451,6 +472,12 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/fork",
       method: "POST",
       policyKey: "apps/fork",
+      summary: "Fork a shared app",
+      description: "Create a local copy of a shared app by its UUID.",
+      tags: ["apps"],
+      requestBody: z.object({
+        uuid: z.string().describe("UUID of the shared app to fork"),
+      }),
       handler: async ({ req }) => {
         try {
           const body = (await req.json()) as { uuid?: string };
@@ -479,6 +506,12 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/gallery/install",
       method: "POST",
       policyKey: "apps/gallery/install",
+      summary: "Install a gallery app",
+      description: "Install an app from the built-in gallery by its ID.",
+      tags: ["apps"],
+      requestBody: z.object({
+        galleryAppId: z.string(),
+      }),
       handler: async ({ req }) => {
         try {
           const body = (await req.json()) as { galleryAppId?: string };
@@ -505,6 +538,12 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/gallery",
       method: "GET",
       policyKey: "apps/gallery",
+      summary: "List gallery apps",
+      description: "Return the built-in app gallery catalog.",
+      tags: ["apps"],
+      responseBody: z.object({
+        gallery: z.array(z.unknown()).describe("Gallery app entries"),
+      }),
       handler: () => {
         return Response.json({ gallery: defaultGallery });
       },
@@ -516,6 +555,19 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/sign-bundle",
       method: "POST",
       policyKey: "apps/sign-bundle",
+      summary: "Sign an app bundle",
+      description:
+        "Return a signing payload or complete the signing step when signature fields are provided.",
+      tags: ["apps"],
+      requestBody: z.object({
+        payload: z.string().describe("Canonical JSON payload to sign"),
+        signature: z
+          .string()
+          .describe("Ed25519 signature (optional, completes signing)")
+          .optional(),
+        keyId: z.string().optional(),
+        publicKey: z.string().optional(),
+      }),
       handler: async ({ req }) => {
         try {
           const body = (await req.json()) as {
@@ -576,6 +628,10 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/signing-identity",
       method: "GET",
       policyKey: "apps/signing-identity",
+      summary: "Get signing identity",
+      description:
+        "Return signing identity info. Signing is managed client-side over HTTP.",
+      tags: ["apps"],
       handler: () => {
         // Signing identity is a client-side concept. Over HTTP, the
         // client already holds its own keys. Return a placeholder
@@ -597,6 +653,9 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/data",
       method: "GET",
       policyKey: "apps/data",
+      summary: "Query app data",
+      description: "Read records from an app's local data store.",
+      tags: ["apps"],
       handler: ({ params, url }) => {
         try {
           const method = url.searchParams.get("method") ?? "query";
@@ -627,6 +686,15 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/data",
       method: "POST",
       policyKey: "apps/data",
+      summary: "Mutate app data",
+      description:
+        "Create, update, or delete records in an app's local data store.",
+      tags: ["apps"],
+      requestBody: z.object({
+        method: z.string().describe("'create', 'update', or 'delete'"),
+        recordId: z.string(),
+        data: z.object({}).passthrough(),
+      }),
       handler: async ({ params, req }) => {
         try {
           const body = (await req.json()) as {
@@ -662,6 +730,16 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/open",
       method: "POST",
       policyKey: "apps/open",
+      summary: "Open an app",
+      description:
+        "Compile (if needed) and return the app's HTML for rendering.",
+      tags: ["apps"],
+      responseBody: z.object({
+        appId: z.string(),
+        dirName: z.string(),
+        name: z.string(),
+        html: z.string(),
+      }),
       handler: async ({ params }) => {
         try {
           const appId = params.id;
@@ -719,6 +797,9 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/delete",
       method: "POST",
       policyKey: "apps/delete",
+      summary: "Delete an app",
+      description: "Permanently remove an app and its data.",
+      tags: ["apps"],
       handler: ({ params }) => {
         try {
           deleteApp(params.id);
@@ -736,6 +817,9 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/preview",
       method: "GET",
       policyKey: "apps/preview",
+      summary: "Get app preview",
+      description: "Return the preview image or HTML for an app.",
+      tags: ["apps"],
       handler: ({ params }) => {
         try {
           const preview = getAppPreview(params.id);
@@ -759,6 +843,12 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/preview",
       method: "PUT",
       policyKey: "apps/preview",
+      summary: "Update app preview",
+      description: "Set a new preview image or HTML for an app.",
+      tags: ["apps"],
+      requestBody: z.object({
+        preview: z.string().describe("Base64-encoded image or HTML string"),
+      }),
       handler: async ({ params, req }) => {
         try {
           const body = (await req.json()) as { preview?: string };
@@ -785,6 +875,13 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/history",
       method: "GET",
       policyKey: "apps/history",
+      summary: "Get app version history",
+      description: "Return the git commit history of an app.",
+      tags: ["apps"],
+      responseBody: z.object({
+        appId: z.string(),
+        versions: z.array(z.unknown()),
+      }),
       handler: async ({ params, url }) => {
         try {
           const limit = url.searchParams.get("limit")
@@ -808,6 +905,9 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/diff",
       method: "GET",
       policyKey: "apps/diff",
+      summary: "Get app diff",
+      description: "Return a git diff between two commits for an app.",
+      tags: ["apps"],
       handler: async ({ params, url }) => {
         try {
           const fromCommit = url.searchParams.get("fromCommit");
@@ -837,6 +937,12 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/restore",
       method: "POST",
       policyKey: "apps/restore",
+      summary: "Restore app version",
+      description: "Restore an app to a previous git commit.",
+      tags: ["apps"],
+      requestBody: z.object({
+        commitHash: z.string(),
+      }),
       handler: async ({ params, req }) => {
         try {
           const body = (await req.json()) as { commitHash?: string };
@@ -862,6 +968,15 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/bundle",
       method: "POST",
       policyKey: "apps/bundle",
+      summary: "Bundle an app",
+      description: "Package an app into a distributable .vbundle archive.",
+      tags: ["apps"],
+      responseBody: z.object({
+        type: z.string(),
+        bundlePath: z.string(),
+        iconImageBase64: z.string(),
+        manifest: z.object({}).passthrough(),
+      }),
       handler: async ({ params }) => {
         try {
           const result = await packageApp(params.id);
@@ -889,6 +1004,14 @@ export function appManagementRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:id/share-cloud",
       method: "POST",
       policyKey: "apps/share-cloud",
+      summary: "Share app to cloud",
+      description: "Package and upload an app to the cloud share service.",
+      tags: ["apps"],
+      responseBody: z.object({
+        success: z.boolean(),
+        shareToken: z.string(),
+        shareUrl: z.string(),
+      }),
       handler: async ({ params }) => {
         try {
           // Package without signing callback (HTTP clients handle signing

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

@@ -6,6 +6,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { extname, join } from "node:path";
 
 import JSZip from "jszip";
+import { z } from "zod";
 
 import type { AppManifest } from "../../bundler/manifest.js";
 import {
@@ -336,30 +337,60 @@ export function appRouteDefinitions(): RouteDefinition[] {
       endpoint: "apps/:appId/dist/:filename",
       method: "GET",
       policyKey: "apps/dist",
+      summary: "Serve app dist file",
+      description:
+        "Serve a static asset from an app's compiled dist/ directory.",
+      tags: ["apps"],
       handler: ({ params }) =>
         handleServeDistFile(params.appId, params.filename),
     },
     {
       endpoint: "apps/share",
       method: "POST",
+      summary: "Share an app",
+      description: "Upload a zip app bundle and create a shareable link.",
+      tags: ["apps"],
+      responseBody: z.object({
+        shareToken: z.string(),
+        shareUrl: z.string(),
+        bundleSizeBytes: z.number(),
+      }),
       handler: async ({ req }) => handleShareApp(req),
     },
     {
       endpoint: "apps/shared/:token/metadata",
       method: "GET",
       policyKey: "apps/shared/metadata",
+      summary: "Get shared app metadata",
+      description: "Return metadata for a shared app bundle.",
+      tags: ["apps"],
+      responseBody: z.object({
+        name: z.string(),
+        description: z.string(),
+        icon: z.string(),
+        bundleSizeBytes: z.number(),
+      }),
       handler: ({ params }) => handleGetSharedAppMetadata(params.token),
     },
     {
       endpoint: "apps/shared/:token",
       method: "GET",
       policyKey: "apps/shared",
+      summary: "Download shared app",
+      description: "Download a shared app bundle as a zip file.",
+      tags: ["apps"],
       handler: ({ params }) => handleDownloadSharedApp(params.token),
     },
     {
       endpoint: "apps/shared/:token",
       method: "DELETE",
       policyKey: "apps/shared",
+      summary: "Delete shared app",
+      description: "Remove a shared app link.",
+      tags: ["apps"],
+      responseBody: z.object({
+        success: z.boolean(),
+      }),
       handler: ({ params }) => handleDeleteSharedApp(params.token),
     },
   ];

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

@@ -8,6 +8,8 @@
  * header. Guardian decisions additionally verify that the actor is the
  * bound guardian.
  */
+import { z } from "zod";
+
 import { getConversationByKey } from "../../memory/conversation-key-store.js";
 import { addRule } from "../../permissions/trust-store.js";
 import type { UserDecision } from "../../permissions/types.js";
@@ -69,6 +71,10 @@ export async function handleConfirm(
   // pending interaction — the client can retry with corrected values.
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
+    log.warn(
+      { requestId, decision },
+      "Confirmation POST for unknown requestId (already consumed or never registered)",
+    );
     return httpError(
       "NOT_FOUND",
       "No pending interaction found for this requestId",
@@ -129,7 +135,23 @@ export async function handleConfirm(
   // Validation passed — consume the pending interaction.
   const interaction = pendingInteractions.resolve(requestId)!;
 
-  interaction.conversation.handleConfirmationResponse(
+  log.info(
+    {
+      requestId,
+      decision,
+      toolName: interaction.confirmationDetails?.toolName,
+      conversationId: interaction.conversationId,
+    },
+    "Confirmation resolved via HTTP",
+  );
+
+  // ACP permissions: resolve directly without a Conversation object.
+  if (interaction.directResolve) {
+    interaction.directResolve(decision as UserDecision);
+    return Response.json({ accepted: true });
+  }
+
+  interaction.conversation!.handleConfirmationResponse(
     requestId,
     decision as UserDecision,
     selectedPattern,
@@ -187,7 +209,7 @@ export async function handleSecret(
     );
   }
 
-  interaction.conversation.handleSecretResponse(
+  interaction.conversation!.handleSecretResponse(
     requestId,
     value,
     delivery as "store" | "transient_send" | undefined,
@@ -355,7 +377,9 @@ export function handleListPendingInteractions(
     resolvedConversationId,
   );
 
-  const confirmation = interactions.find((i) => i.kind === "confirmation");
+  const confirmation = interactions.find(
+    (i) => i.kind === "confirmation" || i.kind === "acp_confirmation",
+  );
   const secret = interactions.find((i) => i.kind === "secret");
 
   return Response.json({
@@ -377,6 +401,8 @@ export function handleListPendingInteractions(
             confirmation.confirmationDetails?.persistentDecisionsAllowed,
           temporaryOptionsAvailable:
             confirmation.confirmationDetails?.temporaryOptionsAvailable,
+          acpToolKind: confirmation.confirmationDetails?.acpToolKind,
+          acpOptions: confirmation.confirmationDetails?.acpOptions,
         }
       : null,
     pendingSecret: secret
@@ -396,22 +422,101 @@ export function approvalRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "confirm",
       method: "POST",
+      summary: "Resolve a pending confirmation",
+      description: "Approve or deny a pending tool confirmation by requestId.",
+      tags: ["approvals"],
+      requestBody: z.object({
+        requestId: z.string().describe("Pending interaction request ID"),
+        decision: z
+          .string()
+          .describe(
+            "One of: allow, allow_10m, allow_conversation, deny, always_allow, always_deny, always_allow_high_risk",
+          ),
+        selectedPattern: z
+          .string()
+          .describe("Allowlist pattern for persistent decisions")
+          .optional(),
+        selectedScope: z
+          .string()
+          .describe("Scope for persistent decisions")
+          .optional(),
+      }),
+      responseBody: z.object({
+        accepted: z.boolean(),
+      }),
       handler: async ({ req, authContext }) => handleConfirm(req, authContext),
     },
     {
       endpoint: "secret",
       method: "POST",
+      summary: "Resolve a pending secret request",
+      description: "Provide a secret value for a pending secret request.",
+      tags: ["approvals"],
+      requestBody: z.object({
+        requestId: z.string().describe("Pending interaction request ID"),
+        value: z.string().describe("Secret value").optional(),
+        delivery: z
+          .string()
+          .describe("Delivery mode: store or transient_send")
+          .optional(),
+      }),
+      responseBody: z.object({
+        accepted: z.boolean(),
+      }),
       handler: async ({ req, authContext }) => handleSecret(req, authContext),
     },
     {
       endpoint: "trust-rules",
       method: "POST",
+      summary: "Add a trust rule for a pending confirmation",
+      description:
+        "Add a trust rule bound to a pending confirmation without resolving it.",
+      tags: ["approvals"],
+      requestBody: z.object({
+        requestId: z.string().describe("Pending confirmation request ID"),
+        pattern: z.string().describe("Allowlist pattern"),
+        scope: z.string().describe("Scope for the rule"),
+        decision: z.string().describe("allow or deny"),
+        allowHighRisk: z
+          .boolean()
+          .describe("Allow high-risk invocations")
+          .optional(),
+      }),
+      responseBody: z.object({
+        accepted: z.boolean(),
+      }),
       handler: async ({ req, authContext }) =>
         handleTrustRule(req, authContext),
     },
     {
       endpoint: "pending-interactions",
       method: "GET",
+      summary: "List pending interactions",
+      description:
+        "Return pending confirmations and secrets for a conversation.",
+      tags: ["approvals"],
+      queryParams: [
+        {
+          name: "conversationKey",
+          schema: { type: "string" },
+          description: "Conversation key",
+        },
+        {
+          name: "conversationId",
+          schema: { type: "string" },
+          description: "Conversation ID",
+        },
+      ],
+      responseBody: z.object({
+        pendingConfirmation: z
+          .object({})
+          .passthrough()
+          .describe("Pending confirmation details or null"),
+        pendingSecret: z
+          .object({})
+          .passthrough()
+          .describe("Pending secret request or null"),
+      }),
       handler: ({ url, authContext }) =>
         handleListPendingInteractions(url, authContext),
     },

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

@@ -3,6 +3,8 @@
  */
 import { existsSync, statSync } from "node:fs";
 
+import { z } from "zod";
+
 import * as attachmentsStore from "../../memory/attachments-store.js";
 import {
   AttachmentUploadError,
@@ -261,23 +263,66 @@ export function attachmentRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "attachments",
       method: "POST",
+      summary: "Upload attachment",
+      description:
+        "Upload an attachment as base64 data or file path reference.",
+      tags: ["attachments"],
+      requestBody: z.object({
+        filename: z.string(),
+        mimeType: z.string(),
+        data: z.string().describe("Base64-encoded file data").optional(),
+        filePath: z
+          .string()
+          .describe("On-disk file path (file-backed upload)")
+          .optional(),
+      }),
+      responseBody: z.object({
+        id: z.string(),
+        original_filename: z.string(),
+        mime_type: z.string(),
+        size_bytes: z.number(),
+        kind: z.string(),
+      }),
       handler: async ({ req }) => handleUploadAttachment(req),
     },
     {
       endpoint: "attachments",
       method: "DELETE",
+      summary: "Delete attachment",
+      description: "Delete an attachment by ID.",
+      tags: ["attachments"],
+      requestBody: z.object({
+        attachmentId: z.string(),
+      }),
       handler: async ({ req }) => handleDeleteAttachment(req),
     },
     {
       endpoint: "attachments/:id/content",
       method: "GET",
       policyKey: "attachments/content",
+      summary: "Get attachment content",
+      description:
+        "Serve raw file bytes for an attachment. Supports Range headers.",
+      tags: ["attachments"],
       handler: ({ req, params }) => handleGetAttachmentContent(params.id, req),
     },
     {
       endpoint: "attachments/:id",
       method: "GET",
       policyKey: "attachments",
+      summary: "Get attachment metadata",
+      description:
+        "Return metadata and optional base64 data for an attachment.",
+      tags: ["attachments"],
+      responseBody: z.object({
+        id: z.string(),
+        filename: z.string(),
+        mimeType: z.string(),
+        sizeBytes: z.number(),
+        kind: z.string(),
+        data: z.string().describe("Base64-encoded content"),
+        fileBacked: z.boolean(),
+      }),
       handler: ({ params }) => handleGetAttachment(params.id),
     },
   ];

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

@@ -1,5 +1,7 @@
 import { join } from "node:path";
 
+import { z } from "zod";
+
 import { getCharacterComponents } from "../../avatar/character-components.js";
 import {
   type CharacterTraits,
@@ -39,11 +41,25 @@ export function avatarRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "avatar/character-components",
       method: "GET",
+      summary: "Get character components",
+      description: "Return available avatar character components.",
+      tags: ["avatar"],
       handler: () => Response.json(getCharacterComponents()),
     },
     {
       endpoint: "avatar/render-from-traits",
       method: "POST",
+      summary: "Render avatar from traits",
+      description: "Write character traits and render an avatar PNG.",
+      tags: ["avatar"],
+      requestBody: z.object({
+        bodyShape: z.string(),
+        eyeStyle: z.string(),
+        color: z.string(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) => {
         let body: CharacterTraits;
         try {

package/src/runtime/routes/brain-graph-routes.ts

@@ -9,6 +9,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { count } from "drizzle-orm";
+import { z } from "zod";
 
 import { getDb } from "../../memory/db.js";
 import { memoryItems } from "../../memory/schema.js";
@@ -136,11 +137,28 @@ export function brainGraphRouteDefinitions(deps: {
     {
       endpoint: "brain-graph",
       method: "GET",
+      summary: "Get brain graph data",
+      description:
+        "Return a knowledge-graph shaped for brain-lobe visualization, with memory items mapped to brain regions.",
+      tags: ["brain-graph"],
+      responseBody: z.object({
+        entities: z.array(z.unknown()).describe("Graph entity nodes"),
+        relations: z.array(z.unknown()).describe("Graph relation edges"),
+        memorySummary: z
+          .array(z.unknown())
+          .describe("Memory kind counts and colors"),
+        totalKnowledgeCount: z.number().int(),
+        generatedAt: z.string().describe("ISO 8601 timestamp"),
+      }),
       handler: () => handleGetBrainGraph(),
     },
     {
       endpoint: "brain-graph-ui",
       method: "GET",
+      summary: "Serve brain graph UI",
+      description:
+        "Return the brain-graph HTML visualization page with an embedded auth token.",
+      tags: ["brain-graph"],
       handler: () => handleServeBrainGraphUI(deps.mintUiPageToken()),
     },
   ];

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

@@ -14,7 +14,13 @@
 
 import { existsSync, readFileSync } from "node:fs";
 
+import { z } from "zod";
+
 import { getConversationByKey } from "../../memory/conversation-key-store.js";
+import {
+  resolveChannelPersona,
+  resolveGuardianPersona,
+} from "../../prompts/persona-resolver.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
 import type { AuthContext } from "../auth/types.js";
@@ -144,10 +150,14 @@ async function handleBtw(
       (async () => {
         try {
           const isIntroRequest = conversationKey === IDENTITY_INTRO_KEY;
+          const userPersona = resolveGuardianPersona();
+          const channelPersona = resolveChannelPersona(undefined);
           const result = await runBtwSidechain({
             content: trimmedContent,
             conversation,
             signal: req.signal,
+            userPersona,
+            channelPersona,
             onEvent: (event) => {
               if (event.type === "text_delta") {
                 controller.enqueue(
@@ -222,6 +232,16 @@ export function btwRouteDefinitions(deps: {
       endpoint: "btw",
       method: "POST",
       policyKey: "btw",
+      summary: "Run ephemeral LLM side-chain",
+      description:
+        "Stream an ephemeral LLM call reusing the conversation's provider and message history. Response is SSE (btw_text_delta, btw_complete, btw_error).",
+      tags: ["btw"],
+      requestBody: z.object({
+        conversationKey: z
+          .string()
+          .describe("Conversation key to scope the call"),
+        content: z.string().describe("User prompt content"),
+      }),
       handler: async ({ req, authContext }) =>
         handleBtw(req, deps, authContext),
     },