feat(session-title): add fallback and model providers

packages/session-title/session-title/README.md

@@ -0,0 +1,52 @@
+# @deepseek-ai/dsh-session-title
+
+Log-backed session titles with an immediate deterministic fallback and one optional asynchronous provider. Every accepted revision is a log-only `session/title` event; `foldSessionTitle()` and `ctx.sessionTitle.get()` select the latest event and return its event seq and timestamp.
+
+Only text blocks from human `user/message` events are eligible. The first eligible prompt schedules a fallback from its first words within the configured UTF-8 byte limit. Whitespace is normalized, terminal control sequences are removed, and truncation never splits a code point. Empty and non-text prompts wait for later eligible input.
+
+## Service: `SessionTitleService` (ctx key: `sessionTitle`)
+
+- `get(session)` folds the latest accepted title from a live or replayed log.
+- `refresh(session, signal?)` materializes the fallback when needed, then explicitly runs the registered provider over the current eligible messages. Provider errors and caller cancellation reject.
+- `register(provider)` installs the sole optional provider and returns its Cordis effect disposer. A second registration throws immediately; disposal aborts pending and active calls before another provider can register.
+
+Automatic work never delays the main agent response. A provider starts after the matching `request/header` records the main request's exact route; its late completion joins an open turn or uses a flushed zero-step `session-title` turn through `ctx.sessions.appendOutOfBand()`. Automatic failures warn and retain the latest title. New all-message revisions, provider disposal, session disposal, and explicit refresh abort older work, and a stale completion cannot append.
+
+Forks inherit title events in their seed unchanged. The first-message cadence does not automatically retitle a child; the all-messages cadence may append a new revision after the child receives a later human prompt.
+
+## Configuration
+
+All limits are required; the library supplies no defaults.
+
+| Key | Contract |
+|---|---|
+| `fallbackMaxWords` | Positive maximum whitespace-delimited words in the deterministic fallback. |
+| `fallbackMaxBytes` | Positive maximum UTF-8 bytes in the fallback; must not exceed `maxTitleBytes`. |
+| `maxTitleBytes` | Positive maximum UTF-8 bytes accepted from any source. |
+
+## Provider contract
+
+A provider supplies a branded stable id, automatic mode (`first-message` or `all-user-messages`), and `generate(request)`. The request carries the live session, all eligible messages through one fixed revision, the current logged main-request route when available, and cancellation. The result identifies a non-empty title, unique ordered source-message seqs from that request, and optional model provenance. The service normalizes and validates the result before it becomes durable.
+
+See the [session-title data structures](../../../docs/core-data-structures/session-title.md) and [implemented decision](../../../.agents/notes/implemented/feature/2026-07-21-log-backed-session-titles.md).
+
+## Model Experience
+
+### Session title state
+
+#### What the model sees
+
+Nothing. `session/title` is log-only and never enters the session surface, `deriveMessages()`, system prompt, tool schemas, or request prefix.
+
+#### Token effect
+
+The fallback and accepted provider revisions add zero tokens to the main agent request. An optional provider's separate auxiliary request is documented by that provider package.
+
+#### KV Cache effect
+
+None for the main request; title events do not change its reconstructed content or cache key.
+
+## Known Limitations and Deferred Work
+
+- Manual rename, title deletion, generated-versus-user precedence, search, and list indexing are outside this service.
+- The provider registry deliberately accepts at most one implementation, so a deployment cannot compose competing title strategies without writing one provider that owns their precedence.

packages/session-title/session-title/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-session-title",
+  "description": "Log-backed session title service and provider registry for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-brand": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-brand": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-sqlite": "workspace:^",
+    "cordis": "^4.0.0-rc.7"
+  }
+}

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

