@vellumai/assistant 0.5.10 → 0.5.12

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),
     },

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

@@ -8,6 +8,8 @@
  * POST   /v1/calls/:callSessionId/instruction — relay an instruction to an active call
  */
 
+import { z } from "zod";
+
 import {
   answerCall,
   cancelCall,
@@ -288,31 +290,110 @@ export function callRouteDefinitions(deps: {
     {
       endpoint: "calls/start",
       method: "POST",
+      summary: "Start a call",
+      description:
+        "Initiate a new outbound phone call. Supports idempotency keys to prevent duplicate calls.",
+      tags: ["calls"],
       handler: async ({ req }) => handleStartCall(req, deps.assistantId),
+      requestBody: z.object({
+        phoneNumber: z.string().describe("Phone number to call").optional(),
+        task: z.string().describe("Task description for the call").optional(),
+        context: z
+          .string()
+          .describe("Additional context for the call")
+          .optional(),
+        conversationId: z.string().describe("Conversation to associate with"),
+        callerIdentityMode: z
+          .string()
+          .describe("Caller identity: 'assistant_number' or 'user_number'")
+          .optional(),
+        idempotencyKey: z
+          .string()
+          .describe("Idempotency key to prevent duplicate calls")
+          .optional(),
+      }),
+      responseBody: z.object({
+        callSessionId: z.string(),
+        callSid: z.string(),
+        status: z.string(),
+        toNumber: z.string(),
+        fromNumber: z.string(),
+        callerIdentityMode: z.string(),
+      }),
     },
     {
       endpoint: "calls/:id/cancel",
       method: "POST",
       policyKey: "calls/cancel",
+      summary: "Cancel a call",
+      description: "Cancel an active or pending call.",
+      tags: ["calls"],
       handler: async ({ req, params }) => handleCancelCall(req, params.id),
+      requestBody: z.object({
+        reason: z.string().describe("Cancellation reason"),
+      }),
+      responseBody: z.object({
+        callSessionId: z.string(),
+        status: z.string(),
+      }),
     },
     {
       endpoint: "calls/:id/answer",
       method: "POST",
       policyKey: "calls/answer",
+      summary: "Answer a pending call question",
+      description:
+        "Provide an answer to a pending question during an active call.",
+      tags: ["calls"],
       handler: async ({ req, params }) => handleAnswerCall(req, params.id),
+      requestBody: z.object({
+        answer: z.string().describe("Answer text"),
+        pendingQuestionId: z.string().describe("ID of the pending question"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+        questionId: z.string(),
+      }),
     },
     {
       endpoint: "calls/:id/instruction",
       method: "POST",
       policyKey: "calls/instruction",
+      summary: "Relay instruction to active call",
+      description: "Send a real-time instruction to an active call.",
+      tags: ["calls"],
       handler: async ({ req, params }) => handleInstructionCall(req, params.id),
+      requestBody: z.object({
+        instruction: z.string().describe("Instruction text to relay"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
     },
     {
       endpoint: "calls/:id",
       method: "GET",
       policyKey: "calls",
+      summary: "Get call status",
+      description: "Return the current status and details of a call session.",
+      tags: ["calls"],
       handler: ({ params }) => handleGetCallStatus(params.id),
+      responseBody: z.object({
+        callSessionId: z.string(),
+        conversationId: z.string(),
+        status: z.string(),
+        toNumber: z.string(),
+        fromNumber: z.string(),
+        provider: z.string(),
+        providerCallSid: z.string(),
+        task: z.string(),
+        startedAt: z.string(),
+        endedAt: z.string(),
+        lastError: z.string(),
+        pendingQuestion: z.object({}).passthrough(),
+        createdAt: z.string(),
+        updatedAt: z.string(),
+      }),
     },
   ];
 }

package/src/runtime/routes/channel-readiness-routes.ts

@@ -5,6 +5,8 @@
  * POST  /v1/channels/readiness/refresh  — invalidate cache and refresh readiness
  */
 
+import { z } from "zod";
+
 import type { ChannelId } from "../../channels/types.js";
 import { getReadinessService } from "../../daemon/handlers/config-channels.js";
 import {
@@ -64,13 +66,18 @@ export async function handleRefreshChannelReadiness(
   req: Request,
 ): Promise<Response> {
   let body: { channel?: ChannelId; includeRemote?: boolean };
-  try {
-    body = (await req.json()) as typeof body;
-  } catch {
-    return Response.json(
-      { success: false, error: "Invalid JSON in request body" },
-      { status: 400 },
-    );
+  const text = await req.text();
+  if (!text.trim()) {
+    body = {};
+  } else {
+    try {
+      body = JSON.parse(text) as typeof body;
+    } catch {
+      return Response.json(
+        { success: false, error: "Invalid JSON in request body" },
+        { status: 400 },
+      );
+    }
   }
 
   const service = getReadinessService();
@@ -123,12 +130,46 @@ export function channelReadinessRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "channels/readiness",
       method: "GET",
+      summary: "Get channel readiness",
+      description: "Return readiness snapshots for one or all channels.",
+      tags: ["channels"],
       handler: async ({ url }) => handleGetChannelReadiness(url),
+      queryParams: [
+        {
+          name: "channel",
+          schema: { type: "string" },
+          description: "Optional channel ID filter",
+        },
+        {
+          name: "includeRemote",
+          schema: { type: "string" },
+          description: "Include remote checks (default true)",
+        },
+      ],
+      responseBody: z.object({
+        success: z.boolean(),
+        snapshots: z.array(z.unknown()).describe("Channel readiness snapshots"),
+      }),
     },
     {
       endpoint: "channels/readiness/refresh",
       method: "POST",
+      summary: "Refresh channel readiness",
+      description: "Invalidate cache and re-evaluate channel readiness.",
+      tags: ["channels"],
       handler: async ({ req }) => handleRefreshChannelReadiness(req),
+      requestBody: z.object({
+        channel: z.string().describe("Optional channel ID to refresh"),
+        includeRemote: z
+          .boolean()
+          .describe("Include remote checks (default true)"),
+      }),
+      responseBody: z.object({
+        success: z.boolean(),
+        snapshots: z
+          .array(z.unknown())
+          .describe("Refreshed readiness snapshots"),
+      }),
     },
   ];
 }

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

@@ -8,6 +8,7 @@
  * - channel-guardian-routes.ts — guardian approval interception, expiry sweep
  */
 
+import type { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
 import type { RouteDefinition } from "../http-router.js";
 import type {
   ApprovalConversationGenerator,
@@ -53,17 +54,24 @@ export function channelRouteDefinitions(deps: {
   approvalConversationGenerator?: ApprovalConversationGenerator;
   guardianActionCopyGenerator?: GuardianActionCopyGenerator;
   guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator;
+  getHeartbeatService?: () => HeartbeatService | undefined;
 }): RouteDefinition[] {
   return [
     {
       endpoint: "channels/conversation",
       method: "DELETE",
+      summary: "Delete channel conversation",
+      description: "Delete a conversation by channel source.",
+      tags: ["channels"],
       handler: async ({ req }) =>
         _handleDeleteConversation(req, deps.assistantId),
     },
     {
       endpoint: "channels/inbound",
       method: "POST",
+      summary: "Process inbound channel message",
+      description: "Receive an inbound message from a channel integration.",
+      tags: ["channels"],
       handler: async ({ req }) =>
         _handleChannelInbound(
           req,
@@ -73,21 +81,31 @@ export function channelRouteDefinitions(deps: {
           deps.approvalConversationGenerator,
           deps.guardianActionCopyGenerator,
           deps.guardianFollowUpConversationGenerator,
+          deps.getHeartbeatService?.(),
         ),
     },
     {
       endpoint: "channels/delivery-ack",
       method: "POST",
+      summary: "Acknowledge channel delivery",
+      description: "Acknowledge delivery of a channel message.",
+      tags: ["channels"],
       handler: async ({ req }) => _handleChannelDeliveryAck(req),
     },
     {
       endpoint: "channels/dead-letters",
       method: "GET",
+      summary: "List dead letters",
+      description: "Return undeliverable channel messages.",
+      tags: ["channels"],
       handler: () => _handleListDeadLetters(),
     },
     {
       endpoint: "channels/replay",
       method: "POST",
+      summary: "Replay dead letters",
+      description: "Retry delivery of dead-letter messages.",
+      tags: ["channels"],
       handler: async ({ req }) => _handleReplayDeadLetters(req),
     },
   ];