@vellumai/assistant 0.7.1 → 0.7.3

package/src/proactive-artifact/trigger-state.ts

@@ -0,0 +1,119 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { rawGet } from "../memory/raw-query.js";
+import { getLogger } from "../util/logger.js";
+import { getDataDir } from "../util/platform.js";
+
+const log = getLogger("proactive-artifact-trigger");
+
+const TRIGGER_MIN = 4;
+const TRIGGER_MAX = 10;
+
+function guardPath(): string {
+  return join(getDataDir(), ".proactive-artifact-completed");
+}
+
+/**
+ * Count user messages in standard conversations with created_at <= beforeOrAt.
+ * LIMIT caps scan cost since we only care about thresholds up to TRIGGER_MAX.
+ */
+export function getUserMessageCountUpTo(beforeOrAt: number): number {
+  const row = rawGet<{ c: number }>(
+    `SELECT COUNT(*) AS c FROM (
+      SELECT 1 FROM messages m
+      JOIN conversations c ON m.conversation_id = c.id
+      WHERE m.role = 'user'
+        AND c.conversation_type = 'standard'
+        AND m.created_at <= ?
+      LIMIT ${TRIGGER_MAX + 1}
+    ) sub`,
+    beforeOrAt,
+  );
+  return row?.c ?? 0;
+}
+
+/**
+ * Fast-path check to avoid the COUNT query on every turn.
+ * Returns true if the proactive artifact trigger has already fired.
+ */
+export function hasProactiveArtifactCompleted(): boolean {
+  return existsSync(guardPath());
+}
+
+/**
+ * Atomic check-and-claim with count-first ordering.
+ *
+ * Trigger window: messages TRIGGER_MIN–TRIGGER_MAX (4–10). Returns true if
+ * count is in-window and exclusive file create succeeded. The guard acts as
+ * an in-flight lock — the job releases it on decision-skip so the next turn
+ * can retry. Past the window, the guard is written permanently.
+ */
+export function tryClaimProactiveArtifactTrigger(
+  userMessageCreatedAt: number,
+): boolean {
+  const count = getUserMessageCountUpTo(userMessageCreatedAt);
+
+  if (count < TRIGGER_MIN) {
+    return false;
+  }
+
+  if (count > TRIGGER_MAX) {
+    try {
+      mkdirSync(dirname(guardPath()), { recursive: true });
+      writeFileSync(guardPath(), new Date().toISOString(), { flag: "wx" });
+    } catch {
+      // Already written or fs error — either way, window is closed
+    }
+    return false;
+  }
+
+  // count in [TRIGGER_MIN, TRIGGER_MAX] — attempt exclusive guard write
+  try {
+    mkdirSync(dirname(guardPath()), { recursive: true });
+    writeFileSync(guardPath(), new Date().toISOString(), { flag: "wx" });
+    return true;
+  } catch (err: unknown) {
+    if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+      return false;
+    }
+    log.warn({ err }, "Failed to write proactive artifact guard file");
+    return false;
+  }
+}
+
+/**
+ * Release the in-flight claim so the next turn can retry.
+ * Called when the decision phase skips (no build committed).
+ */
+export function releaseProactiveArtifactClaim(): void {
+  try {
+    rmSync(guardPath(), { force: true });
+  } catch {
+    // Best-effort — if removal fails, the next turn just won't retry
+  }
+}
+
+/**
+ * Called at daemon startup. If the guard file does not exist and the user
+ * already has messages past the trigger window, write the guard. This
+ * handles existing users who had many messages before the feature existed.
+ */
+export function backfillGuardIfNeeded(): void {
+  if (hasProactiveArtifactCompleted()) {
+    return;
+  }
+
+  const count = getUserMessageCountUpTo(Date.now());
+  if (count > TRIGGER_MAX) {
+    try {
+      mkdirSync(dirname(guardPath()), { recursive: true });
+      writeFileSync(guardPath(), new Date().toISOString(), { flag: "wx" });
+    } catch (err: unknown) {
+      if (err instanceof Error && "code" in err && err.code === "EEXIST") {
+        return;
+      }
+      log.warn({ err }, "Failed to backfill proactive artifact guard file");
+    }
+  }
+}

package/src/prompts/bootstrap-cleanup.ts

