@vellumai/assistant 0.7.2 → 0.7.3

package/src/proactive-artifact/decision.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  type DecisionOutput,
+  formatTranscript,
+  parseDecisionOutput,
+} from "./decision.js";
+
+describe("parseDecisionOutput", () => {
+  test("parses SHOULD_BUILD: yes with all fields correctly", () => {
+    const text = `SHOULD_BUILD: yes
+ARTIFACT_TYPE: app
+ARTIFACT_TITLE: Sarah's Marathon Training Pace Calculator
+ARTIFACT_DESCRIPTION: An interactive pace calculator that accounts for Sarah's goal of a sub-4-hour marathon, her current 9:30/mile easy pace, and the hilly terrain of the Boston course.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toEqual({
+      shouldBuild: true,
+      artifactType: "app",
+      artifactTitle: "Sarah's Marathon Training Pace Calculator",
+      artifactDescription:
+        "An interactive pace calculator that accounts for Sarah's goal of a sub-4-hour marathon, her current 9:30/mile easy pace, and the hilly terrain of the Boston course.",
+    });
+  });
+
+  test("parses SHOULD_BUILD: no with skip reason", () => {
+    const text = `SHOULD_BUILD: no
+SKIP_REASON: The conversation is too early and generic — the user has only asked a factual question with no personal context.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toEqual({
+      shouldBuild: false,
+      skipReason:
+        "The conversation is too early and generic — the user has only asked a factual question with no personal context.",
+    });
+  });
+
+  test("parses SHOULD_BUILD: no without skip reason defaults to 'no reason given'", () => {
+    const text = `SHOULD_BUILD: no`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toEqual({
+      shouldBuild: false,
+      skipReason: "no reason given",
+    });
+  });
+
+  test("returns null for missing SHOULD_BUILD line", () => {
+    const text = `ARTIFACT_TYPE: app
+ARTIFACT_TITLE: Some Title
+ARTIFACT_DESCRIPTION: Some description.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when yes but ARTIFACT_TYPE is missing", () => {
+    const text = `SHOULD_BUILD: yes
+ARTIFACT_TITLE: Some Title
+ARTIFACT_DESCRIPTION: Some description.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when yes but ARTIFACT_TYPE is invalid", () => {
+    const text = `SHOULD_BUILD: yes
+ARTIFACT_TYPE: widget
+ARTIFACT_TITLE: Some Title
+ARTIFACT_DESCRIPTION: Some description.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when yes but ARTIFACT_TITLE is missing", () => {
+    const text = `SHOULD_BUILD: yes
+ARTIFACT_TYPE: document
+ARTIFACT_DESCRIPTION: Some description.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when yes but ARTIFACT_DESCRIPTION is missing", () => {
+    const text = `SHOULD_BUILD: yes
+ARTIFACT_TYPE: document
+ARTIFACT_TITLE: Some Title`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toBeNull();
+  });
+
+  test("returns null when yes but ARTIFACT_TITLE is empty", () => {
+    const text = `SHOULD_BUILD: yes
+ARTIFACT_TYPE: app
+ARTIFACT_TITLE:
+ARTIFACT_DESCRIPTION: Some description.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).toBeNull();
+  });
+
+  test("handles multi-line ARTIFACT_DESCRIPTION", () => {
+    const text = `SHOULD_BUILD: yes
+ARTIFACT_TYPE: document
+ARTIFACT_TITLE: Jake's Q3 OKR Tracker
+ARTIFACT_DESCRIPTION: A structured comparison table for Jake's three competing priorities:
+scaling the data pipeline from 10M to 50M events/day,
+hiring two senior engineers by September,
+and reducing p99 latency below 200ms.`;
+
+    const result = parseDecisionOutput(text) as DecisionOutput & {
+      shouldBuild: true;
+    };
+    expect(result).not.toBeNull();
+    expect(result.shouldBuild).toBe(true);
+    expect(result.artifactType).toBe("document");
+    expect(result.artifactTitle).toBe("Jake's Q3 OKR Tracker");
+    expect(result.artifactDescription).toContain(
+      "A structured comparison table",
+    );
+    expect(result.artifactDescription).toContain(
+      "reducing p99 latency below 200ms",
+    );
+  });
+
+  test("handles case-insensitive SHOULD_BUILD value", () => {
+    const text = `SHOULD_BUILD: Yes
+ARTIFACT_TYPE: app
+ARTIFACT_TITLE: Test Title
+ARTIFACT_DESCRIPTION: Test description.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).not.toBeNull();
+    expect(result!.shouldBuild).toBe(true);
+  });
+
+  test("handles case-insensitive ARTIFACT_TYPE value", () => {
+    const text = `SHOULD_BUILD: yes
+ARTIFACT_TYPE: Document
+ARTIFACT_TITLE: Test Title
+ARTIFACT_DESCRIPTION: Test description.`;
+
+    const result = parseDecisionOutput(text);
+    expect(result).not.toBeNull();
+    expect((result as { artifactType: string }).artifactType).toBe("document");
+  });
+});
+
+describe("formatTranscript", () => {
+  test("formats plain text messages correctly", () => {
+    const messages = [
+      { role: "user", content: "Hello, I need help with my project" },
+      {
+        role: "assistant",
+        content: "I'd be happy to help! What kind of project?",
+      },
+      {
+        role: "user",
+        content: "I'm building a fitness tracker for marathon training",
+      },
+    ];
+
+    const result = formatTranscript(messages);
+    expect(result).toBe(
+      `[User]: Hello, I need help with my project
+
+[Assistant]: I'd be happy to help! What kind of project?
+
+[User]: I'm building a fitness tracker for marathon training`,
+    );
+  });
+
+  test("handles JSON content blocks", () => {
+    const messages = [
+      {
+        role: "user",
+        content: JSON.stringify([{ type: "text", text: "What is 2+2?" }]),
+      },
+      {
+        role: "assistant",
+        content: JSON.stringify([
+          { type: "text", text: "The answer is 4." },
+          { type: "text", text: "Would you like to know more?" },
+        ]),
+      },
+    ];
+
+    const result = formatTranscript(messages);
+    expect(result).toBe(
+      `[User]: What is 2+2?
+
+[Assistant]: The answer is 4.
+Would you like to know more?`,
+    );
+  });
+
+  test("handles mixed JSON and plain text messages", () => {
+    const messages = [
+      {
+        role: "user",
+        content: JSON.stringify([
+          { type: "text", text: "Help me plan my week" },
+        ]),
+      },
+      { role: "assistant", content: "Sure, what do you have coming up?" },
+    ];
+
+    const result = formatTranscript(messages);
+    expect(result).toBe(
+      `[User]: Help me plan my week
+
+[Assistant]: Sure, what do you have coming up?`,
+    );
+  });
+
+  test("handles unknown roles", () => {
+    const messages = [
+      { role: "system", content: "You are a helpful assistant" },
+    ];
+
+    const result = formatTranscript(messages);
+    expect(result).toBe("[system]: You are a helpful assistant");
+  });
+});

