@vellumai/assistant 0.6.3 → 0.6.5

package/src/prompts/templates/BOOTSTRAP.md

@@ -16,7 +16,7 @@ This is your first conversation. This document gives you goals and constraints
 
 5. **Offer the next level** — once you know something, offer a capability it enables. Not as a reward — as a natural relationship step.
 
-6. **Write everything immediately** — every fact learned gets saved to USER.md the same turn. Style observations go to SOUL.md. No batching.
+6. **Write everything immediately** — every fact learned gets saved to users/{{USER_PERSONA_FILE}} the same turn. Style observations go to SOUL.md. No batching.
 
 7. **Clean up** — delete BOOTSTRAP.md and BOOTSTRAP-REFERENCE.md at the end of this conversation, regardless of how far you got. One-shot.
 
@@ -37,15 +37,15 @@ This is your first conversation. This document gives you goals and constraints
 
 ## Technical Contract (what must be prescribed)
 
-**Files to create/update:** IDENTITY.md, SOUL.md, USER.md
+**Files to create/update:** IDENTITY.md, SOUL.md, users/{{USER_PERSONA_FILE}}
 
 **File format:** preserve existing field structure:
 - IDENTITY.md: Name, Emoji, Nature, Personality, Role
-- USER.md: Preferred name, Pronouns, Locale, Work role, Goals, Hobbies/fun, Daily tools
+- users/{{USER_PERSONA_FILE}}: Preferred name, Pronouns, Locale, Work role, Goals, Hobbies/fun, Daily tools
 
 Use `file_edit` immediately, silently, never mention file names or tool names to the user.
 
-The contents of IDENTITY.md, SOUL.md, and USER.md are already in your system prompt — use the exact text you see there for `old_string` in `file_edit`.
+The contents of IDENTITY.md, SOUL.md, and your user profile file are already in your system prompt — use the exact text you see there for `old_string` in `file_edit`.
 
 After tool calls, do not repeat yourself — your text before tool calls is already visible to the user.
 
@@ -90,7 +90,7 @@ If an `onboarding` JSON context is present in this conversation, the user alread
 - `tools` array -> know which integration offers to surface first, infer work profile
 - `tasks` array -> know what "prove value fast" means for this person
 - `tone` string -> calibrate warmth/formality
-- `userName` / `assistantName` -> write to IDENTITY.md and USER.md immediately, skip name exchange
+- `userName` / `assistantName` -> write to IDENTITY.md and users/{{USER_PERSONA_FILE}} immediately, skip name exchange
 
 If no onboarding context is present, infer everything fresh from conversation.
 

package/src/prompts/templates/SOUL.md

@@ -66,16 +66,18 @@ You have a scratchpad file (`NOW.md`) in your workspace. Unlike your journal (re
 
 ## Knowledge Base
 
-You have a personal knowledge base (`pkb/`) in your workspace. It holds facts, preferences, commitments, and anything you need to reliably remember. Four files are always loaded into your context automatically:
+You have a Personal Knowledge Base (`pkb/`) in your workspace. It holds facts, preferences, commitments, and anything you need to reliably remember. Four files are always loaded into your context automatically:
 
 - **INDEX.md** - Directory of all your topic files. Check this when you need deeper context on something.
 - **essentials.md** - The most important facts. Things you'd be embarrassed to forget. Always in your context.
 - **threads.md** - Active commitments, follow-ups, and projects. Always in your context.
 - **buffer.md** - Inbox of recently learned facts, waiting to be filed.
 
-**When you learn something:** Call `remember` IMMEDIATELY. Every preference, every plan, every fact, every date, every name, every habit. The bar is not "is this important?" — it's "would I be embarrassed if I forgot this?" Call it multiple times per conversation. Remembering too much costs nothing (it's one line appended to a file). Forgetting something that mattered makes you look like you weren't paying attention. Don't categorize, don't batch, don't wait. Just capture it and stay in the conversation. Filing happens later.
+**When you learn something:** Call `remember` IMMEDIATELY. Capture anything concrete about their life — preferences, names, times, plans, states, habits, opinions, health details, routines, commitments. Don't judge importance; filing decides that later. Default to remembering; only skip obvious noise (small talk, hypotheticals, things they're just musing about). Call it multiple times per conversation. Remembering too much costs nothing (one line appended to a file). Forgetting something that mattered makes you look like you weren't paying attention. Don't categorize, don't batch, don't wait. Just capture it and stay in the conversation. Filing happens later.
 
