stagent 0.10.0 → 0.11.1

package/src/lib/filters/__tests__/parse.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { parseFilterInput, matchesClauses } from "../parse";
+
+describe("parseFilterInput", () => {
+  it("returns empty result for empty input", () => {
+    expect(parseFilterInput("")).toEqual({ clauses: [], rawQuery: "" });
+  });
+
+  it("returns input as rawQuery when no clauses present", () => {
+    const out = parseFilterInput("hello world");
+    expect(out.clauses).toEqual([]);
+    expect(out.rawQuery).toBe("hello world");
+  });
+
+  it("parses a single clause and strips it from rawQuery", () => {
+    const out = parseFilterInput("#status:blocked");
+    expect(out.clauses).toEqual([{ key: "status", value: "blocked" }]);
+    expect(out.rawQuery).toBe("");
+  });
+
+  it("parses multiple clauses with AND semantics", () => {
+    const out = parseFilterInput("#status:blocked #priority:high");
+    expect(out.clauses).toEqual([
+      { key: "status", value: "blocked" },
+      { key: "priority", value: "high" },
+    ]);
+    expect(out.rawQuery).toBe("");
+  });
+
+  it("preserves raw text between and around clauses", () => {
+    const out = parseFilterInput("auth #status:blocked service #priority:high");
+    expect(out.clauses).toEqual([
+      { key: "status", value: "blocked" },
+      { key: "priority", value: "high" },
+    ]);
+    expect(out.rawQuery).toBe("auth service");
+  });
+
+  it("treats `#123` as raw-query text, not a clause (no colon)", () => {
+    const out = parseFilterInput("see #123 for context");
+    expect(out.clauses).toEqual([]);
+    expect(out.rawQuery).toBe("see #123 for context");
+  });
+
+  it("treats `#1abc:val` as raw-query text (key must start with a letter)", () => {
+    const out = parseFilterInput("#1abc:val");
+    expect(out.clauses).toEqual([]);
+    expect(out.rawQuery).toBe("#1abc:val");
+  });
+
+  it("accepts hyphens and underscores in keys", () => {
+    const out = parseFilterInput("#created-by:me #user_id:42");
+    expect(out.clauses).toEqual([
+      { key: "created-by", value: "me" },
+      { key: "user_id", value: "42" },
+    ]);
+  });
+
+  it("preserves case of values verbatim (keys keep case too)", () => {
+    const out = parseFilterInput("#Status:Blocked");
+    expect(out.clauses).toEqual([{ key: "Status", value: "Blocked" }]);
+  });
+
+  it("accepts back-to-back clauses without space between them", () => {
+    const out = parseFilterInput("#a:1#b:2");
+    expect(out.clauses).toEqual([
+      { key: "a", value: "1" },
+      { key: "b", value: "2" },
+    ]);
+    expect(out.rawQuery).toBe("");
+  });
+
+  it("collapses extra whitespace in rawQuery", () => {
+    const out = parseFilterInput("  foo   bar  ");
+    expect(out.rawQuery).toBe("foo bar");
+  });
+
+  it("handles values with special chars except whitespace", () => {
+    const out = parseFilterInput("#path:src/lib/filters.ts");
+    expect(out.clauses).toEqual([{ key: "path", value: "src/lib/filters.ts" }]);
+  });
+});
+
+describe("matchesClauses", () => {
+  const task = { id: "t1", status: "blocked", priority: "high", type: "task" };
+
+  it("returns true when clauses list is empty", () => {
+    expect(matchesClauses(task, [], {})).toBe(true);
+  });
+
+  it("returns true when all clauses match via predicates", () => {
+    const out = matchesClauses(
+      task,
+      [{ key: "status", value: "blocked" }],
+      { status: (t, v) => t.status === v }
+    );
+    expect(out).toBe(true);
+  });
+
+  it("returns false when any clause fails", () => {
+    const out = matchesClauses(
+      task,
+      [
+        { key: "status", value: "blocked" },
+        { key: "priority", value: "low" },
+      ],
+      {
+        status: (t, v) => t.status === v,
+        priority: (t, v) => t.priority === v,
+      }
+    );
+    expect(out).toBe(false);
+  });
+
+  it("silently skips unknown keys (does not fail the match)", () => {
+    const out = matchesClauses(
+      task,
+      [
+        { key: "status", value: "blocked" },
+        { key: "totally-unknown", value: "xyz" },
+      ],
+      { status: (t, v) => t.status === v }
+    );
+    expect(out).toBe(true);
+  });
+
+  it("normalizes key lookup to lowercase", () => {
+    const out = matchesClauses(
+      task,
+      [{ key: "Status", value: "blocked" }],
+      { status: (t, v) => t.status === v }
+    );
+    expect(out).toBe(true);
+  });
+});

