@vellumai/assistant 0.7.1 → 0.7.3

package/src/permissions/prompter.ts

@@ -2,6 +2,7 @@ import { v4 as uuid } from "uuid";
 
 import { getConfig } from "../config/loader.js";
 import type { ServerMessage } from "../daemon/message-protocol.js";
+import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { redactSensitiveFields } from "../security/redaction.js";
 import type { ExecutionTarget } from "../tools/types.js";
 import { AssistantError, ErrorCode } from "../util/errors.js";
@@ -81,10 +82,36 @@ export class PermissionPrompter {
 
     const requestId = uuid();
 
+    // Self-register in pendingInteractions so /v1/confirm can route the
+    // response to this conversation without going through broadcastMessage.
+    if (conversationId) {
+      pendingInteractions.register(requestId, {
+        conversationId,
+        kind: "confirmation",
+        confirmationDetails: {
+          toolName,
+          input: redactSensitiveFields(input),
+          riskLevel,
+          executionTarget,
+          allowlistOptions: allowlistOptions.map((o) => ({
+            label: o.label,
+            description: o.description,
+            pattern: o.pattern,
+          })),
+          scopeOptions: scopeOptions.map((o) => ({
+            label: o.label,
+            scope: o.scope,
+          })),
+          persistentDecisionsAllowed: persistentDecisionsAllowed ?? true,
+        },
+      });
+    }
+
     return new Promise((resolve, reject) => {
       const timeoutMs = getConfig().timeouts.permissionTimeoutSec * 1000;
       const timer = setTimeout(() => {
         this.pending.delete(requestId);
+        pendingInteractions.resolve(requestId);
         log.warn(
           { requestId, toolName },
           "Permission prompt timed out, defaulting to deny",
@@ -109,6 +136,7 @@ export class PermissionPrompter {
           if (this.pending.has(requestId)) {
             clearTimeout(timer);
             this.pending.delete(requestId);
+            pendingInteractions.resolve(requestId);
             resolve({ decision: "deny", wasAbort: true });
           }
         };
@@ -174,6 +202,9 @@ export class PermissionPrompter {
     }
     clearTimeout(pending.timer);
     this.pending.delete(requestId);
+    // Idempotent — approval-routes already calls pendingInteractions.resolve()
+    // before routing here, but we call it defensively for non-route paths.
+    pendingInteractions.resolve(requestId);
     pending.resolve({
       decision,
       selectedPattern,
@@ -191,6 +222,7 @@ export class PermissionPrompter {
     for (const [requestId, pending] of this.pending) {
       clearTimeout(pending.timer);
       this.pending.delete(requestId);
+      pendingInteractions.resolve(requestId);
       pending.resolve({
         decision: "deny",
         wasSystemCancel: true,
@@ -205,8 +237,9 @@ export class PermissionPrompter {
   }
 
   dispose(): void {
-    for (const [, pending] of this.pending) {
+    for (const [requestId, pending] of this.pending) {
       clearTimeout(pending.timer);
+      pendingInteractions.resolve(requestId);
       pending.reject(
         new AssistantError("Prompter disposed", ErrorCode.INTERNAL_ERROR),
       );

package/src/permissions/secret-prompter.ts

@@ -81,8 +81,12 @@ export class SecretPrompter {
 
       this.pending.set(requestId, { resolve, reject, timer });
 
-      // pendingInteractions.register is now handled by broadcastMessage
-      // when the secret_request event is published to the hub.
+      // Self-register in pendingInteractions so /v1/secret can route the
+      // response to this conversation without relying on broadcastMessage.
+      pendingInteractions.register(requestId, {
+        conversationId: effectiveConversationId,
+        kind: "secret",
+      });
 
       const config = getConfig();
       const msg: SecretRequestMessage = {

package/src/plugins/defaults/injectors.ts

@@ -3,7 +3,7 @@
  * drives the per-turn injection sequence consumed by
  * `applyRuntimeInjections`.
  *
- * Each of the eight default injectors reads its per-turn inputs from
+ * Each default injector reads its per-turn inputs from
  * `ctx.injectionInputs` (see {@link TurnInjectionInputs}), runs its gating
  * conditions (injection mode, feature flags, channel type, null-input
  * short-circuits), and returns an {@link InjectionBlock} with a
@@ -12,6 +12,7 @@
  *
  * | name                     | order | placement               |
  * | ------------------------ | ----- | ----------------------- |
+ * | `disk-pressure-warning`  | 5     | prepend-user-tail       |
  * | `workspace-context`      | 10    | prepend-user-tail       |
  * | `unified-turn-context`   | 20    | prepend-user-tail       |
  * | `pkb-context`            | 30    | after-memory-prefix     |
@@ -45,6 +46,7 @@
 
 import { resolve } from "node:path";
 
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getConfig } from "../../config/loader.js";
 import { getInContextPkbPaths } from "../../daemon/pkb-context-tracker.js";
 import { buildPkbReminder } from "../../daemon/pkb-reminder-builder.js";
@@ -74,7 +76,7 @@ const PKB_HINT_THRESHOLD = 0.5;
 const PKB_HINT_ARCHIVE_THRESHOLD = 0.7;
 
 /**
- * Fixed order values for the eight default injectors. Exported so tests —
+ * Fixed order values for the default injectors. Exported so tests —
  * and any future integration code — can assert ordering without re-deriving
  * the constants.
  *
@@ -83,6 +85,7 @@ const PKB_HINT_ARCHIVE_THRESHOLD = 0.7;
  * without renumbering the defaults.
  */
 export const DEFAULT_INJECTOR_ORDER = {
+  diskPressureWarning: 5,
   workspaceContext: 10,
   unifiedTurnContext: 20,
   pkbContext: 30,
@@ -98,6 +101,35 @@ function readInjectionInputs(ctx: TurnContext): TurnInjectionInputs {
   return ctx.injectionInputs ?? {};
 }
 
+export const DISK_PRESSURE_WARNING_PROMPT = `<disk_pressure_warning>
+Disk usage is critically low: this assistant is in storage cleanup mode because the workspace volume is at least 95% full.
+
+In your first paragraph, warn the user that storage is critically low and that normal work is suspended until space is freed.
+
+Then help the user clean up storage. Prefer safe inspection steps first, such as checking available space and finding large directories. Ask before deleting files or caches unless the user has already clearly approved the specific cleanup action.
+
+Do not work on unrelated tasks until disk usage drops below the critical threshold or the user explicitly overrides the lock. Background processes and messages from trusted contacts are blocked while this cleanup mode is active.
+</disk_pressure_warning>`;
+
+function isSafeStorageLimitsEnabled(): boolean {
+  return isAssistantFeatureFlagEnabled("safe-storage-limits", getConfig());
+}
+
+const diskPressureWarningInjector: Injector = {
+  name: "disk-pressure-warning",
+  order: DEFAULT_INJECTOR_ORDER.diskPressureWarning,
+  async produce(ctx: TurnContext): Promise<InjectionBlock | null> {
+    if (!isSafeStorageLimitsEnabled()) return null;
+    const inputs = readInjectionInputs(ctx);
+    if (!inputs.diskPressureContext?.cleanupModeActive) return null;
+    return {
+      id: "disk-pressure-warning",
+      text: DISK_PRESSURE_WARNING_PROMPT,
+      placement: "prepend-user-tail",
+    };
+  },
+};
+
 /**
  * v2 read-side cutover guard. The `pkb-context` injector silences itself
  * under v2 because the `<knowledge_base>` block surfaces PKB content the v2
@@ -520,6 +552,7 @@ export const defaultInjectorsPlugin: Plugin = {
     },
   },
   injectors: [
+    diskPressureWarningInjector,
     workspaceContextInjector,
     unifiedTurnContextInjector,
     pkbContextInjector,

package/src/plugins/defaults/memory-retrieval.ts

@@ -72,12 +72,6 @@ export interface GraphMemoryPayload {
  * Passed as a second argument to {@link runDefaultMemoryRetrieval} rather
  * than threaded through {@link MemoryArgs} to keep the plugin-facing
  * pipeline surface minimal.
- *
- * The per-turn abort signal lives on {@link MemoryArgs.signal} instead of
- * here so the pipeline runner's `linkAbortSignal` can swap it for an
- * internally-linked signal — that way a plugin timeout actually cancels
- * the underlying `prepareMemory` work instead of letting it run after
- * `Promise.race` has already rejected.
  */
 export interface DefaultMemoryRetrievalDeps {
   /** Live message list for this turn (pre-injection). */
@@ -101,6 +95,11 @@ export interface DefaultMemoryRetrievalDeps {
  * trusted) or a single {@link GraphMemoryPayload} wrapping the graph
  * retriever's full output. The agent loop narrows via
  * {@link DEFAULT_MEMORY_GRAPH_KIND} to consume it.
+ *
+ * Memory retrieval blocks the turn — there is no soft timeout here. Memory
+ * is critical context, and silently dropping it produces a worse outcome
+ * than a slower turn. Cancellation still works via `args.signal`, which is
+ * threaded into `prepareMemory`.
  */
 export async function runDefaultMemoryRetrieval(
   args: MemoryArgs,

package/src/plugins/types.ts

@@ -784,6 +784,8 @@ export interface TurnInjectionInputs {
    * context (unified turn context, etc.). Drives per-injector gating.
    */
   readonly mode?: InjectionMode;
+  /** Disk-pressure cleanup-mode context or null to skip the warning. */
+  readonly diskPressureContext?: DiskPressureInjectionContext | null;
   /** Workspace top-level context text (`<workspace>...`) or null to skip. */
   readonly workspaceTopLevelContext?: string | null;
   /** Pre-built unified-turn-context text (`<turn_context>...`) or null to skip. */
@@ -860,6 +862,11 @@ export interface TurnInjectionInputs {
   readonly isNonInteractive?: boolean;
 }
 
+export interface DiskPressureInjectionContext {
+  /** True when the current turn is allowed to run only for storage cleanup. */
+  readonly cleanupModeActive: boolean;
+}
+
 /**
  * Per-turn execution context threaded through every middleware invocation.
  *

package/src/proactive-artifact/aux-message-injector.ts

@@ -0,0 +1,74 @@
+/**
+ * Auxiliary message injection for proactive artifacts.
+ *
+ * Injects an assistant message into a conversation without going through
+ * the normal agent loop. Defers injection while the conversation is
+ * actively processing to preserve chronological message ordering.
+ */
+
+import { createAssistantMessage } from "../agent/message-types.js";
+import { findConversation } from "../daemon/conversation-store.js";
+import { addMessage } from "../memory/conversation-crud.js";
+import type { BroadcastFn } from "../notifications/adapters/macos.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("aux-message-injector");
+const IDLE_POLL_MS = 200;
+const IDLE_TIMEOUT_MS = 60_000;
+
+async function waitForIdle(conversationId: string): Promise<boolean> {
+  const start = Date.now();
+  while (Date.now() - start < IDLE_TIMEOUT_MS) {
+    const conv = findConversation(conversationId);
+    if (!conv || !conv.processing) return true;
+    await new Promise((resolve) => setTimeout(resolve, IDLE_POLL_MS));
+  }
+  return false;
+}
+
+export async function injectAuxAssistantMessage(params: {
+  conversationId: string;
+  text: string;
+  broadcastMessage: BroadcastFn;
+}): Promise<void> {
+  const conv = findConversation(params.conversationId);
+  if (conv?.processing) {
+    const reachedIdle = await waitForIdle(params.conversationId);
+    if (!reachedIdle) {
+      log.warn(
+        { conversationId: params.conversationId },
+        "Timed out waiting for conversation idle; injecting anyway",
+      );
+    }
+  }
+
+  const msg = await addMessage(
+    params.conversationId,
+    "assistant",
+    JSON.stringify([{ type: "text", text: params.text }]),
+    undefined,
+    { skipIndexing: true },
+  );
+
+  const current = findConversation(params.conversationId);
+  if (current && !current.processing) {
+    current.getMessages().push(createAssistantMessage(params.text));
+
+    params.broadcastMessage({
+      type: "assistant_text_delta",
+      text: params.text,
+      conversationId: params.conversationId,
+    });
+    params.broadcastMessage({
+      type: "message_complete",
+      conversationId: params.conversationId,
+      messageId: msg.id,
+      source: "aux",
+    });
+  }
+
+  params.broadcastMessage({
+    type: "conversation_list_invalidated",
+    reason: "reordered",
+  });
+}

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;
+}