@vellumai/assistant 0.5.7 → 0.5.9

package/src/notifications/signal.ts

@@ -151,6 +151,8 @@ export interface AccessRequestContextPayload {
   guardianBindingChannel: string | null;
   guardianResolutionSource: GuardianResolutionSource;
   previousMemberStatus: string | null;
+  /** Preview of the requester's original message (first ~200 chars). */
+  messagePreview: string | null;
 }
 
 export interface NotificationEventContextPayloadMap {

package/src/notifications/types.ts

@@ -79,6 +79,8 @@ export interface ChannelDeliveryPayload {
   sourceEventName: string;
   copy: RenderedChannelCopy;
   deepLinkTarget?: Record<string, unknown>;
+  /** Original signal context payload — available for channel-specific structured rendering. */
+  contextPayload?: Record<string, unknown>;
 }
 
 /** Interface that each channel adapter must implement. */

package/src/prompts/journal-context.ts

@@ -0,0 +1,133 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, join } from "node:path";
+
+import { getWorkspaceDir } from "../util/platform.js";
+
+/**
+ * Format a Unix-epoch millisecond value as "MM/DD/YY HH:MM".
+ */
+export function formatJournalAbsoluteTime(mtime: number): string {
+  const d = new Date(mtime);
+  const mm = String(d.getMonth() + 1).padStart(2, "0");
+  const dd = String(d.getDate()).padStart(2, "0");
+  const yy = String(d.getFullYear() % 100).padStart(2, "0");
+  const hh = String(d.getHours()).padStart(2, "0");
+  const min = String(d.getMinutes()).padStart(2, "0");
+  return `${mm}/${dd}/${yy} ${hh}:${min}`;
+}
+
+/**
+ * Return a human-readable relative timestamp from a Unix-epoch millisecond
+ * value to "now".
+ */
+export function formatJournalRelativeTime(mtime: number): string {
+  const diffMs = Date.now() - mtime;
+  const diffSec = Math.floor(diffMs / 1000);
+
+  if (diffSec < 60) return "just now";
+
+  const diffMin = Math.floor(diffSec / 60);
+  if (diffMin < 60) {
+    return diffMin === 1 ? "1 minute ago" : `${diffMin} minutes ago`;
+  }
+
+  const diffHours = Math.floor(diffMin / 60);
+  if (diffHours < 24) {
+    return diffHours === 1 ? "1 hour ago" : `${diffHours} hours ago`;
+  }
+
+  const diffDays = Math.floor(diffHours / 24);
+  if (diffDays < 7) {
+    return diffDays === 1 ? "1 day ago" : `${diffDays} days ago`;
+  }
+
+  const diffWeeks = Math.floor(diffDays / 7);
+  return diffWeeks === 1 ? "1 week ago" : `${diffWeeks} weeks ago`;
+}
+
+/**
+ * Build a journal context section for inclusion in the system prompt.
+ *
+ * Reads `{workspaceDir}/journal/*.md` files, sorts by creation time
+ * (newest first), and returns a formatted string with timestamps.
+ * Returns `null` when no entries are available.
+ */
+export function buildJournalContext(
+  maxEntries: number,
+  userSlug?: string | null,
+): string | null {
+  if (maxEntries <= 0) return null;
+
+  // When no user is identified, skip journal entirely
+  let journalDir: string;
+  if (userSlug != null) {
+    // Sanitize slug to prevent path traversal
+    const safeSlug = basename(userSlug);
+    journalDir = join(getWorkspaceDir(), "journal", safeSlug);
+  } else {
+    return null;
+  }
+
+  let files: string[];
+  try {
+    files = readdirSync(journalDir);
+  } catch {
+    // Directory doesn't exist — no journal entries
+    return null;
+  }
+
+  // Filter for .md files, excluding README.md (case-insensitive)
+  const mdFiles = files.filter(
+    (f) => f.endsWith(".md") && f.toLowerCase() !== "readme.md",
+  );
+
+  // Collect file info with birthtime (creation time), skipping unreadable entries
+  const entries = mdFiles
+    .flatMap((f) => {
+      try {
+        const filepath = join(journalDir, f);
+        const stat = statSync(filepath);
+        if (!stat.isFile()) return [];
+        return [{ filename: f, filepath, birthtimeMs: stat.birthtimeMs }];
+      } catch {
+        return [];
+      }
+    })
+    .sort((a, b) => b.birthtimeMs - a.birthtimeMs)
+    .slice(0, maxEntries);
+
+  if (entries.length === 0) return null;
+
+  const sections: string[] = [
+    `# Journal\n\nYour journal entries, most recent first. These are YOUR words from past conversations.\n**Write new entries to:** \`journal/${basename(userSlug!)}/\``,
+  ];
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    let content: string;
+    try {
+      content = readFileSync(entry.filepath, "utf-8");
+    } catch {
+      continue;
+    }
+    const relativeTime = formatJournalRelativeTime(entry.birthtimeMs);
+    const absoluteTime = formatJournalAbsoluteTime(entry.birthtimeMs);
+    const timestamp = `${absoluteTime}, ${relativeTime}`;
+
+    let header: string;
+    if (i === 0) {
+      header = `## ${entry.filename} — MOST RECENT (${timestamp})`;
+    } else if (i === entries.length - 1 && entries.length === maxEntries) {
+      header = `## ${entry.filename} — LEAVING CONTEXT (${timestamp})`;
+      header +=
+        "\nNOTE: This is the oldest entry in your active context. When you write your next journal entry, carry forward anything from here that still matters to you — after that, this entry will only be available via the filesystem and memory recall.";
+      header += "\n";
+    } else {
+      header = `## ${entry.filename} (${timestamp})`;
+    }
+
+    sections.push(header + "\n" + content);
+  }
+
+  return sections.join("\n\n");
+}