@@ -0,0 +1,556 @@
+/**
+ * Log-backed session title service, deterministic fallback, and provider seam.
+ * @module @deepseek-ai/dsh-session-title
+ */
+
+import { Context, Service } from 'cordis'
+import z from 'schemastery'
+import type { Branded } from '@deepseek-ai/dsh-brand'
+import { deepFreeze } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { fallbackSessionTitle, normalizeSessionTitle } from './normalize.ts'
+
+export { fallbackSessionTitle, normalizeSessionTitle, truncateTitleUtf8 } from './normalize.ts'
+
+/** Identifies one session-title provider registration. */
+export type SessionTitleProviderId = Branded<'SessionTitleProviderId'>
+
+/**
+ * Brand a raw provider id.
+ * @param id - stable non-empty provider identifier supplied by a plugin.
+ * @returns the same string with the session-title provider brand.
+ */
+export function SessionTitleProviderId(id: string): SessionTitleProviderId {
+  return id as SessionTitleProviderId
+}
+
+/** Exact auxiliary model route that produced a title. */
+export interface SessionTitleModelProvenance {
+  /** Registered LLM provider route. */
+  readonly provider: string
+  /** Provider model id. */
+  readonly model: string
+}
+
+/** Durable ownership record for an accepted session title. */
+export type SessionTitleSource =
+  | { readonly kind: 'fallback' }
+  | {
+    readonly kind: 'provider'
+    readonly provider: SessionTitleProviderId
+    readonly model?: SessionTitleModelProvenance
+  }
+
+/** Payload of the log-only `session/title` event. */
+export interface SessionTitleEventData {
+  /** Normalized non-empty title text. */
+  readonly title: string
+  /** Exact human `user/message` seqs used to derive this title. */
+  readonly messageSeqs: number[]
+  /** Built-in fallback or registered-provider provenance. */
+  readonly source: SessionTitleSource
+}
+
+/** Latest folded title plus the title event's durable envelope facts. */
+export interface SessionTitleSnapshot extends SessionTitleEventData {
+  /** Seq of the latest `session/title` event. */
+  readonly eventSeq: number
+  /** Timestamp of the latest `session/title` event. */
+  readonly updatedAt: number
+}
+
+/** Required deterministic fallback and accepted-title limits. */
+export interface Config {
+  /** Maximum whitespace-delimited words in the built-in fallback. */
+  readonly fallbackMaxWords: number
+  /** Maximum UTF-8 bytes in the built-in fallback. */
+  readonly fallbackMaxBytes: number
+  /** Maximum UTF-8 bytes in any accepted title. */
+  readonly maxTitleBytes: number
+}
+
+declare module 'cordis' {
+  interface Context {
+    sessionTitle: SessionTitleService
+  }
+}
+
+declare module '@deepseek-ai/dsh-session' {
+  interface TurnTriggerMap {
+    /** Zero-step turn opened only to durably append a late title update. */
+    'session-title': { kind: 'session-title' }
+  }
+
+  interface SessionEventMap {
+    /**
+     * Latest-wins session title snapshot. Log-only: it never enters the model
+     * surface or derived history.
+     */
+    'session/title': SessionTitleEventData
+  }
+
+  interface OutOfBandSessionEventMap {
+    'session/title': true
+  }
+}
+
+/** One eligible human text message exposed to title providers. */
+export interface SessionTitleUserMessage {
+  /** Source `user/message` event seq. */
+  readonly seq: number
+  /** Exact concatenated text-block content. */
+  readonly text: string
+}
+
+/** Automatic generation cadence owned by a registered provider. */
+export type SessionTitleAutomaticMode = 'first-message' | 'all-user-messages'
+
+/** Immutable input supplied to one title-provider call. */
+export interface SessionTitleProviderRequest {
+  /** Live session being titled. */
+  readonly session: Session
+  /** All eligible human messages through this generation revision. */
+  readonly messages: readonly SessionTitleUserMessage[]
+  /** Exact current logged main-request route, when one has been recorded. */
+  readonly route?: SessionTitleModelProvenance
+  /** Cancellation for supersession, disposal, timeout composition, or the explicit caller. */
+  readonly signal: AbortSignal
+}
+
+/** Provider output before service-owned normalization and durable acceptance. */
+export interface SessionTitleProviderResult {
+  /** Proposed title text. */
+  readonly title: string
+  /** Exact seqs from `request.messages` used by this result. */
+  readonly messageSeqs: readonly number[]
+  /** Auxiliary LLM route, when generation used a model. */
+  readonly model?: SessionTitleModelProvenance
+}
+
+/** One optional asynchronous title implementation registered with the service. */
+export interface SessionTitleProvider {
+  /** Stable provider identity recorded in title provenance. */
+  readonly id: SessionTitleProviderId
+  /** When new human prompts start automatic generation. */
+  readonly automatic: SessionTitleAutomaticMode
+  /**
+   * Produce one title revision.
+   * @param request - message snapshot, current route, session, and cancellation.
+   * @returns proposed title plus exact input seqs and optional model provenance.
+   */
+  generate(request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult>
+}
+
+/**
+ * Collect human text-bearing user messages in log order.
+ * @param events - session log or persisted replay.
+ * @param throughSeq - optional inclusive event boundary.
+ * @returns eligible messages with exact source seqs.
+ */
+export function collectSessionTitleMessages(
+  events: readonly SessionEvent[],
+  throughSeq?: number,
+): SessionTitleUserMessage[] {
+  const messages: SessionTitleUserMessage[] = []
+  for (const event of events) {
+    if (throughSeq !== undefined && event.seq > throughSeq) break
+    if (event.type !== 'user/message' || event.data.source.kind !== 'user') continue
+    const text = event.data.content
+      .filter((block): block is Extract<(typeof event.data.content)[number], { type: 'text' }> => block.type === 'text')
+      .map(block => block.text)
+      .join('\n')
+    if (normalizeSessionTitle(text, Number.MAX_SAFE_INTEGER).length === 0) continue
+    messages.push({ seq: event.seq, text })
+  }
+  return messages
+}
+
+/**
+ * Fold the latest logged title without consulting mutable metadata.
+ * @param events - live or persisted session log.
+ * @returns the latest immutable title snapshot, or `undefined`.
+ */
+export function foldSessionTitle(events: readonly SessionEvent[]): SessionTitleSnapshot | undefined {
+  const event = events.findLast(item => item.type === 'session/title')
+  if (event === undefined) return undefined
+  return deepFreeze({
+    title: event.data.title,
+    messageSeqs: [...event.data.messageSeqs],
+    source: event.data.source.kind === 'fallback'
+      ? { kind: 'fallback' }
+      : {
+        kind: 'provider',
+        provider: event.data.source.provider,
+        ...(event.data.source.model === undefined
+          ? {}
+          : { model: { ...event.data.source.model } }),
+      },
+    eventSeq: event.seq,
+    updatedAt: event.time,
+  })
+}
+
+/** Service-owned resolved limits. */
+interface ResolvedConfig {
+  readonly fallbackMaxWords: number
+  readonly fallbackMaxBytes: number
+  readonly maxTitleBytes: number
+}
+
+/** One exact provider registration generation. */
+interface ProviderRegistration {
+  readonly provider: SessionTitleProvider
+}
+
+/** Automatic work waiting for the matching main-request header. */
+interface PendingAutomaticWork {
+  readonly registration: ProviderRegistration
+  readonly revision: number
+  readonly throughSeq: number
+}
+
+/** Provider call currently allowed to commit for one session. */
+interface ActiveProviderWork extends PendingAutomaticWork {
+  readonly controller: AbortController
+  readonly signal: AbortSignal
+}
+
+/** Mutable concurrency state scoped to one live session. */
+interface SessionTitleWorkState {
+  revision: number
+  pending?: PendingAutomaticWork
+  active?: ActiveProviderWork
+}
+
+/** Validate one positive integer configuration field. */
+function assertPositiveInteger(name: keyof Config, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`session-title: ${name} must be a positive integer`)
+  }
+}
+
+/** Log-backed title fold plus asynchronous fallback generation. */
+export class SessionTitleService extends Service {
+  static inject = ['sessions']
+  static Config: z<Config> = z.object({
+    fallbackMaxWords: z.number().step(1).min(1).required(),
+    fallbackMaxBytes: z.number().step(1).min(1).required(),
+    maxTitleBytes: z.number().step(1).min(1).required(),
+  })
+
+  private readonly config: ResolvedConfig
+  private registration: ProviderRegistration | undefined
+  private readonly work = new Map<Session, SessionTitleWorkState>()
+
+  constructor(ctx: Context, config: Config) {
+    super(ctx, 'sessionTitle')
+    const candidate: unknown = config
+    if (candidate === null || typeof candidate !== 'object') {
+      throw new Error('session-title: configuration is required')
+    }
+    const value = candidate as Config
+    assertPositiveInteger('fallbackMaxWords', value.fallbackMaxWords)
+    assertPositiveInteger('fallbackMaxBytes', value.fallbackMaxBytes)
+    assertPositiveInteger('maxTitleBytes', value.maxTitleBytes)
+    if (value.fallbackMaxBytes > value.maxTitleBytes) {
+      throw new Error('session-title: fallbackMaxBytes must not exceed maxTitleBytes')
+    }
+    this.config = deepFreeze({ ...value })
+
+    ctx.on('session/event', (session, event) => {
+      switch (event.type) {
+        case 'user/message':
+          this.onUserMessage(session, event)
+          break
+        case 'request/header':
+          this.onRequestHeader(session, event)
+          break
+        default:
+          break
+      }
+    })
+    ctx.on('session/disposed', (session) => {
+      const state = this.work.get(session)
+      if (state === undefined) return
+      state.active?.controller.abort(new Error('session disposed during title generation'))
+      this.work.delete(session)
+    })
+  }
+
+  /**
+   * Read the latest folded title from one live or replayed session.
+   * @param session - session whose log is the title source of truth.
+   * @returns latest title snapshot, or `undefined` before eligible input.
+   */
+  get(session: Session): SessionTitleSnapshot | undefined {
+    return foldSessionTitle(session.events)
+  }
+
+  /**
+   * Explicitly retry the registered provider, or materialize the built-in
+   * fallback when no provider is registered.
+   * @param session - exact live session to refresh.
+   * @param signal - optional caller cancellation.
+   * @returns latest accepted title, or `undefined` when no eligible text exists.
+   */
+  async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined> {
+    signal?.throwIfAborted()
+    if (this.ctx.sessions.get(session.id) !== session) {
+      throw new Error(`session "${session.id}" is not live in this store`)
+    }
+    const fallback = await this.ensureFallback(session)
+    const registration = this.registration
+    if (registration === undefined) return fallback
+    const messages = collectSessionTitleMessages(session.events)
+    const latest = messages.at(-1)
+    if (latest === undefined) return fallback
+    const state = this.stateFor(session)
+    const revision = this.supersede(state, 'explicit title refresh superseded older generation')
+    const work = this.activate({
+      registration,
+      revision,
+      throughSeq: latest.seq,
+    }, state, signal)
+    const config = session.requestHeader()?.config
+    const route = config === undefined ? undefined : { provider: config.provider, model: config.model }
+    return this.runProvider(session, work, route)
+  }
+
+  /**
+   * Register the sole optional title provider. Disposal aborts its pending and
+   * active work before another provider may register.
+   * @param provider - provider identity, cadence, and generation function.
+   * @returns exact Cordis effect disposer for HMR-safe unregistration.
+   */
+  register(provider: SessionTitleProvider): () => void {
+    this.validateProvider(provider)
+    if (this.registration !== undefined) {
+      throw new Error(`session-title provider "${this.registration.provider.id}" is already registered`)
+    }
+    const registration: ProviderRegistration = {
+      provider,
+    }
+    const dispose = this.ctx.effect(function* (this: SessionTitleService) {
+      this.registration = registration
+      yield () => {
+        this.registration = undefined
+        for (const state of this.work.values()) {
+          delete state.pending
+          state.active?.controller.abort(new Error(`session-title provider "${provider.id}" was disposed`))
+        }
+      }
+    }.bind(this), 'sessionTitle.register()')
+    // eslint-disable-next-line @typescript-eslint/no-misused-promises -- exact effect disposer preserves owner teardown ordering
+    return dispose
+  }
+
+  /** Schedule fallback creation and any provider cadence for one eligible event. */
+  private onUserMessage(session: Session, event: Extract<SessionEvent, { type: 'user/message' }>): void {
+    if (event.data.source.kind !== 'user' || collectSessionTitleMessages([event]).length === 0) return
+    const registration = this.registration
+    if (registration !== undefined) {
+      const messages = collectSessionTitleMessages(session.events, event.seq)
+      const shouldSchedule = registration.provider.automatic === 'all-user-messages'
+        || (session.header.parentSession === undefined && messages.length === 1 && this.get(session) === undefined)
+      if (shouldSchedule) {
+        const state = this.stateFor(session)
+        const revision = this.supersede(state, 'newer user message superseded title generation')
+        state.pending = { registration, revision, throughSeq: event.seq }
+      }
+    }
+    queueMicrotask(() => {
+      void this.ensureFallback(session).catch((error: unknown) => {
+        this.ctx.logger.warn(`session "${session.id}": fallback title update failed: ${String(error)}`)
+      })
+    })
+  }
+
+  /** Start pending automatic work only after its exact main-request route is logged. */
+  private onRequestHeader(session: Session, event: Extract<SessionEvent, { type: 'request/header' }>): void {
+    const state = this.work.get(session)
+    const pending = state?.pending
+    if (state === undefined || pending === undefined || pending.throughSeq >= event.seq) return
+    delete state.pending
+    const route = {
+      provider: event.data.header.config.provider,
+      model: event.data.header.config.model,
+    }
+    queueMicrotask(() => {
+      if (this.registration !== pending.registration || state.revision !== pending.revision) return
+      const work = this.activate(pending, state)
+      void this.runProvider(session, work, route).catch((error: unknown) => {
+        if (work.signal.aborted) return
+        this.ctx.logger.warn(`session "${session.id}": automatic title generation failed: ${String(error)}`)
+      })
+    })
+  }
+
+  /** Execute and durably accept one current provider revision. */
+  private async runProvider(
+    session: Session,
+    work: ActiveProviderWork,
+    route?: SessionTitleModelProvenance,
+  ): Promise<SessionTitleSnapshot | undefined> {
+    try {
+      await this.ensureFallback(session)
+      this.assertCurrent(session, work)
+      const messages = collectSessionTitleMessages(session.events, work.throughSeq)
+      const result = await work.registration.provider.generate({
+        session,
+        messages,
+        ...route === undefined ? {} : { route },
+        signal: work.signal,
+      })
+      this.assertCurrent(session, work)
+      const accepted = this.validateResult(result, messages)
+      await this.ctx.sessions.appendOutOfBand(session, 'session/title', {
+        title: accepted.title,
+        messageSeqs: [...accepted.messageSeqs],
+        source: {
+          kind: 'provider',
+          provider: work.registration.provider.id,
+          ...accepted.model === undefined ? {} : { model: accepted.model },
+        },
+      }, { kind: 'session-title' })
+      return this.get(session)
+    } finally {
+      const state = this.work.get(session)
+      if (state?.active === work) delete state.active
+    }
+  }
+
+  /** Validate and normalize provider output against the supplied message snapshot. */
+  private validateResult(
+    result: unknown,
+    messages: readonly SessionTitleUserMessage[],
+  ): SessionTitleProviderResult {
+    if (result === null || typeof result !== 'object') {
+      throw new Error('session-title provider returned an invalid result')
+    }
+    const candidate = result as Record<string, unknown>
+    if (typeof candidate.title !== 'string') throw new Error('session-title provider title must be a string')
+    const title = normalizeSessionTitle(candidate.title, this.config.maxTitleBytes)
+    if (title.length === 0) throw new Error('session-title provider returned an empty title')
+    if (!Array.isArray(candidate.messageSeqs) || candidate.messageSeqs.length === 0) {
+      throw new Error('session-title provider must identify at least one source message seq')
+    }
+    const messageSeqs: number[] = []
+    const order = new Map(messages.map((message, index) => [message.seq, index]))
+    let previous = -1
+    for (const seq of candidate.messageSeqs as unknown[]) {
+      if (typeof seq !== 'number') {
+        throw new Error('session-title provider messageSeqs must be unique, ordered seqs from the request')
+      }
+      const index = order.get(seq)
+      if (!Number.isSafeInteger(seq) || seq < 0 || index === undefined || index <= previous) {
+        throw new Error('session-title provider messageSeqs must be unique, ordered seqs from the request')
+      }
+      messageSeqs.push(seq)
+      previous = index
+    }
+    const modelCandidate = candidate.model
+    let model: SessionTitleModelProvenance | undefined
+    if (modelCandidate !== undefined) {
+      if (modelCandidate === null || typeof modelCandidate !== 'object') {
+        throw new Error('session-title provider model provenance requires non-empty provider and model')
+      }
+      const record = modelCandidate as Record<string, unknown>
+      if (typeof record.provider !== 'string' || record.provider.length === 0
+        || typeof record.model !== 'string' || record.model.length === 0) {
+        throw new Error('session-title provider model provenance requires non-empty provider and model')
+      }
+      model = { provider: record.provider, model: record.model }
+    }
+    return {
+      title,
+      messageSeqs,
+      ...(model === undefined ? {} : { model }),
+    }
+  }
+
+  /** Fail a completion whose provider, revision, session, or signal is stale. */
+  private assertCurrent(session: Session, work: ActiveProviderWork): void {
+    work.signal.throwIfAborted()
+    const state = this.work.get(session)
+    /* v8 ignore next -- every supported supersession, provider disposal, and session disposal aborts
+     * the work signal before changing this state. */
+    if (this.registration !== work.registration
+      || state?.active !== work
+      || state.revision !== work.revision
+      || this.ctx.sessions.get(session.id) !== session) {
+      throw new Error('session title generation state changed without cancellation')
+    }
+  }
+
+  /** Create and publish an active provider call from one fixed revision. */
+  private activate(
+    pending: PendingAutomaticWork,
+    state: SessionTitleWorkState,
+    upstream?: AbortSignal,
+  ): ActiveProviderWork {
+    const controller = new AbortController()
+    const signal = upstream === undefined
+      ? controller.signal
+      : AbortSignal.any([controller.signal, upstream])
+    const work: ActiveProviderWork = { ...pending, controller, signal }
+    state.active = work
+    return work
+  }
+
+  /** Abort older active work and reserve the next session-local revision. */
+  private supersede(state: SessionTitleWorkState, reason: string): number {
+    state.active?.controller.abort(new Error(reason))
+    delete state.pending
+    state.revision += 1
+    return state.revision
+  }
+
+  /** Return mutable work state for one session. */
+  private stateFor(session: Session): SessionTitleWorkState {
+    let state = this.work.get(session)
+    if (state === undefined) {
+      state = { revision: 0 }
+      this.work.set(session, state)
+    }
+    return state
+  }
+
+  /** Reject malformed provider registrations before publishing an effect. */
+  private validateProvider(provider: unknown): asserts provider is SessionTitleProvider {
+    if (provider === null || typeof provider !== 'object') {
+      throw new Error('session-title provider must be an object')
+    }
+    const candidate = provider as Record<string, unknown>
+    if (typeof candidate.id !== 'string' || candidate.id.length === 0) {
+      throw new Error('session-title provider id must be a non-empty string')
+    }
+    if (candidate.automatic !== 'first-message' && candidate.automatic !== 'all-user-messages') {
+      throw new Error('session-title provider automatic mode is invalid')
+    }
+    if (typeof candidate.generate !== 'function') {
+      throw new Error(`session-title provider "${candidate.id}" requires generate()`)
+    }
+  }
+
+  /** Create the first deterministic fallback if the session still lacks a title. */
+  private async ensureFallback(session: Session): Promise<SessionTitleSnapshot | undefined> {
+    const current = this.get(session)
+    if (current !== undefined) return current
+    const [first] = collectSessionTitleMessages(session.events)
+    if (first === undefined) return undefined
+    const title = fallbackSessionTitle(
+      first.text,
+      this.config.fallbackMaxWords,
+      this.config.fallbackMaxBytes,
+    )
+    if (title.length === 0) return undefined
+    await this.ctx.sessions.appendOutOfBand(session, 'session/title', {
+      title,
+      messageSeqs: [first.seq],
+      source: { kind: 'fallback' },
+    }, { kind: 'session-title' })
+    return this.get(session)
+  }
+}
+
+export default SessionTitleService