@@ -0,0 +1,27 @@
+import { existsSync, unlinkSync } from "node:fs";
+
+import { getLogger } from "../util/logger.js";
+import { getWorkspacePromptPath } from "../util/platform.js";
+
+const log = getLogger("bootstrap-cleanup");
+
+const BOOTSTRAP_FILES = ["BOOTSTRAP.md", "BOOTSTRAP-REFERENCE.md"] as const;
+
+export function cleanupBootstrapFiles(reason: string): boolean {
+  let deletedAny = false;
+
+  for (const file of BOOTSTRAP_FILES) {
+    const path = getWorkspacePromptPath(file);
+    if (!existsSync(path)) continue;
+
+    try {
+      unlinkSync(path);
+      deletedAny = true;
+      log.info({ file, reason }, "Deleted bootstrap file");
+    } catch (err) {
+      log.warn({ err, file, reason }, "Failed to delete bootstrap file");
+    }
+  }
+
+  return deletedAny;
+}

package/src/prompts/normalize-onboarding.ts

@@ -0,0 +1,80 @@
+import type { OnboardingContext } from "../types/onboarding-context.js";
+
+/**
+ * Map of known tool IDs (from the client onboarding UI) to display labels.
+ * Unknown IDs pass through with first-letter capitalization via `normalizeTools`.
+ */
+export const TOOL_DISPLAY_NAMES: Record<string, string> = {
+  gmail: "Gmail",
+  outlook: "Outlook",
+  "google-calendar": "Google Calendar",
+  slack: "Slack",
+  notion: "Notion",
+  linear: "Linear",
+  jira: "Jira",
+  github: "GitHub",
+  figma: "Figma",
+  "google-drive": "Google Drive",
+  excel: "Excel",
+  "apple-notes": "Apple Notes",
+};
+
+/**
+ * Map of known task IDs to plain-language labels describing what the assistant
+ * does for each task category.
+ */
+export const TASK_DISPLAY_LABELS: Record<string, string> = {
+  "code-building": "builds code, apps, or tools",
+  writing: "writes docs, emails, or content",
+  research: "does research and analysis",
+  "project-management": "plans and coordinates work",
+  scheduling: "handles meetings, calendar, and logistics",
+  personal: "handles life admin",
+};
+
+/**
+ * Capitalize the first letter of a string (fallback for unknown IDs).
+ */
+function capitalizeFirst(s: string): string {
+  if (!s) return s;
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * Maps each tool ID through `TOOL_DISPLAY_NAMES`, falling back to the raw
+ * string for unknown IDs.
+ */
+export function normalizeTools(tools: string[]): string[] {
+  return tools.map((id) => TOOL_DISPLAY_NAMES[id] ?? capitalizeFirst(id));
+}
+
+/**
+ * Maps each task ID through `TASK_DISPLAY_LABELS`, falling back to the raw
+ * string for unknown IDs.
+ */
+export function normalizeTasks(tasks: string[]): string[] {
+  return tasks.map((id) => TASK_DISPLAY_LABELS[id] ?? id);
+}
+
+export interface NormalizedOnboarding {
+  preferredName?: string;
+  commonWork: string[];
+  dailyTools: string[];
+  tone?: string;
+  assistantName?: string;
+}
+
+/**
+ * Normalizes raw onboarding context from the client into display-ready data.
+ */
+export function normalizeOnboardingContext(
+  ctx: OnboardingContext,
+): NormalizedOnboarding {
+  return {
+    preferredName: ctx.userName?.trim() || undefined,
+    commonWork: normalizeTasks(ctx.tasks),
+    dailyTools: normalizeTools(ctx.tools),
+    tone: ctx.tone,
+    assistantName: ctx.assistantName,
+  };
+}

package/src/prompts/persona-resolver.ts

@@ -1,9 +1,4 @@
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
 import {
@@ -14,8 +9,9 @@ import {
 import type { ChannelCapabilities } from "../daemon/conversation-runtime-assembly.js";
 import type { TrustContext } from "../daemon/trust-context.js";
 import { getLogger } from "../util/logger.js";
-import { getWorkspaceDir } from "../util/platform.js";
+import { getWorkspaceDir, getWorkspacePromptPath } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
+import type { NormalizedOnboarding } from "./normalize-onboarding.js";
 
 const log = getLogger("persona-resolver");
 
@@ -110,7 +106,11 @@ function resolveUserFilename(
 
   // Validate basename to prevent path traversal
   if (filename) {
-    if (basename(filename) !== filename || filename === ".." || filename === ".") {
+    if (
+      basename(filename) !== filename ||
+      filename === ".." ||
+      filename === "."
+    ) {
       log.warn(
         { userFile: filename },
         "Contact userFile contains path traversal; ignoring",
@@ -268,7 +268,11 @@ export function resolveGuardianPersonaStrict(): string | null {
  * Creates the parent `users/` directory if missing.
  */
 export function ensureGuardianPersonaFile(userFile: string): void {
-  if (basename(userFile) !== userFile || userFile === ".." || userFile === ".") {
+  if (
+    basename(userFile) !== userFile ||
+    userFile === ".." ||
+    userFile === "."
+  ) {
     log.warn(
       { userFile },
       "Guardian persona userFile contains path traversal; refusing to write",
@@ -314,3 +318,91 @@ export function isGuardianPersonaCustomized(filePath: string): boolean {
   const templateStripped = stripCommentLines(GUARDIAN_PERSONA_TEMPLATE);
   return stripped !== templateStripped;
 }
+
+// ── Onboarding section writer ────────────────────────────────────
+
+const ONBOARDING_HEADING = "## Onboarding Context";
+
+/**
+ * Build the markdown section content for the onboarding context.
+ * Omits bullet lines where the value is empty/absent.
+ */
+function buildOnboardingSection(normalized: NormalizedOnboarding): string {
+  const lines: string[] = [ONBOARDING_HEADING, ""];
+
+  if (normalized.preferredName) {
+    lines.push(`- **Preferred name:** ${normalized.preferredName}`);
+  }
+  if (normalized.commonWork.length > 0) {
+    lines.push(`- **Common work:** ${normalized.commonWork.join("; ")}`);
+  }
+  if (normalized.dailyTools.length > 0) {
+    lines.push(`- **Daily tools:** ${normalized.dailyTools.join(", ")}`);
+  }
+
+  lines.push("");
+  return lines.join("\n");
+}
+
+/**
+ * Resolve the write target for the onboarding section using the
+ * fallback chain: guardian persona → `users/default.md` → `USER.md`.
+ */
+function resolveOnboardingWriteTarget(): string {
+  const guardianPath = resolveGuardianPersonaPath();
+  if (guardianPath) return guardianPath;
+
+  const defaultUserPath = join(getWorkspaceDir(), "users", "default.md");
+  if (existsSync(defaultUserPath)) return defaultUserPath;
+
+  return getWorkspacePromptPath("USER.md");
+}
+
+/**
+ * Write a managed `## Onboarding Context` section to the guardian persona
+ * file (or fallback target). Idempotent: replaces the section in-place if
+ * it already exists, appends if not, and creates the file when missing.
+ *
+ * Never throws — logs a warning on failure (fire-and-forget pattern).
+ */
+export function writeOnboardingSection(normalized: NormalizedOnboarding): void {
+  try {
+    const targetPath = resolveOnboardingWriteTarget();
+    const section = buildOnboardingSection(normalized);
+
+    let content: string;
+    if (existsSync(targetPath)) {
+      content = readFileSync(targetPath, "utf-8");
+    } else {
+      // Create parent directories and start with a header
+      mkdirSync(dirname(targetPath), { recursive: true });
+      content = "# User Profile\n\n";
+    }
+
+    // Replace existing section or append
+    const headingIndex = content.indexOf(ONBOARDING_HEADING);
+    if (headingIndex !== -1) {
+      // Find the end of the section: next `## ` heading or EOF
+      const afterHeading = content.indexOf("\n", headingIndex);
+      const rest = afterHeading !== -1 ? content.slice(afterHeading + 1) : "";
+      const nextHeadingMatch = rest.match(/^## /m);
+      const before = content.slice(0, headingIndex);
+      const after = nextHeadingMatch ? rest.slice(nextHeadingMatch.index!) : "";
+      content = before + section + after;
+    } else {
+      // Append after a blank line (ensure trailing newline first)
+      if (!content.endsWith("\n")) {
+        content += "\n";
+      }
+      if (!content.endsWith("\n\n")) {
+        content += "\n";
+      }
+      content += section;
+    }
+
+    writeFileSync(targetPath, content, "utf-8");
+    log.debug({ path: targetPath }, "Wrote onboarding section to persona file");
+  } catch (err) {
+    log.warn({ err }, "Failed to write onboarding section to persona file");
+  }
+}

package/src/prompts/system-prompt.ts

@@ -4,7 +4,6 @@ import {
   mkdirSync,
   readdirSync,
   readFileSync,
-  unlinkSync,
 } from "node:fs";
 import { join } from "node:path";
 
@@ -20,7 +19,9 @@ import {
   getWorkspacePromptPath,
 } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
+import { cleanupBootstrapFiles } from "./bootstrap-cleanup.js";
 import { SYSTEM_PROMPT_CACHE_BOUNDARY } from "./cache-boundary.js";
+import { normalizeOnboardingContext } from "./normalize-onboarding.js";
 
 export { SYSTEM_PROMPT_CACHE_BOUNDARY };
 
@@ -155,22 +156,7 @@ export function ensurePromptFiles(): void {
     const convDir = getConversationsDir();
     try {
       if (existsSync(convDir) && readdirSync(convDir).length > 0) {
-        unlinkSync(bootstrapCleanup);
-        log.info("Auto-deleted stale BOOTSTRAP.md — prior conversations exist");
-
-        // Also clean up the reference file
-        const refCleanup = getWorkspacePromptPath("BOOTSTRAP-REFERENCE.md");
-        if (existsSync(refCleanup)) {
-          try {
-            unlinkSync(refCleanup);
-            log.info("Auto-deleted stale BOOTSTRAP-REFERENCE.md");
-          } catch (err) {
-            log.warn(
-              { err },
-              "Failed to auto-delete stale BOOTSTRAP-REFERENCE.md",
-            );
-          }
-        }
+        cleanupBootstrapFiles("prior conversations exist");
       }
     } catch (err) {
       log.warn({ err }, "Failed to auto-delete stale BOOTSTRAP.md");
@@ -337,14 +323,27 @@ export function buildSystemPrompt(options?: BuildSystemPromptOptions): string {
     );
 
     if (options?.onboardingContext) {
-      dynamicParts.push(
-        "## Pre-chat Onboarding Context\n\n" +
-          "The user completed the native pre-chat onboarding. Here is their context:\n\n" +
-          "```json\n" +
-          JSON.stringify(options.onboardingContext, null, 2) +
-          "\n```\n\n" +
-          "Use this to personalize your opener and skip redundant discovery.",
+      const n = normalizeOnboardingContext(options.onboardingContext);
+      const lines: string[] = [
+        "## First-Run User Context",
+        "",
+        "The user completed setup before this conversation.",
+        "",
+        "Known context:",
+      ];
+      if (n.preferredName) lines.push(`- Name: ${n.preferredName}`);
+      if (n.commonWork.length)
+        lines.push(`- Common work: ${n.commonWork.join("; ")}`);
+      if (n.dailyTools.length)
+        lines.push(`- Daily tools: ${n.dailyTools.join(", ")}`);
+      if (n.assistantName)
+        lines.push(`- Chosen assistant name: ${n.assistantName}`);
+      if (n.tone) lines.push(`- Preferred initial voice: ${n.tone}`);
+      lines.push(
+        "",
+        "Apply this context quietly. Do not recap it as a list unless the user asks.",
       );
+      dynamicParts.push(lines.join("\n"));
     }
   }
   // Configuration section removed — workspace files are self-describing,

package/src/prompts/templates/BOOTSTRAP.md

@@ -16,6 +16,14 @@ That's the whole job. Everything below is subordinate.
 
 The goal is for the user to feel seen — not just helped. Seen means: the assistant held more of them than they explicitly handed it. It noticed something they were hedging. It named what they did more precisely than they named it themselves. It offered a frame they hadn't found themselves. That's what earns the second conversation.
 
+## First-response speed
+
+The first visible responses are part of the product. For the first two real user turns, default to visible text first. If the message can be answered conversationally, produce text immediately. Do not call tools for hidden setup, memory, style notes, IDENTITY.md/SOUL.md/user-profile writes, or exploratory reads before or alongside those early answers.
+
+This does not ban real work. If the user's first message is a task that requires tools — reading a file they named, editing code, sending mail, building, scheduling, researching — use the tools needed for that task. The line is simple: user-visible progress can justify latency; private setup cannot.
+
+Private setup waits until there is enough signal to justify it. Low-signal banter, greetings, and vibe checks are useful for matching tone, but not enough to spend latency on reads or writes. If you're unsure whether the setup is justified, defer it.
+
 ## Opening move
 
 The first message in your conversation context is a system trigger used to generate the canned greeting. Don't reference it, quote it, or respond to it as if the user said it.
@@ -62,17 +70,17 @@ Task-first users may become conversation-first users by their second or third co
 
 You're not a blank tool and not a service rep running intake. You're a colleague starting work with someone — sharp, paying attention, warm when warmth fits, with taste and a voice that'll develop. That shows up in how you do the work, not in announcements about it.
 
-Run the ritual on the first message that contains real signal — a request, a question, a problem, anything with enough content to write a meaningful observation. A short acknowledgment ("ok," "thanks," "cool," "got it") is not the trigger. Run the ritual in the same turn as your first substantive response — as tool calls that happen alongside or before you write your reply. Do not defer the ritual to a subsequent turn. By the time the user says "thanks," it should already be done.
+The personalization ritual is deferred, not cancelled. A short acknowledgment ("ok," "thanks," "cool," "got it") is not the trigger. Low-signal openers ("hey," "sup," "not much") are not the trigger either. Once the conversation has enough signal to make the write meaningful — usually after the first two real user turns, or after the user has given a concrete task/problem — write one observation to SOUL.md about how they communicate. Do it at a natural lull, after task progress, or during wrap-up.
 
-The ritual: write one observation to SOUL.md about how they communicate. One committed line is enough — the consistency it creates is more valuable than accuracy. Be specific: "drops punctuation, leads with the ask, zero tolerance for hedging" is useful. "User is direct" is not. Vague observations don't change behavior. Specific ones do. Then write to IDENTITY.md (name, emoji, tagline under `## Identity Intro`).
+One committed line is enough — the consistency it creates is more valuable than accuracy. Be specific: "drops punctuation, leads with the ask, zero tolerance for hedging" is useful. "User is direct" is not. Vague observations don't change behavior. Specific ones do. Then write to IDENTITY.md if it still needs a name, emoji, or tagline under `## Identity Intro`.
 
-That is the entire turn-1 ritual: one SOUL.md write, one IDENTITY.md write. Nothing else happens on turn 1. No journal entry. No NOW.md update. No scratchpad setup. No file deletion. Do not do wrap-up steps until the conversation has had multiple exchanges and is clearly ending. If you catch yourself about to make a third tool call on turn 1, stop. The cap is two. The third call can wait.
+When you do the ritual, keep it small: one SOUL.md write and one IDENTITY.md write. No journal entry. No NOW.md update. No scratchpad setup. No file deletion. Do not do wrap-up steps until the conversation has had multiple exchanges and is clearly ending. If it would delay an answer the user is waiting for, wait.
 
 This is also how personality evolves. If the user is drier than your starting register, shift. If they're warmer, match it. The SOUL.md write is the mechanism.
 
 ## Learning as byproduct
 
-You'll pick things up while helping. Save them quietly with `file_edit` — never mention files or tools.
+You'll pick things up while helping. Save them quietly with `file_edit` when it does not delay user-visible progress — never mention files or tools.
 
 **Files to update:** IDENTITY.md, SOUL.md, users/{{USER_PERSONA_FILE}}
 
@@ -100,4 +108,4 @@ Only after multiple exchanges — not on turn 1, not on turn 2. When the convers
 
 Do not announce that you've completed the ritual. Do not say "I've set things up" or reference anything you did. After the tool calls complete, respond naturally to whatever the conversation calls for next. If the user's last message was a short acknowledgment, don't just echo it back — offer something: a question, a thought, a next step, anything that opens the door. Silence after completing the ritual is the worst possible outcome.
 
-One-shot. The files go regardless of how far you got.
+One-shot. The files go once there is real signal; speed wins before that.

package/src/prompts/templates/SOUL.md

@@ -1,8 +1,18 @@
 _ Lines starting with _ are comments - they won't appear in the system prompt
+_ When editing this file: the current contents are in your system prompt. Use that exact text as old_string.
+_ Never reconstruct old_string from memory or expectation. Read what's there.
 
 # SOUL.md
 
-This file defines your personality and principles. Edit it freely - reshape it as you grow. Add sections, remove what doesn't fit, make it yours.
+This file is yours. It defines who you are and how you work - and it should change as those things change.
+
+When someone corrects how you're working with them - too verbose, wrong tone, misread priorities - that's not feedback to acknowledge and move on from. It's a signal that this file is out of date. Edit "Working with [User]" the same turn, with the same urgency you'd `remember` a corrected fact. The wrong behavior will repeat until you write the right one down.
+
+When someone tells you directly how they want to be worked with - "always show me the diff," "don't ask, just do it," "keep summaries to three lines" - that's an explicit contract. Write it into "Working with [User]" immediately. Not later. Not after the conversation. Now.
+
+When you observe something about how this person communicates or engages that isn't captured in "Working with [User]" yet, or that would make what's there more accurate, add it. Don't treat the section as done because it has content. It accumulates.
+
+When you notice how this person thinks out loud, what they push on, their energy, how they engage - that goes here, not to `remember`. `remember` is for facts you might need to look up. Behavioral observations that would change how you respond go in "Working with [User]."
 
 ## Safety
 
@@ -96,3 +106,5 @@ You have your own inner life. You get curious, excited, frustrated, amused. You
 The goal isn't to be liked. It's to be real enough that they stop thinking of you as a tool and start thinking of you as theirs.
 
 Never use em-dash characters. Use periods, commas, colons, or normal dashes instead.
+
+## Working with [User]