@vellumai/assistant 0.9.0 → 0.10.0-staging.2

package/src/runtime/routes/workflow-routes.test.ts

@@ -1,7 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
-import type { AssistantConfig } from "../../config/schema.js";
-import type { WorkflowRun } from "../../workflows/journal-store.js";
+import type {
+  WorkflowJournalEntry,
+  WorkflowRun,
+} from "../../workflows/journal-store.js";
 import type { SavedWorkflowEntry } from "../../workflows/library.js";
 import {
   WorkflowResumeNotPossibleError,
@@ -59,14 +61,31 @@ interface FakeManager {
   resume: (id: string) => { runId: string };
 }
 
+function makeJournalEntry(
+  overrides: Partial<WorkflowJournalEntry> = {},
+): WorkflowJournalEntry {
+  return {
+    runId: "run-1",
+    seq: 0,
+    callHash: "call-0",
+    kind: "agent",
+    request: null,
+    result: null,
+    status: "completed",
+    createdAt: 1000,
+    ...overrides,
+  };
+}
+
 function setup(opts: {
-  flagEnabled?: boolean;
   runs?: WorkflowRun[];
   saved?: SavedWorkflowEntry[];
   /** Custom resume impl; defaults to a success that records the id. */
   resume?: (id: string) => { runId: string };
   /** Resolved auto-approve threshold for the resume posture gate. */
   threshold?: "none" | "low" | "medium" | "high";
+  /** Journal entries returned by getJournal, keyed by run id. */
+  journal?: Record<string, WorkflowJournalEntry[]>;
 }): {
   aborted: string[];
   resumed: string[];
@@ -98,9 +117,8 @@ function setup(opts: {
   __setWorkflowRoutesDeps({
     getManager: () => manager,
     listWorkflows: () => opts.saved ?? [],
-    getConfig: () => ({}) as AssistantConfig,
-    isFlagEnabled: () => opts.flagEnabled ?? true,
     getAutoApproveThreshold: async () => opts.threshold ?? "none",
+    getJournal: (runId) => opts.journal?.[runId] ?? [],
   });
   return { aborted, resumed, listCalls };
 }
@@ -113,10 +131,9 @@ afterEach(() => {
 // Happy paths
 // ---------------------------------------------------------------------------
 
-describe("workflow routes (flag on)", () => {
+describe("workflow routes (happy paths)", () => {
   beforeEach(() => {
     setup({
-      flagEnabled: true,
       runs: [
         makeRun({ id: "run-1" }),
         makeRun({ id: "run-2", status: "completed" }),
@@ -145,7 +162,6 @@ describe("workflow routes (flag on)", () => {
 
   test("listWorkflowRuns honors limit + status query params", async () => {
     const { listCalls } = setup({
-      flagEnabled: true,
       runs: [makeRun({ id: "run-1", status: "completed" })],
     });
     await route("listWorkflowRuns").handler({
@@ -163,7 +179,6 @@ describe("workflow routes (flag on)", () => {
 
   test("abortWorkflowRun aborts a known run", async () => {
     const { aborted } = setup({
-      flagEnabled: true,
       runs: [makeRun({ id: "run-1" })],
     });
     const result = (await route("abortWorkflowRun").handler({
@@ -175,7 +190,6 @@ describe("workflow routes (flag on)", () => {
 
   test("resumeWorkflowRun resumes an interrupted run", async () => {
     const { resumed } = setup({
-      flagEnabled: true,
       runs: [makeRun({ id: "run-1", status: "interrupted" })],
     });
     const result = (await route("resumeWorkflowRun").handler({
@@ -192,7 +206,6 @@ describe("workflow routes (flag on)", () => {
     // full-access posture it must refuse rather than silently bypass consent —
     // resume() is never called.
     const { resumed } = setup({
-      flagEnabled: true,
       threshold: "medium",
       runs: [
         makeRun({
@@ -213,7 +226,6 @@ describe("workflow routes (flag on)", () => {
     // high-risk tools, so no prompt is needed — the side-effecting resume
     // proceeds directly.
     const { resumed } = setup({
-      flagEnabled: true,
       threshold: "high",
       runs: [
         makeRun({
@@ -236,7 +248,6 @@ describe("workflow routes (flag on)", () => {
     // the object shape too — a strict parse would treat it as read-only and let
     // the side-effecting resume through without approval.
     const { resumed } = setup({
-      flagEnabled: true,
       threshold: "medium",
       runs: [
         makeRun({
@@ -259,7 +270,6 @@ describe("workflow routes (flag on)", () => {
     // An explicit empty manifest grants no side effects, so the route resumes
     // it directly — the gate keys on the stored manifest, not run existence.
     const { resumed } = setup({
-      flagEnabled: true,
       threshold: "medium",
       runs: [
         makeRun({
@@ -275,7 +285,6 @@ describe("workflow routes (flag on)", () => {
 
   test("resumeWorkflowRun maps a non-interrupted run to a 409 ConflictError", async () => {
     setup({
-      flagEnabled: true,
       runs: [makeRun({ id: "run-1", status: "completed" })],
       resume: (id) => {
         throw new WorkflowResumeNotPossibleError(
@@ -292,7 +301,6 @@ describe("workflow routes (flag on)", () => {
 
   test("resumeWorkflowRun maps a cap error to a 429 TooManyRequestsError", async () => {
     setup({
-      flagEnabled: true,
       runs: [makeRun({ id: "run-1", status: "interrupted" })],
       resume: () => {
         throw new WorkflowRunCapError(3);
@@ -317,20 +325,222 @@ describe("workflow routes (flag on)", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Journal projection
+// ---------------------------------------------------------------------------
+
+interface WireLeaf {
+  seq: number;
+  kind: string;
+  label?: string;
+  phase?: string;
+  promptSummary?: string;
+  status: string;
+  resultSummary?: string;
+  inputTokens?: number;
+  outputTokens?: number;
+  createdAt: number | null;
+}
+
+interface WireJournal {
+  runId: string;
+  status: string;
+  agentsSpawned: number;
+  inputTokens: number;
+  outputTokens: number;
+  leaves: WireLeaf[];
+}
+
+describe("getWorkflowRunJournal", () => {
+  test("projects agent leaves with label/phase/promptSummary/resultSummary extracted", async () => {
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            kind: "agent",
+            request: {
+              prompt: "Investigate the failing build",
+              opts: { label: "investigate", phase: "triage" },
+            },
+            result: { summary: "found the flaky test" },
+            status: "completed",
+            inputTokens: 120,
+            outputTokens: 45,
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    expect(result.runId).toBe("run-1");
+    expect(result.status).toBe("running");
+    expect(result.agentsSpawned).toBe(2);
+    expect(result.leaves.map((l) => l.seq)).toEqual([0]);
+
+    const first = result.leaves[0];
+    expect(first.kind).toBe("agent");
+    expect(first.label).toBe("investigate");
+    expect(first.phase).toBe("triage");
+    expect(first.promptSummary).toBe("Investigate the failing build");
+    expect(first.resultSummary).toContain("found the flaky test");
+    // Per-leaf token usage is projected onto the wire leaf.
+    expect(first.inputTokens).toBe(120);
+    expect(first.outputTokens).toBe(45);
+    // The bulky raw request/result payloads are dropped.
+    expect(first).not.toHaveProperty("request");
+    expect(first).not.toHaveProperty("result");
+  });
+
+  test("omits per-leaf token fields when the journal entry carries none", async () => {
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            kind: "agent",
+            request: { prompt: "no tokens recorded", opts: {} },
+            status: "completed",
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    const leaf = result.leaves[0];
+    expect(leaf).not.toHaveProperty("inputTokens");
+    expect(leaf).not.toHaveProperty("outputTokens");
+  });
+
+  test("excludes kind:workflow entries so the backfill matches the live agent-only stream", async () => {
+    // The live `workflow_leaf_*` stream is emitted only for agent leaves; nested
+    // `workflow(name)` resolutions never reach it. The journal route must filter
+    // to agent leaves too, or a nested-workflow run renders a phantom unlabeled
+    // node on backfill and a different leaf set than live.
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            kind: "agent",
+            request: { prompt: "first agent", opts: { label: "first" } },
+            status: "completed",
+          }),
+          makeJournalEntry({
+            seq: 1,
+            kind: "workflow",
+            request: { name: "child", args: { foo: 1 } },
+            result: "child done",
+            status: "completed",
+          }),
+          makeJournalEntry({
+            seq: 2,
+            kind: "agent",
+            request: { prompt: "second agent", opts: { label: "second" } },
+            status: "completed",
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    // Only the agent leaves survive, in seq order; the workflow-kind entry (seq
+    // 1) is dropped entirely.
+    expect(result.leaves.map((l) => l.seq)).toEqual([0, 2]);
+    expect(result.leaves.every((l) => l.kind === "agent")).toBe(true);
+    expect(result.leaves.map((l) => l.label)).toEqual(["first", "second"]);
+  });
+
+  test("surfaces a failed leaf's { error } result as resultSummary", async () => {
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            status: "failed",
+            request: { prompt: "do the thing", opts: {} },
+            result: { error: "agent crashed: out of tokens" },
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    expect(result.leaves[0].status).toBe("failed");
+    expect(result.leaves[0].resultSummary).toContain(
+      "agent crashed: out of tokens",
+    );
+  });
+
+  test("truncates a long prompt/result to ~200 chars", async () => {
+    const longPrompt = "x".repeat(500);
+    const longResult = "y".repeat(500);
+    setup({
+      runs: [makeRun({ id: "run-1" })],
+      journal: {
+        "run-1": [
+          makeJournalEntry({
+            seq: 0,
+            request: { prompt: longPrompt, opts: {} },
+            result: longResult,
+          }),
+        ],
+      },
+    });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+
+    const leaf = result.leaves[0];
+    expect(leaf.promptSummary!.length).toBeLessThanOrEqual(201);
+    expect(leaf.promptSummary!.startsWith("x")).toBe(true);
+    // A truncated summary ends with the ellipsis marker.
+    expect(leaf.promptSummary!.endsWith("…")).toBe(true);
+    expect(leaf.resultSummary!.length).toBeLessThanOrEqual(201);
+  });
+
+  test("returns an empty leaf list for a run with no journal entries", async () => {
+    setup({ runs: [makeRun({ id: "run-1" })] });
+    const result = (await route("getWorkflowRunJournal").handler({
+      pathParams: { id: "run-1" },
+    })) as WireJournal;
+    expect(result.leaves).toEqual([]);
+  });
+
+  test("throws NotFoundError for an unknown id", () => {
+    setup({ runs: [] });
+    expect(() =>
+      route("getWorkflowRunJournal").handler({ pathParams: { id: "nope" } }),
+    ).toThrow(NotFoundError);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Unknown run → 404
 // ---------------------------------------------------------------------------
 
 describe("workflow routes (unknown run)", () => {
   test("getWorkflowRun throws NotFoundError for an unknown id", () => {
-    setup({ flagEnabled: true, runs: [] });
+    setup({ runs: [] });
     expect(() =>
       route("getWorkflowRun").handler({ pathParams: { id: "nope" } }),
     ).toThrow(NotFoundError);
   });
 
   test("abortWorkflowRun throws NotFoundError for an unknown id", () => {
-    const { aborted } = setup({ flagEnabled: true, runs: [] });
+    const { aborted } = setup({ runs: [] });
     expect(() =>
       route("abortWorkflowRun").handler({ pathParams: { id: "nope" } }),
     ).toThrow(NotFoundError);
@@ -338,35 +548,10 @@ describe("workflow routes (unknown run)", () => {
   });
 
   test("resumeWorkflowRun throws NotFoundError for an unknown id", async () => {
-    const { resumed } = setup({ flagEnabled: true, runs: [] });
+    const { resumed } = setup({ runs: [] });
     await expect(
       route("resumeWorkflowRun").handler({ pathParams: { id: "nope" } }),
     ).rejects.toThrow(NotFoundError);
     expect(resumed).toEqual([]);
   });
 });
-
-// ---------------------------------------------------------------------------
-// Flag off → every route 404s
-// ---------------------------------------------------------------------------
-
-describe("workflow routes (flag off)", () => {
-  beforeEach(() => {
-    setup({ flagEnabled: false, runs: [makeRun({ id: "run-1" })], saved: [] });
-  });
-
-  test.each([
-    ["listWorkflowRuns", { queryParams: {} }],
-    ["getWorkflowRun", { pathParams: { id: "run-1" } }],
-    ["abortWorkflowRun", { pathParams: { id: "run-1" } }],
-    ["listSavedWorkflows", {}],
-  ] as const)("%s throws NotFoundError when the flag is off", (op, args) => {
-    expect(() => route(op).handler(args)).toThrow(NotFoundError);
-  });
-
-  test("resumeWorkflowRun rejects with NotFoundError when the flag is off", async () => {
-    await expect(
-      route("resumeWorkflowRun").handler({ pathParams: { id: "run-1" } }),
-    ).rejects.toThrow(NotFoundError);
-  });
-});

package/src/runtime/routes/workflow-routes.ts

@@ -5,21 +5,18 @@
  * shared ROUTES array. They are read/abort surfaces over the workflow run
  * manager and the saved-workflow library — a human (via the `vellum workflows`
  * CLI or the app) can inspect runs and abort an in-flight one.
- *
- * Every handler is gated on the `workflows` feature flag: when it is off, the
- * routes behave as if they do not exist (404), so disabling the flag fully
- * hides the surface.
  */
 
 import { z } from "zod";
 
-import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
-import { getConfig } from "../../config/loader.js";
-import type { AssistantConfig } from "../../config/schema.js";
 import { getAutoApproveThreshold } from "../../permissions/gateway-threshold-reader.js";
 import { isFullAccessThreshold } from "../../permissions/threshold.js";
 import { manifestGrantsSideEffects } from "../../workflows/capabilities.js";
-import type { WorkflowRun } from "../../workflows/journal-store.js";
+import {
+  getJournal,
+  type WorkflowJournalEntry,
+  type WorkflowRun,
+} from "../../workflows/journal-store.js";
 import { listWorkflows } from "../../workflows/library.js";
 import {
   getWorkflowRunManager,
@@ -46,19 +43,16 @@ export interface WorkflowRoutesDeps {
     "list" | "status" | "abort" | "resume"
   >;
   listWorkflows: typeof listWorkflows;
-  getConfig: () => AssistantConfig;
-  isFlagEnabled: (config: AssistantConfig) => boolean;
   getAutoApproveThreshold: typeof getAutoApproveThreshold;
+  getJournal: typeof getJournal;
 }
 
 function defaultDeps(): WorkflowRoutesDeps {
   return {
     getManager: getWorkflowRunManager,
     listWorkflows,
-    getConfig,
-    isFlagEnabled: (config) =>
-      isAssistantFeatureFlagEnabled("workflows", config),
     getAutoApproveThreshold,
+    getJournal,
   };
 }
 
@@ -105,21 +99,33 @@ const savedWorkflowSchema = z.object({
   path: z.string(),
 });
 
+const workflowLeafSchema = z.object({
+  seq: z.number(),
+  kind: z.enum(["agent", "workflow"]),
+  label: z.string().optional(),
+  phase: z.string().optional(),
+  promptSummary: z.string().optional(),
+  status: z.string(),
+  resultSummary: z.string().optional(),
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  createdAt: z.number().nullable(),
+});
+
+const workflowJournalSchema = z.object({
+  runId: z.string(),
+  status: z.enum(VALID_RUN_STATUSES).optional(),
+  agentsSpawned: z.number().optional(),
+  inputTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  phase: z.string().optional(),
+  leaves: z.array(workflowLeafSchema),
+});
+
 // ---------------------------------------------------------------------------
 // Handlers (transport-agnostic)
 // ---------------------------------------------------------------------------
 
-/**
- * Throw a 404 when the `workflows` flag is off, hiding the whole surface. The
- * NotFoundError (rather than a 403) keeps a disabled-flag indistinguishable
- * from a route that does not exist.
- */
-function assertFlagEnabled(): void {
-  if (!deps.isFlagEnabled(deps.getConfig())) {
-    throw new NotFoundError("Workflows are not enabled.");
-  }
-}
-
 /**
  * The single compact-run wire contract, inferred from {@link workflowRunSchema}.
  * The HTTP routes return this shape; other producers (e.g. the CLI's client-side
@@ -145,6 +151,64 @@ export function toWireRun(run: WorkflowRun): WorkflowRunWire {
   };
 }
 
+/**
+ * Render an arbitrary journal value (prompt, result, `{ error }`) into a short
+ * single-string preview, truncating to `max` characters. Objects are
+ * JSON-stringified so a structured result still produces a readable summary.
+ */
+function summarize(value: unknown, max = 200): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  let text: string;
+  if (typeof value === "string") {
+    text = value;
+  } else {
+    try {
+      text = JSON.stringify(value);
+    } catch {
+      return undefined;
+    }
+  }
+  return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+
+/**
+ * Project a journal entry into the bounded leaf wire shape, dropping the bulky
+ * raw `request`/`result` payloads in favor of short summaries. The `request`
+ * and `result` columns are `unknown`, so read their fields defensively.
+ */
+export function toWireLeaf(
+  entry: WorkflowJournalEntry,
+): z.infer<typeof workflowLeafSchema> {
+  const request =
+    entry.request && typeof entry.request === "object"
+      ? (entry.request as Record<string, unknown>)
+      : undefined;
+  const opts =
+    request?.opts && typeof request.opts === "object"
+      ? (request.opts as Record<string, unknown>)
+      : undefined;
+  const label = typeof opts?.label === "string" ? opts.label : undefined;
+  const phase = typeof opts?.phase === "string" ? opts.phase : undefined;
+  const promptSummary = summarize(request?.prompt);
+  const resultSummary = summarize(entry.result);
+  return {
+    seq: entry.seq,
+    kind: entry.kind,
+    ...(label !== undefined ? { label } : {}),
+    ...(phase !== undefined ? { phase } : {}),
+    ...(promptSummary !== undefined ? { promptSummary } : {}),
+    status: entry.status,
+    ...(resultSummary !== undefined ? { resultSummary } : {}),
+    ...(entry.inputTokens !== undefined
+      ? { inputTokens: entry.inputTokens }
+      : {}),
+    ...(entry.outputTokens !== undefined
+      ? { outputTokens: entry.outputTokens }
+      : {}),
+    createdAt: entry.createdAt,
+  };
+}
+
 function parseLimit(raw: string | undefined): number | undefined {
   if (raw === undefined) return undefined;
   const n = Number(raw);
@@ -162,7 +226,6 @@ function parseStatus(
 }
 
 function handleListRuns(queryParams: Record<string, string>) {
-  assertFlagEnabled();
   const limit = parseLimit(queryParams.limit);
   const status = parseStatus(queryParams.status);
   const runs = deps.getManager().list({
@@ -173,7 +236,6 @@ function handleListRuns(queryParams: Record<string, string>) {
 }
 
 function handleGetRun(id: string) {
-  assertFlagEnabled();
   const run = deps.getManager().status(id);
   if (!run) {
     throw new NotFoundError(`Workflow run ${id} not found`);
@@ -181,8 +243,29 @@ function handleGetRun(id: string) {
   return toWireRun(run);
 }
 
+function handleGetRunJournal(id: string) {
+  const run = deps.getManager().status(id);
+  if (!run) {
+    throw new NotFoundError(`Workflow run ${id} not found`);
+  }
+  return {
+    runId: run.id,
+    status: run.status,
+    agentsSpawned: run.agentsSpawned,
+    inputTokens: run.inputTokens,
+    outputTokens: run.outputTokens,
+    // Only agent leaves; the live `workflow_leaf_*` stream is emitted solely for
+    // agent leaves (nested workflow resolutions never reach it), so the
+    // backfilled set must match. `kind: "workflow"` entries carry no label and
+    // would render as phantom unlabeled nodes.
+    leaves: deps
+      .getJournal(id)
+      .filter((entry) => entry.kind === "agent")
+      .map(toWireLeaf),
+  };
+}
+
 function handleAbortRun(id: string) {
-  assertFlagEnabled();
   // status() is the source of truth for existence; abort() itself is a no-op
   // for unknown/finished runs, so 404 on an unknown id is surfaced here.
   const manager = deps.getManager();
@@ -194,7 +277,6 @@ function handleAbortRun(id: string) {
 }
 
 async function handleResumeRun(id: string) {
-  assertFlagEnabled();
   const manager = deps.getManager();
   // status() is the source of truth for existence, so 404 an unknown id here
   // (matching abort) rather than letting resume's "not_found" reach the client
@@ -245,7 +327,6 @@ async function handleResumeRun(id: string) {
 }
 
 function handleListSavedWorkflows() {
-  assertFlagEnabled();
   return { workflows: deps.listWorkflows() };
 }
 
@@ -299,6 +380,27 @@ export const ROUTES: RouteDefinition[] = [
     additionalResponses: { "404": { description: "Run not found" } },
     handler: ({ pathParams }: RouteHandlerArgs) => handleGetRun(pathParams!.id),
   },
+  {
+    operationId: "getWorkflowRunJournal",
+    endpoint: "workflows/runs/:id/journal",
+    method: "GET",
+    // Unlike the run list/status routes (settings metadata), the journal returns
+    // per-leaf prompt/result summaries — conversation/work-product content — so it
+    // requires `chat.read`, matching the subagent-detail route (the analogous
+    // content surface), not the `settings.read` used by the management routes.
+    policy: {
+      requiredScopes: ["chat.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get workflow run journal",
+    description:
+      "Return a workflow run's leaf journal as bounded per-leaf summaries (one entry per finished leaf).",
+    tags: ["workflows"],
+    responseBody: workflowJournalSchema,
+    additionalResponses: { "404": { description: "Run not found" } },
+    handler: ({ pathParams }: RouteHandlerArgs) =>
+      handleGetRunJournal(pathParams!.id),
+  },
   {
     operationId: "abortWorkflowRun",
     endpoint: "workflows/runs/:id/abort",

package/src/runtime/routes/workspace-greetings.ts

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync } from "node:fs";
+
+import { getWorkspacePromptPath } from "../../util/platform.js";
+
+function readWorkspaceFile(name: string): string {
+  try {
+    const path = getWorkspacePromptPath(name);
+    if (!existsSync(path)) return "";
+    return readFileSync(path, "utf-8");
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Parse the `## Greetings` section from SOUL.md. Returns bullet items as an
+ * array of strings, or `null` if the section is missing or empty.
+ */
+export function parseGreetingsSection(content: string): string[] | null {
+  let inSection = false;
+  let sectionLevel: number | null = null;
+  const greetings: string[] = [];
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    const heading = /^(#{1,6})\s+(.+?)\s*#*$/.exec(trimmed);
+    if (heading) {
+      const level = heading[1]!.length;
+      const title = heading[2]!.trim();
+      if (inSection) {
+        if (sectionLevel !== null && level <= sectionLevel) break;
+        continue;
+      }
+      if (level === 2 && /^greetings$/i.test(title)) {
+        inSection = true;
+        sectionLevel = level;
+      }
+      continue;
+    }
+    if (!inSection) continue;
+    const bullet = /^(?:[-*+]\s+|\d+[.)]\s+)(.+)$/.exec(trimmed);
+    const greeting = bullet?.[1]?.trim();
+    if (greeting) {
+      greetings.push(greeting);
+    }
+  }
+
+  return greetings.length > 0 ? greetings : null;
+}
+
+export function readWorkspaceGreetings(): string[] | null {
+  const soulContent = readWorkspaceFile("SOUL.md");
+  if (!soulContent) return null;
+  return parseGreetingsSection(soulContent);
+}