@vellumai/assistant 0.7.1 → 0.7.2

package/src/runtime/routes/contact-prompt-routes.ts

@@ -0,0 +1,183 @@
+/**
+ * IPC route for the `contacts/prompt` CLI command.
+ *
+ * Flow:
+ *   1. CLI calls `contacts/prompt` IPC route with optional channel/role hints.
+ *   2. Daemon broadcasts a `contact_request` to all connected clients.
+ *   3. Client shows a contact address input form.
+ *   4. User enters an address; client POSTs to the gateway's
+ *      `POST /v1/contacts/prompt` HTTP route.
+ *   5. Gateway upserts the contact + channel (gateway owns all contact writes).
+ *   6. Gateway calls daemon IPC `resolve_contact_prompt` with the new contact info.
+ *   7. Daemon resolves the pending promise; `contacts/prompt` IPC returns to CLI.
+ *
+ * The daemon only broadcasts the prompt and waits. It never writes contacts.
+ * All writes go through the gateway.
+ */
+
+import { v4 as uuid } from "uuid";
+import { z } from "zod";
+
+import { getLogger } from "../../util/logger.js";
+import { broadcastMessage } from "../assistant-event-hub.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const log = getLogger("contact-prompt-routes");
+
+/** Timeout for waiting on the user to submit the contact form (5 min). */
+const CONTACT_PROMPT_TIMEOUT_MS = 300_000;
+
+// ---------------------------------------------------------------------------
+// Pending contact prompts
+// ---------------------------------------------------------------------------
+
+export interface ContactPromptResult {
+  ok: boolean;
+  error?: string;
+  contactId?: string;
+  channelId?: string;
+  channelType?: string;
+  address?: string;
+}
+
+interface PendingContactPrompt {
+  resolve: (result: ContactPromptResult) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+const pendingContactPrompts = new Map<string, PendingContactPrompt>();
+
+/**
+ * Called by the gateway after it writes the contact and channel.
+ * Resolves the pending promise so the CLI's `contacts/prompt` IPC call returns.
+ */
+function resolveContactPrompt({
+  body = {},
+}: RouteHandlerArgs): { resolved: boolean } {
+  const { requestId, contactId, channelId, channelType, address, error } =
+    body as {
+      requestId: string;
+      contactId?: string;
+      channelId?: string;
+      channelType?: string;
+      address?: string;
+      error?: string;
+    };
+  const pending = pendingContactPrompts.get(requestId);
+  if (!pending) {
+    log.warn({ requestId }, "resolve_contact_prompt: no pending prompt found");
+    return { resolved: false };
+  }
+
+  clearTimeout(pending.timer);
+  pendingContactPrompts.delete(requestId);
+
+  if (error) {
+    pending.resolve({ ok: false, error });
+  } else {
+    pending.resolve({
+      ok: true,
+      contactId,
+      channelId,
+      channelType,
+      address,
+    });
+  }
+
+  log.info({ requestId, contactId }, "Contact prompt resolved");
+  return { resolved: true };
+}
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+const ContactPromptParams = z.object({
+  channel: z
+    .string()
+    .optional()
+    .describe(
+      "Suggested channel type hint (e.g. phone, email, telegram). Free text — not enforced.",
+    ),
+  placeholder: z
+    .string()
+    .optional()
+    .describe("Placeholder text for the address input field."),
+  label: z.string().optional().describe("Display label shown in the prompt UI."),
+  description: z.string().optional().describe("Longer description for the prompt UI."),
+  role: z
+    .enum(["guardian", "trusted-contact", "unknown"])
+    .default("unknown")
+    .describe("Intended role of the contact being registered."),
+});
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+async function handleContactPrompt({
+  body = {},
+}: RouteHandlerArgs): Promise<ContactPromptResult> {
+  const { channel, placeholder, label, description, role } =
+    ContactPromptParams.parse(body);
+
+  const requestId = uuid();
+
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pendingContactPrompts.delete(requestId);
+      log.warn({ requestId }, "Contact prompt timed out");
+      resolve({ ok: false, error: "Prompt timed out" });
+    }, CONTACT_PROMPT_TIMEOUT_MS);
+
+    pendingContactPrompts.set(requestId, { resolve, timer });
+
+    broadcastMessage({
+      type: "contact_request",
+      requestId,
+      channel,
+      placeholder,
+      label,
+      description,
+      role,
+    });
+
+    log.info({ requestId, channel, role }, "Contact prompt broadcast");
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Routes
+// ---------------------------------------------------------------------------
+
+export const CONTACT_PROMPT_ROUTES: RouteDefinition[] = [
+  {
+    operationId: "contacts_prompt",
+    endpoint: "contacts/prompt",
+    method: "POST",
+    handler: handleContactPrompt,
+    summary: "Prompt user to register a contact channel",
+    description:
+      "Broadcasts a contact_request to connected clients, waits for the user to submit an address via the gateway. The gateway owns the contact write and notifies the daemon via resolve_contact_prompt IPC.",
+    tags: ["contacts"],
+    requestBody: ContactPromptParams,
+    responseBody: z.object({
+      ok: z.boolean(),
+      error: z.string().optional(),
+      contactId: z.string().optional(),
+      channelId: z.string().optional(),
+      channelType: z.string().optional(),
+      address: z.string().optional(),
+    }),
+  },
+  {
+    operationId: "resolve_contact_prompt",
+    endpoint: "resolve_contact_prompt",
+    method: "POST",
+    handler: resolveContactPrompt,
+    summary: "Gateway callback: resolve a pending contact prompt",
+    description:
+      "Called by the gateway after it writes the contact and channel. Unblocks the waiting contacts/prompt IPC call.",
+    tags: ["contacts"],
+  },
+];