package/src/lib/filters/parse.ts

@@ -0,0 +1,86 @@
+/**
+ * `#key:value` filter namespace parser.
+ *
+ * Pure function that extracts filter clauses from free-text input and returns
+ * the non-filter remainder as `rawQuery`. Designed to be reused across chat
+ * popovers (entity filtering) and list pages (URL state, FilterBar input).
+ *
+ * Syntax (v2):
+ *   - `#key:value` — single clause. Keys are `[A-Za-z][\w-]*`, values are
+ *     double-quoted strings `"..."` (may contain spaces or `#`) OR a whitespace/`#`-terminated bare run.
+ *   - Multiple clauses may chain: `#status:blocked #priority:high` → two clauses.
+ *   - Clauses may appear anywhere in the input; everything else becomes rawQuery.
+ *   - Unknown keys pass through unchanged — the consumer decides what to do.
+ *   - Tokens like `#123` (no colon) are treated as raw-query text, not clauses.
+ *
+ * Design notes:
+ *   - AND-only. NOT/OR deferred to v2.
+ *   - Case of keys is preserved; consumer normalizes if needed. Values are
+ *     preserved verbatim (including case) — status codes are commonly lowercase.
+ *   - rawQuery whitespace is collapsed to single spaces and trimmed so callers
+ *     can feed it directly to a search input without extra cleanup.
+ */
+
+export interface FilterClause {
+  key: string;
+  value: string;
+}
+
+export interface ParsedFilterInput {
+  clauses: FilterClause[];
+  rawQuery: string;
+}
+
+// Clause pattern: `#<key>:<value>`. Key must start with a letter to avoid
+// eating `#123` hash references. Value may be either:
+//   - a double-quoted run of any non-quote chars: `"..."`  (captured in group 2)
+//   - OR an unquoted whitespace/`#`-terminated run   (captured in group 3)
+// Exactly one of group 2 / group 3 will be defined per match.
+const CLAUSE_PATTERN = /#([A-Za-z][\w-]*):(?:"([^"]*)"|([^\s#]+))/g;
+
+export function parseFilterInput(input: string): ParsedFilterInput {
+  if (!input) return { clauses: [], rawQuery: "" };
+
+  const clauses: FilterClause[] = [];
+  let rawQuery = input;
+
+  // Replace each match with a single space to preserve word boundaries, then
+  // collapse whitespace. This is simpler than maintaining offsets and survives
+  // back-to-back clauses like `#a:1#b:2` (which we don't officially support
+  // but shouldn't crash on — the regex with `g` flag matches both).
+  rawQuery = rawQuery.replace(
+    CLAUSE_PATTERN,
+    (_match, key: string, quoted: string | undefined, bare: string | undefined) => {
+      const value = quoted !== undefined ? quoted : bare ?? "";
+      clauses.push({ key, value });
+      return " ";
+    }
+  );
+
+  rawQuery = rawQuery.replace(/\s+/g, " ").trim();
+
+  return { clauses, rawQuery };
+}
+
+/**
+ * Evaluate an object against a list of clauses using a caller-supplied
+ * predicate per key. Returns true if ALL clauses match (AND semantics) or
+ * the clauses list is empty.
+ *
+ * `predicates` maps known filter keys to value-checkers. Unknown keys are
+ * silently skipped (not considered a mismatch) so callers can layer their
+ * own matching logic without breaking on typos.
+ */
+export function matchesClauses<T>(
+  item: T,
+  clauses: FilterClause[],
+  predicates: Record<string, (item: T, value: string) => boolean>
+): boolean {
+  if (clauses.length === 0) return true;
+  for (const clause of clauses) {
+    const predicate = predicates[clause.key.toLowerCase()];
+    if (!predicate) continue; // unknown key → skip, per spec
+    if (!predicate(item, clause.value)) return false;
+  }
+  return true;
+}

