@vellumai/assistant 0.11.1 → 0.11.2-staging.2

package/src/tools/workflows/run-workflow.test.ts

@@ -342,6 +342,7 @@ describe("manage_workflows", () => {
     expect(parsed.profiles).toEqual([
       "balanced",
       "cost-optimized",
+      "latency-optimized",
       "quality-optimized",
     ]);
     expect(parsed.activeProfile).toBe("balanced");

package/src/util/__tests__/short-title.test.ts

@@ -0,0 +1,229 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  normalizeTitle,
+  stripMarkdown,
+  stripThinkingTags,
+  truncateTitle,
+} from "../short-title.js";
+
+/** The character and word budgets `short-title.ts` documents and enforces. */
+const MAX_TITLE_LENGTH = 40;
+const MAX_TITLE_WORDS = 7;
+
+describe("stripMarkdown", () => {
+  test("unwraps bold, italic, strikethrough, and code spans", () => {
+    expect(stripMarkdown("**Auth** Rewrite")).toBe("Auth Rewrite");
+    expect(stripMarkdown("__Auth__ Rewrite")).toBe("Auth Rewrite");
+    expect(stripMarkdown("*Auth* Rewrite")).toBe("Auth Rewrite");
+    expect(stripMarkdown("_Auth_ Rewrite")).toBe("Auth Rewrite");
+    expect(stripMarkdown("~~Auth~~ Rewrite")).toBe("Auth Rewrite");
+    expect(stripMarkdown("`Auth` Rewrite")).toBe("Auth Rewrite");
+  });
+
+  test("keeps link text and drops the target", () => {
+    expect(stripMarkdown("[Auth Rewrite](https://example.com)")).toBe(
+      "Auth Rewrite",
+    );
+  });
+
+  test("removes heading markers", () => {
+    expect(stripMarkdown("## Auth Rewrite")).toBe("Auth Rewrite");
+  });
+
+  test("preserves snake_case identifiers", () => {
+    expect(stripMarkdown("record_conversation_title")).toBe(
+      "record_conversation_title",
+    );
+  });
+});
+
+describe("stripThinkingTags", () => {
+  test("removes paired thinking blocks and their contents", () => {
+    expect(stripThinkingTags("<thinking>hmm</thinking>Auth Rewrite")).toBe(
+      "Auth Rewrite",
+    );
+    expect(stripThinkingTags("<thought>hmm</thought>Auth Rewrite")).toBe(
+      "Auth Rewrite",
+    );
+    expect(stripThinkingTags("<think>hmm</think>Auth Rewrite")).toBe(
+      "Auth Rewrite",
+    );
+  });
+
+  test("removes unpaired tags but keeps the surrounding text", () => {
+    expect(stripThinkingTags("<thinking>Auth Rewrite")).toBe("Auth Rewrite");
+    expect(stripThinkingTags("Auth Rewrite</think>")).toBe("Auth Rewrite");
+  });
+
+  test("removes colon-prefixed pseudo tags", () => {
+    expect(stripThinkingTags("<:anything>Auth Rewrite")).toBe("Auth Rewrite");
+  });
+
+  test("leaves plain text untouched", () => {
+    expect(stripThinkingTags("Auth Rewrite")).toBe("Auth Rewrite");
+  });
+});
+
+describe("truncateTitle", () => {
+  test("leaves titles within the character limit untouched", () => {
+    const title = "Auth Middleware Rewrite";
+    expect(title.length).toBeLessThanOrEqual(MAX_TITLE_LENGTH);
+    expect(truncateTitle(title)).toBe(title);
+  });
+
+  test("trims at a word boundary when few but long words exceed the char limit", () => {
+    const title = "Supercalifragilistic Authentication Middleware Rewrite";
+    expect(title.split(" ").length).toBeLessThanOrEqual(MAX_TITLE_WORDS);
+    expect(truncateTitle(title)).toBe("Supercalifragilistic Authentication");
+  });
+
+  test("hard-slices a single word longer than the char limit", () => {
+    const title = "a".repeat(MAX_TITLE_LENGTH + 5);
+    expect(truncateTitle(title)).toBe("a".repeat(MAX_TITLE_LENGTH));
+  });
+
+  test("keeps the first five words when the word limit is exceeded", () => {
+    const title =
+      "alpha bravo charlie delta echo foxtrot golf hotel india juliet";
+    expect(title.length).toBeGreaterThan(MAX_TITLE_LENGTH);
+    expect(title.split(" ").length).toBeGreaterThan(MAX_TITLE_WORDS);
+    expect(truncateTitle(title)).toBe("alpha bravo charlie delta echo");
+  });
+
+  test("still honors the char limit when the first five words overflow it", () => {
+    const title =
+      "Authentication Infrastructure Modernization Deployment Verification Report Complete Today";
+    expect(title.length).toBeGreaterThan(MAX_TITLE_LENGTH);
+    expect(title.split(" ").length).toBeGreaterThan(MAX_TITLE_WORDS);
+    const result = truncateTitle(title);
+    expect(result).toBe("Authentication Infrastructure");
+    expect(result.length).toBeLessThanOrEqual(MAX_TITLE_LENGTH);
+  });
+});
+
+describe("normalizeTitle prose rejection", () => {
+  test("rejects multi-line output", () => {
+    expect(normalizeTitle("Auth Rewrite\nand more")).toBe("");
+  });
+
+  test("rejects embedded transcript markers", () => {
+    expect(normalizeTitle("User: how do I log in")).toBe("");
+    expect(normalizeTitle("Assistant : here you go")).toBe("");
+  });
+
+  test("rejects sentence-shaped clauses ending in terminal punctuation", () => {
+    expect(normalizeTitle("This is a topic about authentication.")).toBe("");
+    expect(normalizeTitle("What did they want to build here?")).toBe("");
+  });
+
+  test("keeps short phrases that end in punctuation", () => {
+    expect(normalizeTitle("Auth Rewrite?")).toBe("Auth Rewrite?");
+  });
+
+  test("rejects first-person reasoning openers", () => {
+    expect(normalizeTitle("I need to generate a title")).toBe("");
+    expect(normalizeTitle("I'll work through these files")).toBe("");
+    expect(normalizeTitle("I cannot title this")).toBe("");
+  });
+
+  test("rejects imperative and deferral openers", () => {
+    expect(normalizeTitle("Let me summarize the request")).toBe("");
+    expect(normalizeTitle("Looking at the conversation")).toBe("");
+    expect(normalizeTitle("Based on the messages")).toBe("");
+    expect(normalizeTitle("Given the context")).toBe("");
+  });
+
+  test("rejects infinitive openers", () => {
+    expect(normalizeTitle("To generate a good title")).toBe("");
+    expect(normalizeTitle("To summarize the discussion")).toBe("");
+    expect(normalizeTitle("To title this thread")).toBe("");
+  });
+
+  test("rejects subject-led reasoning openers", () => {
+    expect(normalizeTitle("The user wants a summary")).toBe("");
+    expect(normalizeTitle("The conversation is about Docker")).toBe("");
+    expect(normalizeTitle("The assistant should reply")).toBe("");
+    expect(normalizeTitle("The title should be short")).toBe("");
+  });
+
+  test("rejects preamble openers", () => {
+    expect(normalizeTitle("Here's a title")).toBe("");
+    expect(normalizeTitle("Here is a title")).toBe("");
+    expect(normalizeTitle("Here are the options")).toBe("");
+    expect(normalizeTitle("Sure, Auth Rewrite")).toBe("");
+    expect(normalizeTitle("Okay, Auth Rewrite")).toBe("");
+    expect(normalizeTitle("Ok, Auth Rewrite")).toBe("");
+  });
+
+  test("accepts bare noun-phrase titles that share a subject word", () => {
+    expect(normalizeTitle("The Conversation API")).toBe("The Conversation API");
+    expect(normalizeTitle("The User Interface Redesign")).toBe(
+      "The User Interface Redesign",
+    );
+    expect(normalizeTitle("Auth Middleware Rewrite")).toBe(
+      "Auth Middleware Rewrite",
+    );
+  });
+});
+
+describe("normalizeTitle", () => {
+  test("strips surrounding quotes", () => {
+    expect(normalizeTitle('"Auth Rewrite"')).toBe("Auth Rewrite");
+    expect(normalizeTitle("'Auth Rewrite'")).toBe("Auth Rewrite");
+  });
+
+  test("strips markdown and thinking tags together", () => {
+    expect(normalizeTitle("<thinking>hmm</thinking> **Auth Rewrite**")).toBe(
+      "Auth Rewrite",
+    );
+  });
+
+  test("returns empty for blank input", () => {
+    expect(normalizeTitle("")).toBe("");
+    expect(normalizeTitle("   ")).toBe("");
+    expect(normalizeTitle("<thinking>hmm</thinking>")).toBe("");
+  });
+
+  test("returns empty for leaked prose", () => {
+    expect(normalizeTitle("I need to generate a title for this")).toBe("");
+    expect(normalizeTitle("User: how do I log in")).toBe("");
+    expect(normalizeTitle("Auth Rewrite\nand more")).toBe("");
+  });
+
+  test("returns empty for meta-failure titles regardless of case", () => {
+    const metaFailures = [
+      "missing context",
+      "no context",
+      "insufficient context",
+      "unclear context",
+      "empty context",
+      "no topic",
+      "unclear topic",
+      "unclear request",
+      "unclear message",
+      "empty conversation",
+      "empty message",
+      "no content",
+    ];
+    for (const meta of metaFailures) {
+      expect(normalizeTitle(meta)).toBe("");
+    }
+    expect(normalizeTitle("Missing Context")).toBe("");
+    expect(normalizeTitle('"No Topic"')).toBe("");
+  });
+
+  test("truncates an over-long accepted title", () => {
+    expect(
+      normalizeTitle("alpha bravo charlie delta echo foxtrot golf hotel india"),
+    ).toBe("alpha bravo charlie delta echo");
+  });
+
+  test("keeps a wordy title inside the character budget", () => {
+    const result = normalizeTitle(
+      "Authentication Infrastructure Modernization Deployment Verification Report Complete Today",
+    );
+    expect(result).toBe("Authentication Infrastructure");
+    expect(result.length).toBeLessThanOrEqual(MAX_TITLE_LENGTH);
+  });
+});

package/src/util/__tests__/worker-compute.test.ts

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  computeWorkerIntraOpThreads,
+  ONNX_INTRA_OP_THREADS_ENV,
+  WORKER_MAX_INTRA_OP_THREADS,
+  WORKER_MIN_INTRA_OP_THREADS,
+  workerComputeEnv,
+} from "../worker-compute.js";
+
+describe("computeWorkerIntraOpThreads", () => {
+  test("targets a quarter of the available cores", () => {
+    // 8 cores -> 2 threads, inside both clamps.
+    expect(computeWorkerIntraOpThreads(8)).toBe(2);
+  });
+
+  test("clamps small machines up to the minimum", () => {
+    // 2 cores -> 0 raw, which ONNX would read as "unbounded"; clamped up.
+    expect(computeWorkerIntraOpThreads(2)).toBe(WORKER_MIN_INTRA_OP_THREADS);
+  });
+
+  test("clamps large machines down to the maximum", () => {
+    // 64 cores -> 16 raw, clamped down.
+    expect(computeWorkerIntraOpThreads(64)).toBe(WORKER_MAX_INTRA_OP_THREADS);
+  });
+
+  test("never returns a value ONNX would treat as unbounded", () => {
+    for (const cores of [0, -1, -100, NaN, Infinity]) {
+      expect(computeWorkerIntraOpThreads(cores)).toBeGreaterThanOrEqual(
+        WORKER_MIN_INTRA_OP_THREADS,
+      );
+    }
+  });
+
+  test("fractional container quotas floor rather than round up", () => {
+    // A 1.5-core cgroup quota must not hand ONNX more than it has.
+    expect(computeWorkerIntraOpThreads(1.5)).toBe(WORKER_MIN_INTRA_OP_THREADS);
+  });
+});
+
+describe("workerComputeEnv", () => {
+  const saved = process.env[ONNX_INTRA_OP_THREADS_ENV];
+
+  afterEach(() => {
+    if (saved === undefined) {
+      delete process.env[ONNX_INTRA_OP_THREADS_ENV];
+    } else {
+      process.env[ONNX_INTRA_OP_THREADS_ENV] = saved;
+    }
+  });
+
+  test("computes a clamped thread cap", () => {
+    delete process.env[ONNX_INTRA_OP_THREADS_ENV];
+    const env = workerComputeEnv();
+    const threads = Number(env[ONNX_INTRA_OP_THREADS_ENV]);
+    expect(Number.isInteger(threads)).toBe(true);
+    expect(threads).toBeGreaterThanOrEqual(WORKER_MIN_INTRA_OP_THREADS);
+    expect(threads).toBeLessThanOrEqual(WORKER_MAX_INTRA_OP_THREADS);
+  });
+
+  test("keeps an operator-provided override", () => {
+    process.env[ONNX_INTRA_OP_THREADS_ENV] = "7";
+    expect(workerComputeEnv()[ONNX_INTRA_OP_THREADS_ENV]).toBe("7");
+  });
+});

