@vellumai/assistant 0.8.5 → 0.8.6

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

@@ -62,6 +62,32 @@ const patchFeedItemRequestSchema = z.object({
   status: z.enum(["new", "seen", "acted_on", "dismissed"]),
 });
 
+const listHomeFeedRequestSchema = z.object({
+  includeDismissed: z.boolean().optional(),
+  statuses: z
+    .array(z.enum(["new", "seen", "acted_on", "dismissed"]))
+    .optional(),
+  before: z.string().optional(),
+  after: z.string().optional(),
+  urgencies: z.array(z.enum(["low", "medium", "high", "critical"])).optional(),
+  categories: z
+    .array(z.enum(["security", "scheduling", "background", "email", "system"]))
+    .optional(),
+  conversationId: z.string().optional(),
+  fromAssistant: z.boolean().optional(),
+  noteworthy: z.boolean().optional(),
+  limit: z.number().int().positive().max(200).optional(),
+  offset: z.number().int().nonnegative().optional(),
+});
+
+const listHomeFeedResponseSchema = z.object({
+  items: z.array(feedItemSchema),
+  total: z.number().int().nonnegative(),
+  returned: z.number().int().nonnegative(),
+  hasMore: z.boolean(),
+  updatedAt: z.string(),
+});
+
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for direct testing)
 // ---------------------------------------------------------------------------
@@ -183,6 +209,97 @@ export async function handlePatchFeedItem({
   return updated as unknown as Record<string, unknown>;
 }
 
+export function handleListHomeFeed({
+  body = {},
+}: RouteHandlerArgs): Record<string, unknown> {
+  const parsed = listHomeFeedRequestSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new BadRequestError(
+      `Invalid list request: ${parsed.error.issues
+        .map((i) => `${i.path.join(".")} ${i.message}`)
+        .join("; ")}`,
+    );
+  }
+  const params = parsed.data;
+
+  const beforeMs =
+    params.before !== undefined ? Date.parse(params.before) : undefined;
+  if (beforeMs !== undefined && Number.isNaN(beforeMs)) {
+    throw new BadRequestError(
+      `Invalid 'before' timestamp; expected ISO-8601 (got "${params.before}")`,
+    );
+  }
+  const afterMs =
+    params.after !== undefined ? Date.parse(params.after) : undefined;
+  if (afterMs !== undefined && Number.isNaN(afterMs)) {
+    throw new BadRequestError(
+      `Invalid 'after' timestamp; expected ISO-8601 (got "${params.after}")`,
+    );
+  }
+
+  // `statuses` is the explicit override. Otherwise default to excluding
+  // dismissed unless includeDismissed=true — the assistant's primary use
+  // case is "what's still outstanding", so dismissed items are noise
+  // unless explicitly requested.
+  const statusFilter: Set<FeedItemStatus> | null = params.statuses
+    ? new Set(params.statuses)
+    : params.includeDismissed
+      ? null
+      : new Set<FeedItemStatus>(["new", "seen", "acted_on"]);
+
+  const urgencySet = params.urgencies ? new Set(params.urgencies) : null;
+  const categorySet = params.categories ? new Set(params.categories) : null;
+
+  const feed = readHomeFeed();
+
+  const filtered = feed.items.filter((item) => {
+    if (statusFilter && !statusFilter.has(item.status)) return false;
+    if (urgencySet) {
+      if (!item.urgency || !urgencySet.has(item.urgency)) return false;
+    }
+    if (categorySet) {
+      if (!item.category || !categorySet.has(item.category)) return false;
+    }
+    if (
+      params.conversationId !== undefined &&
+      item.conversationId !== params.conversationId
+    )
+      return false;
+    if (
+      params.fromAssistant !== undefined &&
+      (item.fromAssistant ?? false) !== params.fromAssistant
+    )
+      return false;
+    if (
+      params.noteworthy !== undefined &&
+      (item.noteworthy ?? false) !== params.noteworthy
+    )
+      return false;
+
+    if (beforeMs !== undefined || afterMs !== undefined) {
+      const createdMs = Date.parse(item.createdAt);
+      if (Number.isNaN(createdMs)) return false;
+      if (beforeMs !== undefined && createdMs >= beforeMs) return false;
+      if (afterMs !== undefined && createdMs <= afterMs) return false;
+    }
+
+    return true;
+  });
+
+  const total = filtered.length;
+  const offset = params.offset ?? 0;
+  const limit = params.limit ?? 20;
+  const items = filtered.slice(offset, offset + limit);
+
+  return {
+    items,
+    total,
+    returned: items.length,
+    hasMore: total > offset + items.length,
+    updatedAt: feed.updatedAt,
+  };
+}
+
 export async function handlePostFeedAction({
   pathParams = {},
 }: RouteHandlerArgs): Promise<Record<string, unknown>> {
@@ -261,6 +378,18 @@ export const ROUTES: RouteDefinition[] = [
       "500": { description: "Failed to persist feed item status" },
     },
   },
