@vellumai/assistant 0.6.1 → 0.6.3

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

@@ -4,13 +4,17 @@
  * GET /v1/conversation-starters — list conversation starters (chips)
  */
 
-import { and, desc, eq, inArray, like } from "drizzle-orm";
+import { and, desc, eq, inArray, sql } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb } from "../../memory/db.js";
 import { enqueueMemoryJob } from "../../memory/jobs-store.js";
 import { rawGet } from "../../memory/raw-query.js";
-import { conversationStarters, memoryJobs } from "../../memory/schema.js";
+import {
+  conversationStarters,
+  memoryCheckpoints,
+  memoryJobs,
+} from "../../memory/schema.js";
 import type { RouteDefinition } from "../http-router.js";
 
 // ---------------------------------------------------------------------------
@@ -26,6 +30,39 @@ interface StarterItem {
   batch: number;
 }
 
+const CK_ITEM_COUNT = "conversation_starters:item_count_at_last_gen";
+const CK_LAST_GEN_AT = "conversation_starters:last_gen_at";
+export const CONVERSATION_STARTERS_STALE_TTL_MS = 24 * 60 * 60 * 1000;
+
+function checkpointKey(base: string, scopeId: string): string {
+  return `${base}:${scopeId}`;
+}
+
+function parseCheckpointInt(value: string | undefined): number | null {
+  if (!value) return null;
+  const parsed = Number.parseInt(value, 10);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function hasActiveConversationStarterJob(
+  db: ReturnType<typeof getDb>,
+  scopeId: string,
+): boolean {
+  return (
+    db
+      .select({ id: memoryJobs.id })
+      .from(memoryJobs)
+      .where(
+        and(
+          eq(memoryJobs.type, "generate_conversation_starters"),
+          inArray(memoryJobs.status, ["pending", "running"]),
+          sql`json_extract(${memoryJobs.payload}, '$.scopeId') = ${scopeId}`,
+        ),
+      )
+      .get() != null
+  );
+}
+
 /**
  * Re-order starters so adjacent items have distinct categories wherever
  * possible. Within each category, preserve the original (batch-desc) order.
@@ -150,14 +187,47 @@ function handleListConversationStarters(url: URL): Response {
 
   const total = allItems.length;
 
-  // If starters exist, reorder for category diversity then paginate.
+  // If starters exist, return them immediately. If the batch is stale or
+  // the generation checkpoint is ahead of the current active memory count,
+  // kick off a background refresh but keep the existing chips visible.
   if (total > 0) {
+    const totalActive =
+      rawGet<{ c: number }>(
+        `SELECT COUNT(*) AS c FROM memory_graph_nodes WHERE fidelity != 'gone' AND scope_id = ?`,
+        scopeId,
+      )?.c ?? 0;
+    const lastCount = parseCheckpointInt(
+      db
+        .select({ value: memoryCheckpoints.value })
+        .from(memoryCheckpoints)
+        .where(eq(memoryCheckpoints.key, checkpointKey(CK_ITEM_COUNT, scopeId)))
+        .get()?.value,
+    );
+    const lastGenAt = parseCheckpointInt(
+      db
+        .select({ value: memoryCheckpoints.value })
+        .from(memoryCheckpoints)
+        .where(eq(memoryCheckpoints.key, checkpointKey(CK_LAST_GEN_AT, scopeId)))
+        .get()?.value,
+    );
+    const staleByAge =
+      lastGenAt == null ||
+      Date.now() - lastGenAt >= CONVERSATION_STARTERS_STALE_TTL_MS;
+    const checkpointAhead = lastCount != null && totalActive < lastCount;
+    let hasActiveJob = hasActiveConversationStarterJob(db, scopeId);
+    const shouldRefresh = staleByAge || checkpointAhead;
+
+    if (shouldRefresh && !hasActiveJob) {
+      enqueueMemoryJob("generate_conversation_starters", { scopeId });
+      hasActiveJob = true;
+    }
+
     const ordered = orderStrongestFirst(allItems);
     const page = ordered.slice(offsetParam, offsetParam + limitParam);
     return Response.json({
       starters: page,
       total,
-      status: "ready",
+      status: hasActiveJob ? "refreshing" : "ready",
     });
   }
 
@@ -172,17 +242,7 @@ function handleListConversationStarters(url: URL): Response {
   }
 
   // Memory items exist but no starters yet — ensure a generation job is queued.
-  const existing = db
-    .select({ id: memoryJobs.id })
-    .from(memoryJobs)
-    .where(
-      and(
-        eq(memoryJobs.type, "generate_conversation_starters"),
-        inArray(memoryJobs.status, ["pending", "running"]),
-        like(memoryJobs.payload, `%"scopeId":"${scopeId}"%`),
-      ),
-    )
-    .get();
+  const existing = hasActiveConversationStarterJob(db, scopeId);
 
   if (!existing) {
     enqueueMemoryJob("generate_conversation_starters", { scopeId });
@@ -227,7 +287,9 @@ export function conversationStarterRouteDefinitions(): RouteDefinition[] {
           .array(z.unknown())
           .describe("Ordered list of starter chips"),
         total: z.number().int().describe("Total number of available starters"),
-        status: z.string().describe("One of: ready, empty, generating"),
+        status: z
+          .enum(["ready", "refreshing", "empty", "generating"])
+          .describe("One of: ready, refreshing, empty, generating"),
       }),
     },
   ];

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

@@ -63,8 +63,22 @@ export function groupRouteDefinitions(): RouteDefinition[] {
         if (!body.name || typeof body.name !== "string") {
           return httpError("BAD_REQUEST", "Missing or invalid name", 400);
         }
-        const group = createGroup(body.name);
-        return Response.json(serializeGroup(group), { status: 201 });
+        try {
+          const group = createGroup(body.name);
+          return Response.json(serializeGroup(group), { status: 201 });
+        } catch (err) {
+          if (
+            err instanceof Error &&
+            err.message.includes("sort_position must be >= 4")
+          ) {
+            return httpError(
+              "BAD_REQUEST",
+              "Too many custom groups — sort_position ceiling reached",
+              400,
+            );
+          }
+          throw err;
+        }
       },
     },
     {
@@ -105,16 +119,16 @@ export function groupRouteDefinitions(): RouteDefinition[] {
             403,
           );
         }
-        // Custom group sort_position must be >= 3
+        // Custom group sort_position must be >= 4 (0–3 reserved for system groups)
         if (
           body.sortPosition !== undefined &&
           (typeof body.sortPosition !== "number" ||
             !isFinite(body.sortPosition) ||
-            body.sortPosition < 3)
+            body.sortPosition < 4)
         ) {
           return httpError(
             "BAD_REQUEST",
-            "Custom group sort_position must be >= 3",
+            "Custom group sort_position must be >= 4",
             400,
           );
         }
@@ -176,7 +190,7 @@ export function groupRouteDefinitions(): RouteDefinition[] {
         if (!Array.isArray(body.updates)) {
           return httpError("BAD_REQUEST", "Missing updates array", 400);
         }
-        // Validate: no system group reordering, no sort_position < 3 for custom groups
+        // Validate: no system group reordering, sort_position >= 4 for custom groups
         for (const update of body.updates) {
           const group = getGroup(update.groupId);
           if (!group) continue;
@@ -190,11 +204,11 @@ export function groupRouteDefinitions(): RouteDefinition[] {
           if (
             typeof update.sortPosition !== "number" ||
             !isFinite(update.sortPosition) ||
-            update.sortPosition < 3
+            update.sortPosition < 4
           ) {
             return httpError(
               "BAD_REQUEST",
-              `Custom group sort_position must be >= 3 (got ${update.sortPosition} for ${update.groupId})`,
+              `Custom group sort_position must be >= 4 (got ${update.sortPosition} for ${update.groupId})`,
               400,
             );
           }

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

@@ -19,13 +19,14 @@ import {
   type CanonicalGuardianRequest,
   listPendingRequestsByConversationScope,
 } from "../../memory/canonical-guardian-store.js";
+import { isPermissionControlsV2Enabled } from "../../permissions/v2-consent-policy.js";
 import { requireBoundGuardian } from "../auth/require-bound-guardian.js";
 import type { AuthContext } from "../auth/types.js";
 import { processGuardianDecision } from "../guardian-action-service.js";
 import type { GuardianDecisionPrompt } from "../guardian-decision-types.js";
 import {
   buildDecisionActions,
-  GUARDIAN_DECISION_ACTIONS,
+  buildOneTimeDecisionActions,
 } from "../guardian-decision-types.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
@@ -98,6 +99,18 @@ export async function handleGuardianActionDecision(
     return httpError("BAD_REQUEST", "action is required", 400);
   }
 
+  if (
+    isPermissionControlsV2Enabled() &&
+    action !== "approve_once" &&
+    action !== "reject"
+  ) {
+    return httpError(
+      "FORBIDDEN",
+      "permission-controls-v2 only accepts approve_once or reject for guardian actions",
+      403,
+    );
+  }
+
   // 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,
@@ -193,15 +206,17 @@ export function listGuardianDecisionPrompts(params: {
  * Map a canonical guardian request to the client-facing prompt format.
  *
  * Generates kind-specific questionText and action sets:
- * - `tool_approval`: temporal modes (approve_once, approve_10m, approve_conversation) + reject
+ * - `tool_approval`: temporal modes (approve_once, approve_10m, approve_conversation) + reject in legacy mode,
+ *   approve_once + reject only under v2
  * - `pending_question`: approve_once + reject only
  * - `access_request`: approve_once + reject only, with text fallback instructions
  *   (request code + "open invite flow")
  * - `tool_grant_request`: approve_once + reject only
  *
- * Only `tool_approval` receives temporal modes because time-scoped grants
- * are meaningful only for tool execution. All other kinds get a simple
- * approve_once/reject pair.
+ * Under permission-controls-v2 we collapse all deterministic guardian action
+ * prompts to approve_once + reject only. Outside v2, only `tool_approval`
+ * receives temporal modes because time-scoped grants are meaningful only for
+ * tool execution.
  */
 function mapCanonicalRequestToPrompt(
   req: CanonicalGuardianRequest,
@@ -209,15 +224,11 @@ function mapCanonicalRequestToPrompt(
 ): GuardianDecisionPrompt {
   const questionText = buildKindAwareQuestionText(req);
 
-  // Only tool_approval gets temporal modes (approve_10m, approve_conversation);
-  // all other kinds get a simple approve_once + reject pair.
-  const actions =
-    req.kind === "tool_approval"
+  const actions = isPermissionControlsV2Enabled()
+    ? buildOneTimeDecisionActions()
+    : req.kind === "tool_approval"
       ? buildDecisionActions({ forGuardianOnBehalf: true })
-      : [
-          GUARDIAN_DECISION_ACTIONS.approve_once,
-          GUARDIAN_DECISION_ACTIONS.reject,
-        ];
+      : buildOneTimeDecisionActions();
 
   const expiresAt = req.expiresAt
     ? new Date(req.expiresAt).getTime()

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

@@ -0,0 +1,279 @@
+/**
+ * Route handler for host browser result submissions.
+ *
+ * Resolves pending host browser proxy requests by requestId when the desktop
+ * client returns CDP results via HTTP.
+ */
+import { z } from "zod";
+
+import {
+  markTargetInvalidated,
+  publishCdpEvent,
+} from "../../browser-session/events.js";
+import { requireBoundGuardian } from "../auth/require-bound-guardian.js";
+import type { AuthContext } from "../auth/types.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+import * as pendingInteractions from "../pending-interactions.js";
+
+/**
+ * Result of attempting to resolve a host browser result frame. Used by both
+ * the HTTP endpoint and the WS relay path so they share the same validation
+ * and resolution semantics.
+ *
+ * Success → the pending interaction was consumed and the conversation (or
+ * CLI shim callback) was notified.
+ *
+ * Error variants mirror the HTTP status codes the `/v1/host-browser-result`
+ * endpoint returns, so the caller can log/translate them consistently.
+ */
+export type HostBrowserResultResolution =
+  | { ok: true }
+  | {
+      ok: false;
+      code: "BAD_REQUEST" | "NOT_FOUND" | "CONFLICT";
+      status: 400 | 404 | 409;
+      message: string;
+    };
+
+/**
+ * Shared resolver used by both the HTTP route handler and the WS
+ * `host_browser_result` frame handler. Looks up the pending interaction
+ * by requestId, validates its kind, and forwards the response to the
+ * owning conversation (or CLI shim callback).
+ *
+ * This function does NOT perform auth — callers are expected to have
+ * already authenticated the caller (the HTTP route uses
+ * `requireBoundGuardian`, the WS path relies on the JWT check performed
+ * at WebSocket upgrade time).
+ */
+export function resolveHostBrowserResultByRequestId(frame: {
+  requestId?: unknown;
+  content?: unknown;
+  isError?: unknown;
+}): HostBrowserResultResolution {
+  const { requestId, content, isError } = frame;
+
+  if (!requestId || typeof requestId !== "string") {
+    return {
+      ok: false,
+      code: "BAD_REQUEST",
+      status: 400,
+      message: "requestId is required",
+    };
+  }
+
+  // Peek first (non-destructive) so we can validate the interaction kind
+  // without accidentally consuming a confirmation or secret interaction.
+  const peeked = pendingInteractions.get(requestId);
+  if (!peeked) {
+    return {
+      ok: false,
+      code: "NOT_FOUND",
+      status: 404,
+      message: "No pending interaction found for this requestId",
+    };
+  }
+
+  if (peeked.kind !== "host_browser") {
+    return {
+      ok: false,
+      code: "CONFLICT",
+      status: 409,
+      message: `Pending interaction is of kind "${peeked.kind}", expected "host_browser"`,
+    };
+  }
+
+  // Validation passed — consume the pending interaction.
+  const interaction = pendingInteractions.resolve(requestId)!;
+
+  const normalizedContent = typeof content === "string" ? content : "";
+  const normalizedIsError = typeof isError === "boolean" ? isError : false;
+
+  // CLI shim path: pending interactions registered by /v1/browser-cdp carry
+  // a directBrowserResolve callback and are not bound to a Conversation.
+  // Resolve them in place without touching the conversation object.
+  if (interaction.directBrowserResolve) {
+    interaction.directBrowserResolve({
+      content: normalizedContent,
+      isError: normalizedIsError,
+    });
+    return { ok: true };
+  }
+
+  // The host_browser kind always has a conversation attached at register time
+  // (HostBrowserProxy.request wires it through), so this guard exists so a
+  // future refactor of pending-interactions can change the type without
+  // silently breaking the host_browser path. Prefer an explicit error over an
+  // optional-chain no-op that would leave the proxy request unresolved.
+  if (!interaction.conversation) {
+    return {
+      ok: false,
+      code: "BAD_REQUEST",
+      status: 400,
+      message:
+        "host_browser pending interaction has no associated conversation",
+    };
+  }
+
+  interaction.conversation.resolveHostBrowser(requestId, {
+    content: normalizedContent,
+    isError: normalizedIsError,
+  });
+
+  return { ok: true };
+}
+
+/**
+ * Result of attempting to resolve a `host_browser_event` frame. The
+ * event surface never fails — every well-formed frame is published
+ * to the runtime-side CDP event bus — so the resolution is either
+ * `ok: true` or a `BAD_REQUEST` when the frame is malformed. Kept as
+ * a discriminated union (rather than `void`) so the WS dispatcher
+ * can log rejected frames with a consistent shape.
+ */
+export type HostBrowserEventResolution =
+  | { ok: true }
+  | {
+      ok: false;
+      code: "BAD_REQUEST";
+      status: 400;
+      message: string;
+    };
+
+/**
+ * Shared resolver for `host_browser_event` envelopes. Publishes the
+ * event into the module-level browser-session event bus where
+ * runtime-side consumers can subscribe. Validation is intentionally
+ * minimal — the frame is opaque to the bus and the bus's listeners
+ * are the ones that care about params shape.
+ */
+export function resolveHostBrowserEvent(frame: {
+  method?: unknown;
+  params?: unknown;
+  cdpSessionId?: unknown;
+}): HostBrowserEventResolution {
+  const { method, params, cdpSessionId } = frame;
+
+  if (!method || typeof method !== "string") {
+    return {
+      ok: false,
+      code: "BAD_REQUEST",
+      status: 400,
+      message: "method is required",
+    };
+  }
+
+  publishCdpEvent({
+    method,
+    params,
+    cdpSessionId:
+      typeof cdpSessionId === "string" && cdpSessionId.length > 0
+        ? cdpSessionId
+        : undefined,
+  });
+
+  return { ok: true };
+}
+
+/**
+ * Result of attempting to resolve a `host_browser_session_invalidated`
+ * frame. Mirrors {@link HostBrowserEventResolution} — publishing into
+ * the invalidated-target registry never fails, so the resolution is
+ * either `ok: true` or a `BAD_REQUEST` on a malformed frame.
+ */
+export type HostBrowserSessionInvalidatedResolution =
+  | { ok: true }
+  | {
+      ok: false;
+      code: "BAD_REQUEST";
+      status: 400;
+      message: string;
+    };
+
+/**
+ * Shared resolver for `host_browser_session_invalidated` envelopes.
+ * Marks the target as invalidated in the runtime-side registry; the
+ * next `BrowserSessionManager.send()` against that target will
+ * evict the stale session and force the owning tool to reattach.
+ *
+ * A frame without a `targetId` is tolerated (some detach notifications
+ * carry only a `reason`) but logged at info because it is less
+ * actionable than a targeted invalidation — the caller can still
+ * subscribe to the event bus to observe the signal.
+ */
+export function resolveHostBrowserSessionInvalidated(frame: {
+  targetId?: unknown;
+  reason?: unknown;
+}): HostBrowserSessionInvalidatedResolution {
+  const { targetId, reason } = frame;
+
+  if (targetId !== undefined && typeof targetId !== "string") {
+    return {
+      ok: false,
+      code: "BAD_REQUEST",
+      status: 400,
+      message: "targetId must be a string when present",
+    };
+  }
+
+  if (typeof targetId === "string" && targetId.length > 0) {
+    markTargetInvalidated(
+      targetId,
+      typeof reason === "string" ? reason : undefined,
+    );
+  }
+
+  return { ok: true };
+}
+
+/**
+ * POST /v1/host-browser-result — resolve a pending host browser request by requestId.
+ * Requires AuthContext with guardian-bound actor.
+ */
+export async function handleHostBrowserResult(
+  req: Request,
+  authContext: AuthContext,
+): Promise<Response> {
+  const authError = requireBoundGuardian(authContext);
+  if (authError) return authError;
+
+  const body = (await req.json()) as {
+    requestId?: string;
+    content?: string;
+    isError?: boolean;
+  };
+
+  const resolution = resolveHostBrowserResultByRequestId(body);
+  if (!resolution.ok) {
+    return httpError(resolution.code, resolution.message, resolution.status);
+  }
+
+  return Response.json({ accepted: true });
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function hostBrowserRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "host-browser-result",
+      method: "POST",
+      summary: "Submit host browser result",
+      description: "Resolve a pending host browser request by requestId.",
+      tags: ["host"],
+      requestBody: z.object({
+        requestId: z.string().describe("Pending browser request ID"),
+        content: z.string().optional(),
+        isError: z.boolean().optional(),
+      }),
+      responseBody: z.object({
+        accepted: z.boolean(),
+      }),
+      handler: async ({ req, authContext }) =>
+        handleHostBrowserResult(req, authContext),
+    },
+  ];
+}

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

@@ -27,9 +27,10 @@ export async function handleHostFileResult(
     requestId?: string;
     content?: string;
     isError?: boolean;
+    imageData?: string;
   };
 
-  const { requestId, content, isError } = body;
+  const { requestId, content, isError, imageData } = body;
 
   if (!requestId || typeof requestId !== "string") {
     return httpError("BAD_REQUEST", "requestId is required", 400);
@@ -60,6 +61,7 @@ export async function handleHostFileResult(
   interaction.conversation!.resolveHostFile(requestId, {
     content: content ?? "",
     isError: isError ?? false,
+    imageData,
   });
 
   return Response.json({ accepted: true });
@@ -87,6 +89,12 @@ export function hostFileRouteDefinitions(): RouteDefinition[] {
           .boolean()
           .describe("Whether the result is an error")
           .optional(),
+        imageData: z
+          .string()
+          .describe(
+            "Optional base64-encoded image bytes for successful image reads",
+          )
+          .optional(),
       }),
       responseBody: z.object({
         accepted: z.boolean(),