qwen-code/docs/design/session-title/session-title-design.md

Session Title Design

A 3-7 word sentence-case session title generated by the fast model after the first assistant turn. Persisted in the session JSONL with a titleSource: 'auto' | 'manual' tag, surfaced in the session picker, and regeneratable on demand via /rename --auto.

Overview

/rename (#3093) lets a user label a session so they can find it again in the picker later, but until they run it the picker shows the first user prompt — often truncated mid-sentence, or describing a framing question rather than what the session actually became about. Manual renaming is optional friction most users never do.

The goal is to make session names useful by default:

• Descriptive of what the session actually accomplished, not just the opening line. 3-7 words, sentence case, git-commit-subject style.
• Best-effort: fires in the background after the first reply; if it fails the user never sees an error.
• Deferential to the user: never clobber a /rename title the user chose deliberately, even across CLI tabs on the same session.
• Explicitly regeneratable via /rename --auto for the "auto title became stale / I want a fresh one" case.

Triggers

Trigger	Conditions	Implementation
Auto	After recordAssistantTurn fires. Skipped if an existing title is set, another attempt is in-flight, cap reached, non-interactive, env disabled, or no fast model.	ChatRecordingService.maybeTriggerAutoTitle — fire-and-forget
Manual	User runs /rename --auto	renameCommand.ts via tryGenerateSessionTitle

Both paths funnel into a single function — tryGenerateSessionTitle(config, signal) — to guarantee identical prompt, schema, model selection, and sanitization. The auto trigger is a best-effort background call; the manual /rename --auto is a blocking user action that surfaces a reason-specific error on failure.

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                        packages/core/src/services/                      │
│                                                                         │
│  ┌──────────────────────────┐                                           │
│  │ chatRecordingService.ts  │                                           │
│  │                          │                                           │
│  │  recordAssistantTurn()   │                                           │
│  │     │                    │                                           │
│  │     ↓                    │                                           │
│  │  maybeTriggerAutoTitle() │── 6 guards ──→ IIFE(autoTitleController)  │
│  │     │                    │                       │                   │
│  │     └── resume hydrate   │                       ↓                   │
│  │         via              │          tryGenerateSessionTitle          │
│  │         getSessionTitle- │          (sessionTitle.ts)                │
│  │         Info             │                       │                   │
│  │                          │                       ↓                   │
│  └──────────────────────────┘          BaseLlmClient.generateJson       │
│                                        (fastModel + JSON schema)        │
│                                                       │                 │
│  ┌──────────────────────────┐                         ↓                 │
│  │ sessionService.ts        │         sanitizeTitle + sanity checks     │
│  │                          │                         │                 │
│  │  getSessionTitleInfo()   │◀── cross-process        ↓                 │
│  │      uses                │    re-read             recordCustomTitle  │
│  │  readLastJsonString-     │    before write        (…, 'auto')        │
│  │  FieldsSync              │                                           │
│  │  (sessionStorageUtils)   │                                           │
│  └──────────────────────────┘                                           │
│                                                                         │
│                          ┌─────────────────────┐                        │
│                          │ utils/terminalSafe  │                        │
│                          │ stripTerminalCtrl-  │                        │
│                          │ Sequences           │                        │
│                          └─────────────────────┘                        │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐
│                     packages/cli/src/ui/                                │
│                                                                         │
│  commands/renameCommand.ts     ─── /rename <name>          → manual      │
│                                ─── /rename                 → kebab       │
│                                ─── /rename --auto          → auto       │
│                                ─── /rename -- --literal    → manual     │
│                                ─── /rename --unknown-flag  → error      │
│                                                                         │
│  components/SessionPicker.tsx  ── dims rows where                       │
│                                   session.titleSource === 'auto'        │
└─────────────────────────────────────────────────────────────────────────┘

Files

File	Responsibility
packages/core/src/services/sessionTitle.ts	One-shot LLM call + history filter + sanitize. Exports tryGenerateSessionTitle.
packages/core/src/services/chatRecordingService.ts	maybeTriggerAutoTitle trigger, guards, cross-process re-read, abort-on-finalize.
packages/core/src/services/sessionService.ts	getSessionTitleInfo public accessor; renameSession accepts titleSource.
packages/core/src/utils/sessionStorageUtils.ts	extractLastJsonStringFields + readLastJsonStringFieldsSync atomic pair reader.
packages/core/src/utils/terminalSafe.ts	stripTerminalControlSequences shared by sentence-case and kebab paths.
packages/cli/src/ui/commands/renameCommand.ts	/rename --auto, sentinel parser, failure-reason message map.
packages/cli/src/ui/components/SessionPicker.tsx	Dim styling for titleSource === 'auto'.

Prompt Design

System Prompt

Replaces the main agent's system prompt for this single call so the model only tries to label the session, not behave as a coding assistant.

Bullets below correspond 1:1 with TITLE_SYSTEM_PROMPT:

• 3-7 words, sentence case (only first word and proper nouns capitalized).
• No trailing punctuation, no markdown, no quotes.
• Match the dominant language of the conversation; for Chinese, budget roughly 12-20 characters.
• Be specific about the user's actual goal — name the feature, bug, or subject area. Avoid vague catch-alls like "Code changes" or "Help request".
• Four good examples (three English + one Chinese) and four bad examples (too vague / too long / wrong case / trailing punctuation).
• Return only a JSON object with a single title key.

Structured Output (JSON schema)

Instead of wrapping output in tags (as session-recap does), we use BaseLlmClient.generateJson with a function-calling schema:

const TITLE_SCHEMA = {
  type: 'object',
  properties: {
    title: {
      type: 'string',
      description:
        'A concise sentence-case session title, 3-7 words, no trailing punctuation.',
    },
  },
  required: ['title'],
};

Why function calling rather than free text + tag extraction:

1. Cross-provider reliability — OpenAI-compatible endpoints, Gemini, and Qwen's native tool-calling all implement function calling; tag parsing would rely on every model respecting a text convention.
2. No reasoning-preamble leakage — the function call arguments come back structured, so a "thinking" paragraph before the answer can't bleed into the title.
3. Simpler post-processing — a single typeof result.title === 'string' check plus sanitizeTitle covers every realistic model drift.

The model may still return something the schema allows but the UX rejects (empty string, whitespace-only, 500 chars, markdown fencing, control chars). sanitizeTitle handles all of these and returns '' → service returns {ok: false, reason: 'empty_result'}.

Call Parameters

Parameter	Value	Reason
model	getFastModel() — no fallback	Auto-titling on main-model tokens is too expensive to be silent.
schema	TITLE_SCHEMA	Forces {title: string}; filters shape drift at the transport layer.
maxOutputTokens	100	More than enough for 7 words plus schema overhead.
temperature	0.2	Mostly deterministic — session titles benefit from stability across regeneration.
maxAttempts	1	Titles are best-effort cosmetic metadata; retries would queue behind user-visible main traffic.

Contrast with session-recap, which falls back to the main model. Title generation is triggered automatically and often; silently spending main-model tokens without a user opt-in is a real bill surprise. Manual /rename --auto explicitly fails with no_fast_model rather than fallback — forcing the user to make the fast-model choice consciously.

History Filtering

geminiClient.getChat().getHistory() returns Content[] that includes tool calls, tool responses (often 10K+ tokens of file content), and model thought parts. Feeding that raw into the title LLM would bias the label toward implementation noise like "Called grep on auth module".

filterToDialog keeps only user / model entries with non-empty text and no thought / thoughtSignature parts. takeRecentDialog slices to the last 20 messages and refuses to start on a dangling model/tool response. flattenToTail converts to "Role: text" lines and slices the last 1000 characters.

The 1000-character tail slice

A session that starts with help me debug X but pivots to refactoring Y should be titled about Y. Titling by the head locks in the opening framing; titling by the tail captures what the session became.

UTF-16 surrogate handling

.slice(-1000) on a UTF-16 code-unit boundary can orphan a high or low surrogate if a CJK supplementary char or emoji gets cut. Some providers respond to the resulting invalid UTF-16 with a 400 — which, without handling, would burn an attempt for no reason. flattenToTail drops a leading orphaned low surrogate; sanitizeTitle scrubs any orphaned surrogate after the max-length trim on the output path too.

Persistence

Record shape

CustomTitleRecordPayload grows an optional titleSource: 'auto' | 'manual' field:

{
  "type": "system",
  "subtype": "custom_title",
  "systemPayload": {
    "customTitle": "Debug login button on mobile",
    "titleSource": "auto",
  },
}

The field is optional, and absent-in-legacy records are treated as undefined. SessionPicker dims rows only on a strict === 'auto' match — a pre-change user /rename title is never silently reclassified as a model guess.

Resume hydration

On resume, ChatRecordingService constructor calls sessionService.getSessionTitleInfo(sessionId) to read both the title and its source. Without hydrating the source, finalize()'s re-append (which runs on every session lifecycle event) would rewrite auto as manual on every resume cycle — silently stripping the dim affordance.

Atomic pair read

extractLastJsonStringFields returns customTitle and titleSource from the same matching line in a single scan. Two separate readLastJsonStringFieldSync calls could land on different records if an older line has only the primary field, yielding a mismatched pair. The extractor also requires a proper closing quote on the primary value, so a crash-truncated trailing record can't win the latest-match race.

Full-file scan cap

Phase-2 (when the tail-window fast path misses) streams the whole file in 64KB chunks. Capped at MAX_FULL_SCAN_BYTES = 64 MB so a corrupt multi-GB JSONL can't freeze the session picker on the main event loop. The picker's latency envelope survives corruption.

Symlink defense

Session reads open with O_NOFOLLOW (falls back to plain read-only on Windows, where the constant is not exposed). Defense in depth so a symlink planted in ~/.qwen/projects/<proj>/chats/ can't redirect a metadata read to an unrelated file.

Concurrency and Edge Cases

Trigger guard order

maybeTriggerAutoTitle checks six conditions in this exact order — each short-circuits the rest so the cheap ones run first:

1. currentCustomTitle set → skip. Never overwrite manual / prior auto.
2. autoTitleController !== undefined → skip. One attempt at a time.
3. autoTitleAttempts >= 3 → skip. Cap bounds total waste.
4. !config.isInteractive() → skip. Headless qwen -p / CI never spends fast-model tokens on a one-shot session.
5. autoTitleDisabledByEnv() → skip. QWEN_DISABLE_AUTO_TITLE=1 explicit opt-out.
6. !config.getFastModel() → skip. No fast-model → no-op.

Why the cap is 3, not 1

The first assistant turn can be a pure tool-call with no user-visible text (e.g. the model opens with a grep). tryGenerateSessionTitle returns {ok: false, reason: 'empty_history'} in that case. Without a retry window, an entire session's chance at a title would be burned on turn 1 before the user said anything interesting. Cap of 3 covers the common "first turn is noise" case while still bounding runaway retry on a persistently failing fast model.

Cross-process manual-rename race

Two CLI tabs on the same session file can diverge in memory. Tab A runs /rename foo and writes titleSource: manual. Tab B's ChatRecordingService has its own currentCustomTitle = undefined and would naively overwrite with an auto title.

After the LLM call resolves, the IIFE re-reads the JSONL via sessionService.getSessionTitleInfo. If the file shows source: 'manual', the IIFE bails AND syncs its in-memory state so subsequent turns respect the rename too. Cost: one 64KB tail read per successful generation; negligible.

Abort propagation on finalize()

autoTitleController doubles as the in-flight flag. finalize() (run on session switch and process shutdown) calls autoTitleController.abort() before re-appending the title record. The LLM socket is cancelled promptly; session switch doesn't wait on a slow fast-model call. The IIFE's finally block clears autoTitleController only if it's still the active one, so a finalize mid-flight doesn't race a concurrent recordAssistantTurn.

Manual /rename lands mid-flight

Between the IIFE's await completing and the recordCustomTitle('auto') call, the user could /rename foo. The IIFE re-checks this.currentTitleSource === 'manual' and bails. The in-process check AND the cross-process re-read both run; manual wins at both layers.

Configuration

User-facing knobs

Setting / env var	Default	Effect
fastModel	unset	Required for auto-titling. Unset → no-op (no main-model fallback).
QWEN_DISABLE_AUTO_TITLE=1	unset	Opt out of the auto trigger without unsetting fastModel. /rename --auto still works on request.

No settings.json toggle — the env var is the only user-visible off-switch. Rationale: the feature is cosmetic and cheap; a settings toggle would add a UI surface for something that can live as a one-time env export for the few users who want to disable it.

Why auto doesn't fall back to the main model

Auto-titling is triggered unconditionally after every assistant turn. If a user without a fast model were silently charged main-model tokens for every new session's title, the cost delta is invisible until the monthly bill arrives. Failing quietly (no-op, no title, no cost) is the safer default. /rename --auto surfaces no_fast_model as an actionable error so the user can set one if they want to.

Observability

createDebugLogger('SESSION_TITLE') emits debugLogger.warn from the generator's catch block. Failures are fully transparent to the user — auto-title is an auxiliary feature and never throws into the UI.

Developers can grep for the [SESSION_TITLE] tag in the debug log (~/.qwen/debug/<sessionId>.txt; latest.txt symlinks to the current session). A working end-to-end call produces no log output; a failing one gets one WARN line with the underlying error message.

Security Hardening

The title value is rendered verbatim in the terminal (session picker) AND persisted in a user-readable JSONL file. Both surfaces are attack reachable if a compromised or prompt-injected fast model returns hostile text.

Concern	Guard
ANSI / OSC-8 / CSI injection	stripTerminalControlSequences before both JSONL write and picker render.
Clickable-link smuggle via OSC-8	Same — OSC sequences stripped as whole units, not just the ESC byte.
Invalid UTF-16 surrogates	Scrubbed in flattenToTail (LLM input) and sanitizeTitle (LLM output after max-length trim).
Subtype-line spoof via user message content	lineContains: '"subtype":"custom_title"' — user text that happens to contain the literal phrase can't shadow a real record.
Symlink redirect on session reads	O_NOFOLLOW (no-op on Windows where the constant is missing).
Truncated trailing JSONL record	extractLastJsonStringFields requires a closing quote before a record wins the latest-match race.
Pathological file size freezing the picker	MAX_FULL_SCAN_BYTES = 64 MB cap on Phase-2 full-file scan.
Paired CJK bracket decorators (【Draft】)	Stripped as a unit so a lone closing bracket doesn't dangle.

Out of Scope

Item	Why not
Auto-regenerate when the title goes stale	/rename --auto is the explicit user-triggered path. Silent mid-session title swaps would confuse users scrolling back through the picker.
WebUI / VSCode dim-styling parity	Those surfaces read customTitle already and will show auto titles as if manual. A follow-up can wire the titleSource through.
Settings-dialog toggle for auto generation	Env var is the single knob. Full settings UI is easy to add later if user demand surfaces.
i18n locale catalog entries for new strings	Consistent with existing /rename strings, which fall through to English. A repo-wide i18n pass is out of scope.
Migration to re-classify legacy records	Back-compat by design: absent titleSource is treated as manual. Rewriting old records would risk losing user intent.
Non-interactive auto-titling	qwen -p / CI scripts throw the session away; fast-model tokens for a title no one will ever resume is pure waste.