@vellumai/assistant 0.7.1 → 0.7.3

package/src/proactive-artifact/job.ts

@@ -0,0 +1,352 @@
+/**
+ * Proactive artifact background job orchestrator.
+ *
+ * Runs a multi-phase pipeline:
+ *   1. Collect bounded transcript from the conversation
+ *   2. Phase 1 — Decision: ask the LLM whether to build an artifact
+ *   3. Phase 2 — Build: create the artifact (app or document)
+ *   4. Post-build message copy: generate a user-facing message
+ *   5. Message injection: deliver the message to the conversation
+ *   6. Notification: emit a notification signal
+ *
+ * Build failure = total silence (no message, no notification).
+ * Provider unavailable = silent return.
+ */
+
+import { v4 as uuid } from "uuid";
+
+import { processMessage } from "../daemon/process-message.js";
+import { INTERNAL_GUARDIAN_TRUST_CONTEXT } from "../daemon/trust-context.js";
+import { saveDocument } from "../documents/document-store.js";
+import {
+  addAppConversationId,
+  listApps,
+  listAppsByConversation,
+} from "../memory/app-store.js";
+import { bootstrapConversation } from "../memory/conversation-bootstrap.js";
+import { rawAll } from "../memory/raw-query.js";
+import type { BroadcastFn } from "../notifications/adapters/macos.js";
+import { emitNotificationSignal } from "../notifications/emit-signal.js";
+import {
+  extractText,
+  getConfiguredProvider,
+} from "../providers/provider-send-message.js";
+import { getLogger } from "../util/logger.js";
+import { injectAuxAssistantMessage } from "./aux-message-injector.js";
+import {
+  buildDecisionPrompt,
+  formatTranscript,
+  parseDecisionOutput,
+} from "./decision.js";
+import { buildMessageCopyPrompt, parseMessageCopy } from "./message-copy.js";
+import { releaseProactiveArtifactClaim } from "./trigger-state.js";
+
+const log = getLogger("proactive-artifact-job");
+
+export async function runProactiveArtifactJob(params: {
+  conversationId: string;
+  userMessageCutoff: number;
+  assistantMessageId: string | undefined;
+  suppressAppBuild?: boolean;
+  broadcastMessage: BroadcastFn;
+}): Promise<void> {
+  let buildSucceeded = false;
+  try {
+    // ── Collect transcript (bounded) ────────────────────────────────
+    const rows = rawAll<{ role: string; content: string }>(
+      `SELECT m.role, m.content FROM messages m
+       JOIN conversations c ON m.conversation_id = c.id
+       WHERE c.conversation_type = 'standard'
+         AND (m.created_at <= ? OR m.id = ?)
+       ORDER BY m.created_at ASC`,
+      params.userMessageCutoff,
+      params.assistantMessageId ?? "",
+    );
+
+    if (rows.length === 0) {
+      log.info(
+        { conversationId: params.conversationId },
+        "No messages found for proactive artifact transcript",
+      );
+      releaseProactiveArtifactClaim();
+      return;
+    }
+
+    const transcript = formatTranscript(rows);
+
+    // ── Phase 1 — Decision ──────────────────────────────────────────
+    const decisionProvider = await getConfiguredProvider(
+      "proactiveArtifactDecision",
+    );
+    if (!decisionProvider) {
+      log.info("Decision provider unavailable; skipping proactive artifact");
+      releaseProactiveArtifactClaim();
+      return;
+    }
+
+    const decisionResponse = await decisionProvider.sendMessage([
+      {
+        role: "user",
+        content: [{ type: "text", text: buildDecisionPrompt(transcript) }],
+      },
+    ]);
+    const decisionText = extractText(decisionResponse);
+    const decision = parseDecisionOutput(decisionText);
+
+    if (!decision) {
+      log.warn(
+        { conversationId: params.conversationId },
+        "Malformed decision output from proactive artifact LLM",
+      );
+      releaseProactiveArtifactClaim();
+      return;
+    }
+
+    if (!decision.shouldBuild) {
+      log.info(
+        {
+          conversationId: params.conversationId,
+          skipReason: decision.skipReason,
+        },
+        "Proactive artifact decision: skip",
+      );
+      releaseProactiveArtifactClaim();
+      return;
+    }
+
+    // ── Phase 2 — Build ─────────────────────────────────────────────
+    const { artifactType, artifactTitle, artifactDescription } = decision;
+    let artifactId: string;
+
+    if (artifactType === "app") {
+      const suppressionReason = getAppBuildSuppressionReason({
+        conversationId: params.conversationId,
+        userMessageCutoff: params.userMessageCutoff,
+        suppressAppBuild: params.suppressAppBuild,
+      });
+      if (suppressionReason) {
+        log.info(
+          {
+            conversationId: params.conversationId,
+            artifactTitle,
+            suppressionReason,
+          },
+          "Skipping proactive app build because foreground app work already exists",
+        );
+        return;
+      }
+      artifactId = await buildApp({
+        artifactTitle,
+        artifactDescription,
+        conversationId: params.conversationId,
+      });
+    } else {
+      artifactId = await buildDocument({
+        artifactTitle,
+        artifactDescription,
+        conversationId: params.conversationId,
+        transcript,
+      });
+    }
+    buildSucceeded = true;
+
+    // ── Post-build message copy ─────────────────────────────────────
+    let messageCopy: string;
+    const fallbackMessage = `I made something for you — ${artifactTitle}. Take a look when you get a chance.`;
+
+    try {
+      const copyProvider = await getConfiguredProvider(
+        "proactiveArtifactBuild",
+      );
+      if (!copyProvider) {
+        messageCopy = fallbackMessage;
+      } else {
+        const copyResponse = await copyProvider.sendMessage([
+          {
+            role: "user",
+            content: [
+              {
+                type: "text",
+                text: buildMessageCopyPrompt({
+                  artifactType,
+                  artifactTitle,
+                  artifactId,
+                  transcript,
+                }),
+              },
+            ],
+          },
+        ]);
+        const copyText = extractText(copyResponse);
+        messageCopy = parseMessageCopy(copyText) ?? fallbackMessage;
+      }
+    } catch (err) {
+      log.warn({ err }, "Message copy generation failed; using fallback");
+      messageCopy = fallbackMessage;
+    }
+
+    // ── Message injection ───────────────────────────────────────────
+    await injectAuxAssistantMessage({
+      conversationId: params.conversationId,
+      text: messageCopy,
+      broadcastMessage: params.broadcastMessage,
+    });
+
+    // ── Notification ────────────────────────────────────────────────
+    await emitNotificationSignal({
+      sourceEventName: "activity.complete",
+      sourceChannel: "vellum",
+      sourceContextId: params.conversationId,
+      attentionHints: {
+        urgency: "medium",
+        requiresAction: false,
+        isAsyncBackground: true,
+        visibleInSourceNow: false,
+      },
+      contextPayload: {
+        summary: `${artifactTitle} is ready`,
+      },
+      dedupeKey: "proactive-artifact",
+    });
+  } catch (err) {
+    log.error(
+      { err, conversationId: params.conversationId },
+      "Proactive artifact job failed",
+    );
+    if (!buildSucceeded) {
+      releaseProactiveArtifactClaim();
+    }
+  }
+}
+
+// ── App build ─────────────────────────────────────────────────────────
+
+function getAppBuildSuppressionReason(params: {
+  conversationId: string;
+  userMessageCutoff: number;
+  suppressAppBuild?: boolean;
+}): string | null {
+  if (params.suppressAppBuild) {
+    return "foreground-turn-used-app-tool";
+  }
+
+  const recentApps = listAppsByConversation(params.conversationId).filter(
+    (app) =>
+      app.createdAt >= params.userMessageCutoff ||
+      app.updatedAt >= params.userMessageCutoff,
+  );
+  if (recentApps.length > 0) {
+    return "conversation-has-recent-app-activity";
+  }
+
+  return null;
+}
+
+async function buildApp(params: {
+  artifactTitle: string;
+  artifactDescription: string;
+  conversationId: string;
+}): Promise<string> {
+  const conversation = bootstrapConversation({
+    conversationType: "background",
+    source: "proactive_artifact",
+    groupId: "system:background",
+    origin: "heartbeat",
+    systemHint: "Proactive artifact build",
+  });
+
+  const buildStartedAt = Date.now();
+
+  const prompt = `Load the app-builder skill, then create an app with the following details:
+- Title: ${params.artifactTitle}
+- Description: ${params.artifactDescription}
+- auto_open: false
+
+For apps, keep scope tight — single file or 2-3 files max, under ~300 lines. Simple and immediately useful beats impressive and slow. This runs as a background job with limited credits — scope accordingly.
+
+Write the source code following the skill instructions, then compile via app_refresh.`;
+
+  await processMessage(conversation.id, prompt, undefined, {
+    callSite: "proactiveArtifactBuild",
+    trustContext: INTERNAL_GUARDIAN_TRUST_CONTEXT,
+  });
+
+  // Query app store for newly created app
+  const apps = listApps();
+  const match = apps.find(
+    (app) =>
+      app.createdAt >= buildStartedAt &&
+      app.name
+        .trim()
+        .toLowerCase()
+        .includes(params.artifactTitle.trim().toLowerCase()),
+  );
+
+  if (!match) {
+    throw new Error(
+      `App build completed but no matching app found (title: ${params.artifactTitle})`,
+    );
+  }
+
+  addAppConversationId(match.id, params.conversationId);
+
+  return match.id;
+}
+
+// ── Document build ────────────────────────────────────────────────────
+
+async function buildDocument(params: {
+  artifactTitle: string;
+  artifactDescription: string;
+  conversationId: string;
+  transcript: string;
+}): Promise<string> {
+  const buildProvider = await getConfiguredProvider("proactiveArtifactBuild");
+  if (!buildProvider) {
+    throw new Error("Build provider unavailable for document generation");
+  }
+
+  const buildResponse = await buildProvider.sendMessage([
+    {
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: `Generate a well-structured markdown document based on the following specification.
+
+Title: ${params.artifactTitle}
+Description: ${params.artifactDescription}
+
+Original conversation for context:
+${params.transcript}
+
+Write the complete markdown content. Make it specific, actionable, and tailored to the user's situation.`,
+        },
+      ],
+    },
+  ]);
+
+  const generatedMarkdown = extractText(buildResponse);
+  if (!generatedMarkdown) {
+    throw new Error("Build provider returned empty content for document");
+  }
+
+  const surfaceId = `doc-${uuid()}`;
+  const wordCount = generatedMarkdown
+    .split(/\s+/)
+    .filter((w) => w.length > 0).length;
+
+  const result = saveDocument({
+    surfaceId,
+    conversationId: params.conversationId,
+    title: params.artifactTitle,
+    content: generatedMarkdown,
+    wordCount,
+  });
+
+  if (!result.success) {
+    throw new Error(`Failed to save document: ${result.error}`);
+  }
+
+  return surfaceId;
+}

