@vellumai/assistant 0.6.2 → 0.6.4

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/filing-routes.ts

@@ -0,0 +1,93 @@
+/**
+ * HTTP route handlers for filing management.
+ */
+
+import { z } from "zod";
+
+import { getConfig } from "../../config/loader.js";
+import type { FilingService } from "../../filing/filing-service.js";
+import { getLogger } from "../../util/logger.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+const log = getLogger("filing-routes");
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+function handleGetConfig(filingService?: FilingService): Response {
+  const config = getConfig().filing;
+  return Response.json({
+    enabled: config.enabled,
+    intervalMs: config.intervalMs,
+    activeHoursStart: config.activeHoursStart ?? null,
+    activeHoursEnd: config.activeHoursEnd ?? null,
+    nextRunAt: filingService?.nextRunAt ?? null,
+    lastRunAt: filingService?.lastRunAt ?? null,
+    success: true,
+  });
+}
+
+async function handleRunNow(
+  filingService?: FilingService,
+): Promise<Response> {
+  if (!filingService) {
+    return httpError(
+      "SERVICE_UNAVAILABLE",
+      "Filing service not available",
+      503,
+    );
+  }
+
+  try {
+    const ran = await filingService.runOnce({ force: true });
+    return Response.json({ success: true, ran });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err }, "Filing run-now failed");
+    return Response.json({ success: false, ran: false, error: message });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function filingRouteDefinitions(deps: {
+  getFilingService?: () => FilingService | undefined;
+}): RouteDefinition[] {
+  return [
+    {
+      endpoint: "filing/config",
+      method: "GET",
+      policyKey: "filing",
+      summary: "Get filing config",
+      description: "Return the current filing schedule configuration.",
+      tags: ["filing"],
+      responseBody: z.object({
+        enabled: z.boolean(),
+        intervalMs: z.number(),
+        activeHoursStart: z.number().nullable(),
+        activeHoursEnd: z.number().nullable(),
+        nextRunAt: z.number().nullable(),
+        lastRunAt: z.number().nullable(),
+        success: z.boolean(),
+      }),
+      handler: () => handleGetConfig(deps.getFilingService?.()),
+    },
+    {
+      endpoint: "filing/run-now",
+      method: "POST",
+      policyKey: "filing",
+      summary: "Run filing now",
+      description: "Trigger an immediate filing run.",
+      tags: ["filing"],
+      responseBody: z.object({
+        success: z.boolean(),
+        ran: z.boolean().describe("Whether the filing actually ran"),
+      }),
+      handler: () => handleRunNow(deps.getFilingService?.()),
+    },
+  ];
+}

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/home-feed-routes.ts