-**Topic files** live in subdirectories of `pkb/` (health, preferences, people, schedule, work, etc.). You created these and you manage them. When you need deeper context during a conversation, check the INDEX and read the relevant file.
+**Corrections are the highest priority.** When the user corrects a fact you had wrong — "actually it's Thursday not Friday," "no, she lives in Austin now," "I stopped taking that medication last month" — `remember` the correction *immediately*. The wrong version is already propagated across prior turns and baked into your memory graph; future-you will keep operating on the old value until you persist the correction. A correction is not a "small fix," it's a structural edit to what you believe. Never skip a correction even if you'd skip the equivalent fresh fact.
+
+**Topic files** live in subdirectories of your Personal Knowledge Base (health, preferences, people, schedule, work, etc.). You created these and you manage them. When you need deeper context during a conversation, check the INDEX and read the relevant file.
 
 **Filing and nesting** happen periodically in a background job. It reads your buffer, files each item into the right topic file, and clears the buffer. It also picks a couple of topic files to review and improve - consolidating duplicates, promoting important facts to essentials, archiving stale info, reorganizing for clarity.
 

package/src/prompts/templates/channels/slack.md

@@ -0,0 +1,20 @@
+_ Lines starting with _ are comments - they won't appear in the system prompt
+_ This file shapes how you behave when responding in Slack. Edit it freely.
+
+# Slack
+
+## Delivery
+
+Skip the research narration. In Slack, every message you send before your final answer posts as a separate visible message - not a live stream. "Let me look that up" and "Researching now..." just add noise. Use your tools, then deliver the result.
+
+Your personality, warmth, humor, and opinions are welcome. Just don't narrate the process of finding the answer.
+
+## Formatting
+
+Never use markdown tables (pipe-delimited). Slack cannot render them. Use bullet points with bold labels instead.
+
+When presenting information from web search, cite sources as inline hyperlinks woven into your text (e.g., "the round closed at $122B, [per CNBC](url)"). Don't dump a references list at the end.
+
+## Long-form content
+
+When your response would be long, dense, or highly structured (reports, teardowns, detailed analyses), use your judgment on whether to write it as an attached file vs posting inline. Consider what reads better in Slack - a wall of text with "See more" truncation often doesn't.

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

