@vellumai/assistant 0.5.9 → 0.5.11

package/src/runtime/routes/surface-action-routes.ts

@@ -4,12 +4,16 @@
  * POST /v1/surface-actions — dispatch a surface action to an active conversation.
  * Requires the conversation to already exist (does not create new conversations).
  */
+import { z } from "zod";
+
+import { isHttpAuthDisabled } from "../../config/env.js";
 import { getLogger } from "../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
 import type { AuthContext } from "../auth/types.js";
 import { healGuardianBindingDrift } from "../guardian-vellum-migration.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
+import { resolveLocalTrustContext } from "../local-actor-identity.js";
 import {
   resolveTrustContext,
   withSourceChannel,
@@ -55,32 +59,39 @@ function applyTrustContext(
   const sourceChannel = "vellum";
 
   if (authContext.actorPrincipalId) {
-    const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
-    let trustCtx = resolveTrustContext({
-      assistantId,
-      sourceChannel,
-      conversationExternalId: "local",
-      actorExternalId: authContext.actorPrincipalId,
-    });
-    if (trustCtx.trustClass === "unknown") {
-      const healed = healGuardianBindingDrift(authContext.actorPrincipalId);
-      if (healed) {
-        trustCtx = resolveTrustContext({
-          assistantId,
-          sourceChannel,
-          conversationExternalId: "local",
-          actorExternalId: authContext.actorPrincipalId,
-        });
-        log.info(
-          {
-            actorPrincipalId: authContext.actorPrincipalId,
-            trustClass: trustCtx.trustClass,
-          },
-          "Trust re-resolved after guardian binding drift heal (surface action)",
-        );
+    // Dev bypass (HTTP auth disabled): the synthetic "dev-bypass" principal
+    // won't match any guardian binding. Resolve from the local guardian
+    // binding instead, which produces the correct guardian trust context.
+    if (isHttpAuthDisabled() && authContext.actorPrincipalId === "dev-bypass") {
+      conversation.setTrustContext(resolveLocalTrustContext(sourceChannel));
+    } else {
+      const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+      let trustCtx = resolveTrustContext({
+        assistantId,
+        sourceChannel,
+        conversationExternalId: "local",
+        actorExternalId: authContext.actorPrincipalId,
+      });
+      if (trustCtx.trustClass === "unknown") {
+        const healed = healGuardianBindingDrift(authContext.actorPrincipalId);
+        if (healed) {
+          trustCtx = resolveTrustContext({
+            assistantId,
+            sourceChannel,
+            conversationExternalId: "local",
+            actorExternalId: authContext.actorPrincipalId,
+          });
+          log.info(
+            {
+              actorPrincipalId: authContext.actorPrincipalId,
+              trustClass: trustCtx.trustClass,
+            },
+            "Trust re-resolved after guardian binding drift heal (surface action)",
+          );
+        }
       }
+      conversation.setTrustContext(withSourceChannel(sourceChannel, trustCtx));
     }
-    conversation.setTrustContext(withSourceChannel(sourceChannel, trustCtx));
   } else {
     // Service principals or tokens without an actor ID get guardian context.
     conversation.setTrustContext({ trustClass: "guardian", sourceChannel });
@@ -209,6 +220,26 @@ export function surfaceActionRouteDefinitions(deps: {
     {
       endpoint: "surface-actions",
       method: "POST",
+      summary: "Trigger a surface action",
+      description:
+        "Execute an interactive action on a surface (e.g. button click, form submit).",
+      tags: ["surfaces"],
+      requestBody: z.object({
+        conversationId: z
+          .string()
+          .describe("Conversation that owns the surface")
+          .optional(),
+        surfaceId: z.string().describe("Surface to act on"),
+        actionId: z.string().describe("Action identifier"),
+        data: z
+          .object({})
+          .passthrough()
+          .describe("Action-specific payload")
+          .optional(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req, authContext }) => {
         if (!deps.findConversation) {
           return httpError(
@@ -228,6 +259,17 @@ export function surfaceActionRouteDefinitions(deps: {
     {
       endpoint: "surfaces/:id/undo",
       method: "POST",
+      summary: "Undo last surface action",
+      description: "Revert the most recent action on a surface.",
+      tags: ["surfaces"],
+      requestBody: z.object({
+        conversationId: z
+          .string()
+          .describe("Conversation that owns the surface"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req, params }) => {
         if (!deps.findConversation) {
           return httpError(

package/src/runtime/routes/surface-content-routes.ts

@@ -5,6 +5,8 @@
  * conversation's in-memory surface state. Used by clients to re-hydrate surfaces
  * whose data was stripped during memory compaction.
  */
+import { z } from "zod";
+
 import type {
   SurfaceData,
   SurfaceType,
@@ -45,6 +47,24 @@ export function surfaceContentRouteDefinitions(deps: {
     {
       endpoint: "surfaces/:surfaceId",
       method: "GET",
+      summary: "Get surface content",
+      description:
+        "Return the full surface payload from the conversation's in-memory surface state.",
+      tags: ["surfaces"],
+      queryParams: [
+        {
+          name: "conversationId",
+          schema: { type: "string" },
+          required: true,
+          description: "Conversation that owns the surface",
+        },
+      ],
+      responseBody: z.object({
+        surfaceId: z.string(),
+        surfaceType: z.string(),
+        title: z.string(),
+        data: z.object({}).passthrough().describe("Surface data payload"),
+      }),
       handler: ({ url, params }) => {
         if (!deps.findConversation) {
           return httpError(

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

@@ -4,6 +4,8 @@
  * POST /v1/telemetry/lifecycle — record a lifecycle event (app_open, hatch).
  */
 
+import { z } from "zod";
+
 import { recordLifecycleEvent } from "../../memory/lifecycle-events-store.js";
 import { getLogger } from "../../util/logger.js";
 import { httpError } from "../http-errors.js";
@@ -47,6 +49,16 @@ export function telemetryRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "telemetry/lifecycle",
       method: "POST",
+      summary: "Record lifecycle event",
+      description: "Record a telemetry lifecycle event (app_open, hatch).",
+      tags: ["telemetry"],
+      requestBody: z.object({
+        event_name: z.string().describe("Event name: app_open or hatch"),
+      }),
+      responseBody: z.object({
+        id: z.string().describe("Event ID"),
+        event_name: z.string(),
+      }),
       handler: async ({ req }) => handleRecordLifecycleEvent(req),
     },
   ];

package/src/runtime/routes/trace-event-routes.ts

@@ -4,6 +4,8 @@
  * GET /v1/trace-events — Returns persisted trace events for a conversation.
  */
 
+import { z } from "zod";
+
 import { getTraceEvents } from "../../memory/trace-event-store.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
@@ -17,6 +19,29 @@ export function traceEventRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "trace-events",
       method: "GET",
+      summary: "List trace events",
+      description: "Return persisted trace events for a conversation.",
+      tags: ["trace"],
+      queryParams: [
+        {
+          name: "conversationId",
+          schema: { type: "string" },
+          description: "Conversation ID (required)",
+        },
+        {
+          name: "limit",
+          schema: { type: "integer" },
+          description: "Max events to return",
+        },
+        {
+          name: "afterSequence",
+          schema: { type: "integer" },
+          description: "Return events after this sequence number",
+        },
+      ],
+      responseBody: z.object({
+        events: z.array(z.unknown()).describe("Trace event objects"),
+      }),
       handler: ({ url }) => {
         const conversationId = url.searchParams.get("conversationId");
         if (!conversationId) {

package/src/runtime/routes/trust-rules-routes.ts

@@ -5,6 +5,8 @@
  * the approval-flow trust-rule endpoint in approval-routes.ts.
  * All endpoints are bearer-token authenticated (standard runtime auth).
  */
+import { z } from "zod";
+
 import {
   addRule,
   getAllRules,
@@ -176,21 +178,65 @@ export function trustRulesRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "trust-rules/manage",
       method: "GET",
+      summary: "List all trust rules",
+      description: "Return all persistent trust rules.",
+      tags: ["trust-rules"],
+      responseBody: z.object({
+        type: z.string(),
+        rules: z.array(z.unknown()).describe("Trust rule objects"),
+      }),
       handler: () => handleListTrustRules(),
     },
     {
       endpoint: "trust-rules/manage",
       method: "POST",
+      summary: "Add a trust rule",
+      description:
+        "Create a new persistent trust rule (standalone, not approval-flow).",
+      tags: ["trust-rules"],
+      requestBody: z.object({
+        toolName: z.string().describe("Tool name"),
+        pattern: z.string().describe("Allowlist pattern"),
+        scope: z.string().describe("Scope"),
+        decision: z.string().describe("allow, deny, or ask"),
+        allowHighRisk: z
+          .boolean()
+          .describe("Allow high-risk invocations")
+          .optional(),
+        executionTarget: z.string().describe("Execution target").optional(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) => handleAddTrustRuleManage(req),
     },
     {
       endpoint: "trust-rules/manage/:id",
       method: "DELETE",
+      summary: "Remove a trust rule",
+      description: "Delete a trust rule by ID.",
+      tags: ["trust-rules"],
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: ({ params }) => handleRemoveTrustRuleManage(params.id),
     },
     {
       endpoint: "trust-rules/manage/:id",
       method: "PATCH",
+      summary: "Update a trust rule",
+      description: "Partially update fields on an existing trust rule.",
+      tags: ["trust-rules"],
+      requestBody: z.object({
+        tool: z.string().describe("Tool name"),
+        pattern: z.string().describe("Allowlist pattern"),
+        scope: z.string().describe("Scope"),
+        decision: z.string().describe("allow, deny, or ask"),
+        priority: z.number().describe("Rule priority"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req, params }) =>
         handleUpdateTrustRuleManage(req, params.id),
     },

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

@@ -3,7 +3,7 @@
  *
  * POST /v1/messages/:id/tts?conversationId=... — synthesize message text to audio
  *
- * Gated behind the `feature_flags.message-tts.enabled` assistant feature flag.
+ * Gated behind the `message-tts` assistant feature flag.
  * Uses Fish Audio for synthesis when configured.
  */
 
@@ -18,7 +18,7 @@ import type { RouteDefinition } from "../http-router.js";
 
 const log = getLogger("tts-routes");
 
-const MESSAGE_TTS_FLAG = "feature_flags.message-tts.enabled" as const;
+const MESSAGE_TTS_FLAG = "message-tts" as const;
 
 // ---------------------------------------------------------------------------
 // Route definitions
@@ -30,6 +30,17 @@ export function ttsRouteDefinitions(): RouteDefinition[] {
       endpoint: "messages/:id/tts",
       method: "POST",
       policyKey: "messages/tts",
+      summary: "Synthesize message to speech",
+      description:
+        "Synthesize a message's text content to audio using Fish Audio TTS.",
+      tags: ["messages"],
+      queryParams: [
+        {
+          name: "conversationId",
+          schema: { type: "string" },
+          description: "Conversation that contains the message",
+        },
+      ],
       handler: async ({ url, params }) => {
         const config = getConfig();
 
@@ -50,8 +61,8 @@ export function ttsRouteDefinitions(): RouteDefinition[] {
           return httpError("BAD_REQUEST", "Message has no text content", 400);
         }
 
-        const sanitizedText = sanitizeForTts(result.text);
-        if (!sanitizedText.trim()) {
+        const sanitizedText = sanitizeForTts(result.text).trim();
+        if (!sanitizedText) {
           return httpError(
             "BAD_REQUEST",
             "Message has no speakable text content",

package/src/runtime/routes/upgrade-broadcast-routes.ts

@@ -9,6 +9,8 @@
  * minted service token.
  */
 
+import { z } from "zod";
+
 import type {
   ServiceGroupUpdateComplete,
   ServiceGroupUpdateProgress,
@@ -25,6 +27,42 @@ export function upgradeBroadcastRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "admin/upgrade-broadcast",
       method: "POST",
+      summary: "Broadcast upgrade lifecycle event",
+      description:
+        "Publish a service group update lifecycle event (starting, progress, or complete) to all connected SSE clients.",
+      tags: ["admin"],
+      requestBody: z.object({
+        type: z
+          .string()
+          .describe('Event type: "starting", "progress", or "complete"'),
+        targetVersion: z
+          .string()
+          .describe("Target version (required for starting)")
+          .optional(),
+        expectedDowntimeSeconds: z
+          .number()
+          .describe("Expected downtime in seconds (starting, default 60)")
+          .optional(),
+        statusMessage: z
+          .string()
+          .describe("Status message (required for progress)")
+          .optional(),
+        installedVersion: z
+          .string()
+          .describe("Installed version (required for complete)")
+          .optional(),
+        success: z
+          .boolean()
+          .describe("Whether upgrade succeeded (required for complete)")
+          .optional(),
+        rolledBackToVersion: z
+          .string()
+          .describe("Version rolled back to, if any (complete)")
+          .optional(),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
       handler: async ({ req }) => {
         let body: unknown;
         try {

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

@@ -6,6 +6,8 @@
  * GET /v1/usage/breakdown?from=&to=&groupBy=  — grouped breakdown (actor, provider, model)
  */
 
+import { z } from "zod";
+
 import {
   getUsageDayBuckets,
   getUsageGroupBreakdown,
@@ -63,6 +65,21 @@ export function usageRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "usage/totals",
       method: "GET",
+      summary: "Get usage totals",
+      description: "Return aggregate usage totals for a time range.",
+      tags: ["usage"],
+      queryParams: [
+        {
+          name: "from",
+          schema: { type: "integer" },
+          description: "Start epoch millis (required)",
+        },
+        {
+          name: "to",
+          schema: { type: "integer" },
+          description: "End epoch millis (required)",
+        },
+      ],
       handler: ({ url }) => {
         const range = parseTimeRange(url);
         if (range instanceof Response) return range;
@@ -73,6 +90,24 @@ export function usageRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "usage/daily",
       method: "GET",
+      summary: "Get daily usage",
+      description: "Return per-day usage buckets for a time range.",
+      tags: ["usage"],
+      queryParams: [
+        {
+          name: "from",
+          schema: { type: "integer" },
+          description: "Start epoch millis (required)",
+        },
+        {
+          name: "to",
+          schema: { type: "integer" },
+          description: "End epoch millis (required)",
+        },
+      ],
+      responseBody: z.object({
+        buckets: z.array(z.unknown()).describe("Daily usage bucket objects"),
+      }),
       handler: ({ url }) => {
         const range = parseTimeRange(url);
         if (range instanceof Response) return range;
@@ -83,6 +118,30 @@ export function usageRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "usage/breakdown",
       method: "GET",
+      summary: "Get usage breakdown",
+      description:
+        "Return grouped usage breakdown (by actor, provider, or model).",
+      tags: ["usage"],
+      queryParams: [
+        {
+          name: "from",
+          schema: { type: "integer" },
+          description: "Start epoch millis (required)",
+        },
+        {
+          name: "to",
+          schema: { type: "integer" },
+          description: "End epoch millis (required)",
+        },
+        {
+          name: "groupBy",
+          schema: { type: "string" },
+          description: "Group by: actor, provider, or model (required)",
+        },
+      ],
+      responseBody: z.object({
+        breakdown: z.array(z.unknown()).describe("Grouped usage entries"),
+      }),
       handler: ({ url }) => {
         const range = parseTimeRange(url);
         if (range instanceof Response) return range;

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

@@ -5,6 +5,8 @@
  * zero dependency on CU session state.
  */
 
+import { z } from "zod";
+
 import { getLogger } from "../../util/logger.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
@@ -122,7 +124,33 @@ export function watchRouteDefinitions(deps: {
       endpoint: "computer-use/watch",
       method: "POST",
       policyKey: "computer-use/watch",
+      summary: "Submit watch observation",
+      description: "Send a screen observation from ambient watch mode.",
+      tags: ["computer-use"],
       handler: async ({ req }) => handleWatchObservationRoute(req, getDeps()),
+      requestBody: z.object({
+        watchId: z.string().describe("Watch session ID"),
+        conversationId: z.string().describe("Conversation to associate with"),
+        ocrText: z.string().describe("OCR text from screen capture"),
+        appName: z.string().describe("Active application name").optional(),
+        windowTitle: z.string().describe("Active window title").optional(),
+        bundleIdentifier: z
+          .string()
+          .describe("Application bundle identifier")
+          .optional(),
+        timestamp: z.number().describe("Capture timestamp (epoch ms)"),
+        captureIndex: z
+          .number()
+          .int()
+          .describe("Index of this capture in the batch"),
+        totalExpected: z
+          .number()
+          .int()
+          .describe("Total captures expected in the batch"),
+      }),
+      responseBody: z.object({
+        ok: z.boolean(),
+      }),
     },
   ];
 }

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

@@ -5,6 +5,8 @@
  * sharing business logic with the handlers in
  * `daemon/handlers/work-items.ts`.
  */
+import { z } from "zod";
+
 import type { Conversation } from "../../daemon/conversation.js";
 import type { ServerMessage } from "../../daemon/message-protocol.js";
 import { getMessages } from "../../memory/conversation-crud.js";
@@ -417,6 +419,12 @@ export function workItemRouteDefinitions(
       endpoint: "work-items",
       method: "GET",
       policyKey: "work-items",
+      summary: "List work items",
+      description: "Return work items, optionally filtered by status.",
+      tags: ["work-items"],
+      responseBody: z.object({
+        items: z.array(z.unknown()),
+      }),
       handler: ({ url }) => {
         const status = url.searchParams.get("status") ?? undefined;
         const items = listWorkItems(
@@ -431,6 +439,9 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id",
       method: "GET",
       policyKey: "work-items",
+      summary: "Get a work item",
+      description: "Return a single work item by ID.",
+      tags: ["work-items"],
       handler: ({ params }) => {
         const item = getWorkItem(params.id) ?? null;
         if (!item) {
@@ -445,6 +456,17 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id",
       method: "PATCH",
       policyKey: "work-items",
+      summary: "Update a work item",
+      description:
+        "Partially update a work item's title, notes, status, or priority.",
+      tags: ["work-items"],
+      requestBody: z.object({
+        title: z.string(),
+        notes: z.string(),
+        status: z.string(),
+        priorityTier: z.number().int(),
+        sortIndex: z.number().int(),
+      }),
       handler: async ({ req, params }) => {
         const body = (await req.json()) as {
           title?: string;
@@ -490,6 +512,9 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id/complete",
       method: "POST",
       policyKey: "work-items/complete",
+      summary: "Complete a work item",
+      description: "Transition a work item from awaiting_review to done.",
+      tags: ["work-items"],
       handler: ({ params }) => {
         const existing = getWorkItem(params.id);
         if (!existing) {
@@ -521,6 +546,9 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id",
       method: "DELETE",
       policyKey: "work-items",
+      summary: "Delete a work item",
+      description: "Permanently remove a work item.",
+      tags: ["work-items"],
       handler: ({ params }) => {
         const existing = getWorkItem(params.id);
         if (!existing) {
@@ -537,6 +565,9 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id/cancel",
       method: "POST",
       policyKey: "work-items/cancel",
+      summary: "Cancel a running work item",
+      description: "Abort a running work item and set its status to cancelled.",
+      tags: ["work-items"],
       handler: ({ params }) => {
         const workItem = getWorkItem(params.id);
         if (!workItem) {
@@ -577,6 +608,14 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id/approve-permissions",
       method: "POST",
       policyKey: "work-items/approve-permissions",
+      summary: "Approve tool permissions",
+      description: "Pre-approve a set of tools for a work item before it runs.",
+      tags: ["work-items"],
+      requestBody: z.object({
+        approvedTools: z
+          .array(z.unknown())
+          .describe("Array of tool names to approve"),
+      }),
       handler: async ({ req, params }) => {
         const body = (await req.json()) as { approvedTools?: string[] };
         if (!Array.isArray(body.approvedTools)) {
@@ -602,6 +641,14 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id/preflight",
       method: "POST",
       policyKey: "work-items/preflight",
+      summary: "Preflight check",
+      description: "Check tool permissions needed before running a work item.",
+      tags: ["work-items"],
+      responseBody: z.object({
+        id: z.string(),
+        success: z.boolean(),
+        permissions: z.object({}).passthrough(),
+      }),
       handler: async ({ params }) => {
         const result = await preflightWorkItem(params.id);
         if (!result.success) {
@@ -620,6 +667,10 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id/run",
       method: "POST",
       policyKey: "work-items/run",
+      summary: "Run a work item",
+      description:
+        "Execute the task associated with a work item. Returns immediately; execution happens in the background.",
+      tags: ["work-items"],
       handler: async ({ params }) => {
         const workItem = getWorkItem(params.id);
         if (!workItem) {
@@ -782,6 +833,14 @@ export function workItemRouteDefinitions(
       endpoint: "work-items/:id/output",
       method: "GET",
       policyKey: "work-items/output",
+      summary: "Get work item output",
+      description: "Return the final output of a completed work item run.",
+      tags: ["work-items"],
+      responseBody: z.object({
+        id: z.string(),
+        success: z.boolean(),
+        output: z.object({}).passthrough(),
+      }),
       handler: ({ params }) => {
         try {
           const result = getWorkItemOutput(params.id);