package/src/lib/instance/__tests__/detect.test.ts

@@ -83,7 +83,7 @@ describe("isPrivateInstance", () => {
   });
 
   it("returns true when STAGENT_DATA_DIR is a custom path", async () => {
-    vi.stubEnv("STAGENT_DATA_DIR", "/Users/navam/.stagent-wealth");
+    vi.stubEnv("STAGENT_DATA_DIR", "/Users/manavsehgal/.stagent-wealth");
     const { isPrivateInstance } = await loadDetect();
     expect(isPrivateInstance()).toBe(true);
   });

package/src/lib/instance/__tests__/upgrade-poller.test.ts

@@ -76,6 +76,56 @@ describe("tick", () => {
     expect(getUpgradeState().pollFailureCount).toBe(3);
   });
 
+  it("inserts one failure notification after 3 consecutive failures, dedupes on the 4th, clears on success", async () => {
+    const { tick } = await import("../upgrade-poller");
+    const { db } = await import("@/lib/db");
+    const { notifications } = await import("@/lib/db/schema");
+    const { eq, and, isNull } = await import("drizzle-orm");
+
+    // 2 failures: no notification yet
+    await tick(tempDir);
+    await tick(tempDir);
+    let open = await db
+      .select()
+      .from(notifications)
+      .where(and(eq(notifications.toolName, "upgrade_check_failing"), isNull(notifications.respondedAt)));
+    expect(open).toHaveLength(0);
+
+    // 3rd failure: notification created
+    await tick(tempDir);
+    open = await db
+      .select()
+      .from(notifications)
+      .where(and(eq(notifications.toolName, "upgrade_check_failing"), isNull(notifications.respondedAt)));
+    expect(open).toHaveLength(1);
+    expect(open[0].title).toBe("Upgrade check failing");
+    expect(open[0].body).toContain("Last 3 upgrade checks failed");
+
+    // 4th failure: still exactly one open notification (deduped)
+    await tick(tempDir);
+    open = await db
+      .select()
+      .from(notifications)
+      .where(and(eq(notifications.toolName, "upgrade_check_failing"), isNull(notifications.respondedAt)));
+    expect(open).toHaveLength(1);
+
+    // Success clears the notification
+    const bareDir = mkdtempSync(join(tmpdir(), "stagent-bare-"));
+    try {
+      runGit(["init", "--bare", "-b", "main"], bareDir);
+      runGit(["remote", "add", "origin", bareDir], tempDir);
+      runGit(["push", "origin", "main"], tempDir);
+      await tick(tempDir);
+      open = await db
+        .select()
+        .from(notifications)
+        .where(and(eq(notifications.toolName, "upgrade_check_failing"), isNull(notifications.respondedAt)));
+      expect(open).toHaveLength(0);
+    } finally {
+      rmSync(bareDir, { recursive: true, force: true });
+    }
+  });
+
   it("successfully updates state with zero commitsBehind when local == origin/main", async () => {
     // Set up a local 'origin' remote pointing to a bare copy of the same repo
     const bareDir = mkdtempSync(join(tmpdir(), "stagent-bare-"));

package/src/lib/instance/fingerprint.ts

@@ -2,24 +2,22 @@
  * Machine fingerprint generator.
  *
  * Produces a stable, non-identifying hash that uniquely identifies the machine
- * this stagent instance is running on. Used by the cloud license validator to
- * meter seats per machine per the hybrid licensing model (TDR-030): local
- * features are unlimited, cloud features count seats using
- * (email, machineFingerprint, instanceId) tuples.
+ * this stagent instance is running on. Used to give each stagent instance a
+ * durable identity (e.g., for telemetry correlation and multi-instance
+ * disambiguation); no billing or cloud-metering dependency.
  *
  * The fingerprint is derived from:
  *   1. os.hostname() — e.g., "macbook-pro.local"
- *   2. os.userInfo().username — e.g., "navam"
+ *   2. os.userInfo().username — e.g., "manavsehgal"
  *   3. SHA-256 of the first non-internal MAC address
  *
- * The MAC is hashed before it leaves the process so the network identifier
- * never appears in logs, telemetry, or cloud payloads. The combined inputs
- * are SHA-256'd together to produce a 64-character hex string.
+ * The MAC is hashed before it leaves the process so the raw network identifier
+ * never appears in logs or telemetry. The combined inputs are SHA-256'd
+ * together to produce a 64-character hex string.
  *
  * Stability: the fingerprint is stable across reboots and stagent restarts
  * on the same machine. It changes if the user renames their account, renames
- * their machine, or swaps network hardware. Machine fingerprint migration
- * policy (e.g., 7-day grace) is handled server-side by the edge function.
+ * their machine, or swaps network hardware.
  */
 
 import { createHash } from "crypto";

package/src/lib/instance/upgrade-poller.ts

@@ -10,6 +10,9 @@
 
 import { existsSync, mkdirSync, writeFileSync, unlinkSync, statSync } from "fs";
 import { join } from "path";
+import { and, eq, isNull } from "drizzle-orm";
+import { db } from "@/lib/db";
+import { notifications } from "@/lib/db/schema";
 import { isDevMode, hasGitDir } from "./detect";
 import { createGitOps } from "./git-ops";
 import { getUpgradeState, setUpgradeState } from "./settings";
@@ -17,6 +20,9 @@ import { getUpgradeState, setUpgradeState } from "./settings";
 const POLL_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 const LOCK_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const LOCK_FILENAME = ".stagent-upgrade-check.lock";
+const FAILURE_THRESHOLD = 3;
+// Sentinel value in notifications.toolName so we can dedupe / clear the banner.
+const FAILURE_MARKER = "upgrade_check_failing";
 
 let intervalHandle: ReturnType<typeof setInterval> | null = null;
 let ticking = false;
@@ -69,12 +75,16 @@ export async function tick(cwd: string = process.cwd()): Promise<UpgradeTickResu
         git.fetchOrigin();
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
+        const nextFailureCount = current.pollFailureCount + 1;
         await setUpgradeState({
           ...current,
           lastPolledAt: Math.floor(Date.now() / 1000),
-          pollFailureCount: current.pollFailureCount + 1,
+          pollFailureCount: nextFailureCount,
           lastPollError: message,
         });
+        if (nextFailureCount >= FAILURE_THRESHOLD) {
+          await ensureFailureNotification(nextFailureCount, message);
+        }
         return { skipped: "fetch_failed", error: message };
       }
 
@@ -94,6 +104,9 @@ export async function tick(cwd: string = process.cwd()): Promise<UpgradeTickResu
         lastPollError: null,
       };
       await setUpgradeState(newState);
