@vellumai/assistant 0.5.9 → 0.5.11

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

@@ -4,6 +4,8 @@
 
 import { statSync } from "node:fs";
 
+import { z } from "zod";
+
 import { getConfig } from "../../config/loader.js";
 import { countConversations } from "../../memory/conversation-queries.js";
 import { rawAll } from "../../memory/db.js";
@@ -93,7 +95,28 @@ export function debugRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "debug",
       method: "GET",
+      summary: "Debug introspection",
+      description:
+        "Return runtime diagnostics: uptime, provider info, memory stats, job counts, and schedule counts.",
+      tags: ["debug"],
       handler: () => handleDebug(),
+      responseBody: z.object({
+        session: z.object({}).passthrough().describe("Uptime and start time"),
+        provider: z
+          .object({})
+          .passthrough()
+          .describe("Inference provider configuration"),
+        memory: z
+          .object({})
+          .passthrough()
+          .describe("Conversation and memory item counts"),
+        jobs: z.object({}).passthrough().describe("Background job counts"),
+        schedules: z
+          .object({})
+          .passthrough()
+          .describe("Schedule counts (total, enabled)"),
+        timestamp: z.string().describe("Current server timestamp (ISO 8601)"),
+      }),
     },
   ];
 }

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

@@ -2,6 +2,8 @@
  * HTTP route handlers for dictation processing.
  */
 