package/src/util/cgroup-cpu.ts

@@ -7,7 +7,9 @@
  */
 
 import { readFileSync } from "node:fs";
+import { availableParallelism, cpus } from "node:os";
 
+import { getCpuLimit, getIsPlatform } from "../config/env-registry.js";
 import { parseKeyedCounts } from "./cgroup-memory.js";
 
 export interface ContainerCpuStat {
@@ -45,3 +47,94 @@ export function getContainerCpuStat(): ContainerCpuStat | null {
   const raw = readCpuStatRaw();
   return raw != null ? parseCpuStat(raw) : null;
 }
+
+/**
+ * Parse a Kubernetes-style CPU string (e.g. "2000m", "1", "500m") into
+ * fractional cores. Returns null if the value is not a recognized format.
+ */
+export function parseK8sCpuCores(value: string): number | null {
+  const trimmed = value.trim();
+  const milliMatch = trimmed.match(/^(\d+)m$/);
+  if (milliMatch) {
+    const millis = parseInt(milliMatch[1], 10);
+    return millis > 0 ? millis / 1000 : null;
+  }
+  if (/^\d+(\.\d+)?$/.test(trimmed)) {
+    const num = parseFloat(trimmed);
+    return !isNaN(num) && num > 0 ? num : null;
+  }
+  return null;
+}
+
+/**
+ * Read the container's CPU core limit.
+ *
+ * Resolution order:
+ * 1. VELLUM_CPU_LIMIT env var (K8s resource format, e.g. "2000m" or "2").
+ *    In platform mode the container runs under gVisor where cgroup files may
+ *    report the node's CPU count rather than the sandbox limit.
+ * 2. cgroups v2 cpu.max (quota / period → fractional cores).
+ * 3. cgroups v1 cpu.cfs_quota_us / cpu.cfs_period_us.
+ * 4. os.cpus().length as last resort.
+ */
+export function getContainerCpuCores(): number {
+  // 1. Prefer the explicit env var set by the platform StatefulSet template.
+  try {
+    const envLimit = getCpuLimit();
+    if (envLimit) {
+      const parsed = parseK8sCpuCores(envLimit);
+      if (parsed !== null) {
+        return parsed;
+      }
+    }
+  } catch {
+    /* env var parsing failed – fall through */
+  }
+
+  // 2. Try cgroups v2: /sys/fs/cgroup/cpu.max contains "$MAX $PERIOD".
+  try {
+    const raw = readFileSync("/sys/fs/cgroup/cpu.max", "utf-8").trim();
+    if (!raw.startsWith("max")) {
+      const parts = raw.split(/\s+/);
+      const quota = parseInt(parts[0], 10);
+      const period = parseInt(parts[1], 10);
+      if (!isNaN(quota) && !isNaN(period) && period > 0 && quota > 0) {
+        const cores = quota / period;
+        // Sanity check: if the value looks like the node's full CPU count
+        // and we're on a platform pod, it's likely gVisor leaking the host value.
+        if (cores < cpus().length * 0.9 || !getIsPlatform()) {
+          return cores;
+        }
+      }
+    }
+  } catch {
+    /* not available */
+  }
+
+  // 3. Try cgroups v1.
+  try {
+    const quota = parseInt(
+      readFileSync("/sys/fs/cgroup/cpu/cpu.cfs_quota_us", "utf-8").trim(),
+      10,
+    );
+    const period = parseInt(
+      readFileSync("/sys/fs/cgroup/cpu/cpu.cfs_period_us", "utf-8").trim(),
+      10,
+    );
+    if (!isNaN(quota) && !isNaN(period) && period > 0 && quota > 0) {
+      const cores = quota / period;
+      if (cores < cpus().length * 0.9 || !getIsPlatform()) {
+        return cores;
+      }
+    }
+  } catch {
+    /* not available */
+  }
+
+  // 4. Fall back to the visible CPU count; 0 when even that syscall fails.
+  try {
+    return cpus().length || availableParallelism();
+  } catch {
+    return 0;
+  }
+}

package/src/util/errors.ts

@@ -123,6 +123,24 @@ export type ProviderErrorReason =
   | "network_error"
   | "unknown";
 
+export type ProviderCredentialSource =
+  | "byok"
+  | "no-auth"
+  | "oauth-subscription"
+  | "vellum-managed";
+
+export interface ProviderRouteAttribution {
+  connectionName?: string;
+  profileName?: string;
+  isManagedRoute?: boolean;
+  /**
+   * Credential surface used for this request. Finer than `isManagedRoute`:
+   * it separates personal provider keys, keyless endpoints, and subscription
+   * logins from each other so error copy can name what the user must fix.
+   */
+  credentialSource?: ProviderCredentialSource;
+}
+
 export class ProviderError extends AssistantError {
   /** Delay (in ms) suggested by the server's Retry-After header, if present. */
   public readonly retryAfterMs?: number;
@@ -146,6 +164,8 @@ export class ProviderError extends AssistantError {
   public readonly abortReason?: unknown;
   /** Semantic failure classification stamped at the throw site. */
   public readonly reason?: ProviderErrorReason;
+  /** Transport route selected for the failed provider call. */
+  public routeAttribution?: ProviderRouteAttribution;
 
   constructor(
     message: string,
@@ -174,6 +194,13 @@ export class ProviderError extends AssistantError {
     this.abortReason = options?.abortReason;
     this.reason = options?.reason;
   }
+
+  attachRouteAttribution(attribution: ProviderRouteAttribution): void {
+    this.routeAttribution = {
+      ...attribution,
+      ...this.routeAttribution,
+    };
+  }
 }
 
 export class ToolError extends AssistantError {

package/src/util/process-tree.ts

@@ -115,6 +115,25 @@ export function deriveName(command: string): string {
   return argv0;
 }
 
+/**
+ * Redacted command descriptor for a live PID from `/proc/<pid>/cmdline`, or
+ * null when the process is gone or its `/proc` entry is unreadable. Kernel
+ * threads have an empty command line and read as `(unknown)`.
+ *
+ * The raw command line is read here but never returned: it can carry secrets
+ * (bearer tokens, API keys, database URLs) passed as process arguments, so
+ * callers that record process identity in snapshots or logs get only the
+ * {@link deriveName} descriptor.
+ */
+export function readProcessCommand(pid: number): string | null {
+  try {
+    const raw = readFileSync(`/proc/${pid}/cmdline`, "utf8");
+    return deriveName(raw.split("\0").filter(Boolean).join(" "));
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Captures the plugin path segment(s) from a command whose executable/script
  * path lives under a `plugins/<name>/` directory. Group 1 is the first segment

package/src/util/short-title.ts

@@ -0,0 +1,189 @@
+/**
+ * Title hygiene helpers shared by every surface that renders a short,
+ * scannable conversation title: markdown/thinking-tag stripping, prose and
+ * meta-failure rejection, and length truncation.
+ */
+
+const MAX_TITLE_LENGTH = 40;
+const MAX_TITLE_WORDS = 7;
+
+/** Word count a title exceeding `MAX_TITLE_WORDS` is cut back to. */
+const TRIMMED_TITLE_WORDS = 5;
+
+const META_FAILURE_TITLES = new Set([
+  "missing context",
+  "no context",
+  "insufficient context",
+  "unclear context",
+  "empty context",
+  "no topic",
+  "unclear topic",
+  "unclear request",
+  "unclear message",
+  "empty conversation",
+  "empty message",
+  "no content",
+]);
+
+/** Reasoning/sentence openers that never start a legitimate topic title. */
+const LEAKED_PROSE_PREFIXES = [
+  "i need to",
+  "i needed to",
+  "i should",
+  "i will",
+  "i'll",
+  "i can ",
+  "i can't",
+  "i cannot",
+  "i'm ",
+  "i am ",
+  "i've ",
+  "i have ",
+  "i'd ",
+  "i would",
+  "let me",
+  "looking at",
+  "based on",
+  "given the",
+  "to generate",
+  "to summarize",
+  "to title",
+  // Subject-led reasoning openers. A bare noun phrase ("The User Interface
+  // Redesign", "The Conversation API") is a valid title, so each subject only
+  // counts as leaked prose when a verb or possessive follows it, marking the
+  // output as a sentence rather than a topic.
+  "the user wants",
+  "the user asked",
+  "the user is",
+  "the user wanted",
+  "the user needs",
+  "the user said",
+  "the user has",
+  "the user would",
+  "the user's request",
+  "the conversation is",
+  "this conversation is",
+  "the conversation appears",
+  "the conversation seems",
+  "the conversation covers",
+  "the conversation discusses",
+  "the assistant should",
+  "the assistant is",
+  "the assistant wants",
+  "the assistant needs",
+  "the title should",
+  "the title is",
+  "the title would",
+  "the title for",
+  "here's ",
+  "here is ",
+  "here are ",
+  "sure,",
+  "okay,",
+  "ok,",
+];
+
+/** Strip common markdown formatting so titles render as plain text. */
+export function stripMarkdown(text: string): string {
+  return text
+    .replace(/\*\*(.+?)\*\*/g, "$1") // **bold**
+    .replace(/__(.+?)__/g, "$1") // __bold__
+    .replace(/\*(.+?)\*/g, "$1") // *italic*
+    .replace(/(?<!\w)_(.+?)_(?!\w)/g, "$1") // _italic_ (word-boundary-aware to preserve snake_case)
+    .replace(/~~(.+?)~~/g, "$1") // ~~strikethrough~~
+    .replace(/`(.+?)`/g, "$1") // `code`
+    .replace(/\[(.+?)\]\(.+?\)/g, "$1") // [link](url)
+    .replace(/^#{1,6}\s+/gm, ""); // # headings
+}
+
+/** Strip thinking tags so they don't bleed into generated titles. */
+export function stripThinkingTags(text: string): string {
+  return text
+    .replace(/<thinking>[\s\S]*?<\/thinking>/gi, "")
+    .replace(/<thought>[\s\S]*?<\/thought>/gi, "")
+    .replace(/<think>[\s\S]*?<\/think>/gi, "")
+    .replace(/<thought>/gi, "")
+    .replace(/<\/thought>/gi, "")
+    .replace(/<thinking>/gi, "")
+    .replace(/<\/thinking>/gi, "")
+    .replace(/<think>/gi, "")
+    .replace(/<\/think>/gi, "")
+    .replace(/<:[^>]*>/gi, "");
+}
+
+/**
+ * Clamp a title to `MAX_TITLE_LENGTH` characters and `MAX_TITLE_WORDS` words.
+ * Both budgets apply: a wordy title is cut back to `TRIMMED_TITLE_WORDS` words
+ * and the survivors are still trimmed at a word boundary to fit the character
+ * budget, so the returned string is never longer than `MAX_TITLE_LENGTH`.
+ */
+export function truncateTitle(title: string): string {
+  if (title.length <= MAX_TITLE_LENGTH) {
+    return title;
+  }
+  const words = title.split(/\s+/);
+  const kept =
+    words.length > MAX_TITLE_WORDS
+      ? words.slice(0, TRIMMED_TITLE_WORDS)
+      : words;
+  let result = "";
+  for (const word of kept) {
+    const candidate = result ? result + " " + word : word;
+    if (candidate.length > MAX_TITLE_LENGTH) {
+      break;
+    }
+    result = candidate;
+  }
+  // Empty when even the first word overflows: hard-slice rather than return "".
+  return result || title.slice(0, MAX_TITLE_LENGTH);
+}
+
+/**
+ * Heuristic guard for title outputs that are clearly prose: the model
+ * reasoning aloud or replying to the conversation rather than naming it. A real
+ * title is a single-line short noun phrase, so we reject multi-line output,
+ * embedded transcript markers, leading reasoning openers, and sentence-shaped
+ * clauses. Deliberately tight: a false reject only costs a deterministic
+ * fallback title, while a false accept persists a broken one.
+ */
+function looksLikeLeakedProse(title: string): boolean {
+  if (/\n/.test(title)) {
+    return true;
+  }
+  if (/\b(?:user|assistant)\s*:/i.test(title)) {
+    return true;
+  }
+  const lower = title.toLowerCase();
+  if (LEAKED_PROSE_PREFIXES.some((prefix) => lower.startsWith(prefix))) {
+    return true;
+  }
+  // Sentence-shaped: terminal punctuation on a multi-word clause.
+  if (/[.?!]$/.test(title) && title.split(/\s+/).length > 5) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Clean a raw title into a short, scannable label. Returns "" when the input is
+ * empty, reads as leaked prose, or is a meta-failure title, signalling that
+ * callers should fall back to a deterministic title.
+ */
+export function normalizeTitle(raw: string): string {
+  let title = raw.trim().replace(/^["']|["']$/g, "");
+  title = stripMarkdown(title);
+  title = stripThinkingTags(title).trim();
+  if (!title) {
+    return "";
+  }
+  // Reject outputs that are the model reasoning aloud or continuing the
+  // conversation instead of naming it (e.g. "I need to generate a…", "I'll
+  // work through these files…"). Callers fall back to a deterministic title.
+  if (looksLikeLeakedProse(title)) {
+    return "";
+  }
+  if (META_FAILURE_TITLES.has(title.toLowerCase())) {
+    return "";
+  }
+  return truncateTitle(title);
+}