@vellumai/assistant 0.6.2 → 0.6.4

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

@@ -0,0 +1,268 @@
+/**
+ * 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 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.
+ *
+ * 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;
+
+  // 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(),

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");
 }