packages/session-title/session-title/src/normalize.ts

@@ -0,0 +1,74 @@
+/** Title text normalization and UTF-8-safe truncation. */
+
+/** Operating-system-command escape sequences, including unterminated tails. */
+const OSC_SEQUENCE = /(?:\u001B\]|\u009D)(?:(?!\u0007|\u001B\\)[\s\S])*(?:\u0007|\u001B\\|$)/gu
+/** Control-sequence-introducer escapes such as SGR color codes. */
+const CSI_SEQUENCE = /(?:\u001B\[|\u009B)[0-?]*[ -/]*[@-~]/gu
+/** Remaining two-byte ESC control sequences. */
+const ESC_SEQUENCE = /\u001B[@-_]/gu
+/** Non-whitespace C0/C1 control characters. */
+const CONTROL_CHARACTER = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/gu
+/** Directional and invisible controls that can make a displayed title deceptive. */
+const DIRECTIONAL_CONTROL = /[\u200B\u200E\u200F\u202A-\u202E\u2060-\u2064\u2066-\u206F\uFEFF]/gu
+
+/** Reject an invalid public text limit. */
+function assertPositiveInteger(name: string, value: number): void {
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer`)
+  }
+}
+
+/** Remove controls and produce one trimmed, whitespace-normalized line. */
+function cleanTitleText(input: string): string {
+  return input
+    .replace(OSC_SEQUENCE, '')
+    .replace(CSI_SEQUENCE, '')
+    .replace(ESC_SEQUENCE, '')
+    .replace(CONTROL_CHARACTER, '')
+    .replace(DIRECTIONAL_CONTROL, '')
+    .replace(/\s+/gu, ' ')
+    .trim()
+}
+
+/**
+ * Truncate a string to a UTF-8 byte budget without splitting a Unicode code point.
+ * @param input - normalized title text.
+ * @param maxBytes - positive UTF-8 byte budget.
+ * @returns the longest leading code-point prefix within the budget.
+ */
+export function truncateTitleUtf8(input: string, maxBytes: number): string {
+  assertPositiveInteger('maxBytes', maxBytes)
+  if (Buffer.byteLength(input, 'utf8') <= maxBytes) return input
+  let used = 0
+  let output = ''
+  for (const character of input) {
+    const bytes = Buffer.byteLength(character, 'utf8')
+    if (used + bytes > maxBytes) break
+    output += character
+    used += bytes
+  }
+  return output
+}
+
+/**
+ * Normalize one accepted session title and enforce its UTF-8 byte budget.
+ * @param input - untrusted title text.
+ * @param maxBytes - positive maximum encoded size.
+ * @returns a terminal-safe one-line title, possibly empty after sanitization.
+ */
+export function normalizeSessionTitle(input: string, maxBytes: number): string {
+  return truncateTitleUtf8(cleanTitleText(input), maxBytes).trimEnd()
+}
+
+/**
+ * Derive the deterministic first-message fallback.
+ * @param input - text from the first eligible human message.
+ * @param maxWords - positive whitespace-delimited word cap.
+ * @param maxBytes - positive UTF-8 byte cap.
+ * @returns the normalized leading words within both limits.
+ */
+export function fallbackSessionTitle(input: string, maxWords: number, maxBytes: number): string {
+  assertPositiveInteger('maxWords', maxWords)
+  const words = cleanTitleText(input).split(' ').filter(Boolean).slice(0, maxWords)
+  return truncateTitleUtf8(words.join(' '), maxBytes).trimEnd()
+}

packages/session-title/session-title/tests/persistence.spec.ts

@@ -0,0 +1,91 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import SessionPersistenceSqlite from '@deepseek-ai/dsh-session-persistence-sqlite'
+import SessionTitleService, { foldSessionTitle } from '@deepseek-ai/dsh-session-title'
+
+const CONFIG = {
+  fallbackMaxWords: 5,
+  fallbackMaxBytes: 40,
+  maxTitleBytes: 80,
+} as const
+
+const roots: string[] = []
+
+afterEach(async () => {
+  for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true })
+})
+
+async function appendPersistedTitle(ctx: Context, id: ReturnType<typeof SessionId>): Promise<void> {
+  const session = ctx.sessions.create(id)
+  session.append('turn/start', {
+    turn: 1,
+    trigger: { kind: 'message', source: { kind: 'user' } },
+  })
+  session.append('user/message', {
+    content: [{ type: 'text', text: 'Persist this session title' }],
+    source: { kind: 'user' },
+  }, { surfaceOp: 'append' })
+  await new Promise(resolve => setTimeout(resolve, 0))
+  session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+  await ctx.parallel('session/flush', session)
+}
+
+async function expectPersistedTitle(ctx: Context, id: ReturnType<typeof SessionId>): Promise<void> {
+  const loaded = await ctx.sessionPersistence.load(id)
+  expect(foldSessionTitle(loaded.events)).toMatchObject({
+    title: 'Persist this session title',
+    messageSeqs: [1],
+    source: { kind: 'fallback' },
+    eventSeq: 2,
+  })
+  expect(loaded.events.map(event => event.type)).toEqual([
+    'turn/start',
+    'user/message',
+    'session/title',
+    'turn/end',
+  ])
+}
+
+describe('session title persistence round trips', () => {
+  it('round-trips through a remounted JSONL backend', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-title-jsonl-'))
+    roots.push(root)
+    const id = SessionId('title-jsonl')
+    const writer = new Context()
+    await writer.plugin(SessionStore)
+    await writer.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
+    await writer.plugin(SessionTitleService, CONFIG)
+    await appendPersistedTitle(writer, id)
+    await writer.fiber.dispose()
+
+    const reader = new Context()
+    await reader.plugin(SessionStore)
+    await reader.plugin(SessionPersistenceJsonl, { root, compression: 'none' })
+    await expectPersistedTitle(reader, id)
+    await reader.fiber.dispose()
+  })
+
+  it('round-trips through a remounted SQLite backend', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-title-sqlite-'))
+    roots.push(root)
+    const path = join(root, 'sessions.db')
+    const id = SessionId('title-sqlite')
+    const writer = new Context()
+    await writer.plugin(SessionStore)
+    await writer.plugin(SessionPersistenceSqlite, { path })
+    await writer.plugin(SessionTitleService, CONFIG)
+    await appendPersistedTitle(writer, id)
+    await writer.fiber.dispose()
+
+    const reader = new Context()
+    await reader.plugin(SessionStore)
+    await reader.plugin(SessionPersistenceSqlite, { path })
+    await expectPersistedTitle(reader, id)
+    await reader.fiber.dispose()
+  })
+})

packages/session-title/session-title/tests/provider.spec.ts

@@ -0,0 +1,289 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SessionTitleService, {
+  SessionTitleProviderId,
+  type SessionTitleProvider,
+  type SessionTitleProviderRequest,
+  type SessionTitleProviderResult,
+} from '@deepseek-ai/dsh-session-title'
+
+const CONFIG = {
+  fallbackMaxWords: 5,
+  fallbackMaxBytes: 24,
+  maxTitleBytes: 24,
+} as const
+
+function deferred<T>(): {
+  promise: Promise<T>
+  resolve(value: T): void
+  reject(error: unknown): void
+} {
+  let resolve!: (value: T) => void
+  let reject!: (error: unknown) => void
+  const promise = new Promise<T>((accept, decline) => {
+    resolve = accept
+    reject = decline
+  })
+  return { promise, resolve, reject }
+}
+
+async function settle(): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, 0))
+}
+
+function appendHumanPrompt(session: ReturnType<Context['sessions']['create']>, text: string) {
+  return session.append('user/message', {
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  }, { surfaceOp: 'append' })
+}
+
+function appendRoute(session: ReturnType<Context['sessions']['create']>, reason: 'initial' | 'change' = 'initial'): void {
+  session.append('request/header', {
+    header: { config: { provider: 'main-route', model: 'chat-model' } },
+    reason,
+  })
+}
+
+describe('SessionTitleService provider lifecycle', () => {
+  it('inherits title events across forks, skips first-message retitling, and lets all-messages update later', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const parent = ctx.sessions.create(SessionId('title-parent'))
+    parent.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const inheritedMessage = appendHumanPrompt(parent, 'Inherited title prompt')
+    await settle()
+    parent.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+    const child = ctx.sessions.fork(parent, undefined, SessionId('title-child'))
+    expect(ctx.sessionTitle.get(child)).toEqual(ctx.sessionTitle.get(parent))
+    expect(child.events.find(event => event.type === 'session/title'))
+      .toEqual(parent.events.find(event => event.type === 'session/title'))
+
+    const firstGenerate = vi.fn(async (request: SessionTitleProviderRequest) => ({
+      title: 'Should not run',
+      messageSeqs: [request.messages[0]!.seq],
+    }))
+    const disposeFirst = ctx.sessionTitle.register({
+      id: SessionTitleProviderId('fork-first'),
+      automatic: 'first-message',
+      generate: firstGenerate,
+    })
+    child.append('turn/start', {
+      turn: 2,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const childMessage = appendHumanPrompt(child, 'Child follow-up prompt')
+    await settle()
+    appendRoute(child)
+    await settle()
+    child.append('turn/end', { turn: 2, reason: { kind: 'completed' } })
+    expect(firstGenerate).not.toHaveBeenCalled()
+    disposeFirst()
+
+    const allGenerate = vi.fn(async (request: SessionTitleProviderRequest) => ({
+      title: 'Fork all prompts',
+      messageSeqs: request.messages.map(message => message.seq),
+    }))
+    ctx.sessionTitle.register({
+      id: SessionTitleProviderId('fork-all'),
+      automatic: 'all-user-messages',
+      generate: allGenerate,
+    })
+    child.append('turn/start', {
+      turn: 3,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const latestMessage = appendHumanPrompt(child, 'Retitle the fork now')
+    await settle()
+    appendRoute(child, 'change')
+    await settle()
+    child.append('turn/end', { turn: 3, reason: { kind: 'completed' } })
+
+    expect(allGenerate).toHaveBeenCalledOnce()
+    expect(ctx.sessionTitle.get(child)).toMatchObject({
+      title: 'Fork all prompts',
+      messageSeqs: [inheritedMessage.seq, childMessage.seq, latestMessage.seq],
+      source: { kind: 'provider', provider: SessionTitleProviderId('fork-all') },
+    })
+    expect(ctx.sessionTitle.get(parent)?.title).toBe('Inherited title prompt')
+  })
+
+  it('runs a first-message provider once after the routed request and retries only through refresh', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const requests: SessionTitleProviderRequest[] = []
+    const provider: SessionTitleProvider = {
+      id: SessionTitleProviderId('first-model'),
+      automatic: 'first-message',
+      async generate(request) {
+        requests.push(request)
+        return {
+          title: '\u001B[31m  A   model-generated title that is too long  ',
+          messageSeqs: [request.messages[0]!.seq],
+          model: { provider: 'aux-route', model: 'title-model' },
+        }
+      },
+    }
+    ctx.sessionTitle.register(provider)
+    const session = ctx.sessions.create(SessionId('first-provider'))
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const first = appendHumanPrompt(session, 'Explain asynchronous title generation')
+    await settle()
+    expect(ctx.sessionTitle.get(session)?.source.kind).toBe('fallback')
+
+    appendRoute(session)
+    await settle()
+
+    expect(requests).toHaveLength(1)
+    expect(requests[0]).toMatchObject({
+      session,
+      messages: [{ seq: first.seq, text: 'Explain asynchronous title generation' }],
+      route: { provider: 'main-route', model: 'chat-model' },
+    })
+    expect(ctx.sessionTitle.get(session)).toMatchObject({
+      title: 'A model-generated title',
+      messageSeqs: [first.seq],
+      source: {
+        kind: 'provider',
+        provider: SessionTitleProviderId('first-model'),
+        model: { provider: 'aux-route', model: 'title-model' },
+      },
+    })
+
+    const second = appendHumanPrompt(session, 'A later prompt')
+    appendRoute(session, 'change')
+    await settle()
+    expect(requests).toHaveLength(1)
+
+    await ctx.sessionTitle.refresh(session)
+    expect(requests).toHaveLength(2)
+    expect(requests[1]?.messages.map(message => message.seq)).toEqual([first.seq, second.seq])
+  })
+
+  it('rejects a second provider and aborts stale work when the winner is disposed', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const pending = deferred<SessionTitleProviderResult>()
+    let observedSignal: AbortSignal | undefined
+    const first: SessionTitleProvider = {
+      id: SessionTitleProviderId('winner'),
+      automatic: 'all-user-messages',
+      generate(request) {
+        observedSignal = request.signal
+        return pending.promise
+      },
+    }
+    const dispose = ctx.sessionTitle.register(first)
+    expect(() => ctx.sessionTitle.register({
+      id: SessionTitleProviderId('duplicate'),
+      automatic: 'first-message',
+      generate: async () => ({ title: 'duplicate', messageSeqs: [0] }),
+    })).toThrow(/already registered/)
+
+    const session = ctx.sessions.create(SessionId('dispose-provider'))
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const message = appendHumanPrompt(session, 'Generate this title')
+    await settle()
+    appendRoute(session)
+    await settle()
+    expect(observedSignal?.aborted).toBe(false)
+
+    dispose()
+    expect(observedSignal?.aborted).toBe(true)
+    pending.resolve({ title: 'stale provider result', messageSeqs: [message.seq] })
+    await settle()
+    expect(ctx.sessionTitle.get(session)?.source.kind).toBe('fallback')
+
+    const replacement: SessionTitleProvider = {
+      id: SessionTitleProviderId('replacement'),
+      automatic: 'first-message',
+      generate: async () => ({ title: 'replacement', messageSeqs: [message.seq] }),
+    }
+    const disposeReplacement = ctx.sessionTitle.register(replacement)
+    disposeReplacement()
+  })
+
+  it('supersedes an older all-messages revision and cannot commit an ignored abort', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const firstResult = deferred<SessionTitleProviderResult>()
+    const requests: SessionTitleProviderRequest[] = []
+    const provider: SessionTitleProvider = {
+      id: SessionTitleProviderId('all-model'),
+      automatic: 'all-user-messages',
+      generate(request) {
+        requests.push(request)
+        if (requests.length === 1) return firstResult.promise
+        return Promise.resolve({
+          title: 'Newest complete title',
+          messageSeqs: request.messages.map(message => message.seq),
+        })
+      },
+    }
+    ctx.sessionTitle.register(provider)
+    const session = ctx.sessions.create(SessionId('supersede'))
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const first = appendHumanPrompt(session, 'First prompt')
+    await settle()
+    appendRoute(session)
+    await settle()
+
+    const second = appendHumanPrompt(session, 'Second prompt')
+    expect(requests[0]?.signal.aborted).toBe(true)
+    appendRoute(session, 'change')
+    await settle()
+    expect(ctx.sessionTitle.get(session)).toMatchObject({
+      title: 'Newest complete title',
+      messageSeqs: [first.seq, second.seq],
+    })
+
+    firstResult.resolve({ title: 'Old ignored result', messageSeqs: [first.seq] })
+    await settle()
+    expect(ctx.sessionTitle.get(session)?.title).toBe('Newest complete title')
+  })
+
+  it('contains automatic failures but lets explicit refresh reject', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const provider: SessionTitleProvider = {
+      id: SessionTitleProviderId('failing'),
+      automatic: 'all-user-messages',
+      generate: async () => { throw new Error('title backend failed') },
+    }
+    ctx.sessionTitle.register(provider)
+    const session = ctx.sessions.create(SessionId('failure'))
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    appendHumanPrompt(session, 'Keep a fallback')
+    await settle()
+    appendRoute(session)
+    await settle()
+
+    expect(ctx.sessionTitle.get(session)?.source.kind).toBe('fallback')
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('automatic title generation failed'))
+    await expect(ctx.sessionTitle.refresh(session)).rejects.toThrow('title backend failed')
+    warn.mockRestore()
+  })
+})

packages/session-title/session-title/tests/service-contracts.spec.ts

@@ -0,0 +1,287 @@
+import { Context } from 'cordis'
+import { describe, expect, it, vi } from 'vitest'
+import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionTitleService, {
+  SessionTitleProviderId,
+  type Config,
+  type SessionTitleProvider,
+  type SessionTitleProviderRequest,
+  type SessionTitleProviderResult,
+} from '@deepseek-ai/dsh-session-title'
+
+const CONFIG = {
+  fallbackMaxWords: 5,
+  fallbackMaxBytes: 40,
+  maxTitleBytes: 80,
+} as const
+
+function deferred<T>(): { promise: Promise<T>; resolve(value: T): void } {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((accept) => { resolve = accept })
+  return { promise, resolve }
+}
+
+async function settle(): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, 0))
+}
+
+async function setup(config: Config = CONFIG): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SessionTitleService, config)
+  return ctx
+}
+
+function startSession(ctx: Context, id: string): ReturnType<Context['sessions']['create']> {
+  const session = ctx.sessions.create(SessionId(id))
+  session.append('turn/start', {
+    turn: 1,
+    trigger: { kind: 'message', source: { kind: 'user' } },
+  })
+  return session
+}
+
+function appendPrompt(session: ReturnType<Context['sessions']['create']>, text: string) {
+  return session.append('user/message', {
+    content: [{ type: 'text', text }],
+    source: { kind: 'user' },
+  }, { surfaceOp: 'append' })
+}
+
+describe('SessionTitleService configuration and refresh boundaries', () => {
+  it('requires explicit positive limits with a fallback cap no larger than the accepted-title cap', () => {
+    expect(() => new SessionTitleService(new Context(), undefined as never))
+      .toThrow('configuration is required')
+    expect(() => new SessionTitleService(new Context(), null as never))
+      .toThrow('configuration is required')
+    expect(() => new SessionTitleService(new Context(), { ...CONFIG, fallbackMaxWords: 0 }))
+      .toThrow(/fallbackMaxWords must be a positive integer/)
+    expect(() => new SessionTitleService(new Context(), { ...CONFIG, fallbackMaxWords: 1.5 }))
+      .toThrow(/fallbackMaxWords must be a positive integer/)
+    expect(() => new SessionTitleService(new Context(), { ...CONFIG, fallbackMaxBytes: 81 }))
+      .toThrow(/fallbackMaxBytes must not exceed maxTitleBytes/)
+  })
+
+  it('returns no title for empty input with or without a provider, and rejects detached or pre-aborted refreshes', async () => {
+    const fallbackOnly = await setup()
+    const empty = fallbackOnly.sessions.create(SessionId('empty-fallback'))
+    await expect(fallbackOnly.sessionTitle.refresh(empty)).resolves.toBeUndefined()
+
+    const withProvider = await setup()
+    const generate = vi.fn(async (): Promise<SessionTitleProviderResult> => ({
+      title: 'unused',
+      messageSeqs: [0],
+    }))
+    withProvider.sessionTitle.register({
+      id: SessionTitleProviderId('empty-provider'),
+      automatic: 'first-message',
+      generate,
+    })
+    const providerEmpty = withProvider.sessions.create(SessionId('empty-provider'))
+    await expect(withProvider.sessionTitle.refresh(providerEmpty)).resolves.toBeUndefined()
+    expect(generate).not.toHaveBeenCalled()
+
+    await expect(withProvider.sessionTitle.refresh(new Session(SessionId('detached'))))
+      .rejects.toThrow(/not live in this store/)
+    const controller = new AbortController()
+    controller.abort(new Error('already cancelled'))
+    await expect(withProvider.sessionTitle.refresh(providerEmpty, controller.signal))
+      .rejects.toThrow('already cancelled')
+  })
+
+  it('passes an absent route and caller cancellation into explicit generation', async () => {
+    const ctx = await setup()
+    let observed: SessionTitleProviderRequest | undefined
+    ctx.sessionTitle.register({
+      id: SessionTitleProviderId('explicit-no-route'),
+      automatic: 'first-message',
+      async generate(request) {
+        observed = request
+        return { title: 'Explicit title', messageSeqs: [request.messages[0]!.seq] }
+      },
+    })
+    const session = startSession(ctx, 'explicit-no-route')
+    appendPrompt(session, 'Refresh before any request header')
+    await settle()
+    const controller = new AbortController()
+
+    await expect(ctx.sessionTitle.refresh(session, controller.signal))
+      .resolves.toMatchObject({ title: 'Explicit title' })
+    expect(observed?.route).toBeUndefined()
+    expect(observed?.signal.aborted).toBe(false)
+  })
+
+  it('propagates explicit cancellation and session disposal to active work', async () => {
+    const callerCtx = await setup()
+    const callerPending = deferred<SessionTitleProviderResult>()
+    let callerSignal: AbortSignal | undefined
+    callerCtx.sessionTitle.register({
+      id: SessionTitleProviderId('caller-cancel'),
+      automatic: 'first-message',
+      generate(request) {
+        callerSignal = request.signal
+        return callerPending.promise
+      },
+    })
+    const callerSession = startSession(callerCtx, 'caller-cancel')
+    const callerMessage = appendPrompt(callerSession, 'Cancel this refresh')
+    await settle()
+    const controller = new AbortController()
+    const refresh = callerCtx.sessionTitle.refresh(callerSession, controller.signal)
+    await settle()
+    controller.abort(new Error('caller cancelled'))
+    callerPending.resolve({ title: 'ignored', messageSeqs: [callerMessage.seq] })
+    await expect(refresh).rejects.toThrow('caller cancelled')
+    expect(callerSignal?.aborted).toBe(true)
+
+    const disposeCtx = await setup()
+    const disposePending = deferred<SessionTitleProviderResult>()
+    let disposeSignal: AbortSignal | undefined
+    disposeCtx.sessionTitle.register({
+      id: SessionTitleProviderId('session-dispose'),
+      automatic: 'first-message',
+      generate(request) {
+        disposeSignal = request.signal
+        return disposePending.promise
+      },
+    })
+    const disposed = disposeCtx.sessions.prepare(SessionId('session-dispose'))
+    const detach = disposeCtx.sessions.enter(disposed)
+    disposeCtx.sessions.announce(disposed)
+    disposed.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const disposedMessage = appendPrompt(disposed, 'Dispose this session')
+    await settle()
+    const disposedRefresh = disposeCtx.sessionTitle.refresh(disposed)
+    await settle()
+    detach()
+    disposePending.resolve({ title: 'ignored', messageSeqs: [disposedMessage.seq] })
+    await expect(disposedRefresh).rejects.toThrow(/session disposed/)
+    expect(disposeSignal?.aborted).toBe(true)
+  })
+
+  it('warns when a detached session prevents queued fallback publication', async () => {
+    const ctx = await setup()
+    const warn = vi.spyOn(ctx.logger, 'warn').mockImplementation(() => undefined)
+    const session = ctx.sessions.prepare(SessionId('fallback-detach'))
+    const detach = ctx.sessions.enter(session)
+    ctx.sessions.announce(session)
+    ctx.on('session/event', (subject, event) => {
+      if (subject === session && event.type === 'user/message') detach()
+    })
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    appendPrompt(session, 'Detach before the fallback microtask')
+    await settle()
+
+    expect(warn).toHaveBeenCalledWith(expect.stringContaining('fallback title update failed'))
+    expect(ctx.sessionTitle.get(session)).toBeUndefined()
+  })
+
+  it('leaves a title absent when the byte cap cannot hold the first code point', async () => {
+    const ctx = await setup({ fallbackMaxWords: 5, fallbackMaxBytes: 1, maxTitleBytes: 2 })
+    const session = startSession(ctx, 'no-code-point')
+    appendPrompt(session, '😀')
+    await settle()
+    expect(ctx.sessionTitle.get(session)).toBeUndefined()
+    await expect(ctx.sessionTitle.refresh(session)).resolves.toBeUndefined()
+  })
+})
+
+describe('SessionTitleService provider validation and stale scheduling', () => {
+  it('rejects malformed provider registrations before publishing them', async () => {
+    const ctx = await setup()
+    const generate = async (): Promise<SessionTitleProviderResult> => ({ title: 'title', messageSeqs: [0] })
+    expect(() => ctx.sessionTitle.register(null as never)).toThrow(/must be an object/)
+    expect(() => ctx.sessionTitle.register('provider' as never)).toThrow(/must be an object/)
+    expect(() => ctx.sessionTitle.register({
+      id: 1,
+      automatic: 'first-message',
+      generate,
+    } as unknown as SessionTitleProvider)).toThrow(/id must be a non-empty string/)
+    expect(() => ctx.sessionTitle.register({
+      id: SessionTitleProviderId(''),
+      automatic: 'first-message',
+      generate,
+    })).toThrow(/id must be a non-empty string/)
+    expect(() => ctx.sessionTitle.register({
+      id: SessionTitleProviderId('bad-mode'),
+      automatic: 'sometimes' as never,
+      generate,
+    })).toThrow(/automatic mode is invalid/)
+    expect(() => ctx.sessionTitle.register({
+      id: SessionTitleProviderId('missing-generate'),
+      automatic: 'first-message',
+      generate: undefined,
+    } as unknown as SessionTitleProvider)).toThrow(/requires generate/)
+  })
+
+  it('drops automatic work when its provider is disposed before the queued start', async () => {
+    const ctx = await setup()
+    const generate = vi.fn(async (request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult> => ({
+      title: 'too late',
+      messageSeqs: [request.messages[0]!.seq],
+    }))
+    const dispose = ctx.sessionTitle.register({
+      id: SessionTitleProviderId('queued-dispose'),
+      automatic: 'all-user-messages',
+      generate,
+    })
+    const session = startSession(ctx, 'queued-dispose')
+    appendPrompt(session, 'Queue provider work')
+    await settle()
+    session.append('request/header', {
+      header: { config: { provider: 'main', model: 'main' } },
+      reason: 'initial',
+    })
+    dispose()
+    await settle()
+    expect(generate).not.toHaveBeenCalled()
+    expect(ctx.sessionTitle.get(session)?.source.kind).toBe('fallback')
+  })
+
+  it('rejects malformed provider results without replacing the fallback', async () => {
+    const ctx = await setup()
+    let result: unknown
+    ctx.sessionTitle.register({
+      id: SessionTitleProviderId('invalid-results'),
+      automatic: 'first-message',
+      generate: async () => result as SessionTitleProviderResult,
+    })
+    const session = startSession(ctx, 'invalid-results')
+    const first = appendPrompt(session, 'First source')
+    await settle()
+    const second = appendPrompt(session, 'Second source')
+    await settle()
+
+    const cases: Array<{ value: unknown; error: RegExp }> = [
+      { value: null, error: /invalid result/ },
+      { value: 1, error: /invalid result/ },
+      { value: { title: 1, messageSeqs: [first.seq] }, error: /title must be a string/ },
+      { value: { title: '\u001B[31m', messageSeqs: [first.seq] }, error: /empty title/ },
+      { value: { title: 'valid', messageSeqs: undefined }, error: /at least one source message/ },
+      { value: { title: 'valid', messageSeqs: [] }, error: /at least one source message/ },
+      { value: { title: 'valid', messageSeqs: ['not-a-seq'] }, error: /unique, ordered seqs/ },
+      { value: { title: 'valid', messageSeqs: [1.5] }, error: /unique, ordered seqs/ },
+      { value: { title: 'valid', messageSeqs: [-1] }, error: /unique, ordered seqs/ },
+      { value: { title: 'valid', messageSeqs: [999] }, error: /unique, ordered seqs/ },
+      { value: { title: 'valid', messageSeqs: [first.seq, first.seq] }, error: /unique, ordered seqs/ },
+      { value: { title: 'valid', messageSeqs: [second.seq, first.seq] }, error: /unique, ordered seqs/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: null }, error: /model provenance/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: 'route' }, error: /model provenance/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 1, model: 'm' } }, error: /model provenance/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: '', model: 'm' } }, error: /model provenance/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: 1 } }, error: /model provenance/ },
+      { value: { title: 'valid', messageSeqs: [first.seq], model: { provider: 'p', model: '' } }, error: /model provenance/ },
+    ]
+    for (const item of cases) {
+      result = item.value
+      await expect(ctx.sessionTitle.refresh(session)).rejects.toThrow(item.error)
+      expect(ctx.sessionTitle.get(session)?.source.kind).toBe('fallback')
+    }
+  })
+})

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

@@ -0,0 +1,145 @@
+import { Context } from 'cordis'
+import { describe, expect, it } from 'vitest'
+import SessionStore, { Session, SessionId } from '@deepseek-ai/dsh-session'
+import SessionTitleService, {
+  SessionTitleProviderId,
+  fallbackSessionTitle,
+  foldSessionTitle,
+  normalizeSessionTitle,
+  truncateTitleUtf8,
+} from '@deepseek-ai/dsh-session-title'
+
+const CONFIG = {
+  fallbackMaxWords: 5,
+  fallbackMaxBytes: 40,
+  maxTitleBytes: 80,
+} as const
+
+async function settleTitles(): Promise<void> {
+  await new Promise(resolve => setTimeout(resolve, 0))
+}
+
+describe('session title normalization', () => {
+  it('removes terminal controls, collapses whitespace, and applies word and UTF-8 byte caps', () => {
+    expect(normalizeSessionTitle('\u001B]0;stolen\u0007  Hello\t brave\nnew world  ', 80))
+      .toBe('Hello brave new world')
+    expect(fallbackSessionTitle('one two three four', 3, 80)).toBe('one two three')
+    expect(fallbackSessionTitle('你好世界', 5, 7)).toBe('你好')
+    expect(Buffer.byteLength(fallbackSessionTitle('😀😀', 5, 5), 'utf8')).toBe(4)
+  })
+
+  it('rejects non-positive and fractional public limits', () => {
+    expect(() => truncateTitleUtf8('title', 0)).toThrow(/maxBytes must be a positive integer/)
+    expect(() => fallbackSessionTitle('title', 1.5, 10)).toThrow(/maxWords must be a positive integer/)
+  })
+})
+
+describe('SessionTitleService', () => {
+  it('logs and folds an immediate fallback after the first eligible human text message', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const session = ctx.sessions.create(SessionId('fresh'))
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const message = session.append('user/message', {
+      content: [{ type: 'text', text: '  Build\nlog-backed session titles please  ' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+
+    await settleTitles()
+
+    const titleEvent = session.events.findLast(event => event.type === 'session/title')
+    expect(titleEvent).toMatchObject({
+      type: 'session/title',
+      seq: 2,
+      data: {
+        title: 'Build log-backed session titles please',
+        messageSeqs: [message.seq],
+        source: { kind: 'fallback' },
+      },
+    })
+    expect(ctx.sessionTitle.get(session)).toEqual({
+      title: 'Build log-backed session titles please',
+      messageSeqs: [message.seq],
+      source: { kind: 'fallback' },
+      eventSeq: 2,
+      updatedAt: titleEvent?.time,
+    })
+    expect(session.deriveMessages()).toHaveLength(1)
+    expect(session.surface.nodes).toEqual([message.seq])
+  })
+
+  it('waits through synthetic, empty, and non-text messages, then keeps the first fallback', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const session = ctx.sessions.create(SessionId('eligibility'))
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'plugin text' }],
+      source: { kind: 'plugin', plugin: 'seed' },
+    }, { surfaceOp: 'append' })
+    session.append('user/message', {
+      content: [{ type: 'reasoning', text: 'not visible text' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    session.append('user/message', {
+      content: [{ type: 'text', text: ' \n\t ' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    await settleTitles()
+    expect(ctx.sessionTitle.get(session)).toBeUndefined()
+
+    const eligible = session.append('user/message', {
+      content: [{ type: 'text', text: 'first real prompt' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    await settleTitles()
+    const first = ctx.sessionTitle.get(session)
+    session.append('user/message', {
+      content: [{ type: 'text', text: 'later prompt' }],
+      source: { kind: 'user' },
+    }, { surfaceOp: 'append' })
+    await settleTitles()
+
+    expect(first?.messageSeqs).toEqual([eligible.seq])
+    expect(ctx.sessionTitle.get(session)).toEqual(first)
+    expect(session.events.filter(event => event.type === 'session/title')).toHaveLength(1)
+  })
+
+  it('folds the latest title event during replay', () => {
+    const seed = new Session(SessionId('source'))
+    seed.append('session/title', {
+      title: 'Earlier',
+      messageSeqs: [1],
+      source: { kind: 'fallback' },
+    })
+    seed.append('session/title', {
+      title: 'Later',
+      messageSeqs: [1, 4],
+      source: {
+        kind: 'provider',
+        provider: SessionTitleProviderId('test-provider'),
+        model: { provider: 'mock', model: 'title-model' },
+      },
+    })
+
+    expect(foldSessionTitle(seed.events)).toEqual({
+      title: 'Later',
+      messageSeqs: [1, 4],
+      source: {
+        kind: 'provider',
+        provider: SessionTitleProviderId('test-provider'),
+        model: { provider: 'mock', model: 'title-model' },
+      },
+      eventSeq: 1,
+      updatedAt: seed.events[1]?.time,
+    })
+  })
+})

packages/session-title/session-title/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cosmokit"
+    },
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../util/brand"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    }
+  ]
+}