+  {
+    operationId: "list_home_feed",
+    endpoint: "home/feed/query",
+    method: "POST",
+    handler: handleListHomeFeed,
+    summary: "List home feed items with filters",
+    description:
+      "Return home feed items filtered by status, urgency, category, conversation, and date range. Defaults to excluding dismissed items. Used by the assistant CLI to inspect what notifications have been surfaced to the user.",
+    tags: ["home"],
+    requestBody: listHomeFeedRequestSchema,
+    responseBody: listHomeFeedResponseSchema,
+  },
   {
     operationId: "trigger_home_feed_action",
     endpoint: "home/feed/:id/actions/:actionId",

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

@@ -1,11 +1,13 @@
 /**
- * Caching layer for the LLM-generated identity intro text.
+ * Caching layer for identity greetings.
  *
- * 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 IDENTITY.md, SOUL.md, or the guardian's per-user persona file change,
- * the cache is busted.
+ * Greetings are sourced from (in priority order):
+ * 1. A `## Greetings` section in SOUL.md (user-defined bullet list)
+ * 2. A cached greetings array (populated by the BTW side-chain LLM call)
+ * 3. Fallback: the assistant name from IDENTITY.md
+ *
+ * Cache uses TTL + content-hash invalidation: when IDENTITY.md, SOUL.md, or
+ * the guardian persona change, the cache is busted.
  *
  * Storage uses the existing `memory_checkpoints` table (simple key-value store).
  */
@@ -26,7 +28,7 @@ import { getWorkspacePromptPath } from "../../util/platform.js";
 
 const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
 
-const CHECKPOINT_KEY_TEXT = "identity:intro:text";
+const CHECKPOINT_KEY_GREETINGS = "identity:intro:greetings";
 const CHECKPOINT_KEY_HASH = "identity:intro:content_hash";
 const CHECKPOINT_KEY_TIMESTAMP = "identity:intro:cached_at";
 
@@ -78,6 +80,40 @@ export function readWorkspaceIdentityIntro(): string | null {
   );
 }
 