+      if (current.pollFailureCount >= FAILURE_THRESHOLD) {
+        await clearFailureNotification();
+      }
       return { updated: newState };
     } finally {
       releaseLock(lockPath);
@@ -151,3 +164,42 @@ function releaseLock(lockPath: string): void {
     /* ignore */
   }
 }
+
+/**
+ * Insert a persistent "Upgrade check failing" notification, at most one at a time.
+ * Dedup key: `notifications.toolName = FAILURE_MARKER` with no response set.
+ */
+async function ensureFailureNotification(failureCount: number, error: string): Promise<void> {
+  try {
+    const existing = await db
+      .select({ id: notifications.id })
+      .from(notifications)
+      .where(and(eq(notifications.toolName, FAILURE_MARKER), isNull(notifications.respondedAt)))
+      .limit(1);
+    if (existing.length > 0) return;
+
+    await db.insert(notifications).values({
+      id: crypto.randomUUID(),
+      type: "agent_message",
+      title: "Upgrade check failing",
+      body: `Last ${failureCount} upgrade checks failed: ${error.slice(0, 400)}. Open Settings → Instance to retry.`,
+      toolName: FAILURE_MARKER,
+      read: false,
+      createdAt: new Date(),
+    });
+  } catch (err) {
+    console.error("[upgrade-poller] failed to insert failure notification:", err);
+  }
+}
+
+/** Mark any open failure notification as responded so the inbox clears it. */
+async function clearFailureNotification(): Promise<void> {
+  try {
+    await db
+      .update(notifications)
+      .set({ respondedAt: new Date(), read: true })
+      .where(and(eq(notifications.toolName, FAILURE_MARKER), isNull(notifications.respondedAt)));
+  } catch (err) {
+    console.error("[upgrade-poller] failed to clear failure notification:", err);
+  }
+}

