@vellumai/assistant 0.5.2 → 0.5.4

package/src/memory/brief-time.ts

@@ -0,0 +1,162 @@
+/**
+ * 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, eq, 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: scopeId match AND activeFrom <= now AND activeUntil >= now
+  // Uses idx_time_contexts_scope_active_until composite index
+  const rows = db
+    .select()
+    .from(timeContexts)
+    .where(
+      and(
+        eq(timeContexts.scopeId, scopeId),
+        lte(timeContexts.activeFrom, now),
+        gte(timeContexts.activeUntil, now),
+      ),
+    )
+    .all();
+
+  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 };
+}