package/src/proactive-artifact/message-copy.ts

@@ -0,0 +1,41 @@
+/**
+ * Post-build message copy generation for proactive artifacts.
+ *
+ * After building an artifact, we ask the LLM to write a short,
+ * conversational message explaining what was built and why.
+ */
+
+export function buildMessageCopyPrompt(params: {
+  artifactType: "app" | "document";
+  artifactTitle: string;
+  artifactId: string;
+  transcript: string;
+}): string {
+  return `You just built a personalized ${params.artifactType} for the user based on their conversation.
+
+Artifact details:
+- Type: ${params.artifactType}
+- Title: ${params.artifactTitle}
+- ID: ${params.artifactId}
+
+Original conversation:
+${params.transcript}
+
+Write a short message (2-3 sentences) to the user explaining:
+1. What you built
+2. Why you built it (reference something specific from the conversation)
+3. Where to find it
+
+Keep it warm and natural — not robotic. This should feel like a thoughtful gift, not a system notification.
+
+Respond in EXACTLY this format (no extra text before or after):
+
+MESSAGE: <your message>`;
+}
+
+export function parseMessageCopy(text: string): string | null {
+  const match = text.match(/^MESSAGE:\s*(.+)/ms);
+  if (!match) return null;
+  const value = match[1].trim();
+  return value.length > 0 ? value : null;
+}

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

