@vellumai/assistant 0.5.2 → 0.5.3

package/src/memory/brief-open-loops.ts

@@ -0,0 +1,266 @@
+/**
+ * Open-loop brief compiler.
+ *
+ * Merges reducer-created open_loops rows with live task queue (work items)
+ * and follow-up state into a ranked, deduplicated list of bullets for the
+ * memory brief.
+ *
+ * Ranking tiers (highest first):
+ *   1. Overdue     — dueAt in the past
+ *   2. Due ≤ 24 h  — dueAt within the next 24 hours
+ *   3. Due ≤ 7 d   — dueAt within the next 7 days
+ *   4. High-priority / blocked — work items at priority tier 0 or
+ *      follow-ups with status "nudged"
+ *   5. Recently touched — updatedAt within the last 48 hours
+ *
+ * After ranked items, at most ONE low-salience loop is resurfaced via
+ * deterministic pseudo-random sampling seeded by `scopeId + userMessageId`.
+ * The resurfaced loop's `surfacedAt` is updated so it won't repeat
+ * immediately.
+ */
+
+import { and, eq } from "drizzle-orm";
+
+import {
+  type BriefFollowUp,
+  getPendingAndOverdueFollowUps,
+} from "../followups/followup-store.js";
+import {
+  type ActionableWorkItem,
+  getActionableWorkItems,
+} from "../tasks/task-store.js";
+import { getDb } from "./db.js";
+import { updateLastSurfacedAt } from "./reducer-store.js";
+import { openLoops } from "./schema.js";
+
+// ── Constants ─────────────────────────────────────────────────────────
+
+const MS_24H = 24 * 60 * 60 * 1000;
+const MS_7D = 7 * 24 * 60 * 60 * 1000;
+const MS_48H = 48 * 60 * 60 * 1000;
+
+// ── Types ─────────────────────────────────────────────────────────────
+
+export interface OpenLoopBullet {
+  /** Dedupe key — one of `loop:<id>`, `work:<id>`, or `followup:<id>`. */
+  key: string;
+  summary: string;
+  tier: number; // 1–5, lower = higher priority
+  source: "loop" | "work_item" | "followup";
+  sourceId: string;
+}
+
+export interface OpenLoopBriefResult {
+  /** Bullets ordered by tier then recency. */
+  bullets: OpenLoopBullet[];
+  /** ID of the resurfaced low-salience loop, if any. */
+  resurfacedLoopId: string | null;
+}
+
+interface OpenLoopRow {
+  id: string;
+  scopeId: string;
+  summary: string;
+  status: string;
+  source: string;
+  dueAt: number | null;
+  surfacedAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+// ── Deterministic hash ────────────────────────────────────────────────
+
+/**
+ * Simple 32-bit FNV-1a hash for deterministic pseudo-random selection.
+ * Not cryptographic — only needs to be well-distributed for sampling.
+ */
+function fnv1a(input: string): number {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    h ^= input.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0; // unsigned 32-bit
+}
+
+// ── Tier assignment ───────────────────────────────────────────────────
+
+function assignLoopTier(loop: OpenLoopRow, now: number): number {
+  if (loop.dueAt != null) {
+    if (loop.dueAt <= now) return 1; // overdue
+    if (loop.dueAt <= now + MS_24H) return 2; // due within 24h
+    if (loop.dueAt <= now + MS_7D) return 3; // due within 7d
+  }
+  if (now - loop.updatedAt <= MS_48H) return 5; // recently touched
+  return 6; // low salience — candidate for resurfacing
+}
+
+function assignWorkItemTier(item: ActionableWorkItem, now: number): number {
+  if (item.priorityTier === 0) return 4; // high priority
+  if (item.status === "awaiting_review") return 4;
+  if (now - item.updatedAt <= MS_48H) return 5;
+  return 6;
+}
+
+function assignFollowUpTier(fu: BriefFollowUp, now: number): number {
+  if (fu.expectedResponseBy != null && fu.expectedResponseBy <= now) return 1;
+  if (fu.expectedResponseBy != null && fu.expectedResponseBy <= now + MS_24H)
+    return 2;
+  if (fu.expectedResponseBy != null && fu.expectedResponseBy <= now + MS_7D)
+    return 3;
+  if (fu.status === "nudged") return 4;
+  if (now - fu.updatedAt <= MS_48H) return 5;
+  return 6;
+}
+
+// ── Compiler ──────────────────────────────────────────────────────────
+
+/**
+ * Compile the open-loop section of the memory brief.
+ *
+ * @param scopeId   Memory scope (e.g. assistant instance ID)
+ * @param userMessageId  Current user message ID — used as part of the
+ *                       resurfacing seed so the selection is deterministic
+ *                       per turn but varies across turns.
+ * @param now       Current epoch-ms timestamp (injectable for testing).
+ */
+export function compileOpenLoopBrief(
+  scopeId: string,
+  userMessageId: string,
+  now: number = Date.now(),
+): OpenLoopBriefResult {
+  // 1. Gather data from all three sources
+  const loops = getOpenLoopsForScope(scopeId);
+  const workItems = getActionableWorkItems();
+  const followUps = getPendingAndOverdueFollowUps();
+
+  // 2. Convert to bullets with tier assignment
+  const bullets: OpenLoopBullet[] = [];
+  const seenKeys = new Set<string>();
+
+  // Loops first (they are the authoritative open-loop source)
+  for (const loop of loops) {
+    const key = `loop:${loop.id}`;
+    if (seenKeys.has(key)) continue;
+    seenKeys.add(key);
+    bullets.push({
+      key,
+      summary: loop.summary,
+      tier: assignLoopTier(loop, now),
+      source: "loop",
+      sourceId: loop.id,
+    });
+  }
+
+  // Work items — skip if already represented by a loop with matching summary
+  const loopSummaries = new Set(loops.map((l) => l.summary.toLowerCase()));
+  for (const item of workItems) {
+    const key = `work:${item.id}`;
+    if (seenKeys.has(key)) continue;
+    // Deduplicate against loop summaries
+    if (loopSummaries.has(item.title.toLowerCase())) continue;
+    seenKeys.add(key);
+    bullets.push({
+      key,
+      summary: item.title,
+      tier: assignWorkItemTier(item, now),
+      source: "work_item",
+      sourceId: item.id,
+    });
+  }
+
+  // Follow-ups — skip if already represented by a loop
+  for (const fu of followUps) {
+    const key = `followup:${fu.id}`;
+    if (seenKeys.has(key)) continue;
+    const fuSummary =
+      `Awaiting reply on ${fu.channel} (${fu.conversationId})`.toLowerCase();
+    if (loopSummaries.has(fuSummary)) continue;
+    seenKeys.add(key);
+    bullets.push({
+      key,
+      summary: `Awaiting reply on ${fu.channel} (${fu.conversationId})`,
+      tier: assignFollowUpTier(fu, now),
+      source: "followup",
+      sourceId: fu.id,
+    });
+  }
+
+  // 3. Split into ranked (tiers 1–5) and low-salience (tier 6)
+  const ranked: OpenLoopBullet[] = [];
+  const lowSalience: OpenLoopBullet[] = [];
+
+  for (const b of bullets) {
+    if (b.tier <= 5) {
+      ranked.push(b);
+    } else {
+      lowSalience.push(b);
+    }
+  }
+
+  // Sort ranked: by tier ascending, then by source priority (loop > work > followup)
+  ranked.sort((a, b) => {
+    if (a.tier !== b.tier) return a.tier - b.tier;
+    return sourcePriority(a.source) - sourcePriority(b.source);
+  });
+
+  // 4. Deterministic resurfacing of ONE low-salience loop
+  let resurfacedLoopId: string | null = null;
+
+  if (lowSalience.length > 0) {
+    // Only consider loops from the open_loops table for resurfacing
+    // (work items and follow-ups have their own lifecycle)
+    const resurfaceCandidates = lowSalience.filter((b) => b.source === "loop");
+
+    if (resurfaceCandidates.length > 0) {
+      // Sort candidates deterministically by key for stable ordering
+      resurfaceCandidates.sort((a, b) => a.key.localeCompare(b.key));
+
+      const seed = `${scopeId}:${userMessageId}`;
+      const hash = fnv1a(seed);
+      const idx = hash % resurfaceCandidates.length;
+      const picked = resurfaceCandidates[idx];
+
+      // Promote picked to tier 5 and add to ranked output
+      ranked.push({ ...picked, tier: 5 });
+      resurfacedLoopId = picked.sourceId;
+
+      // Update surfacedAt so it is deprioritised on subsequent turns
+      updateLastSurfacedAt(picked.sourceId, now);
+    }
+  }
+
+  // Re-sort after potential resurfaced bullet insertion
+  ranked.sort((a, b) => {
+    if (a.tier !== b.tier) return a.tier - b.tier;
+    return sourcePriority(a.source) - sourcePriority(b.source);
+  });
+
+  return {
+    bullets: ranked,
+    resurfacedLoopId,
+  };
+}
+
+// ── Internals ─────────────────────────────────────────────────────────
+
+function sourcePriority(source: "loop" | "work_item" | "followup"): number {
+  switch (source) {
+    case "loop":
+      return 0;
+    case "work_item":
+      return 1;
+    case "followup":
+      return 2;
+  }
+}
+
+function getOpenLoopsForScope(scopeId: string): OpenLoopRow[] {
+  const db = getDb();
+  return db
+    .select()
+    .from(openLoops)
+    .where(and(eq(openLoops.scopeId, scopeId), eq(openLoops.status, "open")))
+    .all() as OpenLoopRow[];
+}

package/src/memory/brief-time.ts

@@ -0,0 +1,161 @@
+/**
+ * Deterministic compiler for the "Time-Relevant Context" section of the
+ * memory brief.  Reads active `time_contexts` rows plus due-soon live
+ * schedule jobs, sorts them by urgency bucket, and caps the output.
+ */
+
+import { and, gte, lte } from "drizzle-orm";
+
+import { getDueSoonSchedules } from "../schedule/schedule-store.js";
+import type { BriefEntry } from "./brief-formatting.js";
+import { renderBriefSection } from "./brief-formatting.js";
+import type { DrizzleDb } from "./db-connection.js";
+import { timeContexts } from "./schema/memory-brief.js";
+
+const MAX_ENTRIES = 3;
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+
+/** Urgency buckets — lower number = higher priority. */
+const enum Bucket {
+  HappeningNow = 0,
+  Overdue = 1,
+  Within24h = 2,
+  Within7d = 3,
+}
+
+interface Candidate {
+  bucket: Bucket;
+  /** Epoch ms timestamp used for secondary sort within a bucket. */
+  sortKey: number;
+  entry: BriefEntry;
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Public API
+// ────────────────────────────────────────────────────────────────────
+
+/**
+ * Compile the time-relevant brief section.
+ *
+ * @param db    Drizzle database instance
+ * @param now   Current epoch-ms timestamp (injectable for deterministic tests)
+ * @returns     Markdown string for the section, or `null` if nothing qualifies
+ */
+export function compileTimeBrief(
+  db: DrizzleDb,
+  scopeId: string,
+  now: number,
+): string | null {
+  const candidates: Candidate[] = [];
+
+  collectTimeContexts(db, scopeId, now, candidates);
+  collectDueSoonSchedules(now, candidates);
+
+  // Sort: primary = bucket ascending, secondary = sortKey ascending (sooner first)
+  candidates.sort((a, b) => a.bucket - b.bucket || a.sortKey - b.sortKey);
+
+  const entries = candidates.slice(0, MAX_ENTRIES).map((c) => c.entry);
+  return renderBriefSection("Time-Relevant Context", entries, MAX_ENTRIES);
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Internal collectors
+// ────────────────────────────────────────────────────────────────────
+
+function collectTimeContexts(
+  db: DrizzleDb,
+  scopeId: string,
+  now: number,
+  out: Candidate[],
+): void {
+  // Active time contexts: activeFrom <= now AND activeUntil >= now
+  const rows = db
+    .select()
+    .from(timeContexts)
+    .where(
+      and(
+        lte(timeContexts.activeFrom, now),
+        gte(timeContexts.activeUntil, now),
+      ),
+    )
+    .all()
+    .filter((r) => r.scopeId === scopeId);
+
+  for (const row of rows) {
+    const remaining = row.activeUntil - now;
+    let bucket: Bucket;
+
+    if (row.activeFrom <= now && row.activeUntil >= now) {
+      // Currently active — classify by how much time remains
+      if (remaining <= ONE_DAY_MS) {
+        bucket = Bucket.HappeningNow;
+      } else if (remaining <= SEVEN_DAYS_MS) {
+        bucket = Bucket.Within24h;
+      } else {
+        bucket = Bucket.Within7d;
+      }
+    } else {
+      bucket = Bucket.Within7d;
+    }
+
+    out.push({
+      bucket,
+      sortKey: row.activeUntil,
+      entry: { text: row.summary },
+    });
+  }
+}
+
+function collectDueSoonSchedules(now: number, out: Candidate[]): void {
+  const jobs = getDueSoonSchedules(now, SEVEN_DAYS_MS);
+
+  for (const job of jobs) {
+    const delta = job.nextRunAt - now;
+    let bucket: Bucket;
+
+    if (delta <= 0) {
+      bucket = Bucket.Overdue;
+    } else if (delta <= ONE_DAY_MS) {
+      bucket = Bucket.Within24h;
+    } else {
+      bucket = Bucket.Within7d;
+    }
+
+    const label = formatScheduleLabel(job.name, job.nextRunAt, now);
+    out.push({
+      bucket,
+      sortKey: job.nextRunAt,
+      entry: { text: label },
+    });
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────
+// Formatting
+// ────────────────────────────────────────────────────────────────────
+
+function formatScheduleLabel(
+  name: string,
+  nextRunAt: number,
+  now: number,
+): string {
+  const delta = nextRunAt - now;
+
+  if (delta <= 0) {
+    return `Scheduled: "${name}" — overdue`;
+  }
+
+  const minutes = Math.round(delta / 60_000);
+  if (minutes < 60) {
+    return `Scheduled: "${name}" — in ${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+
+  const hours = Math.round(delta / 3_600_000);
+  if (hours < 24) {
+    return `Scheduled: "${name}" — in ${hours} hour${hours === 1 ? "" : "s"}`;
+  }
+
+  const days = Math.round(delta / 86_400_000);
+  return `Scheduled: "${name}" — in ${days} day${days === 1 ? "" : "s"}`;
+}

package/src/memory/brief.ts

@@ -0,0 +1,75 @@
+/**
+ * Top-level memory brief composer.
+ *
+ * Composes the "Time-Relevant Context" and "Open Loops" sections into a
+ * single `<memory_brief>` XML-wrapped block. Omits empty sections and
+ * returns an empty string when neither section has content.
+ */
+
+import { renderBriefSection } from "./brief-formatting.js";
+import type { OpenLoopBriefResult } from "./brief-open-loops.js";
+import { compileOpenLoopBrief } from "./brief-open-loops.js";
+import { compileTimeBrief } from "./brief-time.js";
+import type { DrizzleDb } from "./db-connection.js";
+
+/** Maximum number of open-loop bullets to include in the brief. */
+const MAX_OPEN_LOOP_ENTRIES = 5;
+
+export interface MemoryBriefResult {
+  /** Rendered `<memory_brief>` block, or empty string if nothing to show. */
+  text: string;
+  /** Forwarded from `compileOpenLoopBrief` for downstream tracking. */
+  resurfacedLoopId: string | null;
+}
+
+/**
+ * Compile the full memory brief block.
+ *
+ * @param db             Drizzle database instance
+ * @param scopeId        Memory scope (e.g. assistant instance ID)
+ * @param userMessageId  Current user message ID — used for deterministic
+ *                       open-loop resurfacing
+ * @param now            Current epoch-ms timestamp (injectable for tests)
+ * @returns              `{ text, resurfacedLoopId }` — `text` is the
+ *                       rendered `<memory_brief>` block or empty string
+ */
+export function compileMemoryBrief(
+  db: DrizzleDb,
+  scopeId: string,
+  userMessageId: string,
+  now: number = Date.now(),
+): MemoryBriefResult {
+  // Compile individual sections
+  const timeSection = compileTimeBrief(db, scopeId, now);
+
+  const openLoopResult: OpenLoopBriefResult = compileOpenLoopBrief(
+    scopeId,
+    userMessageId,
+    now,
+  );
+
+  // Convert open-loop bullets to a rendered section via the shared helper
+  const openLoopEntries = openLoopResult.bullets.map((b) => ({
+    text: b.summary,
+  }));
+  const openLoopSection = renderBriefSection(
+    "Open Loops",
+    openLoopEntries,
+    MAX_OPEN_LOOP_ENTRIES,
+  );
+
+  // Collect non-empty sections
+  const sections: string[] = [];
+  if (timeSection) sections.push(timeSection);
+  if (openLoopSection) sections.push(openLoopSection);
+
+  // If no sections have content, return empty
+  if (sections.length === 0) {
+    return { text: "", resurfacedLoopId: openLoopResult.resurfacedLoopId };
+  }
+
+  const body = sections.join("\n\n");
+  const text = `<memory_brief>\n${body}\n</memory_brief>`;
+
+  return { text, resurfacedLoopId: openLoopResult.resurfacedLoopId };
+}