+import { z } from "zod";
+
 import {
   type ProfileResolution,
   resolveProfile,
@@ -435,6 +437,34 @@ export function diagnosticsRouteDefinitions(): RouteDefinition[] {
       endpoint: "dictation",
       method: "POST",
       policyKey: "dictation",
+      summary: "Process dictation",
+      description:
+        "Classify voice input as dictation or action, clean up text, and apply user style preferences.",
+      tags: ["diagnostics"],
+      requestBody: z.object({
+        transcription: z.string().describe("Raw speech transcription"),
+        context: z
+          .object({})
+          .passthrough()
+          .describe(
+            "Dictation context (app name, window title, bundle ID, cursor state, selected text)",
+          ),
+        profileId: z
+          .string()
+          .describe("Optional dictation profile ID")
+          .optional(),
+      }),
+      responseBody: z.object({
+        text: z.string().describe("Processed text output"),
+        mode: z
+          .string()
+          .describe("Detected mode: dictation, command, or action"),
+        actionPlan: z
+          .string()
+          .describe("Action plan (only when mode is action)"),
+        resolvedProfileId: z.string().describe("Resolved dictation profile ID"),
+        profileSource: z.string().describe("How the profile was resolved"),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as DictationBody;
         if (!body.transcription) {

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

@@ -4,6 +4,8 @@
  * Exposes document CRUD over HTTP, sharing business logic with the
  * handlers in `daemon/handlers/documents.ts`.
  */
+import { z } from "zod";
+
 import { rawAll, rawGet, rawRun } from "../../memory/db.js";
 import { getLogger } from "../../util/logger.js";
 import { httpError } from "../http-errors.js";
@@ -161,6 +163,19 @@ export function documentRouteDefinitions(): RouteDefinition[] {
       endpoint: "documents",
       method: "GET",
       policyKey: "documents",
+      summary: "List documents",
+      description: "Return all documents, optionally filtered by conversation.",
+      tags: ["documents"],
+      queryParams: [
+        {
+          name: "conversationId",
+          schema: { type: "string" },
+          description: "Filter by conversation ID",
+        },
+      ],
+      responseBody: z.object({
+        documents: z.array(z.unknown()).describe("Document summary objects"),
+      }),
       handler: ({ url }) => {
         const conversationId =
           url.searchParams.get("conversationId") ?? undefined;
@@ -172,6 +187,19 @@ export function documentRouteDefinitions(): RouteDefinition[] {
       endpoint: "documents/:id",
       method: "GET",
       policyKey: "documents",
+      summary: "Get a document",
+      description: "Return a single document by surface ID.",
+      tags: ["documents"],
+      responseBody: z.object({
+        success: z.boolean(),
+        surfaceId: z.string(),
+        conversationId: z.string(),
+        title: z.string(),
+        content: z.string(),
+        wordCount: z.number(),
+        createdAt: z.number(),
+        updatedAt: z.number(),
+      }),
       handler: ({ params }) => {
         const result = loadDocument(params.id);
         if (!result.success) {
@@ -184,6 +212,20 @@ export function documentRouteDefinitions(): RouteDefinition[] {
       endpoint: "documents",
       method: "POST",
       policyKey: "documents",
+      summary: "Save a document",
+      description: "Create or upsert a document (by surfaceId).",
+      tags: ["documents"],
+      requestBody: z.object({
+        surfaceId: z.string().describe("Surface ID (unique key)"),
+        conversationId: z.string().describe("Owning conversation"),
+        title: z.string().describe("Document title"),
+        content: z.string().describe("Document content"),
+        wordCount: z.number().describe("Word count"),
+      }),
+      responseBody: z.object({
+        success: z.boolean(),
+        surfaceId: z.string(),
+      }),
       handler: async ({ req }) => {
         const body = (await req.json()) as {
           surfaceId?: string;

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

@@ -215,6 +215,16 @@ export function eventsRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "events",
       method: "GET",
+      summary: "Subscribe to assistant events",
+      description: "Stream assistant events as Server-Sent Events (SSE).",
+      tags: ["events"],
+      queryParams: [
+        {
+          name: "conversationKey",
+          schema: { type: "string" },
+          description: "Scope to a single conversation",
+        },
+      ],
       handler: ({ req, url, authContext }) =>
         handleSubscribeAssistantEvents(req, url, { authContext }),
     },

package/src/runtime/routes/global-search-routes.ts

@@ -8,6 +8,8 @@
  * and merges results with lexical matches.
  */
 
+import { z } from "zod";
+
 import { getConfig } from "../../config/loader.js";
 import { searchContacts } from "../../contacts/contact-store.js";
 import { searchConversations } from "../../memory/conversation-queries.js";
@@ -273,6 +275,39 @@ export function globalSearchRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "search/global",
       method: "GET",
+      summary: "Global search",
+      description:
+        "Federated search across conversations, memories, schedules, and contacts.",
+      tags: ["search"],
+      queryParams: [
+        {
+          name: "q",
+          schema: { type: "string" },
+          description: "Search query (required)",
+        },
+        {
+          name: "limit",
+          schema: { type: "integer" },
+          description: "Max results per category (1–100, default 20)",
+        },
+        {
+          name: "categories",
+          schema: { type: "string" },
+          description: "Comma-separated categories to search",
+        },
+        {
+          name: "deep",
+          schema: { type: "string" },
+          description: "Enable semantic search for memories (true/false)",
+        },
+      ],
+      responseBody: z.object({
+        query: z.string(),
+        results: z
+          .object({})
+          .passthrough()
+          .describe("Results grouped by category"),
+      }),
       handler: async ({ url }) => handleGlobalSearch(url),
     },
   ];

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

@@ -11,6 +11,10 @@
  * Guardian decisions additionally verify the actor is the bound guardian
  * via the AuthContext's actorPrincipalId.
  */
+import { z } from "zod";
+
+import { isHttpAuthDisabled } from "../../config/env.js";
+import { findGuardianForChannel } from "../../contacts/contact-store.js";
 import {
   type CanonicalGuardianRequest,
   listPendingRequestsByConversationScope,
@@ -91,14 +95,25 @@ export async function handleGuardianActionDecision(
     return httpError("BAD_REQUEST", "action is required", 400);
   }
 
+  // Resolve the actor's guardian principal ID. For JWT-verified actors this
+  // comes from the token claims. For dev bypass (HTTP auth disabled) the
+  // synthetic "dev-bypass" principal won't match the real guardian binding,
+  // so fall back to the local guardian binding to avoid identity_mismatch.
+  let guardianPrincipalId: string | undefined =
+    authContext.actorPrincipalId ?? undefined;
+  if (isHttpAuthDisabled() && authContext.actorPrincipalId === "dev-bypass") {
+    const binding = findGuardianForChannel("vellum");
+    guardianPrincipalId = binding?.contact.principalId ?? undefined;
+  }
+
   const result = await processGuardianDecision({
     requestId,
     action,
     conversationId,
     channel: "vellum",
     actorContext: {
-      actorPrincipalId: authContext.actorPrincipalId ?? undefined,
-      guardianPrincipalId: authContext.actorPrincipalId ?? undefined,
+      actorPrincipalId: guardianPrincipalId,
+      guardianPrincipalId,
     },
   });
 
@@ -248,12 +263,42 @@ export function guardianActionRouteDefinitions(): RouteDefinition[] {
     {
       endpoint: "guardian-actions/pending",
       method: "GET",
+      summary: "List pending guardian actions",
+      description:
+        "Return pending guardian decision prompts for a conversation.",
+      tags: ["guardian"],
+      queryParams: [
+        {
+          name: "conversationId",
+          schema: { type: "string" },
+          description: "Conversation ID (required)",
+        },
+      ],
+      responseBody: z.object({
+        conversationId: z.string(),
+        prompts: z
+          .array(z.unknown())
+          .describe("Guardian decision prompt objects"),
+      }),
       handler: ({ url, authContext }) =>
         handleGuardianActionsPending(url, authContext),
     },
     {
       endpoint: "guardian-actions/decision",
       method: "POST",
+      summary: "Submit guardian decision",
+      description: "Submit a guardian action decision (approve/reject).",
+      tags: ["guardian"],
+      requestBody: z.object({
+        requestId: z.string().describe("Guardian request ID"),
+        action: z.string().describe("Decision action"),
+        conversationId: z.string().describe("Conversation ID").optional(),
+      }),
+      responseBody: z.object({
+        applied: z.boolean(),
+        requestId: z.string(),
+        reason: z.string(),
+      }),
       handler: async ({ req, authContext }) =>
         handleGuardianActionDecision(req, authContext),
     },

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

@@ -2,6 +2,7 @@
  * Approval prompt delivery: rich UI (buttons) with plain-text fallback.
  */
 import type { ChannelId } from "../../channels/types.js";
+import { redactSecrets } from "../../security/secret-scanner.js";
 import { getLogger } from "../../util/logger.js";
 import type { ApprovalMessageContext } from "../approval-message-composer.js";
 import { composeApprovalMessageGenerative } from "../approval-message-composer.js";
@@ -20,6 +21,66 @@ import { requiredDecisionKeywords } from "./channel-route-shared.js";
 
 const log = getLogger("runtime-http");
 
+// ---------------------------------------------------------------------------
+// Tool input summary for rich-UI approval prompts
+// ---------------------------------------------------------------------------
+
+/** Max characters for the tool input preview line. */
+const INPUT_PREVIEW_MAX_LENGTH = 200;
+
+/**
+ * Extract a concise, human-readable preview of the tool input so that
+ * sequential approval prompts for the same tool are distinguishable.
+ *
+ * Returns `null` when no meaningful preview can be produced.
+ */
+/** Escape backticks in user-controlled input so they don't break inline code spans. */
+function escapeBackticks(value: string): string {
+  return value.replace(/`/g, "'");
+}
+
+/** Redact potential secrets from tool input before previewing. */
+function sanitizePreviewValue(value: string): string {
+  return escapeBackticks(redactSecrets(value));
+}
+
+function formatToolInputPreview(
+  toolName: string,
+  toolInput: Record<string, unknown>,
+): string | null {
+  // Pick the most relevant field based on tool type
+  const command = toolInput.command ?? toolInput.cmd;
+  if (typeof command === "string" && command.length > 0) {
+    return truncatePreview(`\`${sanitizePreviewValue(command)}\``);
+  }
+
+  const path = toolInput.path ?? toolInput.file_path ?? toolInput.filePath;
+  if (typeof path === "string" && path.length > 0) {
+    const verb =
+      toolName.includes("write") || toolName.includes("edit")
+        ? "writing to"
+        : toolName.includes("read")
+          ? "reading"
+          : "on";
+    return truncatePreview(`${verb} \`${sanitizePreviewValue(path)}\``);
+  }
+
+  const url = toolInput.url;
+  if (typeof url === "string" && url.length > 0) {
+    return truncatePreview(`fetching \`${sanitizePreviewValue(url)}\``);
+  }
+
+  return null;
+}
+
+function truncatePreview(text: string): string {
+  if (text.length <= INPUT_PREVIEW_MAX_LENGTH) return text;
+  const truncated = text.slice(0, INPUT_PREVIEW_MAX_LENGTH - 1) + "…";
+  // Preserve backtick pairing so markdown renders correctly.
+  const openBackticks = (truncated.match(/`/g) || []).length;
+  return openBackticks % 2 !== 0 ? truncated + "`" : truncated;
+}
+
 export interface DeliverGeneratedApprovalPromptParams {
   replyCallbackUrl: string;
   chatId: string;
@@ -61,15 +122,29 @@ export async function deliverGeneratedApprovalPrompt(
       approvalCopyGenerator,
     );
 
+    // Append a tool input preview so sequential approvals are distinguishable
+    let enrichedText = richText;
+    if (uiMetadata.permissionDetails) {
+      const preview = formatToolInputPreview(
+        uiMetadata.permissionDetails.toolName,
+        uiMetadata.permissionDetails.toolInput,
+      );
+      if (preview) {
+        enrichedText = `${enrichedText}\n\n${preview}`;
+      }
+    }
+
     // Append a legend explaining what each button does
     const legend = buildActionLegend(uiMetadata.actions);
-    const richTextWithLegend = legend ? `${richText}\n\n${legend}` : richText;
+    if (legend) {
+      enrichedText = `${enrichedText}\n\n${legend}`;
+    }
 
     try {
       await deliverApprovalPrompt(
         replyCallbackUrl,
         chatId,
-        richTextWithLegend,
+        enrichedText,
         uiMetadata,
         assistantId,
         bearerToken,

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

@@ -0,0 +1,278 @@
+/**
+ * HTTP route handlers for heartbeat management.
+ */
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { desc, eq } from "drizzle-orm";
+import { z } from "zod";
+
+import { getConfig, saveConfig } from "../../config/loader.js";
+import type { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
+import { getDb } from "../../memory/db.js";
+import { conversations } from "../../memory/schema/conversations.js";
+import { readTextFileSync } from "../../util/fs.js";
+import { getLogger } from "../../util/logger.js";
+import { getWorkspacePromptPath } from "../../util/platform.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+const log = getLogger("heartbeat-routes");
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+function handleGetConfig(heartbeatService?: HeartbeatService): Response {
+  const config = getConfig().heartbeat;
+  return Response.json({
+    enabled: config.enabled,
+    intervalMs: config.intervalMs,
+    activeHoursStart: config.activeHoursStart ?? null,
+    activeHoursEnd: config.activeHoursEnd ?? null,
+    nextRunAt: heartbeatService?.nextRunAt ?? null,
+    lastRunAt: heartbeatService?.lastRunAt ?? null,
+    success: true,
+  });
+}
+
+function handleUpdateConfig(
+  body: Record<string, unknown>,
+  heartbeatService?: HeartbeatService,
+): Response {
+  const config = getConfig();
+  const heartbeat = { ...config.heartbeat };
+
+  if (typeof body.enabled === "boolean") heartbeat.enabled = body.enabled;
+  if (typeof body.intervalMs === "number")
+    heartbeat.intervalMs = body.intervalMs;
+  if ("activeHoursStart" in body) {
+    heartbeat.activeHoursStart =
+      typeof body.activeHoursStart === "number"
+        ? body.activeHoursStart
+        : undefined;
+  }
+  if ("activeHoursEnd" in body) {
+    heartbeat.activeHoursEnd =
+      typeof body.activeHoursEnd === "number" ? body.activeHoursEnd : undefined;
+  }
+
+  try {
+    saveConfig({ ...config, heartbeat });
+    log.info({ heartbeat }, "Heartbeat config updated via HTTP");
+  } catch (err) {
+    log.error({ err }, "Failed to save heartbeat config");
+    return httpError("INTERNAL_ERROR", "Failed to save config", 500);
+  }
+
+  return Response.json({
+    enabled: heartbeat.enabled,
+    intervalMs: heartbeat.intervalMs,
+    activeHoursStart: heartbeat.activeHoursStart ?? null,
+    activeHoursEnd: heartbeat.activeHoursEnd ?? null,
+    nextRunAt: heartbeatService?.nextRunAt ?? null,
+    lastRunAt: heartbeatService?.lastRunAt ?? null,
+    success: true,
+  });
+}
+
+function handleListRuns(limit: number): Response {
+  const db = getDb();
+  const rows = db
+    .select({
+      id: conversations.id,
+      title: conversations.title,
+      createdAt: conversations.createdAt,
+    })
+    .from(conversations)
+    .where(eq(conversations.source, "heartbeat"))
+    .orderBy(desc(conversations.createdAt))
+    .limit(limit)
+    .all();
+
+  return Response.json({
+    runs: rows.map((r) => ({
+      id: r.id,
+      title: r.title ?? "Heartbeat",
+      createdAt: r.createdAt,
+      result: "ok",
+    })),
+  });
+}
+
+async function handleRunNow(
+  heartbeatService?: HeartbeatService,
+): Promise<Response> {
+  if (!heartbeatService) {
+    return httpError(
+      "SERVICE_UNAVAILABLE",
+      "Heartbeat service not available",
+      503,
+    );
+  }
+
+  try {
+    const ran = await heartbeatService.runOnce({ force: true });
+    return Response.json({ success: true, ran });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err }, "Heartbeat run-now failed");
+    return Response.json({ success: false, error: message });
+  }
+}
+
+function handleGetChecklist(): Response {
+  const path = getWorkspacePromptPath("HEARTBEAT.md");
+  const content = readTextFileSync(path);
+  return Response.json({
+    content: content ?? "",
+    isDefault: content == null,
+  });
+}
+
+function handleWriteChecklist(content: string): Response {
+  const path = getWorkspacePromptPath("HEARTBEAT.md");
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, content, "utf-8");
+    log.info("Heartbeat checklist updated via HTTP");
+    return Response.json({ success: true });
+  } catch (err) {
+    log.error({ err }, "Failed to write heartbeat checklist");
+    return httpError("INTERNAL_ERROR", "Failed to write checklist", 500);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function heartbeatRouteDefinitions(deps: {
+  getHeartbeatService?: () => HeartbeatService | undefined;
+}): RouteDefinition[] {
+  return [
+    {
+      endpoint: "heartbeat/config",
+      method: "GET",
+      policyKey: "heartbeat",
+      summary: "Get heartbeat config",
+      description: "Return the current heartbeat schedule configuration.",
+      tags: ["heartbeat"],
+      responseBody: z.object({
+        enabled: z.boolean(),
+        intervalMs: z.number(),
+        activeHoursStart: z.number(),
+        activeHoursEnd: z.number(),
+        nextRunAt: z.string(),
+        success: z.boolean(),
+      }),
+      handler: () => handleGetConfig(deps.getHeartbeatService?.()),
+    },
+    {
+      endpoint: "heartbeat/config",
+      method: "PUT",
+      policyKey: "heartbeat",
+      summary: "Update heartbeat config",
+      description: "Update the heartbeat schedule configuration.",
+      tags: ["heartbeat"],
+      requestBody: z.object({
+        enabled: z.boolean().describe("Enable or disable heartbeat"),
+        intervalMs: z.number().describe("Heartbeat interval in ms"),
+        activeHoursStart: z.number().describe("Active hours start (0–23)"),
+        activeHoursEnd: z.number().describe("Active hours end (0–23)"),
+      }),
+      responseBody: z.object({
+        enabled: z.boolean(),
+        intervalMs: z.number(),
+        activeHoursStart: z.number(),
+        activeHoursEnd: z.number(),
+        nextRunAt: z.string(),
+        success: z.boolean(),
+      }),
+      handler: async ({ req }) => {
+        const body: unknown = await req.json();
+        if (typeof body !== "object" || !body || Array.isArray(body)) {
+          return httpError(
+            "BAD_REQUEST",
+            "Request body must be a JSON object",
+            400,
+          );
+        }
+        return handleUpdateConfig(
+          body as Record<string, unknown>,
+          deps.getHeartbeatService?.(),
+        );
+      },
+    },
+    {
+      endpoint: "heartbeat/runs",
+      method: "GET",
+      policyKey: "heartbeat",
+      summary: "List heartbeat runs",
+      description: "Return recent heartbeat conversation runs.",
+      tags: ["heartbeat"],
+      queryParams: [
+        {
+          name: "limit",
+          schema: { type: "integer" },
+          description: "Max runs to return (default 20)",
+        },
+      ],
+      responseBody: z.object({
+        runs: z.array(z.unknown()).describe("Heartbeat run records"),
+      }),
+      handler: ({ url }) => {
+        const limit = Number(url.searchParams.get("limit") ?? 20);
+        return handleListRuns(limit);
+      },
+    },
+    {
+      endpoint: "heartbeat/run-now",
+      method: "POST",
+      policyKey: "heartbeat",
+      summary: "Run heartbeat now",
+      description: "Trigger an immediate heartbeat run.",
+      tags: ["heartbeat"],
+      responseBody: z.object({
+        success: z.boolean(),
+        ran: z.boolean().describe("Whether the heartbeat actually ran"),
+      }),
+      handler: () => handleRunNow(deps.getHeartbeatService?.()),
+    },
+    {
+      endpoint: "heartbeat/checklist",
+      method: "GET",
+      policyKey: "heartbeat",
+      summary: "Get heartbeat checklist",
+      description: "Return the HEARTBEAT.md checklist content.",
+      tags: ["heartbeat"],
+      responseBody: z.object({
+        content: z.string().describe("Checklist markdown content"),
+        isDefault: z.boolean().describe("True when no custom checklist exists"),
+      }),
+      handler: () => handleGetChecklist(),
+    },
+    {
+      endpoint: "heartbeat/checklist",
+      method: "PUT",
+      policyKey: "heartbeat",
+      summary: "Write heartbeat checklist",
+      description: "Overwrite the HEARTBEAT.md checklist content.",
+      tags: ["heartbeat"],
+      requestBody: z.object({
+        content: z.string().describe("Checklist markdown content"),
+      }),
+      responseBody: z.object({
+        success: z.boolean(),
+      }),
+      handler: async ({ req }) => {
+        const body = (await req.json()) as { content?: string };
+        if (typeof body.content !== "string") {
+          return httpError("BAD_REQUEST", "content is required", 400);
+        }
+        return handleWriteChecklist(body.content);
+      },
+    },
+  ];
+}