dsh-session-title gives every session a title clients can display: a deterministic fallback from the first eligible human message, an optional asynchronous provider (such as a model-backed one), or an explicit user rename. Every accepted revision is a log-only session/title event, so titles survive replay, resume, and paging exactly like any other session event and never enter the model surface. The service owns scheduling and acceptance; the optional provider owns generation. Automatic work never delays the main agent response, and a newer revision supersedes older work. Configuration and title sources come first; the implementation internals live in a collapsible developer section below.

Use this package
Understand the implementation
Further Exploration
Model Experience
Known Limitations and Deferred Work
Dev Note

Use this package

Mount the service to give sessions titles that clients can display and that never reach the model. The common path is explicit: load the session store, mount the service with its required limits, and optionally mount one provider plugin.

Choosing a title source

Titles come from three sources, newest wins. The built-in fallback derives from the first eligible human message's leading words within the configured caps; a registered provider generates a title over eligible messages; an explicit rename() accepts a user-supplied title. Only text blocks from human user/message events are eligible, and empty or non-text prompts wait for later eligible input. A user-sourced latest title pins the session — later user messages schedule no automatic revision, and an explicit refresh() remains the deliberate unpin.

Minimal configuration

All limits are required; the library supplies no defaults. Mount the service with the three bounds:

- name: '@deepseek-ai/dsh-session'
- name: '@deepseek-ai/dsh-session-title'
  config:
    fallbackMaxWords: 8
    fallbackMaxBytes: 96
    maxTitleBytes: 120

Field	Default	Meaning
`fallbackMaxWords`	required	Maximum whitespace-delimited words in the deterministic fallback
`fallbackMaxBytes`	required	Maximum UTF-8 bytes in the fallback; must not exceed `maxTitleBytes`
`maxTitleBytes`	required	Maximum UTF-8 bytes accepted from any source

The generated configuration catalog is the exhaustive source for every accepted field and its JSDoc.

Adding a provider

One optional asynchronous provider may be registered through ctx.sessionTitle.register(provider); a second registration throws. The shipped model-backed providers are first-prompt and all-prompts, both using the shared LLM generation policy. A provider starts only after a marked loop-built request's exact route matches the logged request/header, and a newer revision supersedes and aborts older work.

Reading titles

get(session) folds the latest accepted title from the live or replayed log, and foldSessionTitle(events) is the pure fold over a log. The service also registers a title projection unit — the plain title string — for client list rows when a projection registry is composed. An explicit refresh(session) materializes the fallback when needed, then explicitly runs the registered provider over the current eligible messages.

Failures and recovery

Automatic failures warn and retain the latest title; explicit refresh() rejects on provider error or caller cancellation, and cancellation does not roll back an already accepted fallback event. Automatic work never delays the main agent response, its late completion appends a standalone log-only event without opening a turn, and a stale completion cannot append. Forks inherit title events in their seed unchanged.

Understand the implementation

Implementation internals — click to expand

This section explains the title design; the observable behavior is fully covered in Use this package.

Design concept

Titles are durable, log-only state: every accepted revision is a session/title event, and foldSessionTitle() selects the latest, so a title survives replay, resume, and paging exactly like any other session event. The service owns scheduling, supersession, and acceptance; providers own generation.

Source map

File	Role
`src/index.ts`	Service: config, fold, fallback scheduling, provider registry, concurrency, `title` projection unit
`src/normalize.ts`	Title-text cleaning, UTF-8-safe truncation, and the deterministic fallback
`src/types.ts`	One home of the `title` projection-key declaration

Lifecycle and concurrency

Per-session work state tracks a revision counter, an in-flight fallback, and pending and active provider work. A newer user message, provider disposal, session disposal, or explicit refresh aborts older work through an AbortController; a completion whose provider, revision, session, or signal is stale cannot append. Explicit refreshes reserve their revision before provider work; overlapping automatic and explicit fallback requests share one session-local in-flight append. Service teardown cancels queued work and drains calls that ignore cancellation before unloading completes.

Normalization

Accepted titles are cleaned of terminal control sequences, directional and invisible controls, and non-whitespace C0/C1 controls; whitespace is normalized, and truncation to the byte caps never splits a Unicode code point. The deterministic fallback takes the first eligible message's leading words within fallbackMaxWords and fallbackMaxBytes.

Further Exploration

Read these pages when the service contract is not enough. They move from the subsystem reference to the model-backed providers that plug in here.

Session title subsystem — durable title state and the provider vocabulary types.
Shared LLM title policy — the model-backed generation helper both shipped providers use.
First-message title provider — titles from the first eligible human message.
All-messages title provider — titles from every eligible human message.
Session package map — adjacent persistence, projection, title, and telemetry packages.

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

These limits define what the title service does not provide. They are current package constraints.

No title deletion, search, or list indexing — unpinning back to automatic titles without an explicit refresh, search, and list indexing are outside this service.
At most one provider — the registry deliberately accepts a single implementation, so a deployment cannot compose competing title strategies without writing one provider that owns their precedence.

Dev Note

Working context for maintainers — click to expand

None.

README.md

@deepseek-ai/dsh-session-title

Summary

Table of Contents