@vellumai/assistant 0.6.3 → 0.6.4

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/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(),
+      }),
+    },
+  ];
+}

package/src/runtime/routes/home-state-routes.ts

@@ -0,0 +1,138 @@
+/**
+ * Home state HTTP routes.
+ *
+ * Exposes `GET /v1/home/state` so macOS (and other) clients can fetch
+ * the current `RelationshipState` snapshot. The normal path reads
+ * the JSON file produced by `writeRelationshipState()`; if that file
+ * is missing — e.g. on a fresh install before the writer has landed
+ * its first snapshot — the handler falls back to computing the
+ * state on-demand so the client never sees a 404 and the UI can
+ * always render.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+
+import { z } from "zod";
+
+import {
+  computeRelationshipState,
+  getRelationshipStatePath,
+} from "../../home/relationship-state-writer.js";
+import { getLogger } from "../../util/logger.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+const log = getLogger("home-state-routes");
+
+// ---------------------------------------------------------------------------
+// Response schema (shared with the OpenAPI generator and runtime validation)
+// ---------------------------------------------------------------------------
+
+const factSchema = z.object({
+  id: z.string(),
+  category: z.enum(["voice", "world", "priorities"]),
+  text: z.string(),
+  confidence: z.enum(["strong", "uncertain"]),
+  source: z.enum(["onboarding", "inferred"]),
+});
+
+const capabilitySchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  description: z.string(),
+  tier: z.enum(["unlocked", "next-up", "earned"]),
+  gate: z.string(),
+  unlockHint: z.string().optional(),
+  ctaLabel: z.string().optional(),
+});
+
+const relationshipStateSchema = z.object({
+  version: z.literal(1),
+  assistantId: z.string(),
+  tier: z.union([z.literal(1), z.literal(2), z.literal(3), z.literal(4)]),
+  progressPercent: z.number(),
+  facts: z.array(factSchema),
+  capabilities: z.array(capabilitySchema),
+  conversationCount: z.number(),
+  hatchedDate: z.string(),
+  assistantName: z.string(),
+  userName: z.string().optional(),
+  updatedAt: z.string(),
+});
+
+/**
+ * Handle `GET /v1/home/state`.
+ *
+ * Always computes a fresh snapshot so the response reflects the
+ * latest OAuth connection state, conversation count, and extracted
+ * facts — not just whatever the conversation-complete writer last
+ * persisted. This avoids serving stale capability tiers when the
+ * user connects an integration between turns, or when a delete/wipe
+ * flow mutates conversation count outside the turn-boundary writer.
+ *
+ * The persisted `relationship-state.json` remains useful as:
+ *   - A seed for the existing-user backfill on daemon startup.
+ *   - A fallback when live compute fails (e.g. DB not yet ready at
+ *     cold start, or a transient filesystem error).
+ *
+ * The route does NOT write to disk or emit SSE on read — writes are
+ * still owned exclusively by the writer so turn-boundary SSE events
+ * remain tied to real state transitions rather than GET traffic.
+ */
+export async function handleGetHomeState(): Promise<Response> {
+  try {
+    const state = await computeRelationshipState();
+    return Response.json(state);
+  } catch (computeErr) {
+    log.warn(
+      { err: computeErr },
+      "Live compute failed; falling back to persisted relationship-state.json",
+    );
+  }
+
+  const path = getRelationshipStatePath();
+  if (existsSync(path)) {
+    try {
+      const raw = readFileSync(path, "utf-8");
+      const parsed: unknown = JSON.parse(raw);
+      const validated = relationshipStateSchema.safeParse(parsed);
+      if (validated.success) {
+        return Response.json(validated.data);
+      }
+      log.warn(
+        { path, issues: validated.error.issues },
+        "Persisted relationship-state.json failed schema validation",
+      );
+    } catch (err) {
+      log.warn(
+        { err, path },
+        "Failed to read persisted relationship-state.json as fallback",
+      );
+    }
+  }
+
+  return httpError(
+    "INTERNAL_ERROR",
+    "Failed to compute relationship state",
+    500,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export function homeStateRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "home/state",
+      method: "GET",
+      handler: () => handleGetHomeState(),
+      summary: "Get relationship state",
+      description:
+        "Return the current `RelationshipState` snapshot. Reads the persisted `relationship-state.json` when present; falls back to an on-demand compute so fresh installs never see a 404.",
+      tags: ["home"],
+      responseBody: relationshipStateSchema,
+    },
+  ];
+}

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