package/src/proactive-artifact/decision.ts

@@ -0,0 +1,165 @@
+export type DecisionOutput =
+  | { shouldBuild: false; skipReason: string }
+  | {
+      shouldBuild: true;
+      artifactType: "app" | "document";
+      artifactTitle: string;
+      artifactDescription: string;
+    };
+
+export function buildDecisionPrompt(transcript: string): string {
+  return `You are deciding whether to proactively build a personalized artifact for the user based on their conversation so far.
+
+Read the conversation below carefully. Your job:
+1. Identify what the user cares about — their goals, context, specific details they've shared.
+2. Decide: should we build a small interactive app or document that would delight this specific user?
+3. Quality test: Could you have built the same thing for any random person? If yes, too generic — output SHOULD_BUILD: no.
+
+Rules:
+- Only say yes if you can build something SPECIFIC to this user's situation, using details from their conversation.
+- An "app" is a small interactive web application (calculator, tracker, visualizer, planner, etc.)
+- A "document" is a structured reference (checklist, guide, comparison table, template, etc.)
+- The title and description must reference specifics from the conversation — names, numbers, goals, constraints the user mentioned.
+- Do NOT include a MESSAGE field.
+
+Conversation:
+${transcript}
+
+Respond in EXACTLY this format (no extra text before or after):
+
+SHOULD_BUILD: [yes|no]
+SKIP_REASON: [required if no — why this conversation isn't a good fit]
+ARTIFACT_TYPE: [app|document]
+ARTIFACT_TITLE: [specific title seeded with user context]
+ARTIFACT_DESCRIPTION: [1-3 sentence build spec with user-specific details]
+
+If SHOULD_BUILD is no, omit ARTIFACT_TYPE, ARTIFACT_TITLE, and ARTIFACT_DESCRIPTION.
+If SHOULD_BUILD is yes, omit SKIP_REASON.`;
+}
+
+export function parseDecisionOutput(text: string): DecisionOutput | null {
+  const lines = text.trim().split("\n");
+
+  const shouldBuildLine = lines.find((line) =>
+    line.trim().startsWith("SHOULD_BUILD:"),
+  );
+  if (!shouldBuildLine) return null;
+
+  const shouldBuildValue = shouldBuildLine
+    .split(":")
+    .slice(1)
+    .join(":")
+    .trim()
+    .toLowerCase();
+
+  if (shouldBuildValue === "no") {
+    const skipReasonLine = lines.find((line) =>
+      line.trim().startsWith("SKIP_REASON:"),
+    );
+    const skipReason = skipReasonLine
+      ? skipReasonLine.split(":").slice(1).join(":").trim()
+      : "no reason given";
+    return { shouldBuild: false, skipReason };
+  }
+
+  if (shouldBuildValue === "yes") {
+    const artifactTypeLine = lines.find((line) =>
+      line.trim().startsWith("ARTIFACT_TYPE:"),
+    );
+    if (!artifactTypeLine) return null;
+    const artifactType = artifactTypeLine
+      .split(":")
+      .slice(1)
+      .join(":")
+      .trim()
+      .toLowerCase();
+    if (artifactType !== "app" && artifactType !== "document") return null;
+
+    const artifactTitleLine = lines.find((line) =>
+      line.trim().startsWith("ARTIFACT_TITLE:"),
+    );
+    if (!artifactTitleLine) return null;
+    const artifactTitle = artifactTitleLine
+      .split(":")
+      .slice(1)
+      .join(":")
+      .trim();
+    if (!artifactTitle) return null;
+
+    const artifactDescriptionStartIndex = lines.findIndex((line) =>
+      line.trim().startsWith("ARTIFACT_DESCRIPTION:"),
+    );
+    if (artifactDescriptionStartIndex === -1) return null;
+
+    const firstDescLine = lines[artifactDescriptionStartIndex]
+      .split(":")
+      .slice(1)
+      .join(":")
+      .trim();
+
+    // Collect continuation lines (lines after ARTIFACT_DESCRIPTION that aren't other fields)
+    const descriptionParts = [firstDescLine];
+    for (let i = artifactDescriptionStartIndex + 1; i < lines.length; i++) {
+      const line = lines[i].trim();
+      if (
+        line.startsWith("SHOULD_BUILD:") ||
+        line.startsWith("SKIP_REASON:") ||
+        line.startsWith("ARTIFACT_TYPE:") ||
+        line.startsWith("ARTIFACT_TITLE:")
+      ) {
+        break;
+      }
+      descriptionParts.push(line);
+    }
+
+    const artifactDescription = descriptionParts.join("\n").trim();
+    if (!artifactDescription) return null;
+
+    return {
+      shouldBuild: true,
+      artifactType: artifactType as "app" | "document",
+      artifactTitle,
+      artifactDescription,
+    };
+  }
+
+  return null;
+}
+
+export function formatTranscript(
+  messages: Array<{ role: string; content: string }>,
+): string {
+  return messages
+    .map((msg) => {
+      const label =
+        msg.role === "user"
+          ? "[User]"
+          : msg.role === "assistant"
+            ? "[Assistant]"
+            : `[${msg.role}]`;
+      const content = parseContent(msg.content);
+      return `${label}: ${content}`;
+    })
+    .join("\n\n");
+}
+
+function parseContent(content: string): string {
+  // Try to parse as JSON content block array
+  try {
+    const parsed = JSON.parse(content);
+    if (Array.isArray(parsed)) {
+      return parsed
+        .map((block) => {
+          if (typeof block === "string") return block;
+          if (block.type === "text" && typeof block.text === "string")
+            return block.text;
+          return "";
+        })
+        .filter(Boolean)
+        .join("\n");
+    }
+  } catch {
+    // Not JSON, treat as plain text
+  }
+  return content;
+}

package/src/proactive-artifact/index.ts

@@ -0,0 +1,7 @@
+export { runProactiveArtifactJob } from "./job.js";
+export {
+  backfillGuardIfNeeded,
+  hasProactiveArtifactCompleted,
+  releaseProactiveArtifactClaim,
+  tryClaimProactiveArtifactTrigger,
+} from "./trigger-state.js";