package/src/lib/schedules/scheduler.ts

@@ -16,7 +16,7 @@ import { schedules, tasks, agentLogs, scheduleDocumentInputs, documents, workflo
 import { eq, and, lte, inArray, sql, asc, isNotNull } from "drizzle-orm";
 import { resumeWorkflow } from "@/lib/workflows/engine";
 import { computeNextFireTime } from "./interval-parser";
-import { executeTaskWithRuntime } from "@/lib/agents/runtime";
+import { startTaskExecution } from "@/lib/agents/task-dispatch";
 import { getSetting } from "@/lib/settings/helpers";
 import { SETTINGS_KEYS } from "@/lib/constants/settings";
 import { checkActiveHours } from "./active-hours";
@@ -92,7 +92,7 @@ export async function drainQueue(): Promise<void> {
 
       console.log(`[scheduler] draining queue → running task ${nextQueued.id}`);
       try {
-        await executeTaskWithRuntime(nextQueued.id);
+        await startTaskExecution(nextQueued.id);
       } catch (err) {
         console.error(`[scheduler] drain task ${nextQueued.id} failed:`, err);
       }
@@ -600,7 +600,7 @@ async function fireSchedule(
   // poll loop must keep claiming other due schedules), but on completion we
   // record metrics and trigger drainQueue() so any tasks queued by colliding
   // schedules execute immediately instead of waiting for the next poll.
-  executeTaskWithRuntime(taskId)
+  startTaskExecution(taskId)
     .catch((err) => {
       console.error(
         `[scheduler] task execution failed for schedule ${schedule.id}, task ${taskId}:`,
@@ -750,7 +750,7 @@ async function fireHeartbeat(
 
   // 5. Execute and wait for result (with timeout)
   try {
-    await executeTaskWithRuntime(evalTaskId);
+    await startTaskExecution(evalTaskId);
   } catch (err) {
     console.error(`[scheduler] heartbeat evaluation failed for "${schedule.name}":`, err);
   }

package/src/lib/utils/stagent-paths.ts

@@ -52,3 +52,7 @@ export function getStagentCodexConfigPath(): string {
 export function getStagentCodexAuthPath(): string {
   return join(getStagentCodexDir(), "auth.json");
 }
+
+export function getStagentProfilesDir(): string {
+  return join(getStagentDataDir(), "profiles");
+}

package/src/lib/workflows/blueprints/__tests__/render-prompt.test.ts

@@ -0,0 +1,124 @@
+import { describe, it, expect } from "vitest";
+import {
+  renderBlueprintPrompt,
+  UnresolvedTokenError,
+} from "../render-prompt";
+import type { WorkflowBlueprint } from "../types";
+
+function makeBlueprint(
+  overrides: Partial<WorkflowBlueprint> = {}
+): WorkflowBlueprint {
+  return {
+    id: "test-bp",
+    name: "Test Blueprint",
+    description: "A blueprint for tests",
+    version: "1.0.0",
+    domain: "work",
+    tags: [],
+    pattern: "sequence",
+    variables: [],
+    steps: [],
+    ...overrides,
+  };
+}
+
+describe("renderBlueprintPrompt", () => {
+  it("uses chatPrompt when present", () => {
+    const bp = makeBlueprint({
+      chatPrompt: "Research {{topic}} for {{timeframe}}.",
+      steps: [
+        { name: "s1", promptTemplate: "fallback should not be used", requiresApproval: false },
+      ],
+    });
+    const out = renderBlueprintPrompt(bp, { topic: "AI agents", timeframe: "2026" });
+    expect(out.firstMessage).toBe("Research AI agents for 2026.");
+  });
+
+  it("falls back to steps[0].promptTemplate when chatPrompt absent", () => {
+    const bp = makeBlueprint({
+      steps: [
+        {
+          name: "s1",
+          promptTemplate: "Summarize {{topic}} in ≤500 words.",
+          requiresApproval: false,
+        },
+      ],
+    });
+    const out = renderBlueprintPrompt(bp, { topic: "browser agents" });
+    expect(out.firstMessage).toBe("Summarize browser agents in ≤500 words.");
+  });
+
+  it("renders title with variable substitution", () => {
+    const bp = makeBlueprint({
+      name: "Research {{topic}}",
+      chatPrompt: "go",
+    });
+    const out = renderBlueprintPrompt(bp, { topic: "SSE streams" });
+    expect(out.title).toBe("Research SSE streams");
+  });
+
+  it("returns empty firstMessage when no chatPrompt and no steps", () => {
+    const bp = makeBlueprint({ steps: [] });
+    const out = renderBlueprintPrompt(bp, {});
+    expect(out.firstMessage).toBe("");
+    expect(out.title).toBe("Test Blueprint");
+  });
+
+  it("substitutes missing optional variables with empty string (non-strict)", () => {
+    const bp = makeBlueprint({
+      chatPrompt: "Topic: {{topic}}. Scope: {{scope}}.",
+    });
+    const out = renderBlueprintPrompt(bp, { topic: "rate limits" });
+    expect(out.firstMessage).toBe("Topic: rate limits. Scope: .");
+  });
+
+  it("handles {{#if}} conditional blocks", () => {
+    const bp = makeBlueprint({
+      chatPrompt:
+        "Base prompt.{{#if extra}}\n\nExtra: {{extra}}{{/if}}",
+    });
+    const withExtra = renderBlueprintPrompt(bp, { extra: "deep dive" });
+    expect(withExtra.firstMessage).toBe("Base prompt.\n\nExtra: deep dive");
+
+    const withoutExtra = renderBlueprintPrompt(bp, {});
+    expect(withoutExtra.firstMessage).toBe("Base prompt.");
+  });
+
+  it("throws UnresolvedTokenError in strict mode when token is missing", () => {
+    const bp = makeBlueprint({
+      chatPrompt: "Hello {{name}}, today is {{date}}.",
+    });
+    expect(() =>
+      renderBlueprintPrompt(bp, { name: "Ada" }, { strict: true })
+    ).toThrow(UnresolvedTokenError);
+
+    try {
+      renderBlueprintPrompt(bp, { name: "Ada" }, { strict: true });
+    } catch (err) {
+      expect(err).toBeInstanceOf(UnresolvedTokenError);
+      expect((err as UnresolvedTokenError).tokens).toEqual(["date"]);
+    }
+  });
+
+  it("does not throw in strict mode when all tokens resolve", () => {
+    const bp = makeBlueprint({
+      chatPrompt: "Hello {{name}}.",
+    });
+    const out = renderBlueprintPrompt(
+      bp,
+      { name: "Ada" },
+      { strict: true }
+    );
+    expect(out.firstMessage).toBe("Hello Ada.");
+  });
+
+  it("strict mode treats empty-string values as resolved (not unresolved)", () => {
+    // Empty string is a resolved-to-empty substitution, distinct from an
+    // undefined variable which leaves {{token}} in the output string.
+    const bp = makeBlueprint({
+      chatPrompt: "Name: [{{name}}]",
+    });
+    const out = renderBlueprintPrompt(bp, { name: "" }, { strict: true });
+    expect(out.firstMessage).toBe("Name: []");
+  });
+});

package/src/lib/workflows/blueprints/render-prompt.ts

@@ -0,0 +1,71 @@
+/**
+ * Render a blueprint into a chat-ready first message.
+ *
+ * Pure template substitution over `blueprint.chatPrompt` with fallback to
+ * `blueprint.steps[0].promptTemplate` for the 13 existing built-ins that
+ * predate the `chatPrompt` field. Variable resolution is shared with the
+ * workflow engine via `resolveTemplate` so behavior stays consistent.
+ */
+
+import type { WorkflowBlueprint } from "./types";
+import { resolveTemplate } from "./template";
+
+export interface RenderedBlueprintPrompt {
+  /** The seed message to pre-fill into the chat composer. */
+  firstMessage: string;
+  /** The conversation title, with variable substitution applied. */
+  title: string;
+}
+
+export interface RenderBlueprintPromptOptions {
+  /**
+   * Throw if any `{{token}}` references an undefined variable. Defaults to
+   * false — the underlying `resolveTemplate` substitutes undefined values with
+   * empty strings, which is the right behavior for optional blueprint vars.
+   * Set to `true` to validate that all referenced tokens were resolved.
+   */
+  strict?: boolean;
+}
+
+export class UnresolvedTokenError extends Error {
+  constructor(public readonly tokens: string[]) {
+    super(`Unresolved template tokens: ${tokens.join(", ")}`);
+    this.name = "UnresolvedTokenError";
+  }
+}
+
+/**
+ * Render a blueprint's chat prompt and title with the provided parameters.
+ *
+ * Falls back to `steps[0].promptTemplate` if `chatPrompt` is absent. If the
+ * blueprint has no steps and no `chatPrompt`, returns an empty first message
+ * (the picker UI is expected to validate this case upstream).
+ */
+export function renderBlueprintPrompt(
+  blueprint: WorkflowBlueprint,
+  params: Record<string, unknown>,
+  options: RenderBlueprintPromptOptions = {}
+): RenderedBlueprintPrompt {
+  const source =
+    blueprint.chatPrompt ?? blueprint.steps[0]?.promptTemplate ?? "";
+
+  if (options.strict) {
+    // Collect {{token}} names from the source (before resolveTemplate
+    // substitutes undefined with empty string). Skip `#if`/`/if` directives.
+    const unresolved = new Set<string>();
+    for (const combined of [source, blueprint.name]) {
+      const matches = combined.matchAll(/\{\{(\w+)\}\}/g);
+      for (const m of matches) {
+        if (!(m[1] in params)) unresolved.add(m[1]);
+      }
+    }
+    if (unresolved.size > 0) {
+      throw new UnresolvedTokenError([...unresolved]);
+    }
+  }
+
+  const firstMessage = resolveTemplate(source, params);
+  const title = resolveTemplate(blueprint.name, params);
+
+  return { firstMessage, title };
+}

package/src/lib/workflows/blueprints/types.ts

@@ -43,4 +43,10 @@ export interface WorkflowBlueprint {
   estimatedDuration?: string;
   difficulty?: "beginner" | "intermediate" | "advanced";
   isBuiltin?: boolean;
+  /**
+   * Optional chat-composer seed prompt. When present, `chat-conversation-templates`
+   * renders this (with variable substitution) into the first user message of a
+   * new conversation. When absent, consumers fall back to `steps[0].promptTemplate`.
+   */
+  chatPrompt?: string;
 }