+/**
+ * Parse the `## Greetings` section from SOUL.md. Returns bullet items as an
+ * array of strings, or `null` if the section is missing or empty.
+ */
+export function parseGreetingsSection(content: string): string[] | null {
+  let inSection = false;
+  const greetings: string[] = [];
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (/^#+\s/.test(trimmed)) {
+      if (inSection) break;
+      inSection = /^#+\s+greetings\s*$/i.test(trimmed);
+      continue;
+    }
+    if (!inSection) continue;
+    const bullet = trimmed.replace(/^[-*]\s+/, "");
+    if (bullet.length > 0 && bullet !== trimmed) {
+      greetings.push(bullet);
+    }
+  }
+
+  return greetings.length > 0 ? greetings : null;
+}
+
+/**
+ * Read user-defined greetings from the `## Greetings` section of SOUL.md.
+ */
+export function readWorkspaceGreetings(): string[] | null {
+  const soulContent = readWorkspaceFile("SOUL.md");
+  if (!soulContent) return null;
+  return parseGreetingsSection(soulContent);
+}
+
 /** Compute a SHA-256 hex hash of the concatenated identity file contents. */
 export function computeIdentityContentHash(): string {
   const staticFiles = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");
@@ -91,22 +127,22 @@ export function computeIdentityContentHash(): string {
 // ---------------------------------------------------------------------------
 
 export interface CachedIntro {
-  text: string;
+  greetings: string[];
 }
 
 /**
- * Retrieve the cached identity intro if it exists, is within the TTL window,
+ * Retrieve the cached greetings array if it exists, is within the TTL window,
  * and the identity files have not changed since it was generated.
  *
  * Returns `null` when the cache is missing, expired, or invalidated.
  */
 export function getCachedIntro(): CachedIntro | null {
   try {
-    const text = getMemoryCheckpoint(CHECKPOINT_KEY_TEXT);
+    const raw = getMemoryCheckpoint(CHECKPOINT_KEY_GREETINGS);
     const hash = getMemoryCheckpoint(CHECKPOINT_KEY_HASH);
     const timestampStr = getMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
 
-    if (!text || !hash || !timestampStr) return null;
+    if (!raw || !hash || !timestampStr) return null;
 
     // TTL check
     const cachedAt = Number(timestampStr);
@@ -116,21 +152,30 @@ export function getCachedIntro(): CachedIntro | null {
     const currentHash = computeIdentityContentHash();
     if (currentHash !== hash) return null;
 
-    return { text };
+    // Parse stored value — handles both JSON array and legacy single string
+    let greetings: string[];
+    try {
+      const parsed = JSON.parse(raw);
+      greetings = Array.isArray(parsed) ? parsed : [raw];
+    } catch {
+      greetings = [raw];
+    }
+
+    return { greetings };
   } catch {
     return null;
   }
 }
 
 /**
- * Store the generated identity intro text in the cache along with
- * the current content hash and timestamp.
+ * Store a greetings array in the cache along with the current content hash
+ * and timestamp.
  */
-export function setCachedIntro(text: string): void {
+export function setCachedIntro(greetings: string[]): void {
   try {
     const hash = computeIdentityContentHash();
     const now = String(Date.now());
-    setMemoryCheckpoint(CHECKPOINT_KEY_TEXT, text);
+    setMemoryCheckpoint(CHECKPOINT_KEY_GREETINGS, JSON.stringify(greetings));
     setMemoryCheckpoint(CHECKPOINT_KEY_HASH, hash);
     setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, now);
   } catch {

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

@@ -23,7 +23,10 @@ import { resolveHatchedAtReadOnly } from "../../workspace/hatched-date.js";
 import { WORKSPACE_MIGRATIONS } from "../../workspace/migrations/registry.js";
 import { getLastWorkspaceMigrationId } from "../../workspace/migrations/runner.js";
 import { NotFoundError } from "./errors.js";
-import { getCachedIntro } from "./identity-intro-cache.js";
+import {
+  getCachedIntro,
+  readWorkspaceGreetings,
+} from "./identity-intro-cache.js";
 import type { RouteDefinition } from "./types.js";
 
 interface MemoryInfo {
@@ -391,21 +394,38 @@ function resolveIdentityCreatedAt(identityPath: string): string | undefined {
   return resolveHatchedAtReadOnly(identityPath);
 }
 
+const FALLBACK_GREETINGS = [
+  "What are we working on?",
+  "I'm here whenever you need me.",
+  "What's on your mind?",
+  "Ready when you are.",
+];
+
 function getIdentityIntro() {
+  // 1. User-defined greetings from SOUL.md `## Greetings`
+  const workspaceGreetings = readWorkspaceGreetings();
+  if (workspaceGreetings) {
+    return { greetings: workspaceGreetings, text: workspaceGreetings[0] };
+  }
+
+  // 2. Cached LLM-generated greetings
+  const cached = getCachedIntro();
+  if (cached) {
+    return { greetings: cached.greetings, text: cached.greetings[0] };
+  }
+
+  // 3. Fallback: name-based greeting + static defaults
   const identityPath = getWorkspacePromptPath("IDENTITY.md");
   if (existsSync(identityPath)) {
     const content = readFileSync(identityPath, "utf-8");
     const fields = parseIdentityFields(content);
     if (fields.name) {
-      return { text: `Hi, I'm ${fields.name}!` };
+      const greetings = [`Hi, I'm ${fields.name}!`, ...FALLBACK_GREETINGS];
+      return { greetings, text: greetings[0] };
     }
   }
 
-  const cached = getCachedIntro();
-  if (!cached) {
-    throw new NotFoundError("No cached identity intro available");
-  }
-  return { text: cached.text };
+  return { greetings: FALLBACK_GREETINGS, text: FALLBACK_GREETINGS[0] };
 }
 
 // ---------------------------------------------------------------------------
@@ -512,11 +532,12 @@ export const ROUTES: RouteDefinition[] = [
     endpoint: "identity/intro",
     method: "GET",
     handler: getIdentityIntro,
-    summary: "Get identity intro text",
+    summary: "Get identity greetings",
     description:
-      "Returns a deterministic greeting derived from the assistant name in IDENTITY.md, falling back to LLM-generated cache.",
+      "Returns an array of greetings sourced from SOUL.md, LLM cache, or static fallbacks.",
     tags: ["identity"],
     responseBody: z.object({
+      greetings: z.array(z.string()),
       text: z.string(),
     }),
   },