@@ -0,0 +1,277 @@
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { beforeEach, describe, expect, test } from "bun:test";
+
+import { initializeDb } from "../memory/db-init.js";
+import { rawRun } from "../memory/raw-query.js";
+import { getDataDir } from "../util/platform.js";
+
+initializeDb();
+
+import {
+  backfillGuardIfNeeded,
+  getUserMessageCountUpTo,
+  hasProactiveArtifactCompleted,
+  releaseProactiveArtifactClaim,
+  tryClaimProactiveArtifactTrigger,
+} from "./trigger-state.js";
+
+let seedId = 0;
+
+function guardPath(): string {
+  return join(getDataDir(), ".proactive-artifact-completed");
+}
+
+function seedUserMessage(createdAt: number): void {
+  const id = ++seedId;
+  const convId = `test-conv-${id}`;
+  rawRun(
+    `INSERT INTO conversations (id, title, created_at, updated_at, conversation_type, source)
+     VALUES (?, ?, ?, ?, 'standard', 'user')`,
+    convId,
+    `Test ${id}`,
+    createdAt,
+    createdAt,
+  );
+  rawRun(
+    `INSERT INTO messages (id, conversation_id, role, content, created_at)
+     VALUES (?, ?, 'user', 'hello', ?)`,
+    `test-msg-${id}`,
+    convId,
+    createdAt,
+  );
+}
+
+function removeGuard(): void {
+  try {
+    rmSync(guardPath(), { force: true });
+  } catch {
+    /* ignore */
+  }
+}
+
+describe("trigger-state", () => {
+  beforeEach(() => {
+    rawRun("DELETE FROM messages");
+    rawRun("DELETE FROM conversations");
+    removeGuard();
+    seedId = 0;
+  });
+
+  describe("getUserMessageCountUpTo", () => {
+    test("returns 0 when no messages exist", () => {
+      expect(getUserMessageCountUpTo(Date.now())).toBe(0);
+    });
+
+    test("counts only user messages in standard conversations", () => {
+      const now = 1000;
+      seedUserMessage(now);
+      seedUserMessage(now + 1);
+
+      // Insert a non-user message
+      const convId = "non-user-conv";
+      rawRun(
+        `INSERT INTO conversations (id, title, created_at, updated_at, conversation_type, source)
+         VALUES (?, ?, ?, ?, 'standard', 'user')`,
+        convId,
+        "Non-user",
+        now + 2,
+        now + 2,
+      );
+      rawRun(
+        `INSERT INTO messages (id, conversation_id, role, content, created_at)
+         VALUES (?, ?, 'assistant', 'hi', ?)`,
+        "assistant-msg",
+        convId,
+        now + 2,
+      );
+
+      // Insert a user message in a non-standard conversation
+      const bgConvId = "bg-conv";
+      rawRun(
+        `INSERT INTO conversations (id, title, created_at, updated_at, conversation_type, source)
+         VALUES (?, ?, ?, ?, 'background', 'user')`,
+        bgConvId,
+        "Background",
+        now + 3,
+        now + 3,
+      );
+      rawRun(
+        `INSERT INTO messages (id, conversation_id, role, content, created_at)
+         VALUES (?, ?, 'user', 'hello', ?)`,
+        "bg-msg",
+        bgConvId,
+        now + 3,
+      );
+
+      expect(getUserMessageCountUpTo(now + 10)).toBe(2);
+    });
+
+    test("respects beforeOrAt filter", () => {
+      seedUserMessage(100);
+      seedUserMessage(200);
+      seedUserMessage(300);
+
+      expect(getUserMessageCountUpTo(150)).toBe(1);
+      expect(getUserMessageCountUpTo(250)).toBe(2);
+      expect(getUserMessageCountUpTo(350)).toBe(3);
+    });
+
+    test("caps at 11 due to LIMIT", () => {
+      for (let i = 1; i <= 15; i++) {
+        seedUserMessage(i * 100);
+      }
+      expect(getUserMessageCountUpTo(Date.now())).toBe(11);
+    });
+  });
+
+  describe("tryClaimProactiveArtifactTrigger", () => {
+    test("returns false at count 1, 2, 3 and does NOT write guard", () => {
+      seedUserMessage(100);
+      expect(tryClaimProactiveArtifactTrigger(100)).toBe(false);
+      expect(existsSync(guardPath())).toBe(false);
+
+      seedUserMessage(200);
+      expect(tryClaimProactiveArtifactTrigger(200)).toBe(false);
+      expect(existsSync(guardPath())).toBe(false);
+
+      seedUserMessage(300);
+      expect(tryClaimProactiveArtifactTrigger(300)).toBe(false);
+      expect(existsSync(guardPath())).toBe(false);
+    });
+
+    test("returns true at count 4 (start of window) and writes guard", () => {
+      for (let i = 1; i <= 4; i++) seedUserMessage(i * 100);
+
+      expect(tryClaimProactiveArtifactTrigger(400)).toBe(true);
+      expect(existsSync(guardPath())).toBe(true);
+    });
+
+    test("returns true at count 10 (end of window) and writes guard", () => {
+      for (let i = 1; i <= 10; i++) seedUserMessage(i * 100);
+
+      expect(tryClaimProactiveArtifactTrigger(1000)).toBe(true);
+      expect(existsSync(guardPath())).toBe(true);
+    });
+
+    test("returns true at count 7 (mid-window) and writes guard", () => {
+      for (let i = 1; i <= 7; i++) seedUserMessage(i * 100);
+
+      expect(tryClaimProactiveArtifactTrigger(700)).toBe(true);
+      expect(existsSync(guardPath())).toBe(true);
+    });
+
+    test("returns false on second call (EEXIST from wx)", () => {
+      for (let i = 1; i <= 4; i++) seedUserMessage(i * 100);
+
+      expect(tryClaimProactiveArtifactTrigger(400)).toBe(true);
+      expect(tryClaimProactiveArtifactTrigger(400)).toBe(false);
+    });
+
+    test("returns false at count > 10 and writes guard permanently", () => {
+      for (let i = 1; i <= 11; i++) seedUserMessage(i * 100);
+
+      expect(tryClaimProactiveArtifactTrigger(1100)).toBe(false);
+      expect(existsSync(guardPath())).toBe(true);
+    });
+
+    test("concurrent calls: only one returns true", () => {
+      for (let i = 1; i <= 4; i++) seedUserMessage(i * 100);
+
+      const results = [
+        tryClaimProactiveArtifactTrigger(400),
+        tryClaimProactiveArtifactTrigger(400),
+        tryClaimProactiveArtifactTrigger(400),
+      ];
+
+      expect(results.filter((r) => r === true)).toHaveLength(1);
+      expect(results.filter((r) => r === false)).toHaveLength(2);
+    });
+
+    test("rapid next-message race: in-window trigger still fires", () => {
+      for (let i = 1; i <= 5; i++) seedUserMessage(i * 100);
+
+      expect(tryClaimProactiveArtifactTrigger(400)).toBe(true);
+    });
+  });
+
+  describe("releaseProactiveArtifactClaim", () => {
+    test("removes guard file so next turn can retry", () => {
+      for (let i = 1; i <= 4; i++) seedUserMessage(i * 100);
+
+      expect(tryClaimProactiveArtifactTrigger(400)).toBe(true);
+      expect(existsSync(guardPath())).toBe(true);
+
+      releaseProactiveArtifactClaim();
+      expect(existsSync(guardPath())).toBe(false);
+
+      seedUserMessage(500);
+      expect(tryClaimProactiveArtifactTrigger(500)).toBe(true);
+      expect(existsSync(guardPath())).toBe(true);
+    });
+
+    test("is no-op when guard does not exist", () => {
+      expect(existsSync(guardPath())).toBe(false);
+      releaseProactiveArtifactClaim();
+      expect(existsSync(guardPath())).toBe(false);
+    });
+  });
+
+  describe("hasProactiveArtifactCompleted", () => {
+    test("returns false when guard does not exist", () => {
+      expect(hasProactiveArtifactCompleted()).toBe(false);
+    });
+
+    test("returns true when guard exists", () => {
+      mkdirSync(join(getDataDir()), { recursive: true });
+      writeFileSync(guardPath(), new Date().toISOString());
+      expect(hasProactiveArtifactCompleted()).toBe(true);
+    });
+  });
+
+  describe("backfillGuardIfNeeded", () => {
+    test("creates guard when count > 10", () => {
+      for (let i = 1; i <= 11; i++) {
+        seedUserMessage(i * 100);
+      }
+
+      backfillGuardIfNeeded();
+      expect(existsSync(guardPath())).toBe(true);
+    });
+
+    test("is no-op when count is within window (4-10)", () => {
+      for (let i = 1; i <= 7; i++) {
+        seedUserMessage(i * 100);
+      }
+
+      backfillGuardIfNeeded();
+      expect(existsSync(guardPath())).toBe(false);
+    });
+
+    test("is no-op when count < 4", () => {
+      seedUserMessage(100);
+      seedUserMessage(200);
+      seedUserMessage(300);
+
+      backfillGuardIfNeeded();
+      expect(existsSync(guardPath())).toBe(false);
+    });
+
+    test("is no-op when guard already exists", () => {
+      for (let i = 1; i <= 11; i++) {
+        seedUserMessage(i * 100);
+      }
+
+      mkdirSync(join(getDataDir()), { recursive: true });
+      writeFileSync(guardPath(), "already-exists");
+      backfillGuardIfNeeded();
+      expect(readFileSync(guardPath(), "utf-8")).toBe("already-exists");
+    });
+  });
+});