@vellumai/assistant 0.12.5 → 0.12.6-dev.202609292116.41f7caa

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

@@ -6,71 +6,40 @@
  */
 import { z } from "zod";
 
+import {
+  getDocumentRevision,
+  listDocumentRevisions,
+} from "../../documents/document-revisions-store.js";
 import {
   addDocumentConversation,
   createDocument,
   DEFAULT_DOCUMENT_TITLE,
   getDocumentById,
   getDocumentsForConversation,
+  listAllDocuments,
+  restoreDocumentRevision,
   saveDocument,
 } from "../../documents/document-store.js";
 import { getConversation } from "../../persistence/conversation-crud.js";
-import { rawAll } from "../../persistence/raw-query.js";
 import { getLogger } from "../../util/logger.js";
+import { broadcastMessage } from "../assistant-event-hub.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import {
   getOriginClientId,
   publishDocumentsChanged,
 } from "../sync/resource-sync-events.js";
 import { renderMarkdownToPDF } from "./document-pdf-renderer.js";
-import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
+import {
+  BadRequestError,
+  ConflictError,
+  InternalError,
+  NotFoundError,
+} from "./errors.js";
 import type { RouteDefinition } from "./types.js";
 import { RouteResponse } from "./types.js";
 
 const log = getLogger("documents-routes");
 
-interface DocumentListRow {
-  surface_id: string;
-  conversation_id: string;
-  title: string;
-  word_count: number;
-  created_at: number;
-  updated_at: number;
-}
-
-function listAllDocuments(): Array<{
-  surfaceId: string;
-  conversationId: string;
-  title: string;
-  wordCount: number;
-  createdAt: number;
-  updatedAt: number;
-}> {
-  try {
-    const results = rawAll<DocumentListRow>(
-      "documents:listAllDocuments",
-      /*sql*/ `
-      SELECT surface_id, conversation_id, title, word_count, created_at, updated_at
-      FROM documents
-      ORDER BY updated_at DESC
-      `,
-    );
-
-    log.info({ count: results.length }, "Listed documents");
-    return results.map((row) => ({
-      surfaceId: row.surface_id,
-      conversationId: row.conversation_id,
-      title: row.title,
-      wordCount: row.word_count,
-      createdAt: row.created_at,
-      updatedAt: row.updated_at,
-    }));
-  } catch (error) {
-    log.error({ err: error }, "List error");
-    return [];
-  }
-}
-
 /** The document payload shape returned by `GET documents/{id}`. */
 const documentPayloadSchema = z.object({
   success: z.boolean(),
@@ -81,8 +50,32 @@ const documentPayloadSchema = z.object({
   wordCount: z.number(),
   createdAt: z.number(),
   updatedAt: z.number(),
+  revision: z
+    .number()
+    .optional()
+    .describe(
+      "Bumped by one on every write. Absent from assistants that predate document revisions.",
+    ),
 });
 
+const revisionSummarySchema = z.object({
+  revision: z.number().describe("The document revision this snapshot holds"),
+  author: z
+    .enum(["user", "assistant"])
+    .describe("Who made the edit that replaced this state"),
+  createdAt: z.number().describe("When the snapshot was taken"),
+  wordCount: z.number(),
+  title: z.string(),
+});
+
+function parseRevisionParam(raw: string | undefined): number {
+  const revision = Number(raw);
+  if (!raw || !Number.isInteger(revision) || revision < 0) {
+    throw new BadRequestError("revision must be a non-negative integer");
+  }
+  return revision;
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -115,6 +108,12 @@ export const ROUTES: RouteDefinition[] = [
           wordCount: z.number(),
           createdAt: z.number(),
           updatedAt: z.number(),
+          revision: z
+            .number()
+            .optional()
+            .describe(
+              "Bumped by one on every write. Absent from assistants that predate document revisions.",
+            ),
         }),
       ),
     }),
