feat(session-title): integrate queries ACP and TUI

packages/examples/agent-spine-demo/src/index.ts

@@ -13,6 +13,7 @@ import Timer from '@cordisjs/plugin-timer'
 import z from 'schemastery'
 import LlmService from '@deepseek-ai/dsh-llm'
 import SessionStore from '@deepseek-ai/dsh-session'
+import SessionTitleService from '@deepseek-ai/dsh-session-title'
 import SystemPrompt, { type Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import SkillService, { type Config as SkillRegistryConfig } from '@deepseek-ai/dsh-skill'
@@ -155,6 +156,11 @@ export function apply(ctx: Context, config: Config): void {
   ctx.plugin(Timer)
   ctx.plugin(LlmService)
   ctx.plugin(SessionStore)
+  ctx.plugin(SessionTitleService, {
+    fallbackMaxWords: 5,
+    fallbackMaxBytes: 40,
+    maxTitleBytes: 80,
+  })
   // Owner schemas resolve defaults; forward toolOrder only when explicitly set.
   ctx.plugin(SystemPrompt, {
     persona: config.persona ?? '',

packages/examples/agent-spine-demo/tests/agent-core.spec.ts

@@ -118,6 +118,7 @@ describe('dsh-agent-spine-demo bundle', () => {
     expect(ctx.get('timer')).toBeDefined()
     expect(ctx.get('llm')).toBeDefined()
     expect(ctx.get('sessions')).toBeDefined()
+    expect(ctx.get('sessionTitle')).toBeDefined()
     expect(ctx.get('systemPrompt')).toBeDefined()
     expect(ctx.get('tools')).toBeDefined()
     expect(ctx.get('skills')).toBeDefined()
@@ -153,6 +154,7 @@ describe('dsh-agent-spine-demo bundle', () => {
     expect(retryEvents).toHaveLength(1)
     expect(retryEvents[0]?.data.retry).toBe(1)
     expect(retryEvents[0]?.data.maxRetries).toBe(1)
+    expect(handle.agent.session.events.find(event => event.type === 'session/title')?.data.title).toBe('recover')
     expect(messageText(handle.agent.session.deriveMessages().at(-1))).toBe('recovered by bundled policy')
     await handle.dispose()
     await ctx.fiber.dispose()

packages/session-query/session-query/src/index.ts

@@ -7,6 +7,8 @@
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
 import type { SessionId } from '@deepseek-ai/dsh-session'
+import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
+import type { SessionTitleSnapshot } from '@deepseek-ai/dsh-session-title'
 import type {
   SessionEventReadRequest,
   SessionEventRecord,
@@ -64,6 +66,16 @@ export class SessionQueryService extends Service {
     return this._corpus.listSessions()
   }
 
+  /**
+   * Fold the latest log-backed title from one live-preferred logical session.
+   * @param sessionId - live or persisted session id to read.
+   * @returns latest title snapshot, or `undefined` when the log has no title event.
+   */
+  async readTitle(sessionId: SessionId): Promise<SessionTitleSnapshot | undefined> {
+    const loaded = await this._corpus.load(sessionId)
+    return foldSessionTitle(loaded.events)
+  }
+
   /**
    * List lightweight raw-log event records for one logical session.
    * @param sessionId - live-preferred session id to read.

packages/session-query/session-query/tests/session-query.spec.ts

@@ -6,6 +6,7 @@ import SessionPersistence from '@deepseek-ai/dsh-session-persistence'
 import SessionQueryService, {
   type SessionQueryErrorCode,
 } from '@deepseek-ai/dsh-session-query'
+import { SessionTitleProviderId } from '@deepseek-ai/dsh-session-title'
 
 function header(id: string, createdAt = 1, extra: Partial<SessionHeader> = {}): SessionHeader {
   return { version: SESSION_FORMAT_VERSION, id: SessionId(id), createdAt, ...extra }
@@ -85,6 +86,58 @@ function rejectUnknown<T>(reason: unknown): Promise<T> {
 }
 
 describe('session-query exact reads', () => {
+  it('reads the latest title from one live-preferred or persisted log without widening listSessions', async () => {
+    const persistedHeader = header('persisted-title', 2)
+    const sharedHeader = header('shared-title', 3)
+    TestPersistence.reset([
+      {
+        meta: persistedHeader,
+        events: [{
+          type: 'session/title',
+          seq: 0,
+          time: 20,
+          data: {
+            title: 'Persisted title',
+            messageSeqs: [4],
+            source: { kind: 'fallback' },
+          },
+        }],
+      },
+      {
+        meta: sharedHeader,
+        events: [{
+          type: 'session/title',
+          seq: 0,
+          time: 30,
+          data: {
+            title: 'Stale durable title',
+            messageSeqs: [1],
+            source: { kind: 'fallback' },
+          },
+        }],
+      },
+    ])
+    const ctx = await liveContext()
+    const shared = ctx.sessions.create(sharedHeader.id, { meta: { createdAt: 3 } })
+    shared.append('session/title', {
+      title: 'Live title',
+      messageSeqs: [7],
+      source: {
+        kind: 'provider',
+        provider: SessionTitleProviderId('query-test'),
+      },
+    })
+    await ctx.plugin(TestPersistence)
+
+    await expect(ctx.sessionQuery.readTitle(persistedHeader.id)).resolves.toMatchObject({
+      title: 'Persisted title', eventSeq: 0, updatedAt: 20,
+    })
+    await expect(ctx.sessionQuery.readTitle(shared.id)).resolves.toMatchObject({
+      title: 'Live title', eventSeq: 0,
+    })
+    expect(Object.keys((await ctx.sessionQuery.listSessions())[0]!)).toEqual(['header', 'live', 'persisted'])
+  })
+
   it('lists live sessions deterministically and returns detached headers', async () => {
     const ctx = await liveContext()
     const older = ctx.sessions.create(SessionId('older'), { meta: { createdAt: 1 } })

packages/support/acp-snapshot/src/index.ts

@@ -41,6 +41,8 @@ export {
 } from './normalize.ts'
 export {
   defineAcpSnapshotSuite,
+  refreshFixtureReplacements,
+  stabilizeRefreshLog,
   type Scenario,
   type SnapshotSuiteOptions,
 } from './suite.ts'

packages/support/acp-snapshot/src/normalize.ts

@@ -11,6 +11,7 @@ const CWD = '{{cwd}}'
 const SYSTEM = '{{system}}'
 const TOOLS = '{{tools}}'
 const MESSAGE_PREFIX = '{{messagePrefix}}'
+const UPDATED_AT = '{{updatedAt}}'
 
 /** A UUID v4 string, the shape `randomUUID()` produces for session ids. */
 const UUID_RE = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi
@@ -85,6 +86,8 @@ export function normalizeStdout(rawStdout: string, ctx: NormalizeContext): strin
     if ('id' in frame && frame.id !== undefined && frame.id !== null) {
       frame.id = stableId(frame.id)
     }
+    const update = (frame.params as { update?: Record<string, unknown> } | undefined)?.update
+    if (update?.sessionUpdate === 'session_info_update') update.updatedAt = UPDATED_AT
     return scrubValue(frame, ctx) as Record<string, unknown>
   })
   return frames.map(f => JSON.stringify(f)).join('\n') + '\n'

packages/support/acp-snapshot/src/suite.ts

@@ -420,8 +420,21 @@ export function stabilizeRefreshLog(fresh: string, existing: string, replacement
   for (const { from, to } of replacements) stable = stable.split(from).join(to)
   const existingRecords = parseJsonlRecords(existing)
   const records = parseJsonlRecords(stable)
+  let existingIndex = 0
+  let previousEventTime: unknown
   for (let i = 0; i < records.length; i++) {
-    preserveFixtureVolatiles(records[i] as Record<string, unknown>, existingRecords[i])
+    const record = records[i] as Record<string, unknown>
+    const existingRecord = existingRecords[existingIndex]
+    const insertedTitle = record.type === 'session/title' && existingRecord?.type !== 'session/title'
+    if (insertedTitle) {
+      /* v8 ignore next -- a title is turn-enclosed, so a preceding event time exists in every valid fixture. */
+      if (typeof previousEventTime !== 'number') throw new Error('acp-snapshot: inserted title has no preceding event time')
+      record.time = previousEventTime
+    } else {
+      preserveFixtureVolatiles(record, existingRecord)
+      existingIndex += 1
+    }
+    if (typeof record.time === 'number') previousEventTime = record.time
   }
   return records.map(record => JSON.stringify(record)).join('\n') + '\n'
 }

packages/support/acp-snapshot/tests/normalize.spec.ts

@@ -55,6 +55,24 @@ describe('normalizeStdout', () => {
     expect(out).not.toContain('"id"')
   })
 
+  it('stabilizes the timestamp carried by session title updates', () => {
+    const raw = JSON.stringify({
+      jsonrpc: '2.0',
+      method: 'session/update',
+      params: {
+        sessionId: ctx.sessionIds[0],
+        update: {
+          sessionUpdate: 'session_info_update',
+          title: 'Stable title',
+          updatedAt: '2026-07-20T17:03:13.689Z',
+        },
+      },
+    })
+    const out = normalizeStdout(raw, ctx)
+    expect(out).toContain('"updatedAt":"{{updatedAt}}"')
+    expect(out).not.toContain('2026-07-20T17:03:13.689Z')
+  })
+
   it('throws on a non-JSON stdout line (the purity check)', () => {
     const raw = `${JSON.stringify({ jsonrpc: '2.0', id: 1 })}\noops a log leaked\n`
     expect(() => normalizeStdout(raw, ctx)).toThrow()

packages/support/acp-snapshot/tests/suite.spec.ts

@@ -407,6 +407,36 @@ describe('refreshFixtureReplacements', () => {
 })
 
 describe('stabilizeRefreshLog', () => {
+  it('aligns volatile times across a newly inserted log event', () => {
+    const fresh = [
+      '{"type":"session","id":"same","createdAt":200}',
+      '{"type":"turn/start","seq":0,"time":21}',
+      '{"type":"user/message","seq":1,"time":22}',
+      '{"type":"session/title","seq":2,"time":999}',
+      '{"type":"step/start","seq":3,"time":1000}',
+      '{"type":"request/header","seq":4,"time":1001}',
+      '',
+    ].join('\n')
+    const existing = [
+      '{"type":"session","id":"same","createdAt":100}',
+      '{"type":"turn/start","seq":0,"time":11}',
+      '{"type":"user/message","seq":1,"time":12}',
+      '{"type":"step/start","seq":2,"time":13}',
+      '{"type":"request/header","seq":3,"time":14}',
+      '',
+    ].join('\n')
+
+    expect(stabilizeRefreshLog(fresh, existing, [])).toBe([
+      '{"type":"session","id":"same","createdAt":100}',
+      '{"type":"turn/start","seq":0,"time":11}',
+      '{"type":"user/message","seq":1,"time":12}',
+      '{"type":"session/title","seq":2,"time":12}',
+      '{"type":"step/start","seq":3,"time":13}',
+      '{"type":"request/header","seq":4,"time":14}',
+      '',
+    ].join('\n'))
+  })
+
   it('keeps volatile fixture fields while preserving fresh meaningful payloads', () => {
     const fresh = [
       '{"type":"session","id":"new-child","createdAt":200,"cwd":"/new","parentSession":"new-parent","seedLength":1}',

packages/ui/acp/src/index.ts

@@ -50,6 +50,8 @@ import { SessionId } from '@deepseek-ai/dsh-session'
 // Side-effect type import: resolves `ctx.get('permission')` to the service.
 import type {} from '@deepseek-ai/dsh-permission'
 import type { SessionEvent, TodoItem, TurnEndReason } from '@deepseek-ai/dsh-session'
+// Side-effect type import: adds the log-only session/title event translated below.
+import type {} from '@deepseek-ai/dsh-session-title'
 import type { ToolCallView, ToolRegistry, ToolResultView, TerminalResultView } from '@deepseek-ai/dsh-tools'
 // Side-effect type import: declaration-merges `ctx.sessionPersistence` onto
 // Context (the bridge injects it and reads `list()` for load cwd validation).
@@ -1123,6 +1125,17 @@ export function streamSessionEventUpdate(
       notify({ sessionId, update: { sessionUpdate: 'plan', ...todosToPlan(event.data.todos) } })
       return
     }
+    case 'session/title': {
+      notify({
+        sessionId,
+        update: {
+          sessionUpdate: 'session_info_update',
+          title: event.data.title,
+          updatedAt: new Date(event.time).toISOString(),
+        },
+      })
+      return
+    }
     case 'turn/end': {
       if (event.data.reason.kind !== 'error' || !('failure' in event.data.reason)) return
       const text = `\n\n[Model attempt failed; any partial output above is discarded: ${event.data.reason.failure.message}]\n\n`

packages/ui/acp/tests/load.spec.ts

@@ -4,6 +4,7 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { PROTOCOL_VERSION } from '@agentclientprotocol/sdk'
 import { SESSION_FORMAT_VERSION, SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-title'
 import { makeBridgeHarness, textResponse, toolCallResponse, type BridgeHarness, type CapturedUpdate } from './harness.ts'
 
 /** Concatenate the text of all agent_message_chunk updates. */
@@ -56,6 +57,31 @@ describe('acp bridge — session/load replay', () => {
     expect(userText).toBe('remember this')
   })
 
+  it('streams and replays the same persisted session_info_update for a title event', async () => {
+    live = await makeBridgeHarness({ storageDir, script: [] })
+    await live.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    const { sessionId } = await live.client.newSession({ cwd: process.cwd(), mcpServers: [] })
+    const session = live.ctx.agents.get(SessionId(sessionId))!.session
+    const event = await live.ctx.sessions.appendOutOfBand(session, 'session/title', {
+      title: 'Durable ACP title',
+      messageSeqs: [1],
+      source: { kind: 'fallback' },
+    }, { kind: 'session-title' })
+    const expected = {
+      sessionUpdate: 'session_info_update' as const,
+      title: 'Durable ACP title',
+      updatedAt: new Date(event.time).toISOString(),
+    }
+    expect(live.updates).toContainEqual(expected)
+    await live.dispose()
+    live = undefined
+
+    loader = await makeBridgeHarness({ storageDir, script: [] })
+    await loader.client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
+    await loader.client.loadSession({ sessionId, cwd: process.cwd(), mcpServers: [] })
+    expect(loader.updates).toContainEqual(expected)
+  })
+
   it('replays a persisted tool call with the TOOL-OWNED presentation (title/rawInput/console output)', async () => {
     // Persist a real bash call, then replay it through a fresh bridge. A throwaway presenter pairs
     // call and result in log order so replay uses the shipping tool's same cards as live streaming.

packages/ui/acp/tests/stream-update.spec.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-title'
 import type { SessionNotification } from '@agentclientprotocol/sdk'
 import type { ToolDefinition, ToolRegistry as ToolRegistryType } from '@deepseek-ai/dsh-tools'
 import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
@@ -50,6 +51,23 @@ function evt<T extends SessionEvent['type']>(type: T, data: Extract<SessionEvent
 }
 
 describe('streamSessionEventUpdate', () => {
+  it('maps a title event to session_info_update with the event timestamp', () => {
+    expect(updatesFor({
+      type: 'session/title',
+      seq: 3,
+      time: 1_725_000_000_000,
+      data: {
+        title: 'Log-backed titles',
+        messageSeqs: [1],
+        source: { kind: 'fallback' },
+      },
+    })).toEqual([{
+      sessionUpdate: 'session_info_update',
+      title: 'Log-backed titles',
+      updatedAt: new Date(1_725_000_000_000).toISOString(),
+    }])
+  })
+
   it('maps assistant/chunk text-delta to agent_message_chunk', () => {
     expect(updatesFor(evt('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } })))
       .toEqual([{ sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'hi' } }])

packages/ui/tui/src/index.ts

@@ -39,6 +39,7 @@ import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm'
 import type {} from '@deepseek-ai/dsh-llm-retry'
 import { SessionId, type Session, type SessionEvent, type TodoItem } from '@deepseek-ai/dsh-session'
+import { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
 import type {
   FileDiff,
   TerminalCallView,
@@ -286,7 +287,7 @@ function textBlocks(content: readonly ContentBlock[], type: 'text' | 'reasoning'
 class HeaderComponent implements Component {
   constructor(
     private readonly agent: Agent,
-    private readonly welcome: string,
+    private readonly subtitle: () => string,
     private readonly palette: Palette,
   ) {}
 
@@ -299,7 +300,7 @@ class HeaderComponent implements Component {
     const detail = `${model}  •  ${displayText(this.agent.session.id)}`
     const top = this.palette.accent(`╭${'─'.repeat(Math.max(0, width - 2))}╮`)
     const bottom = this.palette.accent(`╰${'─'.repeat(Math.max(0, width - 2))}╯`)
-    const lines = [title, this.palette.muted(displayText(this.welcome)), this.palette.dim(detail)]
+    const lines = [title, this.palette.muted(displayText(this.subtitle())), this.palette.dim(detail)]
       .flatMap(line => wrapTextWithAnsi(line, usable))
       .map((line) => {
         const clipped = truncateToWidth(line, usable, '')
@@ -858,7 +859,8 @@ export function createTuiChat(
   let activeQuestion: PendingQuestion | undefined
 
   const welcome = config.welcome ?? 'ready.'
-  const header = new HeaderComponent(agent, welcome, palette)
+  let sessionTitle = foldSessionTitle(agent.session.events)?.title
+  const header = new HeaderComponent(agent, () => sessionTitle ?? welcome, palette)
   const footer = new FooterComponent(agent, palette, () => toolsExpanded, () => showReasoning, () => tokens)
   ui.addChild(header)
   ui.addChild(chat)
@@ -868,7 +870,12 @@ export function createTuiChat(
   ui.addChild(editor)
   ui.addChild(footer)
   ui.setFocus(editor)
-  runtime.terminal.setTitle(displayText(resolved.title))
+  const updateTerminalTitle = (): void => {
+    runtime.terminal.setTitle(displayText(
+      sessionTitle === undefined ? resolved.title : `${sessionTitle} — ${resolved.title}`,
+    ))
+  }
+  updateTerminalTitle()
 
   const requestRender = (): void => {
     footer.invalidate()
@@ -997,6 +1004,11 @@ export function createTuiChat(
       case 'todo/write':
         todo.update(event.data.todos)
         break
+      case 'session/title':
+        sessionTitle = event.data.title
+        header.invalidate()
+        updateTerminalTitle()
+        break
       case 'turn/end':
         clearStreaming()
         if (event.data.reason.kind === 'error') {

packages/ui/tui/tests/tui.spec.ts

@@ -5,6 +5,7 @@ import { Context } from 'cordis'
 import type { Terminal } from '@earendil-works/pi-tui'
 import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-title'
 import type { ToolDefinition } from '@deepseek-ai/dsh-tools'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import type {} from '@deepseek-ai/dsh-llm-retry'
@@ -146,6 +147,34 @@ describe('TUI config', () => {
 })
 
 describe('pi-tui chat lifecycle and transcript', () => {
+  it('uses the latest log-backed title for the header subtitle and terminal window', async () => {
+    const result = await setup({
+      beforeMount(session) {
+        session.append('session/title', {
+          title: 'Restored session title',
+          messageSeqs: [1],
+          source: { kind: 'fallback' },
+        })
+      },
+    })
+
+    expect(result.terminal.title).toBe('Restored session title — DeepSeek Harness')
+    expect(result.terminal.output).toContain('Restored session title')
+    expect(result.terminal.output).not.toContain('Coding agent ready.')
+
+    result.session.append('session/title', {
+      title: 'Live title \u001B]0;unsafe\u0007',
+      messageSeqs: [1, 5],
+      source: { kind: 'fallback' },
+    })
+    await tick()
+
+    expect(result.terminal.title).toContain('Live title \\x1b]0;unsafe\\x07 — DeepSeek Harness')
+    expect(result.terminal.title).not.toContain('\u001B')
+    expect(result.terminal.output).toContain('Live title \\x1b]0;unsafe\\x07')
+    await dispose(result)
+  })
+
   it('renders its header, footer, replay, streaming answer, todos, and status', async () => {
     const result = await setup({
       beforeMount(session) {