refactor(session): centralize fallback title policy (#39890)

packages/util/package.json

@@ -28,6 +28,7 @@
   },
   "scripts": {
     "build": "bun run script/build.ts",
+    "test": "bun test --only-failures",
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {

packages/util/src/session-title-fallback.ts

@@ -0,0 +1,36 @@
+export * as SessionTitleFallback from "./session-title-fallback.js"
+
+const pattern = /^(New session|Child session) - \d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/
+
+interface Info {
+  readonly title?: string
+  readonly parentID?: string
+  readonly time: {
+    readonly created: number
+  }
+}
+
+/** Supplies the timestamped title required by compatibility surfaces. */
+export function withTimestampedFallback(info: Info) {
+  return info.title ?? fallback(info)
+}
+
+/** Supplies a compact human label and collapses historical timestamped fallbacks. */
+export function displayLabel(info: Pick<Info, "title" | "parentID">) {
+  if (!info.title) return info.parentID ? "Child session" : "New session"
+  return info.title.match(pattern)?.[1] ?? info.title
+}
+
+/** Recognizes missing and historical root or child fallback titles. */
+export function isFallbackTitle(title?: string) {
+  return title === undefined || pattern.test(title)
+}
+
+/** Recognizes a missing title or the exact root fallback for this session. */
+export function isExactRootFallback(info: Pick<Info, "title" | "time">) {
+  return info.title === undefined || info.title === fallback({ time: info.time })
+}
+
+function fallback(info: Pick<Info, "parentID" | "time">) {
+  return `${info.parentID ? "Child" : "New"} session - ${new Date(info.time.created).toISOString()}`
+}

packages/util/test/session-title-fallback.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "bun:test"
+import { SessionTitleFallback } from "../src/session-title-fallback.js"
+
+const root = { title: undefined, time: { created: 0 } }
+const child = { ...root, parentID: "ses_parent" }
+
+describe("SessionTitleFallback", () => {
+  test("supplies timestamped compatibility titles", () => {
+    expect(SessionTitleFallback.withTimestampedFallback(root)).toBe("New session - 1970-01-01T00:00:00.000Z")
+    expect(SessionTitleFallback.withTimestampedFallback(child)).toBe("Child session - 1970-01-01T00:00:00.000Z")
+    expect(SessionTitleFallback.withTimestampedFallback({ ...root, title: "Generated title" })).toBe("Generated title")
+    expect(SessionTitleFallback.withTimestampedFallback({ ...root, title: "" })).toBe("")
+  })
+
+  test("supplies compact display labels", () => {
+    expect(SessionTitleFallback.displayLabel(root)).toBe("New session")
+    expect(SessionTitleFallback.displayLabel(child)).toBe("Child session")
+    expect(SessionTitleFallback.displayLabel({ title: "", parentID: "ses_parent" })).toBe("Child session")
+    expect(SessionTitleFallback.displayLabel({ title: "New session - 2026-07-30T18:45:03.662Z" })).toBe("New session")
+    expect(SessionTitleFallback.displayLabel({ title: "Child session - 2026-07-30T18:45:03.662Z" })).toBe(
+      "Child session",
+    )
+    expect(SessionTitleFallback.displayLabel({ title: "Generated title" })).toBe("Generated title")
+  })
+
+  test("recognizes historical fallback titles", () => {
+    expect(SessionTitleFallback.isFallbackTitle(undefined)).toBeTrue()
+    expect(SessionTitleFallback.isFallbackTitle("New session - 2026-07-30T18:45:03.662Z")).toBeTrue()
+    expect(SessionTitleFallback.isFallbackTitle("Child session - 2026-07-30T18:45:03.662Z")).toBeTrue()
+    expect(SessionTitleFallback.isFallbackTitle("")).toBeFalse()
+    expect(SessionTitleFallback.isFallbackTitle("New session - custom")).toBeFalse()
+  })
+
+  test("recognizes only the fallback associated with a session", () => {
+    expect(SessionTitleFallback.isExactRootFallback(root)).toBeTrue()
+    expect(
+      SessionTitleFallback.isExactRootFallback({ ...root, title: "New session - 1970-01-01T00:00:00.000Z" }),
+    ).toBeTrue()
+    expect(
+      SessionTitleFallback.isExactRootFallback({ ...root, title: "New session - 2099-01-01T00:00:00.000Z" }),
+    ).toBeFalse()
+    expect(
+      SessionTitleFallback.isExactRootFallback({
+        ...child,
+        title: "Child session - 1970-01-01T00:00:00.000Z",
+      }),
+    ).toBeFalse()
+  })
+})