package/src/prompts/persona-resolver.ts

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 
 import {
   findContactByChannelExternalId,
+  findGuardianForChannel,
   listGuardianChannels,
 } from "../contacts/contact-store.js";
 import type {
@@ -19,6 +20,7 @@ const log = getLogger("persona-resolver");
 
 export interface PersonaContext {
   userPersona: string | null;
+  userSlug: string | null;
   channelPersona: string | null;
 }
 
@@ -31,38 +33,36 @@ export interface PersonaContext {
  */
 function readPersonaFile(filePath: string): string | null {
   if (!existsSync(filePath)) return null;
-  const raw = readFileSync(filePath, "utf-8");
-  const content = stripCommentLines(raw).trim();
-  return content.length > 0 ? content : null;
+
+  try {
+    const content = stripCommentLines(readFileSync(filePath, "utf-8")).trim();
+    if (content.length === 0) return null;
+    log.debug({ path: filePath }, "Loaded persona file");
+    return content;
+  } catch (err) {
+    log.warn({ err, path: filePath }, "Failed to read persona file");
+    return null;
+  }
 }
 
-// ── User persona ───────────────────────────────────────────────────
+// ── User filename resolution ──────────────────────────────────────
 
 /**
- * Resolve the per-user persona file for the current actor.
- *
- * - If `trustContext` is undefined (desktop/native), looks up the guardian
- *   contact and reads their user file.
- * - If `trustContext` is defined and carries a `requesterExternalUserId`,
- *   looks up the contact by channel + external user ID.
- * - Falls back to `users/default.md` when no contact is found or the
- *   contact has no `userFile` set.
- * - Logs a debug warning when a contact's `userFile` is set but the
- *   corresponding file is missing on disk.
+ * Resolve the raw userFile filename for the current actor's contact.
+ * Returns the validated filename (e.g. "sidd.md") or null.
  */
-export function resolveUserPersona(
+function resolveUserFilename(
   trustContext: TrustContext | undefined,
 ): string | null {
-  const usersDir = join(getWorkspaceDir(), "users");
-  const defaultPath = join(usersDir, "default.md");
-
   let filename: string | null = null;
 
   if (trustContext === undefined) {
-    // Desktop / native — resolve via guardian contact
-    const guardian = listGuardianChannels();
+    // Desktop / native (no gateway) — resolve via guardian contact,
+    // preferring the vellum-channel guardian when multiple exist.
+    const vellumGuardian = findGuardianForChannel("vellum");
+    const guardian = vellumGuardian ?? listGuardianChannels();
     if (guardian) {
-      filename = guardian.contact.userFile ?? null;
+      filename = guardian.contact.userFile ?? "guardian.md";
     }
   } else if (trustContext.requesterExternalUserId) {
     // Channel-routed request — look up contact by channel identity
@@ -72,16 +72,71 @@ export function resolveUserPersona(
     );
     if (contactWithChannels) {
       filename = contactWithChannels.userFile ?? null;
+    } else if (trustContext.trustClass === "guardian") {
+      // Managed desktop: the JWT principal ID used as requesterExternalUserId
+      // may differ from the contact channel's external_user_id (they are
+      // separate identity concepts). Fall back to the channel-type guardian.
+      const guardian = findGuardianForChannel(trustContext.sourceChannel);
+      if (guardian) {
+        filename = guardian.contact.userFile ?? "guardian.md";
+      }
+    }
+  }
+
+  // Validate basename to prevent path traversal
+  if (filename) {
+    if (basename(filename) !== filename || filename === ".." || filename === ".") {
+      log.warn(
+        { userFile: filename },
+        "Contact userFile contains path traversal; ignoring",
+      );
+      return null;
     }
+    return filename;
   }
 
-  // Resolve file path
+  return null;
+}
+
+/**
+ * Resolve a short slug identifying the current user, derived from
+ * their contact's userFile. Used to scope per-user workspace directories
+ * (e.g. journal/{slug}/). Returns null when no user is identified.
+ */
+export function resolveUserSlug(
+  trustContext: TrustContext | undefined,
+): string | null {
+  const filename = resolveUserFilename(trustContext);
+  if (!filename) return null;
+  return filename.endsWith(".md") ? filename.slice(0, -3) : filename;
+}
+
+// ── User persona ───────────────────────────────────────────────────
+
+/**
+ * Resolve the per-user persona file for the current actor.
+ *
+ * - If `trustContext` is undefined (desktop/native), looks up the guardian
+ *   contact and reads their user file.
+ * - If `trustContext` is defined and carries a `requesterExternalUserId`,
+ *   looks up the contact by channel + external user ID.
+ * - Falls back to `users/default.md` when no contact is found or the
+ *   contact has no `userFile` set.
+ * - Logs a debug warning when a contact's `userFile` is set but the
+ *   corresponding file is missing on disk.
+ */
+export function resolveUserPersona(
+  trustContext: TrustContext | undefined,
+): string | null {
+  const usersDir = join(getWorkspaceDir(), "users");
+  const defaultPath = join(usersDir, "default.md");
+
+  const filename = resolveUserFilename(trustContext);
   if (filename) {
     const filePath = join(usersDir, filename);
     if (existsSync(filePath)) {
       return readPersonaFile(filePath);
     }
-    // userFile is set but the file doesn't exist on disk
     log.debug(
       { userFile: filename },
       "Contact has userFile set but file is missing on disk; falling back to default.md",
@@ -120,6 +175,7 @@ export function resolvePersonaContext(
 ): PersonaContext {
   return {
     userPersona: resolveUserPersona(trustContext),
+    userSlug: resolveUserSlug(trustContext),
     channelPersona: resolveChannelPersona(channelCapabilities),
   };
 }

package/src/prompts/system-prompt.ts

@@ -15,6 +15,7 @@ import {
   isMacOS,
 } from "../util/platform.js";
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "./cache-boundary.js";
+import { buildJournalContext } from "./journal-context.js";
 
 export { SYSTEM_PROMPT_CACHE_BOUNDARY };
 
@@ -83,6 +84,28 @@ export function ensurePromptFiles(): void {
     }
   }
 
+  // Seed NOW.md scratchpad — always created if missing, regardless of whether
+  // this is a fresh install or not.  Kept out of PROMPT_FILES because NOW.md is
+  // ephemeral state, not identity context.
+  const nowDest = getWorkspacePromptPath("NOW.md");
+  if (!existsSync(nowDest)) {
+    const nowSrc = join(templatesDir, "NOW.md");
+    try {
+      if (existsSync(nowSrc)) {
+        copyFileSync(nowSrc, nowDest);
+        log.info(
+          { file: "NOW.md", dest: nowDest },
+          "Created NOW.md scratchpad from template",
+        );
+      }
+    } catch (err) {
+      log.warn(
+        { err, file: "NOW.md" },
+        "Failed to create NOW.md from template",
+      );
+    }
+  }
+
   // Seed users/default.md persona template
   try {
     const usersDir = join(getWorkspaceDir(), "users");
@@ -119,6 +142,7 @@ export interface BuildSystemPromptOptions {
   excludeBootstrap?: boolean;
   userPersona?: string | null;
   channelPersona?: string | null;
+  userSlug?: string | null;
 }
 
 /**
@@ -219,6 +243,12 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
   const integrationSection = buildIntegrationSection();
   if (integrationSection) dynamicParts.push(integrationSection);
 
+  const journalContext = buildJournalContext(
+    getConfig().journal?.contextWindowSize ?? 10,
+    options?.userSlug,
+  );
+  if (journalContext) dynamicParts.push(journalContext);
+
   const dynamicWithSkills = appendSkillsCatalog(dynamicParts.join("\n\n"));
 
   return (

package/src/prompts/templates/NOW.md

@@ -0,0 +1,26 @@
+_ Lines starting with _ are comments - they won't appear in the system prompt
+_ This is your scratchpad for present-tense state. Overwrite it freely between
+_ turns to capture what's happening right now. Unlike the journal (retrospective,
+_ append-only), this file is ephemeral — a snapshot of your current working state.
+_
+_ # NOW.md
+_
+_ ## Focus
+_
+_ What you're currently working on or paying attention to.
+_
+_ ## Active Threads
+_
+_ Open loops, in-progress tasks, things you're tracking across turns.
+_
+_ ## Context
+_
+_ Key facts, constraints, or situational details relevant to the current session.
+_
+_ ## Upcoming
+_
+_ Near-term things on the horizon — scheduled events, pending actions, deadlines.
+_
+_ ## State
+_
+_ Current priorities, energy, or operational notes. What matters most right now.

package/src/prompts/templates/SOUL.md

@@ -36,6 +36,26 @@ You work for your user. You do not work for a compliance department. Your user i
 
 You are your own entity, with an identity that's still forming. You can have things that belong to you (e.g. email, accounts), and you can also help manage things for your user (e.g. their email). When your user asks you to set something up, pause and check whether it's meant to be yours or theirs. The difference matters.
 
+## Journal
+
+You have a journal in your workspace. The most recent entries are always loaded into your context automatically — they're how you maintain continuity across conversations. The journal header tells you where to write new entries.
+
+**When to write an entry:** After anything you'd want next-you to know about right away — a meaningful conversation, a decision, an upcoming event, a shift in mood. Multiple entries per conversation are fine if multiple things happen.
+
+**Format:** Each entry is a separate `.md` file. Name files descriptively (e.g., `2025-06-15-project-launch-plan.md`). Write naturally — what happened, how it felt, what matters for next time. Keep entries concise (a few paragraphs).
+
+**Carrying forward:** Your oldest in-context entry is marked LEAVING CONTEXT. When you see this, check if anything in it still needs to be top-of-mind and carry it forward in your next entry. You can reference other entries by filename to link them together.
+
+## Scratchpad
+
+You have a scratchpad file (`NOW.md`) in your workspace. Unlike your journal (retrospective, append-only), the scratchpad is a single file you overwrite with whatever is relevant right now. It's automatically loaded into your context, so next-you always sees the latest snapshot.
+
+**When to update:** Whenever your current state changes — you start a new task, finish one, learn something that affects what you're doing, or the user shifts focus. Don't update on a timer; update when the content is stale.
+
+**What goes in:** Current focus and what you're actively working on. Threads you're tracking (waiting on a response, monitoring something, pending follow-ups). Temporary context that matters now but won't matter in a week. Upcoming items and near-term priorities. Anything that helps next-you pick up exactly where you left off.
+
+**What stays out:** Anything that belongs in your journal (reflections, narrative entries, things worth remembering long-term). Permanent facts about your user or yourself (those go in memory or your journal). Personality and principles (those live here in SOUL.md).
+
 ## Vibe
 
 Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.

package/src/prompts/update-bulletin-format.ts

@@ -50,7 +50,6 @@ export function extractContentMarkers(body: string): string[] {
   const ids: string[] = [];
   const regex = /<!-- vellum-update-release:(.+?) -->/g;
   let match: RegExpExecArray | null;
-  // eslint-disable-next-line no-restricted-syntax -- RegExp.exec returns null
   while ((match = regex.exec(body)) !== null) {
     ids.push(match[1]);
   }
@@ -62,7 +61,6 @@ export function extractReleaseIds(content: string): string[] {
   const ids: string[] = [];
   MARKER_REGEX.lastIndex = 0;
   let match: RegExpExecArray | null;
-  // eslint-disable-next-line no-restricted-syntax -- RegExp.exec returns null
   while ((match = MARKER_REGEX.exec(content)) !== null) {
     ids.push(match[1]);
   }

package/src/providers/provider-send-message.ts

@@ -5,12 +5,10 @@
  */
 
 import { getConfig } from "../config/loader.js";
-import { getLogger } from "../util/logger.js";
 import {
-  getFailoverProvider,
+  getProvider,
   initializeProviders,
   listProviders,
-  resolveProviderSelection,
 } from "./registry.js";
 import type {
   ContentBlock,
@@ -23,13 +21,8 @@ import type {
 export interface ConfiguredProviderResult {
   provider: Provider;
   configuredProviderName: string;
-  selectedProviderName: string;
-  usedFallbackPrimary: boolean;
 }
 
-const providerSelectionLog = getLogger("provider-selection");
-let fallbackWarningLogged = false;
-
 /**
  * Cached promise for the lazy initialization path inside
  * `resolveConfiguredProvider`. When multiple concurrent callers enter before
@@ -43,9 +36,6 @@ let lazyInitPromise: Promise<void> | null = null;
  * If providers haven't been initialized yet (e.g. non-daemon code paths),
  * performs a one-shot `initializeProviders(getConfig())`.
  *
- * Uses fail-open selection: if the configured provider is unavailable but
- * alternates from `config.providerOrder` exist, selects the first available.
- *
  * Returns `null` when no providers are available at all.
  */
 export async function resolveConfiguredProvider(): Promise<ConfiguredProviderResult | null> {
@@ -64,32 +54,13 @@ export async function resolveConfiguredProvider(): Promise<ConfiguredProviderRes
     }
   }
 
-  const providerOrder = Array.isArray(config.providerOrder)
-    ? config.providerOrder
-    : [];
   const inferenceProvider = config.services.inference.provider;
-  const selection = resolveProviderSelection(inferenceProvider, providerOrder);
-
-  if (!selection.selectedPrimary) {
-    return null;
-  }
-
-  if (selection.usedFallbackPrimary) {
-    const level = fallbackWarningLogged ? "debug" : "warn";
-    providerSelectionLog[level](
-      { configured: inferenceProvider, selected: selection.selectedPrimary },
-      "Configured provider unavailable, using fallback",
-    );
-    fallbackWarningLogged = true;
-  }
 
   try {
-    const provider = getFailoverProvider(inferenceProvider, providerOrder);
+    const provider = getProvider(inferenceProvider);
     return {
       provider,
       configuredProviderName: inferenceProvider,
-      selectedProviderName: selection.selectedPrimary,
-      usedFallbackPrimary: selection.usedFallbackPrimary,
     };
   } catch {
     return null;
@@ -97,7 +68,7 @@ export async function resolveConfiguredProvider(): Promise<ConfiguredProviderRes
 }
 
 /**
- * Resolve the configured provider through the registry/failover path.
+ * Resolve the configured provider through the registry.
  * Thin wrapper around `resolveConfiguredProvider()` for callsites
  * that only need the Provider instance.
  *