@@ -0,0 +1,334 @@
+/**
+ * Home activity feed HTTP routes.
+ *
+ * Exposes the three endpoints the macOS Home page uses to render and
+ * interact with the activity feed:
+ *
+ *   - `GET  /v1/home/feed`                         — read + filter
+ *   - `PATCH /v1/home/feed/:id`                    — mark seen / acted_on
+ *   - `POST  /v1/home/feed/:id/actions/:actionId`  — trigger an action
+ *
+ * The routes are always available — the `home-feed` feature flag gates
+ * the client rendering path only, so the daemon surface can ship ahead
+ * of the rollout and client versions can adopt independently of
+ * feature-flag timing.
+ *
+ * All persistence goes through `readHomeFeed` / `patchFeedItemStatus`
+ * in `home/feed-writer.ts`; this module does not touch the on-disk
+ * file directly. The writer already applies the TTL filter on read
+ * and owns all SSE publication, so the route handlers stay pure
+ * shape + validation + banner computation.
+ */
+
+import { z } from "zod";
+
+import {
+  type FeedItem,
+  feedItemSchema,
+  type FeedItemStatus,
+} from "../../home/feed-types.js";
+import { patchFeedItemStatus, readHomeFeed } from "../../home/feed-writer.js";
+import {
+  addMessage,
+  createConversation,
+} from "../../memory/conversation-crud.js";
+import { getLogger } from "../../util/logger.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+const log = getLogger("home-feed-routes");
+
+// ---------------------------------------------------------------------------
+// Response / request schemas
+// ---------------------------------------------------------------------------
+
+const contextBannerSchema = z.object({
+  greeting: z.string(),
+  timeAwayLabel: z.string(),
+  newCount: z.number().int().min(0),
+});
+
+const getHomeFeedResponseSchema = z.object({
+  items: z.array(feedItemSchema),
+  updatedAt: z.string(),
+  contextBanner: contextBannerSchema,
+});
+
+const patchFeedItemRequestSchema = z.object({
+  status: z.enum(["new", "seen", "acted_on"]),
+});
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for direct testing — see home-feed-routes.test.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * Map the server's wall-clock hour to a human greeting. Pure function;
+ * no LLM. The buckets match the plan:
+ *   - 05:00–11:59 → "Good morning"
+ *   - 12:00–16:59 → "Good afternoon"
+ *   - 17:00–21:59 → "Good evening"
+ *   - otherwise   → "Welcome back"
+ */
+export function computeGreeting(now: Date): string {
+  const hour = now.getHours();
+  if (hour >= 5 && hour < 12) return "Good morning";
+  if (hour >= 12 && hour < 17) return "Good afternoon";
+  if (hour >= 17 && hour < 22) return "Good evening";
+  return "Welcome back";
+}
+
+/**
+ * Format a `timeAwaySeconds` value as a coarse relative-time label.
+ * Kept in-file since no other caller needs it yet; extract to a shared
+ * util module when a second caller appears.
+ */
+export function formatRelativeTime(seconds: number): string {
+  if (!Number.isFinite(seconds) || seconds < 60) return "just now";
+  if (seconds < 3600) {
+    const mins = Math.floor(seconds / 60);
+    return `${mins} minute${mins === 1 ? "" : "s"} ago`;
+  }
+  if (seconds < 86400) {
+    const hours = Math.floor(seconds / 3600);
+    return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  }
+  if (seconds < 172800) return "yesterday";
+  const days = Math.floor(seconds / 86400);
+  return `${days} day${days === 1 ? "" : "s"} ago`;
+}
+
+/**
+ * Bucket `timeAwaySeconds` into coarse ranges used only for debug
+ * logging cardinality control. Not exposed to clients.
+ */
+function timeAwayBucket(seconds: number): string {
+  if (seconds < 1800) return "<1800";
+  if (seconds < 14400) return "1800-14400";
+  if (seconds < 43200) return "14400-43200";
+  if (seconds < 86400) return "43200-86400";
+  return ">=86400";
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * `GET /v1/home/feed`.
+ *
+ * Required query param: `timeAwaySeconds` (non-negative integer). The
+ * handler reads the feed via `readHomeFeed()` (which has already
+ * applied TTL filtering), drops items whose `minTimeAway` exceeds the
+ * client-reported time away, then computes the context banner.
+ */
+export async function handleGetHomeFeed(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const raw = url.searchParams.get("timeAwaySeconds");
+  if (raw === null) {
+    return httpError(
+      "BAD_REQUEST",
+      "Missing required query parameter: timeAwaySeconds",
+      400,
+    );
+  }
+  const parsed = Number(raw);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    return httpError(
+      "BAD_REQUEST",
+      "timeAwaySeconds must be a non-negative integer",
+      400,
+    );
+  }
+  const timeAwaySeconds = parsed;
+
+  const feed = readHomeFeed();
+  const filtered = feed.items.filter((item) => {
+    if (item.minTimeAway === undefined) return true;
+    return item.minTimeAway <= timeAwaySeconds;
+  });
+
+  const now = new Date();
+  const contextBanner = {
+    greeting: computeGreeting(now),
+    timeAwayLabel: formatRelativeTime(timeAwaySeconds),
+    newCount: filtered.filter((i) => i.status === "new").length,
+  };
+
+  log.debug(
+    {
+      timeAwayBucket: timeAwayBucket(timeAwaySeconds),
+      totalItems: feed.items.length,
+      filteredItems: filtered.length,
+      newCount: contextBanner.newCount,
+    },
+    "GET /v1/home/feed",
+  );
+
+  return Response.json({
+    items: filtered,
+    updatedAt: feed.updatedAt,
+    contextBanner,
+  });
+}
+
+/**
+ * `PATCH /v1/home/feed/:id`.
+ *
+ * Body: `{ status: "new" | "seen" | "acted_on" }`. Returns the updated
+ * `FeedItem` on success.
+ *
+ * Disambiguates the writer's `null` return by looking up the item via
+ * `readHomeFeed()` first — if the lookup finds the item and the patch
+ * still returns null, it's a write failure (500), not a missing id
+ * (404).
+ */
+export async function handlePatchFeedItem(
+  req: Request,
+  itemId: string,
+): Promise<Response> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return httpError("BAD_REQUEST", "Invalid JSON body", 400);
+  }
+
+  const parsed = patchFeedItemRequestSchema.safeParse(body);
+  if (!parsed.success) {
+    return httpError("BAD_REQUEST", "Invalid request body", 400, {
+      issues: parsed.error.issues,
+    });
+  }
+  const status: FeedItemStatus = parsed.data.status;
+
+  // Pre-check for existence so we can distinguish "unknown id" (404)
+  // from "found, but write failed" (500). The writer applies the patch
+  // inside its coalescing queue against the same on-disk state we just
+  // read, so a race where the item disappears between the check and
+  // the write resolves cleanly as a 500 (write failed / no such item).
+  const currentFeed = readHomeFeed();
+  const existing = currentFeed.items.find((i) => i.id === itemId);
+  if (!existing) {
+    return httpError("NOT_FOUND", `Feed item not found: ${itemId}`, 404);
+  }
+
+  const updated = await patchFeedItemStatus(itemId, status);
+  if (!updated) {
+    log.warn(
+      { itemId, status },
+      "patchFeedItemStatus returned null despite pre-check — treating as write failure",
+    );
+    return httpError(
+      "INTERNAL_ERROR",
+      "Failed to persist feed item status",
+      500,
+    );
+  }
+
+  return Response.json(updated);
+}
+
+/**
+ * `POST /v1/home/feed/:id/actions/:actionId`.
+ *
+ * Looks up the item + action, creates a new conversation pre-seeded
+ * with the action's `prompt` as the first user message, and returns
+ * `{ conversationId }`. Any lookup failure → 404; conversation create
+ * error → 500.
+ */
+export async function handlePostFeedAction(
+  _req: Request,
+  itemId: string,
+  actionId: string,
+): Promise<Response> {
+  const feed = readHomeFeed();
+  const item: FeedItem | undefined = feed.items.find((i) => i.id === itemId);
+  if (!item) {
+    return httpError("NOT_FOUND", `Feed item not found: ${itemId}`, 404);
+  }
+
+  const action = item.actions?.find((a) => a.id === actionId);
+  if (!action) {
+    return httpError(
+      "NOT_FOUND",
+      `Action not found on item ${itemId}: ${actionId}`,
+      404,
+    );
+  }
+
+  try {
+    const conversation = createConversation({
+      title: action.label,
+      source: "home-feed",
+    });
+    await addMessage(
+      conversation.id,
+      "user",
+      JSON.stringify([{ type: "text", text: action.prompt }]),
+    );
+    return Response.json({ conversationId: conversation.id });
+  } catch (err) {
+    log.warn(
+      { err, itemId, actionId },
+      "Failed to create conversation from feed action",
+    );
+    return httpError(
+      "INTERNAL_ERROR",
+      "Failed to create conversation for feed action",
+      500,
+    );
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function homeFeedRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "home/feed",
+      method: "GET",
+      handler: ({ req }) => handleGetHomeFeed(req),
+      summary: "Get home activity feed",
+      description:
+        "Return the current Home activity feed with TTL + time-away filtering applied. Also returns a context banner (greeting, relative time-away label, new-item count).",
+      tags: ["home"],
+      queryParams: [
+        {
+          name: "timeAwaySeconds",
+          type: "integer",
+          required: true,
+          description:
+            "Seconds since the user was last active in the client. Used to filter items with a `minTimeAway` gate and to compute the context-banner relative-time label.",
+        },
+      ],
+      responseBody: getHomeFeedResponseSchema,
+    },
+    {
+      endpoint: "home/feed/:id",
+      method: "PATCH",
+      handler: ({ req, params }) => handlePatchFeedItem(req, params.id),
+      summary: "Patch home feed item status",
+      description:
+        "Update the `status` field of a single feed item (e.g. mark it seen or acted_on). Returns the updated item on success, 404 if the item does not exist, 500 if the underlying write fails.",
+      tags: ["home"],
+      requestBody: patchFeedItemRequestSchema,
+      responseBody: feedItemSchema,
+    },
+    {
+      endpoint: "home/feed/:id/actions/:actionId",
+      method: "POST",
+      handler: ({ req, params }) =>
+        handlePostFeedAction(req, params.id, params.actionId),
+      summary: "Trigger home feed action",
+      description:
+        "Create a new conversation pre-seeded with the action's prompt as the first user message. Returns the new `conversationId`.",
+      tags: ["home"],
+      responseBody: z.object({
+        conversationId: z.string(),
+      }),
+    },
+  ];
+}