@@ -157,7 +156,8 @@ export const ROUTES: RouteDefinition[] = [
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
     summary: "Save a document",
-    description: "Create or upsert a document (by surfaceId).",
+    description:
+      "Create or upsert a document (by surfaceId). With `baseRevision`, an existing document is only overwritten while its revision still equals `baseRevision`; otherwise the save is rejected with 409 CONFLICT and `error.details` carries the current `revision`, `title`, and `content`.",
     tags: ["documents"],
     requestBody: z.object({
       surfaceId: z.string().describe("Surface ID (unique key)"),
@@ -165,19 +165,40 @@ export const ROUTES: RouteDefinition[] = [
       title: z.string().describe("Document title"),
       content: z.string().describe("Document content"),
       wordCount: z.number().describe("Word count"),
+      baseRevision: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe(
+          "The revision this save was edited from. When set and the stored revision differs, nothing is written and the request fails with 409. Omit for an unconditional write.",
+        ),
     }),
     responseBody: z.object({
       success: z.literal(true),
       surfaceId: z.string(),
+      revision: z
+        .number()
+        .optional()
+        .describe(
+          "The document's revision after the save. Absent from assistants that predate document revisions.",
+        ),
     }),
     handler: ({ body, headers }) => {
-      const { surfaceId, conversationId, title, content, wordCount } = (body ??
-        {}) as {
+      const {
+        surfaceId,
+        conversationId,
+        title,
+        content,
+        wordCount,
+        baseRevision,
+      } = (body ?? {}) as {
         surfaceId?: string;
         conversationId?: string;
         title?: string;
         content?: string;
         wordCount?: number;
+        baseRevision?: number | null;
       };
 
       if (!surfaceId || typeof surfaceId !== "string") {
@@ -195,6 +216,14 @@ export const ROUTES: RouteDefinition[] = [
       if (typeof wordCount !== "number") {
         throw new BadRequestError("wordCount is required");
       }
+      if (
+        baseRevision != null &&
+        (!Number.isInteger(baseRevision) || baseRevision < 0)
+      ) {
+        throw new BadRequestError(
+          "baseRevision must be a non-negative integer",
+        );
+      }
 
       const result = saveDocument({
         surfaceId,
@@ -202,9 +231,13 @@ export const ROUTES: RouteDefinition[] = [
         title,
         content,
         wordCount,
+        baseRevision: baseRevision ?? undefined,
       });
 
       if (!result.success) {
+        if (result.conflict) {
+          throw new ConflictError(result.error, result.conflict);
+        }
         throw new InternalError(result.error);
       }
       // Every save moves `updated_at`, which both document lists order by and
@@ -305,6 +338,111 @@ export const ROUTES: RouteDefinition[] = [
     },
   },
 
+  {
+    operationId: "listDocumentRevisions",
+    endpoint: "documents/:id/revisions",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "List a document's revisions",
+    description:
+      "Return the document's history snapshots, newest first, without their content.",
+    tags: ["documents"],
+    responseBody: z.object({ revisions: z.array(revisionSummarySchema) }),
+    handler: ({ pathParams }) => {
+      if (!getDocumentById(pathParams!.id)) {
+        throw new NotFoundError("Document not found");
+      }
+      return { revisions: listDocumentRevisions(pathParams!.id) };
+    },
+  },
+
+  {
+    operationId: "getDocumentRevision",
+    endpoint: "documents/:id/revisions/:revision",
+    method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get a document revision",
+    description: "Return one history snapshot with its content.",
+    tags: ["documents"],
+    responseBody: revisionSummarySchema.extend({ content: z.string() }),
+    handler: ({ pathParams }) => {
+      const revision = parseRevisionParam(pathParams!.revision);
+      const snapshot = getDocumentRevision(pathParams!.id, revision);
+      if (!snapshot) {
+        throw new NotFoundError("Revision not found");
+      }
+      return snapshot;
+    },
+  },
+
+  {
+    operationId: "restoreDocumentRevision",
+    endpoint: "documents/:id/revisions/:revision/restore",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Restore a document revision",
+    description:
+      "Write a snapshot's title and content back as a new revision. The current state is snapshotted first, so the restore can itself be undone.",
+    tags: ["documents"],
+    responseBody: z.object({
+      success: z.literal(true),
+      surfaceId: z.string(),
+      revision: z
+        .number()
+        .describe("The document's revision after the restore"),
+      title: z.string(),
+      content: z.string(),
+    }),
+    handler: ({ pathParams, headers }) => {
+      const surfaceId = pathParams!.id;
+      const revision = parseRevisionParam(pathParams!.revision);
+      const result = restoreDocumentRevision(surfaceId, revision);
+      if (!result.success) {
+        throw new NotFoundError(
+          result.notFound === "document"
+            ? "Document not found"
+            : "Revision not found",
+        );
+      }
+      const doc = getDocumentById(surfaceId);
+      if (doc) {
+        broadcastMessage(
+          {
+            type: "document_editor_update",
+            conversationId: doc.conversationId,
+            surfaceId,
+            markdown: result.content,
+            mode: "replace",
+            revision: result.revision,
+            title: result.title,
+          },
+          doc.conversationId,
+        );
+      }
+      publishDocumentsChanged(getOriginClientId(headers));
+      log.info(
+        { surfaceId, restoredRevision: revision, revision: result.revision },
+        "Restored document revision via HTTP",
+      );
+      return {
+        success: true as const,
+        surfaceId,
+        revision: result.revision,
+        title: result.title,
+        content: result.content,
+      };
+    },
+  },
+
   {
     operationId: "exportDocumentPDF",
     endpoint: "documents/:id/pdf",

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

@@ -492,7 +492,7 @@ export function handleSubscribeAssistantEvents(
     });
   }
 
-  const stream = new ReadableStream<Uint8Array>(
+  return new ReadableStream<Uint8Array>(
     {
       start(controller) {
         controllerRef = controller;
@@ -573,8 +573,6 @@ export function handleSubscribeAssistantEvents(
     },
     new CountQueuingStrategy({ highWaterMark: 16 }),
   );
-
-  return stream;
 }
 
 /**

package/src/runtime/routes/host-app-control-routes.ts

@@ -91,6 +91,7 @@ async function handleHostAppControlResult({ body, headers }: RouteHandlerArgs) {
   await assertHostProxyResultBinding({
     headers,
     targetClientId: peeked.targetClientId,
+    targetConnectionId: peeked.targetConnectionId,
     targetActorPrincipalId: peeked.targetActorPrincipalId,
     op: "host_app_control",
     missingClientIdMessage:

package/src/runtime/routes/host-bash-routes.ts

@@ -64,6 +64,7 @@ async function handleHostBashResult({ body, headers }: RouteHandlerArgs) {
   await assertHostProxyResultBinding({
     headers,
     targetClientId: peeked.targetClientId,
+    targetConnectionId: peeked.targetConnectionId,
     targetActorPrincipalId: peeked.targetActorPrincipalId,
     op: "host_bash",
     missingClientIdMessage:

package/src/runtime/routes/host-browser-routes.ts

@@ -122,6 +122,21 @@ export async function resolveHostBrowserResultByRequestId(
         message: `Client "${submittingClientId}" is not the target for this request (expected "${peeked.targetClientId}"). The targeted client must submit the result.`,
       };
     }
+    if (
+      peeked.targetConnectionId &&
+      !assistantEventHub.hasActiveClientConnection(
+        peeked.targetConnectionId,
+        peeked.targetClientId,
+      )
+    ) {
+      return {
+        ok: false,
+        code: "FORBIDDEN",
+        status: 403,
+        message:
+          "This host-proxy result is bound to a connection that is no longer active.",
+      };
+    }
 
     // Defense-in-depth: require the submitting actor's principal id to match
     // the actor principal id captured when the target client opened its SSE

package/src/runtime/routes/host-cu-routes.ts

@@ -6,6 +6,7 @@
  */
 import { z } from "zod";
 
+import { prepareComputerUseObservation } from "../../daemon/computer-use-observation.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { SAME_ACTOR_FORBIDDEN_DESCRIPTION } from "../auth/same-actor.js";
@@ -77,6 +78,7 @@ async function handleHostCuResult({ body, headers }: RouteHandlerArgs) {
   await assertHostProxyResultBinding({
     headers: headers as Record<string, string | undefined> | undefined,
     targetClientId: peeked.targetClientId,
+    targetConnectionId: peeked.targetConnectionId,
     targetActorPrincipalId: peeked.targetActorPrincipalId,
     op: "host_cu",
     missingClientIdMessage:
@@ -112,7 +114,7 @@ async function handleHostCuResult({ body, headers }: RouteHandlerArgs) {
     throw new NotFoundError("No host CU proxy for conversation");
   }
 
-  conversation.hostCuProxy.processObservation(requestId, {
+  const observation = await prepareComputerUseObservation({
     axTree,
     axDiff,
     screenshot,
@@ -126,6 +128,7 @@ async function handleHostCuResult({ body, headers }: RouteHandlerArgs) {
     userGuidance,
     timings,
   });
+  conversation.hostCuProxy.processObservation(requestId, observation);
 
   return { accepted: true };
 }

package/src/runtime/routes/host-file-routes.ts

@@ -63,6 +63,7 @@ async function handleHostFileResult({ body, headers }: RouteHandlerArgs) {
   await assertHostProxyResultBinding({
     headers: headers as Record<string, string | undefined> | undefined,
     targetClientId: peeked.targetClientId,
+    targetConnectionId: peeked.targetConnectionId,
     targetActorPrincipalId: peeked.targetActorPrincipalId,
     op: "host_file",
     missingClientIdMessage:

package/src/runtime/routes/host-proxy-result-binding.test.ts

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { assistantEventHub } from "../assistant-event-hub.js";
+import * as pendingInteractions from "../pending-interactions.js";
+import { ForbiddenError } from "./errors.js";
+import { assertHostProxyResultBinding } from "./host-proxy-result-binding.js";
+
+const ACTOR = "actor-host-proxy-bind";
+const subscriptions: Array<{ dispose(): void }> = [];
+
+function subscribeClient(clientId: string) {
+  const sub = assistantEventHub.subscribe({
+    type: "client",
+    clientId,
+    interfaceId: "macos",
+    capabilities: ["host_bash"],
+    actorPrincipalId: ACTOR,
+    callback: () => {},
+  });
+  subscriptions.push(sub);
+  return sub;
+}
+
+describe("assertHostProxyResultBinding connection snapshot", () => {
+  afterEach(() => {
+    pendingInteractions.clear();
+    for (const sub of subscriptions.splice(0)) {
+      sub.dispose();
+    }
+  });
+
+  test("allows a result while the dispatch connection is still active", async () => {
+    const sub = subscribeClient("host-proxy-bind-1");
+    pendingInteractions.register("req-active", {
+      kind: "host_bash",
+      targetClientId: "host-proxy-bind-1",
+    });
+    const pending = pendingInteractions.get("req-active");
+    expect(pending?.targetConnectionId).toBe(sub.connectionId);
+
+    await assertHostProxyResultBinding({
+      headers: {
+        "x-vellum-client-id": "host-proxy-bind-1",
+        "x-vellum-actor-principal-id": ACTOR,
+      },
+      targetClientId: pending?.targetClientId,
+      targetConnectionId: pending?.targetConnectionId,
+      targetActorPrincipalId: ACTOR,
+      op: "host_bash",
+      missingClientIdMessage: "missing",
+    });
+    sub.dispose();
+  });
+
+  test("rejects a result after the same clientId reconnects", async () => {
+    const first = subscribeClient("host-proxy-bind-2");
+    pendingInteractions.register("req-stale", {
+      kind: "host_bash",
+      targetClientId: "host-proxy-bind-2",
+    });
+    const pending = pendingInteractions.get("req-stale");
+    expect(pending?.targetConnectionId).toBe(first.connectionId);
+
+    const second = subscribeClient("host-proxy-bind-2");
+    expect(first.active).toBe(false);
+    expect(second.connectionId).not.toBe(first.connectionId);
+
+    await expect(
+      assertHostProxyResultBinding({
+        headers: {
+          "x-vellum-client-id": "host-proxy-bind-2",
+          "x-vellum-actor-principal-id": ACTOR,
+        },
+        targetClientId: pending?.targetClientId,
+        targetConnectionId: pending?.targetConnectionId,
+        targetActorPrincipalId: ACTOR,
+        op: "host_bash",
+        missingClientIdMessage: "missing",
+      }),
+    ).rejects.toBeInstanceOf(ForbiddenError);
+    second.dispose();
+  });
+});

package/src/runtime/routes/host-proxy-result-binding.ts

@@ -18,9 +18,29 @@ import {
 import { resolveActorPrincipalIdForLocalGuardian } from "../local-actor-identity.js";
 import { BadRequestError, ForbiddenError } from "./errors.js";
 
+export function assertHostProxyConnectionBinding(args: {
+  targetClientId?: string;
+  targetConnectionId?: string;
+}): void {
+  if (!args.targetConnectionId) {
+    return;
+  }
+  if (
+    !assistantEventHub.hasActiveClientConnection(
+      args.targetConnectionId,
+      args.targetClientId,
+    )
+  ) {
+    throw new ForbiddenError(
+      "This host-proxy result is bound to a connection that is no longer active.",
+    );
+  }
+}
+
 export async function assertHostProxyResultBinding(args: {
   headers?: Record<string, string | undefined>;
   targetClientId?: string;
+  targetConnectionId?: string;
   targetActorPrincipalId?: string;
   op: SameActorOp;
   missingClientIdMessage: string;
@@ -43,6 +63,11 @@ export async function assertHostProxyResultBinding(args: {
     }
   }
 
+  assertHostProxyConnectionBinding({
+    targetClientId: args.targetClientId,
+    targetConnectionId: args.targetConnectionId,
+  });
+
   if (!args.targetClientId && !args.targetActorPrincipalId) {
     return;
   }

package/src/runtime/routes/host-transfer-routes.ts

@@ -249,6 +249,7 @@ async function handleTransferResult({ body, headers }: RouteHandlerArgs) {
   await assertHostProxyResultBinding({
     headers: headers as Record<string, string | undefined> | undefined,
     targetClientId: peeked.targetClientId,
+    targetConnectionId: peeked.targetConnectionId,
     targetActorPrincipalId: peeked.targetActorPrincipalId,
     op: "host_transfer",
     missingClientIdMessage:

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

@@ -159,6 +159,7 @@ async function getDetailedHealth() {
       memoryOptOut: true,
       retryLastTurn: true,
       appPins: true,
+      chatsSettings: true,
     },
     ...(profiler ? { profiler } : {}),
     ...migrationHealthFields,
@@ -226,8 +227,6 @@ function getIdentity() {
   const content = readFileSync(identityPath, "utf-8");
   const fields = parseIdentityFields(content);
 
-  const version = APP_VERSION;
-
   const createdAt = resolveHatchedAtReadOnly(identityPath);
 
   return {
@@ -236,7 +235,7 @@ function getIdentity() {
     personality: fields.personality ?? "",
     emoji: fields.emoji ?? "",
     home: fields.home ?? "",
-    version,
+    version: APP_VERSION,
     createdAt,
   };
 }
@@ -280,6 +279,7 @@ const healthCapabilitiesSchema = z.object({
   memoryOptOut: z.boolean(),
   retryLastTurn: z.boolean(),
   appPins: z.boolean(),
+  chatsSettings: z.boolean().optional(),
 });
 
 const healthDiskSchema = z.object({

package/src/runtime/routes/inbound-stages/background-dispatch.ts

@@ -19,6 +19,7 @@ import {
 } from "../../../contacts/guardian-delivery-reader.js";
 import { isConversationBusyError } from "../../../daemon/conversation-messaging.js";
 import type { TrustContext } from "../../../daemon/trust-context-types.js";
+import { negotiateLocale } from "../../../i18n/index.js";
 import type { ProviderMessageMetadata } from "../../../messaging/provider-message-metadata.js";
 import {
   channelActivityRefreshMs,
@@ -288,6 +289,9 @@ export function processChannelMessageInBackground(
           trustContext: trustCtx,
           author: trustCtx,
           isInteractive: resolveRoutingState(trustCtx).promptWaitingAllowed,
+          ...(sourceLanguageCode
+            ? { locale: negotiateLocale([sourceLanguageCode]) }
+            : {}),
           ...(displayContent !== undefined ? { displayContent } : {}),
           ...(cmdIntent ? { commandIntent: cmdIntent } : {}),
           ...(slackInbound ? { slackInbound } : {}),

package/src/runtime/routes/integrations/a2a.ts

@@ -317,7 +317,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "integrations_a2a_invite_accept_post",
     endpoint: "integrations/a2a/invite/accept",
     method: "POST",
-    policy: null,
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Accept A2A invite (self-hosted broker)",
     description:
       "Orchestrate cross-daemon invite acceptance for self-hosted deployments. Calls the sender's invite/complete, then creates a local contact via invite/redeem.",

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

@@ -2056,7 +2056,9 @@ export async function handleMigrationPreflightFromGcs({
   }
 
   const bytes = new Uint8Array(await upstream.arrayBuffer());
-  const validationResult = validateVBundle(bytes);
+  const validationResult = validateVBundle(bytes, {
+    enforceStreamingLimits: true,
+  });
 
   if (!validationResult.is_valid || !validationResult.manifest) {
     return {

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

@@ -94,8 +94,7 @@ async function handleEmitSignal({ body = {} }: RouteHandlerArgs) {
       parsed.error.issues[0]?.message ?? "Invalid signal parameters",
     );
   }
-  const validated = parsed.data;
-  const result = await emitNotificationSignal(validated);
+  const result = await emitNotificationSignal(parsed.data);
   return {
     signalId: result.signalId,
     dispatched: result.dispatched,

package/src/runtime/routes/ui-snapshot-routes.test.ts

@@ -33,6 +33,7 @@ mock.module("../assistant-event-hub.js", () => ({
       fakeClient?.clientId === clientId
         ? fakeClient.actorPrincipalId
         : undefined,
+    getClientById: () => undefined,
   },
   broadcastMessage: (
     msg: Record<string, unknown>,

package/src/runtime/routes/user-route-dispatcher.ts

@@ -135,7 +135,11 @@ export class UserRouteDispatcher {
    * @returns A Response from the handler, or an error response (404, 405, 500).
    */
   async dispatch(routePath: string, request: Request): Promise<Response> {
-    if (routePath.includes("..")) {
+    // ".." covers classic dot-segment traversal. "\" is rejected alongside it
+    // because some URL normalizers treat a backslash as a path separator, so
+    // a routePath that looks in-namespace after percent-decoding can still
+    // resolve outside the routes directory once such a normalizer runs.
+    if (routePath.includes("..") || routePath.includes("\\")) {
       return httpError("BAD_REQUEST", "Path traversal is not allowed", 400);
     }
 

package/src/runtime/verification-templates.ts

@@ -174,8 +174,7 @@ export function composeVerificationText(
   templateKey: TextVerifyTemplateKey,
   vars: GuardianVerifyTemplateVars,
 ): string {
-  const composer = templates[templateKey];
-  return composer(vars);
+  return templates[templateKey](vars);
 }
 
 // ---------------------------------------------------------------------------