package/src/runtime/routes/conversation-query-routes.ts

@@ -50,7 +50,11 @@ import {
   CONFIG_RELOAD_DEBOUNCE_MS,
   log,
 } from "../../daemon/handlers/shared.js";
-import { getAssistantMessageIdsInTurn } from "../../memory/conversation-crud.js";
+import {
+  getAssistantMessageIdsInTurn,
+  getConversation,
+  getMessageById,
+} from "../../memory/conversation-crud.js";
 import { clearEmbeddingBackendCache } from "../../memory/embedding-backend.js";
 import {
   getRequestLogById,
@@ -58,6 +62,7 @@ import {
 } from "../../memory/llm-request-log-store.js";
 import { getMemoryRecallLogByMessageIds } from "../../memory/memory-recall-log-store.js";
 import { getMemoryV2ActivationLogByMessageIds } from "../../memory/memory-v2-activation-log-store.js";
+import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../memory/v2/constants.js";
 import { initializeProviders } from "../../providers/registry.js";
 import { resolvePricingForUsage } from "../../util/pricing.js";
 import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
@@ -459,6 +464,26 @@ function handleGetMessageContent({
   return result;
 }
 
+const CONVERSATION_KINDS = [
+  "user",
+  "background",
+  "background_memory_consolidation",
+  "scheduled",
+] as const;
+type ConversationKind = (typeof CONVERSATION_KINDS)[number];
+
+function resolveConversationKind(
+  source: string,
+  conversationType: string,
+): ConversationKind {
+  if (source === MEMORY_V2_CONSOLIDATION_SOURCE) {
+    return "background_memory_consolidation";
+  }
+  if (conversationType === "background") return "background";
+  if (conversationType === "scheduled") return "scheduled";
+  return "user";
+}
+
 function handleGetLlmContext({ pathParams = {} }: RouteHandlerArgs) {
   const messageId = pathParams.id;
   if (!messageId) {
@@ -469,8 +494,17 @@ function handleGetLlmContext({ pathParams = {} }: RouteHandlerArgs) {
   const memoryRecallLog = getMemoryRecallLogByMessageIds(turnMessageIds);
   const memoryV2Activation =
     getMemoryV2ActivationLogByMessageIds(turnMessageIds);
+  const message = getMessageById(messageId);
+  const conversation = message ? getConversation(message.conversationId) : null;
+  const conversationKind: ConversationKind = conversation
+    ? resolveConversationKind(
+        conversation.source,
+        conversation.conversationType,
+      )
+    : "user";
   return {
     messageId,
+    conversationKind,
     logs: logs.map((log) => {
       let requestPayload: unknown;
       try {
@@ -709,6 +743,7 @@ export const ROUTES: RouteDefinition[] = [
     tags: ["messages"],
     responseBody: z.object({
       messageId: z.string(),
+      conversationKind: z.enum(CONVERSATION_KINDS),
       logs: z.array(z.unknown()),
       memoryRecall: z.object({}).passthrough().nullable(),
       memoryV2Activation: z.object({}).passthrough().nullable(),

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

@@ -44,7 +44,9 @@ import {
   isWakeUpGreeting,
 } from "../../daemon/first-greeting.js";
 import { renderHistoryContent } from "../../daemon/handlers/shared.js";
+import { HostAppControlProxy } from "../../daemon/host-app-control-proxy.js";
 import { HostCuProxy } from "../../daemon/host-cu-proxy.js";
+import { preactivateHostProxySkills } from "../../daemon/host-proxy-preactivation.js";
 import type { ServerMessage } from "../../daemon/message-protocol.js";
 import type {
   HostProxyTransportMetadata,
@@ -1320,10 +1322,9 @@ export async function handleSendMessage(
 
   // Store pre-chat onboarding context on the conversation when this is the
   // very first message (no prior messages loaded). Artifact persistence
-  // (IDENTITY.md, USER.md, sidecar) is deferred: on the canned greeting
-  // path it runs inside the setTimeout right before warmPromptCache() so
-  // the warmed system prompt includes the identity; on the normal LLM
-  // path it runs immediately before inference starts.
+  // (IDENTITY.md, USER.md, sidecar) runs before either the canned greeting
+  // broadcast or normal LLM inference so client-side identity reads observe
+  // the selected assistant name.
   const isFirstOnboarding =
     !!body.onboarding && conversation.messages.length === 0;
   if (isFirstOnboarding) {
@@ -1395,15 +1396,30 @@ export async function handleSendMessage(
     if (!conversation.isProcessing() || !conversation.hostCuProxy) {
       conversation.setHostCuProxy(new HostCuProxy());
     }
-    // Only preactivate CU when the conversation is idle — if the conversation is
-    // processing, this message will be queued and preactivation is deferred
-    // to dequeue time in drainQueueImpl to avoid mutating in-flight turn state.
-    if (!conversation.isProcessing()) {
-      conversation.addPreactivatedSkillId("computer-use");
-    }
   } else if (!conversation.isProcessing()) {
     conversation.setHostCuProxy(undefined);
   }
+  // App-control mirrors CU's per-conversation lifecycle: the proxy owns a
+  // singleton lock plus per-session loop tracking. Instantiation is
+  // unconditional when the client supports the capability — feature-flag
+  // gating lives in the skill-projection layer (which reads the
+  // `feature-flag: app-control` declaration in SKILL.md frontmatter), so
+  // an attached proxy is harmless when the flag resolves to off.
+  if (supportsHostProxy(sourceInterface, "host_app_control")) {
+    if (!conversation.isProcessing() || !conversation.hostAppControlProxy) {
+      conversation.setHostAppControlProxy(
+        new HostAppControlProxy(mapping.conversationId),
+      );
+    }
+  } else if (!conversation.isProcessing()) {
+    conversation.setHostAppControlProxy(undefined);
+  }
+  // Only preactivate when the conversation is idle — if it's processing,
+  // this message will be queued and preactivation is deferred to dequeue
+  // time in drainQueueImpl to avoid mutating in-flight turn state.
+  if (!conversation.isProcessing()) {
+    preactivateHostProxySkills(conversation, sourceInterface);
+  }
   // Wire sendToClient to the SSE hub so all subsystems can reach the HTTP client.
   // hasNoClient must remain `!isInteractive` so downstream tool gating
   // (`isToolActiveForContext` for HOST_TOOL_NAMES, `createToolExecutor`'s
@@ -1473,6 +1489,10 @@ export async function handleSendMessage(
         conversationId,
       };
 
+      if (isFirstOnboarding) {
+        persistOnboardingArtifacts(body.onboarding!);
+      }
+
       setTimeout(() => {
         broadcastMessage({
           type: "user_message_echo",
@@ -1493,9 +1513,6 @@ export async function handleSendMessage(
           "canned-greeting queue drain",
         );
 
-        if (isFirstOnboarding) {
-          persistOnboardingArtifacts(body.onboarding!);
-        }
         conversation.warmPromptCache();
       }, 0);
 

package/src/runtime/routes/document-pdf-renderer.ts

@@ -0,0 +1,165 @@
+/**
+ * Markdown to PDF renderer for document export.
+ *
+ * Converts markdown content to styled HTML via `marked`, then renders
+ * the HTML to a PDF buffer using Playwright headless Chromium.
+ * The HTML template uses print-friendly styling that matches the
+ * document editor typography.
+ */
+
+import { marked } from "marked";
+
+import { importPlaywright } from "../../tools/browser/runtime-check.js";
+
+// ---------------------------------------------------------------------------
+// Print template
+// ---------------------------------------------------------------------------
+
+const FONT_STACK = `"DM Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`;
+
+function wrapInPrintTemplate(innerHtml: string): string {
+  return `<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    font-family: ${FONT_STACK};
+    font-size: 14px;
+    line-height: 1.7;
+    color: #1a1a1a;
+    background: #ffffff;
+    padding: 0;
+  }
+
+  h1 { font-size: 28px; font-weight: 600; margin-top: 32px; margin-bottom: 12px; }
+  h2 { font-size: 22px; font-weight: 600; margin-top: 28px; margin-bottom: 10px; }
+  h3 { font-size: 18px; font-weight: 600; margin-top: 24px; margin-bottom: 8px; }
+  h4, h5, h6 { font-size: 16px; font-weight: 600; margin-top: 20px; margin-bottom: 8px; }
+
+  p {
+    margin-bottom: 12px;
+  }
+
+  pre {
+    background: #f5f5f5;
+    border-radius: 8px;
+    padding: 12px 16px;
+    overflow-x: auto;
+    margin-bottom: 12px;
+  }
+
+  code {
+    font-family: "DM Mono", "SF Mono", monospace;
+    font-size: 13px;
+    background: #f5f5f5;
+    border-radius: 4px;
+    padding: 2px 5px;
+  }
+
+  pre code {
+    background: none;
+    padding: 0;
+    border-radius: 0;
+  }
+
+  blockquote {
+    border-left: 3px solid #6366f1;
+    padding-left: 16px;
+    margin: 12px 0;
+    color: #555555;
+  }
+
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    margin: 12px 0;
+  }
+
+  th, td {
+    border: 1px solid #e0e0e0;
+    padding: 8px 12px;
+    text-align: left;
+  }
+
+  th {
+    background: #f5f5f5;
+    font-weight: 600;
+  }
+
+  ul, ol {
+    margin: 12px 0;
+    padding-left: 24px;
+  }
+
+  li {
+    margin-bottom: 4px;
+  }
+
+  a {
+    color: #6366f1;
+    text-decoration: none;
+  }
+
+  hr {
+    border: none;
+    border-top: 1px solid #e0e0e0;
+    margin: 24px 0;
+  }
+
+  img {
+    max-width: 100%;
+    height: auto;
+  }
+
+</style>
+</head>
+<body>
+${innerHtml}
+</body>
+</html>`;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a markdown string to a PDF buffer.
+ *
+ * Parses markdown to HTML via `marked`, wraps it in a print-friendly
+ * template, then renders to PDF using Playwright headless Chromium.
+ * The browser is always closed in a `finally` block.
+ */
+export async function renderMarkdownToPDF(
+  title: string,
+  markdown: string,
+): Promise<Buffer> {
+  const innerHtml = marked.parse(markdown, {
+    gfm: true,
+    breaks: true,
+  }) as string;
+  const fullHtml = wrapInPrintTemplate(innerHtml);
+
+  const pw = await importPlaywright();
+  const browser = await pw.chromium.launch({ headless: true });
+  try {
+    const page = await browser.newPage();
+    await page.setContent(fullHtml, { waitUntil: "networkidle" });
+    const pdfBuffer = await page.pdf({
+      format: "A4",
+      margin: {
+        top: "0.75in",
+        bottom: "0.75in",
+        left: "0.75in",
+        right: "0.75in",
+      },
+      printBackground: true,
+    });
+    return Buffer.from(pdfBuffer);
+  } finally {
+    await browser.close();
+  }
+}

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

@@ -8,8 +8,10 @@ import { z } from "zod";
 
 import { rawAll, rawGet, rawRun } 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");
 
@@ -312,4 +314,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

@@ -22,7 +22,10 @@ import type { HostProxyCapability } from "../../channels/types.js";
 import { parseInterfaceId, supportsHostProxy } from "../../channels/types.js";
 import { getOrCreateConversation } from "../../memory/conversation-key-store.js";
 import { getLogger } from "../../util/logger.js";
-import { formatSseFrame, formatSseHeartbeat } from "../assistant-event.js";
+import {
+  formatSseFrame,
+  formatSseHeartbeatWithData,
+} from "../assistant-event.js";
 import type {
   AssistantEventCallback,
   AssistantEventFilter,
@@ -37,8 +40,8 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("events-routes");
 
-/** Keep-alive comment sent to idle clients every 7 s by default. */
-const DEFAULT_HEARTBEAT_INTERVAL_MS = 7_000;
+/** Keep-alive comment sent to idle clients every 5 s by default. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
 
 /**
  * Stream assistant events as Server-Sent Events.
@@ -58,7 +61,7 @@ const DEFAULT_HEARTBEAT_INTERVAL_MS = 7_000;
  *
  * Options (for testing):
  *   hub               -- override the event hub (defaults to process singleton).
- *   heartbeatIntervalMs -- how often to emit keep-alive comments (default 7 s).
+ *   heartbeatIntervalMs -- how often to emit keep-alive comments (default 5 s).
  */
 export function handleSubscribeAssistantEvents(
   args: RouteHandlerArgs,
@@ -77,6 +80,7 @@ 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 clientId = rawClientId?.trim() || null;
   const interfaceId = clientId
     ? parseInterfaceId(rawInterfaceId?.trim())
@@ -100,6 +104,7 @@ export function handleSubscribeAssistantEvents(
     "host_bash",
     "host_file",
     "host_cu",
+    "host_app_control",
     "host_browser",
   ];
 
@@ -165,6 +170,7 @@ export function handleSubscribeAssistantEvents(
             capabilities: ALL_CAPABILITIES.filter((cap) =>
               supportsHostProxy(interfaceId, cap),
             ),
+            machineName: rawMachineName?.trim() || undefined,
           })
         : hub.subscribe({
             ...subscriberBase,
@@ -188,7 +194,7 @@ export function handleSubscribeAssistantEvents(
           return;
         }
 
-        controller.enqueue(encoder.encode(formatSseHeartbeat()));
+        controller.enqueue(encoder.encode(formatSseHeartbeatWithData()));
 
         heartbeatTimer = setInterval(() => {
           try {
@@ -200,7 +206,7 @@ export function handleSubscribeAssistantEvents(
             if (clientId) {
               hub.touchClient(clientId);
             }
-            controller.enqueue(encoder.encode(formatSseHeartbeat()));
+            controller.enqueue(encoder.encode(formatSseHeartbeatWithData()));
           } catch {
             sub.dispose();
             cleanup();