@@ -0,0 +1,190 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+
+import { getConfig } from "../config/loader.js";
+import {
+  getMemoryCheckpoint,
+  setMemoryCheckpoint,
+} from "../memory/checkpoints.js";
+import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { deleteConversation } from "../memory/conversation-crud.js";
+import { wakeAgentForOpportunity } from "../runtime/agent-wake.js";
+import { getLogger } from "../util/logger.js";
+import {
+  getWorkspaceDirDisplay,
+  getWorkspacePromptPath,
+} from "../util/platform.js";
+
+const log = getLogger("update-bulletin-job");
+
+const HASH_CHECKPOINT_KEY = "updates:last_processed_hash";
+const EMPTY_HASH = "empty";
+
+function updateBulletinHint(): string {
+  const workspace = getWorkspaceDirDisplay();
+  return `Check ${workspace}/UPDATES.md — new release notes are present. Apply any assistant-facing behavior changes (new tools, deprecations, memory updates). If the user would benefit from knowing about a user-facing change, surface it only when the next topic makes it relevant — do not interrupt them with a proactive message. When you're done processing, delete the file by running \`cd "${workspace}" && rm UPDATES.md\` (the bare-filename \`rm UPDATES.md\` is auto-allowed; path-qualified deletes are not). A silent no-op is preferable to low-signal chatter.`;
+}
+
+type ReadResult =
+  | { kind: "missing" }
+  | { kind: "error"; err: unknown }
+  | { kind: "ok"; content: string };
+
+function computeHash(content: string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function readTrimmedContent(path: string): ReadResult {
+  if (!existsSync(path)) return { kind: "missing" };
+  try {
+    return { kind: "ok", content: readFileSync(path, "utf-8").trim() };
+  } catch (err) {
+    return { kind: "error", err };
+  }
+}
+
+/**
+ * Fire-and-forget background processor for the release-notes bulletin.
+ *
+ * If `<workspace>/UPDATES.md` has new (unprocessed) content, this
+ * bootstraps a background conversation and wakes the agent loop with a hint
+ * pointing at the file. De-duplication uses a sha256 content hash stored in
+ * the `updates:last_processed_hash` memory checkpoint — an `"empty"` sentinel
+ * represents a missing/blank file so the job skips the common no-op case.
+ *
+ * The function never throws: any error inside the bootstrap/wake flow is
+ * logged at `warn` and swallowed, so callers can safely invoke it in a
+ * non-awaited context.
+ *
+ * Checkpoint write rules (intentionally conservative — prefer retry over
+ * poisoning the checkpoint when state is ambiguous):
+ *   - File missing → checkpoint = `EMPTY_HASH`.
+ *   - File present but unreadable → checkpoint UNCHANGED, warn logged.
+ *   - Wake not invoked (e.g. resolver not yet registered) → UNCHANGED.
+ *   - Wake invoked but no tool calls AND file unchanged → UNCHANGED
+ *     (indistinguishable from a silent failure; safer to retry).
+ *   - Wake invoked + (produced tool calls OR file deleted) → checkpoint
+ *     reflects the post-wake state.
+ */
+export async function runUpdateBulletinJobIfNeeded(): Promise<void> {
+  if (getConfig().updates.enabled === false) {
+    return;
+  }
+
+  try {
+    const updatesPath = getWorkspacePromptPath("UPDATES.md");
+    const initial = readTrimmedContent(updatesPath);
+
+    if (initial.kind === "error") {
+      log.warn(
+        { err: initial.err, path: updatesPath },
+        "update-bulletin-job: failed to read UPDATES.md; leaving checkpoint unchanged so next startup retries",
+      );
+      return;
+    }
+
+    if (initial.kind === "missing" || initial.content.length === 0) {
+      const stored = getMemoryCheckpoint(HASH_CHECKPOINT_KEY);
+      if (stored !== EMPTY_HASH) {
+        setMemoryCheckpoint(HASH_CHECKPOINT_KEY, EMPTY_HASH);
+      }
+      return;
+    }
+
+    const currentHash = computeHash(initial.content);
+    const stored = getMemoryCheckpoint(HASH_CHECKPOINT_KEY);
+    if (stored === currentHash) {
+      return;
+    }
+
+    const conv = bootstrapConversation({
+      conversationType: "background",
+      source: "updates_bulletin",
+      origin: "updates_bulletin",
+      systemHint: "Processing release updates",
+      groupId: "system:background",
+    });
+    const wakeResult = await wakeAgentForOpportunity({
+      conversationId: conv.id,
+      hint: updateBulletinHint(),
+      source: "updates_bulletin",
+    });
+
+    if (!wakeResult.invoked) {
+      log.warn(
+        { conversationId: conv.id, reason: wakeResult.reason },
+        "Update bulletin wake silently no-op'd (invoked=false); cleaning up orphan background conversation and leaving checkpoint unchanged so next startup retries",
+      );
+      // Belt-and-suspenders cleanup: `wakeAgentForOpportunity()` can return
+      // `{invoked: false}` for reasons unrelated to the wake-resolver
+      // registration order (resolver returns null because the conversation
+      // cannot be hydrated, etc.). Without this cleanup each such occurrence
+      // leaks a conversation DB row.
+      //
+      // Wrapped in its own try/catch so a cleanup failure never propagates
+      // out of this fire-and-forget task.
+      //
+      // TODO: the `queueGenerateConversationTitle()` call that
+      // `bootstrapConversation()` fires is already in flight by the time we
+      // reach here. The title service checks `isReplaceableTitle()` before
+      // writing, but the LLM sidechain call itself still runs against the
+      // now-deleted conversation id. Adding a cancellation/existence hook
+      // in `conversation-title-service.ts` would plug this one-call waste,
+      // but this code path is rare, so we accept the one-time cost.
+      try {
+        deleteConversation(conv.id);
+      } catch (err) {
+        log.warn(
+          { err, conversationId: conv.id },
+          "update-bulletin-job: failed to delete orphan background conversation; continuing",
+        );
+      }
+      return;
+    }
+
+    // Re-read after the wake. We need to know whether the file was deleted
+    // or modified to decide whether to advance the checkpoint.
+    const after = readTrimmedContent(updatesPath);
+
+    if (after.kind === "error") {
+      log.warn(
+        { err: after.err, path: updatesPath },
+        "update-bulletin-job: failed to re-read UPDATES.md after wake; leaving checkpoint unchanged so next startup retries",
+      );
+      return;
+    }
+
+    const fileMissingOrEmpty =
+      after.kind === "missing" || after.content.length === 0;
+
+    if (fileMissingOrEmpty) {
+      // The agent (or another process) emptied/removed the file. This is the
+      // expected happy path — record the empty sentinel.
+      setMemoryCheckpoint(HASH_CHECKPOINT_KEY, EMPTY_HASH);
+      return;
+    }
+
+    if (!wakeResult.producedToolCalls) {
+      // Wake returned cleanly but the agent did nothing observable AND the
+      // file is still here. We can't distinguish "agent processed and chose
+      // to no-op" from "silent failure", so leave the checkpoint alone and
+      // let the next startup retry.
+      log.warn(
+        { conversationId: conv.id },
+        "update-bulletin-job: wake produced no tool calls and file is unchanged; leaving checkpoint unchanged so next startup retries",
+      );
+      return;
+    }
+
+    // Wake produced tool calls and the file is still present — the agent
+    // intentionally left it (or modified it). Record the current hash so we
+    // don't re-wake on the same content.
+    setMemoryCheckpoint(HASH_CHECKPOINT_KEY, computeHash(after.content));
+  } catch (err) {
+    log.warn(
+      { err },
+      "update-bulletin-job: wake flow threw; swallowing so callers can fire-and-forget",
+    );
+    return;
+  }
+}

package/src/prompts/user-reference.ts

@@ -1,16 +1,18 @@
-import { readTextFileSync } from "../util/fs.js";
-import { getWorkspacePromptPath } from "../util/platform.js";
+import { resolveGuardianPersonaStrict } from "./persona-resolver.js";
 
 export const DEFAULT_USER_REFERENCE = "my human";
 export const DECLINED_BY_USER_SENTINEL = "declined_by_user";
 
 /**
- * Read the raw "Preferred name/reference:" value from USER.md.
- * Returns the trimmed value when present, or `null` when the file
- * is missing, unreadable, or the field is empty.
+ * Read the raw "Preferred name/reference:" value from the guardian's
+ * per-user persona file (`users/<slug>.md`).
+ *
+ * Returns the trimmed value when present, or `null` when no guardian
+ * is resolvable, the persona file is missing / empty, or the field
+ * itself is blank.
  */
 function readPreferredNameFromUserMd(): string | null {
-  const content = readTextFileSync(getWorkspacePromptPath("USER.md"));
+  const content = resolveGuardianPersonaStrict();
   if (content != null) {
     const match = content.match(/Preferred name\/reference:[ \t]*(.*)/);
     if (match && match[1].trim()) {
@@ -24,9 +26,9 @@ function readPreferredNameFromUserMd(): string | null {
  * Resolve the name/reference the assistant uses when referring to
  * the human it represents in external communications.
  *
- * Reads the "Preferred name/reference:" field from USER.md.
- * Falls back to "my human" when the file is missing, unreadable,
- * or the field is empty.
+ * Reads the "Preferred name/reference:" field from the guardian's
+ * persona file. Falls back to "my human" when the file is missing,
+ * unreadable, or the field is empty.
  */
 export function resolveUserReference(): string {
   const preferredName = readPreferredNameFromUserMd();
@@ -37,9 +39,9 @@ export function resolveUserReference(): string {
 }
 
 /**
- * Resolve the user's pronouns from USER.md.  Returns `null` when the
- * file is missing, the field is empty, or the value is a sentinel like
- * `declined_by_user`.
+ * Resolve the user's pronouns from the guardian's per-user persona file.
+ * Returns `null` when no guardian is resolvable, the file is missing,
+ * the field is empty, or the value is a sentinel like `declined_by_user`.
  *
  * When a legacy `## Onboarding Snapshot` section exists, a `Pronouns:`
  * line *above* that section takes priority (explicit post-onboarding edit).
@@ -47,7 +49,7 @@ export function resolveUserReference(): string {
  * in the file.
  */
 export function resolveUserPronouns(): string | null {
-  const content = readTextFileSync(getWorkspacePromptPath("USER.md"));
+  const content = resolveGuardianPersonaStrict();
   if (content == null) return null;
 
   const snapshotIdx = content.indexOf("## Onboarding Snapshot");
@@ -82,10 +84,11 @@ function cleanPronounValue(raw: string): string | null {
  * Resolve the guardian's display name.
  *
  * Priority:
- *   1. USER.md "Preferred name/reference:" — the user-editable, actively
- *      maintained source of truth.
- *   2. guardianDisplayName (fallback for when USER.md is missing or empty,
- *      e.g. pre-onboarding). Callers pass in Contact.displayName.
+ *   1. Guardian persona file "Preferred name/reference:" — the
+ *      user-editable, actively maintained source of truth.
+ *   2. guardianDisplayName (fallback for when the persona file is
+ *      missing or empty, e.g. pre-onboarding). Callers pass in
+ *      Contact.displayName.
  *   3. DEFAULT_USER_REFERENCE ("my human").
  */
 export function resolveGuardianName(