@@ -21,8 +21,8 @@ import * as pendingInteractions from "../pending-interactions.js";
  * 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.
+ * Success → the pending interaction was consumed and the conversation was
+ * notified.
  *
  * Error variants mirror the HTTP status codes the `/v1/host-browser-result`
  * endpoint returns, so the caller can log/translate them consistently.
@@ -40,7 +40,7 @@ export type HostBrowserResultResolution =
  * 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).
+ * owning conversation.
  *
  * This function does NOT perform auth — callers are expected to have
  * already authenticated the caller (the HTTP route uses
@@ -90,17 +90,6 @@ export function resolveHostBrowserResultByRequestId(frame: {
   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

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

@@ -4,7 +4,8 @@
  * The intro (a short identity tagline) is generated via the
  * /v1/btw endpoint and displayed on the Identity panel. To avoid redundant LLM
  * calls, we cache the result for 4 hours with content-hash-based invalidation:
- * when USER.md, IDENTITY.md, or SOUL.md change, the cache is busted.
+ * when IDENTITY.md, SOUL.md, or the guardian's per-user persona file change,
+ * the cache is busted.
  *
  * Storage uses the existing `memory_checkpoints` table (simple key-value store).
  */
@@ -16,6 +17,7 @@ import {
   getMemoryCheckpoint,
   setMemoryCheckpoint,
 } from "../../memory/checkpoints.js";
+import { resolveGuardianPersona } from "../../prompts/persona-resolver.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
 
 // ---------------------------------------------------------------------------
@@ -29,7 +31,7 @@ const CHECKPOINT_KEY_HASH = "identity:intro:content_hash";
 const CHECKPOINT_KEY_TIMESTAMP = "identity:intro:cached_at";
 
 /** Workspace files whose content influences the identity intro. */
-const IDENTITY_FILES = ["USER.md", "IDENTITY.md", "SOUL.md"] as const;
+const IDENTITY_FILES = ["IDENTITY.md", "SOUL.md"] as const;
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -48,7 +50,9 @@ function readWorkspaceFile(name: string): string {
 
 /** Compute a SHA-256 hex hash of the concatenated identity file contents. */
 export function computeIdentityContentHash(): string {
-  const combined = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");
+  const staticFiles = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");
+  const guardianPersona = resolveGuardianPersona() ?? "";
+  const combined = staticFiles + "\n---\n" + guardianPersona;
   return createHash("sha256").update(combined).digest("hex");
 }
 

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

@@ -4,8 +4,6 @@
 
 import { existsSync, readFileSync, statfsSync, statSync } from "node:fs";
 import { availableParallelism, cpus, totalmem } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 
 import { z } from "zod";
 
@@ -17,6 +15,7 @@ import {
   getWorkspaceDir,
   getWorkspacePromptPath,
 } from "../../util/platform.js";
+import { APP_VERSION } from "../../version.js";
 import { WORKSPACE_MIGRATIONS } from "../../workspace/migrations/registry.js";
 import { getLastWorkspaceMigrationId } from "../../workspace/migrations/runner.js";
 import { httpError } from "../http-errors.js";
@@ -370,19 +369,6 @@ function getCpuInfo(): CpuInfo {
   };
 }
 
-function getPackageVersion(): string | undefined {
-  try {
-    const pkgPath = join(
-      dirname(fileURLToPath(import.meta.url)),
-      "../../../package.json",
-    );
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-    return pkg.version;
-  } catch {
-    return undefined;
-  }
-}
-
 export function handleHealth(): Response {
   return Response.json({ status: "ok" });
 }
@@ -398,7 +384,7 @@ export function handleDetailedHealth(): Response {
   return Response.json({
     status: "healthy",
     timestamp: new Date().toISOString(),
-    version: getPackageVersion(),
+    version: APP_VERSION,
     disk: getDiskSpaceInfo(),
     memory: getMemoryInfo(),
     cpu: getCpuInfo(),
@@ -424,7 +410,7 @@ export function handleGetIdentity(): Response {
   const content = readFileSync(identityPath, "utf-8");
   const fields = parseIdentityFields(content);
 
-  const version = getPackageVersion();
+  const version = APP_VERSION;
 
   // Read createdAt from IDENTITY.md file birthtime
   let createdAt: string | undefined;