@vellumai/assistant 0.7.1 → 0.7.3

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

@@ -6,10 +6,13 @@
  */
 import { z } from "zod";
 
-import { rawAll, rawGet, rawRun } from "../../memory/raw-query.js";
+import { saveDocument } from "../../documents/document-store.js";
+import { rawAll, rawGet } from "../../memory/raw-query.js";
 import { getLogger } from "../../util/logger.js";
+import { renderMarkdownToPDF } from "./document-pdf-renderer.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
 import type { RouteDefinition } from "./types.js";
+import { RouteResponse } from "./types.js";
 
 const log = getLogger("documents-routes");
 
@@ -25,80 +28,6 @@ interface DocumentRow {
 
 type DocumentListRow = Omit<DocumentRow, "content">;
 
-// ---------------------------------------------------------------------------
-// Junction table helper
-// ---------------------------------------------------------------------------
-
-/** Insert a document–conversation association (idempotent via INSERT OR IGNORE). */
-function addDocumentConversation(
-  surfaceId: string,
-  conversationId: string,
-): void {
-  rawRun(
-    /*sql*/ `INSERT OR IGNORE INTO document_conversations (surface_id, conversation_id, created_at) VALUES (?, ?, ?)`,
-    surfaceId,
-    conversationId,
-    Date.now(),
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Shared business logic (used by both message handlers and HTTP routes)
-// ---------------------------------------------------------------------------
-
-function saveDocument(params: {
-  surfaceId: string;
-  conversationId: string;
-  title: string;
-  content: string;
-  wordCount: number;
-}): { success: true; surfaceId: string } | { success: false; error: string } {
-  try {
-    const now = Date.now();
-    rawRun(
-      `INSERT INTO documents (surface_id, conversation_id, title, content, word_count, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?)
-       ON CONFLICT(surface_id) DO UPDATE SET
-         title = excluded.title,
-         content = excluded.content,
-         word_count = excluded.word_count,
-         updated_at = excluded.updated_at`,
-      params.surfaceId,
-      params.conversationId,
-      params.title,
-      params.content,
-      params.wordCount,
-      now,
-      now,
-    );
-    log.info(
-      { surfaceId: params.surfaceId, title: params.title },
-      "Saved document",
-    );
-
-    // Best-effort: associate the document with the conversation.
-    // Failures (e.g. migration not yet applied, table missing) must not
-    // cause the save response to report failure — the document itself is
-    // already persisted at this point.
-    try {
-      addDocumentConversation(params.surfaceId, params.conversationId);
-    } catch (err) {
-      log.warn(
-        { err, surfaceId: params.surfaceId },
-        "Failed to record document–conversation association",
-      );
-    }
-
-    return { success: true, surfaceId: params.surfaceId };
-  } catch (error) {
-    log.error({ err: error, surfaceId: params.surfaceId }, "Save error");
-    return {
-      success: false,
-      error: error instanceof Error ? error.message : "Unknown error",
-    };
-  }
-}
-
 function loadDocument(surfaceId: string):
   | {
       success: true;
@@ -312,4 +241,32 @@ export const ROUTES: RouteDefinition[] = [
       return result;
     },
   },
+
+  {
+    operationId: "exportDocumentPDF",
+    endpoint: "documents/:id/pdf",
+    method: "GET",
+    policyKey: "documents",
+    requirePolicyEnforcement: true,
+    summary: "Export a document as PDF",
+    description: "Render a document to PDF and return the binary content.",
+    tags: ["documents"],
+    handler: async ({ pathParams }) => {
+      const result = loadDocument(pathParams!.id);
+      if (!result.success) {
+        throw new NotFoundError(result.error);
+      }
+      const pdfBuffer = await renderMarkdownToPDF(result.title, result.content);
+      const filename =
+        result.title
+          .replace(/[^a-zA-Z0-9_-]/g, "-")
+          .replace(/-+/g, "-")
+          .replace(/^-|-$/g, "") || "document";
+      return new RouteResponse(new Uint8Array(pdfBuffer), {
+        "Content-Type": "application/pdf",
+        "Content-Disposition": `attachment; filename="${filename}.pdf"`,
+        "Content-Length": String(pdfBuffer.length),
+      });
+    },
+  },
 ];

package/src/runtime/routes/errors.ts

@@ -10,12 +10,27 @@
 export class RouteError extends Error {
   readonly code: string;
   readonly statusCode: number;
-
-  constructor(message: string, code: string, statusCode: number) {
+  /**
+   * Optional structured payload surfaced to clients in the standard
+   * error envelope as `error.details`. Use sparingly — only when the
+   * client genuinely needs machine-readable context beyond `code` and
+   * `message` (e.g. mirroring a platform-side response shape).
+   */
+  readonly details?: unknown;
+
+  constructor(
+    message: string,
+    code: string,
+    statusCode: number,
+    details?: unknown,
+  ) {
     super(message);
     this.name = "RouteError";
     this.code = code;
     this.statusCode = statusCode;
+    if (details !== undefined) {
+      this.details = details;
+    }
   }
 }
 
@@ -55,8 +70,8 @@ export class NotFoundError extends RouteError {
 }
 
 export class UnprocessableEntityError extends RouteError {
-  constructor(message: string) {
-    super(message, "UNPROCESSABLE_ENTITY", 422);
+  constructor(message: string, details?: unknown) {
+    super(message, "UNPROCESSABLE_ENTITY", 422, details);
     this.name = "UnprocessableEntityError";
   }
 }

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

@@ -18,8 +18,11 @@
  *   handles registration, touch (heartbeat), and unregistration (dispose).
  */
 
+import { z } from "zod";
+
 import type { HostProxyCapability } from "../../channels/types.js";
 import { parseInterfaceId, supportsHostProxy } from "../../channels/types.js";
+import { emitContactChange } from "../../contacts/contact-events.js";
 import { getOrCreateConversation } from "../../memory/conversation-key-store.js";
 import { getLogger } from "../../util/logger.js";
 import { formatSseFrame, formatSseHeartbeat } from "../assistant-event.js";
@@ -32,6 +35,7 @@ import {
   AssistantEventHub,
   assistantEventHub,
 } from "../assistant-event-hub.js";
+import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import { BadRequestError, ServiceUnavailableError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
@@ -77,10 +81,19 @@ export function handleSubscribeAssistantEvents(
   // ── Client identity from headers ──────────────────────────────────────
   const rawClientId = headers?.["x-vellum-client-id"];
   const rawInterfaceId = headers?.["x-vellum-interface-id"];
+  const rawMachineName = headers?.["x-vellum-machine-name"];
+  const rawActorPrincipalId = headers?.["x-vellum-actor-principal-id"];
   const clientId = rawClientId?.trim() || null;
   const interfaceId = clientId
     ? parseInterfaceId(rawInterfaceId?.trim())
     : null;
+  // Verified by RuntimeHttpServer and forwarded by the http-adapter from the
+  // bearer token's AuthContext. May be absent for legacy / service-token
+  // connections that have no principal. See `resolveActorPrincipalId` for the
+  // dev-bypass translation rationale.
+  const actorPrincipalId = resolveActorPrincipalIdForLocalGuardian(
+    rawActorPrincipalId?.trim() || undefined,
+  );
 
   if (clientId && !interfaceId) {
     log.error(
@@ -100,6 +113,7 @@ export function handleSubscribeAssistantEvents(
     "host_bash",
     "host_file",
     "host_cu",
+    "host_app_control",
     "host_browser",
   ];
 
@@ -165,6 +179,8 @@ export function handleSubscribeAssistantEvents(
             capabilities: ALL_CAPABILITIES.filter((cap) =>
               supportsHostProxy(interfaceId, cap),
             ),
+            machineName: rawMachineName?.trim() || undefined,
+            actorPrincipalId,
           })
         : hub.subscribe({
             ...subscriberBase,
@@ -231,7 +247,29 @@ export function handleSubscribeAssistantEvents(
 // Route definitions
 // ---------------------------------------------------------------------------
 
+const EmitEventBodySchema = z.object({
+  kind: z.enum(["contacts_changed"]),
+});
+
 export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "emit_event",
+    endpoint: "events/emit",
+    method: "POST",
+    summary: "Emit an assistant event",
+    description:
+      "Trigger an in-process assistant event by kind. Used by the gateway after owning a write that the assistant runtime would normally emit.",
+    tags: ["events"],
+    requestBody: EmitEventBodySchema,
+    responseStatus: "204",
+    handler: ({ body }) => {
+      const { kind } = EmitEventBodySchema.parse(body);
+      if (kind === "contacts_changed") {
+        emitContactChange();
+      }
+      return null;
+    },
+  },
   {
     operationId: "subscribe_assistant_events",
     endpoint: "events",

package/src/runtime/routes/gateway-log-routes.ts

@@ -0,0 +1,79 @@
+/**
+ * Gateway log tail route — gateway HTTP proxy.
+ *
+ * The handler makes a single HTTP call to the gateway's log-tail API
+ * and surfaces the body's `.error` message on non-OK responses.
+ */
+import { z } from "zod";
+
+import { getGatewayInternalBaseUrl } from "../../config/env.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ── Shared helper ───────────────────────────────────────────────────────
+
+async function gatewayFetch(
+  path: string,
+  init?: RequestInit,
+): Promise<unknown> {
+  const base = getGatewayInternalBaseUrl();
+  const res = await fetch(`${base}${path}`, init);
+  if (!res.ok) {
+    let message = `Gateway request failed (${res.status})`;
+    try {
+      const body = (await res.json()) as { error?: unknown };
+      if (typeof body.error === "string") {
+        message = body.error;
+      }
+    } catch {
+      // ignore JSON parse failures
+    }
+    throw new Error(message);
+  }
+  return res.json();
+}
+
+// ── Schemas ─────────────────────────────────────────────────────────────
+
+const LEVEL_NAMES = ["trace", "debug", "info", "warn", "error", "fatal"] as const;
+
+const GatewayLogsTailParams = z
+  .object({
+    n: z.coerce.number().int().min(1).max(1000).optional(),
+    level: z.enum(LEVEL_NAMES).optional(),
+    module: z.string().optional(),
+  })
+  .strict();
+
+// ── Handlers ────────────────────────────────────────────────────────────
+
+async function handleGatewayLogsTail({ queryParams = {}, body = {} }: RouteHandlerArgs) {
+  // HTTP GET delivers filters via queryParams; CLI IPC puts them in body.
+  const source = Object.keys(queryParams).length > 0 ? queryParams : body;
+  const p = GatewayLogsTailParams.parse(source);
+  const qs = new URLSearchParams();
+  if (p.n !== undefined) qs.set("n", String(p.n));
+  if (p.level !== undefined) qs.set("level", p.level);
+  if (p.module !== undefined) qs.set("module", p.module);
+  const query = qs.toString();
+  return gatewayFetch(`/v1/logs/tail${query ? `?${query}` : ""}`);
+}
+
+// ── Route definitions ───────────────────────────────────────────────────
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "gateway_logs_tail",
+    method: "GET",
+    endpoint: "gateway/logs/tail",
+    handler: handleGatewayLogsTail,
+    summary: "Tail gateway log entries",
+    description:
+      "Return the last N structured log entries from the gateway log files.",
+    tags: ["gateway-logs"],
+    queryParams: [
+      { name: "n", description: "Number of lines to return (1–1000, default: 10)" },
+      { name: "level", description: "Minimum pino level name (default: info)" },
+      { name: "module", description: "Filter to exact pino module name" },
+    ],
+  },
+];

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

@@ -71,14 +71,8 @@ export interface ApprovalInterceptionParams {
   approvalMessageTs?: string;
 }
 
-export interface ApprovalInterceptionResult {
-  handled: boolean;
-  type?:
-    | "decision_applied"
-    | "assistant_turn"
-    | "guardian_decision_applied"
-    | "stale_ignored";
-}
+import type { ApprovalInterceptionResult } from "./approval-interception-types.js";
+export type { ApprovalInterceptionResult } from "./approval-interception-types.js";
 
 /**
  * Check for pending approvals and handle inbound messages accordingly.

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

@@ -8,13 +8,16 @@
 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 {
+  getConfig,
+  invalidateConfigCache,
+  loadRawConfig,
+  saveRawConfig,
+} from "../../config/loader.js";
+import { listHeartbeatRuns } from "../../heartbeat/heartbeat-run-store.js";
 import { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
-import { getDb } from "../../memory/db-connection.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";
@@ -32,25 +35,20 @@ function handleListRuns(queryParams: Record<string, string>) {
   const limit = Number.isFinite(rawLimit)
     ? Math.min(Math.max(Math.floor(rawLimit), 1), 100)
     : 20;
-  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();
 
+  const runs = listHeartbeatRuns(limit);
   return {
-    runs: rows.map((r) => ({
+    runs: runs.map((r) => ({
       id: r.id,
-      title: r.title ?? "Heartbeat",
+      scheduledFor: r.scheduledFor,
+      startedAt: r.startedAt,
+      finishedAt: r.finishedAt,
+      durationMs: r.durationMs,
+      status: r.status,
+      skipReason: r.skipReason,
+      error: r.error,
+      conversationId: r.conversationId,
       createdAt: r.createdAt,
-      result: "ok",
     })),
   };
 }
@@ -102,7 +100,22 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      runs: z.array(z.unknown()).describe("Heartbeat run records"),
+      runs: z
+        .array(
+          z.object({
+            id: z.string(),
+            scheduledFor: z.number(),
+            startedAt: z.number().nullable(),
+            finishedAt: z.number().nullable(),
+            durationMs: z.number().nullable(),
+            status: z.string(),
+            skipReason: z.string().nullable(),
+            error: z.string().nullable(),
+            conversationId: z.string().nullable(),
+            createdAt: z.number(),
+          }),
+        )
+        .describe("Heartbeat run records"),
     }),
     handler: ({ queryParams }: RouteHandlerArgs) =>
       handleListRuns(queryParams ?? {}),
@@ -135,8 +148,7 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       success: z.boolean(),
     }),
-    handler: ({ body }: RouteHandlerArgs) =>
-      handleWriteChecklist(body ?? {}),
+    handler: ({ body }: RouteHandlerArgs) => handleWriteChecklist(body ?? {}),
   },
   {
     operationId: "getHeartbeatConfig",
@@ -152,6 +164,8 @@ export const ROUTES: RouteDefinition[] = [
       intervalMs: z.number(),
       activeHoursStart: z.number().nullable(),
       activeHoursEnd: z.number().nullable(),
+      cronExpression: z.string().nullable(),
+      timezone: z.string().nullable(),
       nextRunAt: z.number().nullable(),
       lastRunAt: z.number().nullable(),
       success: z.boolean(),
@@ -164,6 +178,8 @@ export const ROUTES: RouteDefinition[] = [
         intervalMs: config.intervalMs,
         activeHoursStart: config.activeHoursStart ?? null,
         activeHoursEnd: config.activeHoursEnd ?? null,
+        cronExpression: config.cronExpression ?? null,
+        timezone: config.timezone ?? null,
         nextRunAt: svc?.nextRunAt ?? null,
         lastRunAt: svc?.lastRunAt ?? null,
         success: true,
@@ -180,46 +196,95 @@ export const ROUTES: RouteDefinition[] = [
     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)"),
+      enabled: z.boolean().optional().describe("Enable or disable heartbeat"),
+      intervalMs: z.number().optional().describe("Heartbeat interval in ms"),
+      activeHoursStart: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Active hours start (0–23)"),
+      activeHoursEnd: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Active hours end (0–23)"),
+      cronExpression: z
+        .string()
+        .nullable()
+        .optional()
+        .describe(
+          "Cron expression for heartbeat timing, or null for fixed interval",
+        ),
+      timezone: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Timezone for cron evaluation"),
     }),
     responseBody: z.object({
       enabled: z.boolean(),
       intervalMs: z.number(),
       activeHoursStart: z.number().nullable(),
       activeHoursEnd: z.number().nullable(),
+      cronExpression: z.string().nullable(),
+      timezone: z.string().nullable(),
       nextRunAt: z.number().nullable(),
       lastRunAt: z.number().nullable(),
       success: z.boolean(),
     }),
     handler: async ({ body = {} }: RouteHandlerArgs) => {
-      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 (typeof body.activeHoursStart === "number")
-        heartbeat.activeHoursStart = body.activeHoursStart;
-      if (typeof body.activeHoursEnd === "number")
-        heartbeat.activeHoursEnd = body.activeHoursEnd;
+      // Build a patch containing only the fields the caller actually set.
+      // Writing back the full Zod-defaulted heartbeat object would bake
+      // defaults onto disk, masking later schema changes from the user.
+      // Use "key in body" checks for nullable fields so explicit null clears them.
+      const heartbeatPatch: Record<string, unknown> = {};
+      if ("enabled" in body && typeof body.enabled === "boolean")
+        heartbeatPatch.enabled = body.enabled;
+      if ("intervalMs" in body && typeof body.intervalMs === "number")
+        heartbeatPatch.intervalMs = body.intervalMs;
+      if ("activeHoursStart" in body)
+        heartbeatPatch.activeHoursStart =
+          typeof body.activeHoursStart === "number"
+            ? body.activeHoursStart
+            : null;
+      if ("activeHoursEnd" in body)
+        heartbeatPatch.activeHoursEnd =
+          typeof body.activeHoursEnd === "number" ? body.activeHoursEnd : null;
+      if ("cronExpression" in body)
+        heartbeatPatch.cronExpression =
+          typeof body.cronExpression === "string" ? body.cronExpression : null;
+      if ("timezone" in body)
+        heartbeatPatch.timezone =
+          typeof body.timezone === "string" ? body.timezone : null;
 
       try {
-        saveConfig({ ...config, heartbeat });
-        log.info({ heartbeat }, "Heartbeat config updated");
+        const raw = loadRawConfig();
+        raw.heartbeat = {
+          ...((raw.heartbeat as Record<string, unknown>) ?? {}),
+          ...heartbeatPatch,
+        };
+        saveRawConfig(raw);
+        invalidateConfigCache();
+        log.info({ heartbeat: heartbeatPatch }, "Heartbeat config updated");
       } catch (err) {
         log.error({ err }, "Failed to save heartbeat config");
         throw new InternalError("Failed to save config");
       }
 
+      // Read effective values back through the schema-defaulting loader so
+      // callers that only set a subset of fields still see the resolved
+      // (post-default) shape in the response.
+      const heartbeat = getConfig().heartbeat;
       const svc = HeartbeatService.getInstance();
+      svc?.reconfigure();
+
       return {
         enabled: heartbeat.enabled,
         intervalMs: heartbeat.intervalMs,
         activeHoursStart: heartbeat.activeHoursStart ?? null,
         activeHoursEnd: heartbeat.activeHoursEnd ?? null,
+        cronExpression: heartbeat.cronExpression ?? null,
+        timezone: heartbeat.timezone ?? null,
         nextRunAt: svc?.nextRunAt ?? null,
         lastRunAt: svc?.lastRunAt ?? null,
         success: true,