fix(session-title): honor request lifecycle

2026-07-21 13:37:28 +08:00
parent a9d518a38e
commit 63cb16a540
12 changed files with 169 additions and 15 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-2026-07-21-log-backed-session-titles.md: d536e8623652116c1194c303cd50ea44f27bb34d
-2026-07-21-log-backed-session-titles.zh.md: b44f7cfaede440291445894ddb73829b1a3404ec
+2026-07-21-log-backed-session-titles.md: 9c54b0b6c24e393f9e7c9f6585d4c80642be9e87
+2026-07-21-log-backed-session-titles.zh.md: 351acb5d2fd6047547a31ec4a16912ff9ea74a95
@@ -24,7 +24,7 @@ The core session package exposes `ctx.sessions.appendOutOfBand()` only for plugi

 Only text blocks from human-source `user/message` events are eligible. Empty, control-only, and non-text prompts wait for the next eligible message. The service schedules the first fallback without awaiting it from the prompt path, normalizes whitespace and control sequences, applies the configured word and UTF-8 byte limits without splitting a code point, and records the first message seq.

-Automatic provider work waits until the corresponding `request/header` records the main request's exact provider/model route, then runs independently of the agent response. A completion joins whichever turn is open at acceptance time or uses the zero-step append path. Explicit `refresh(session, signal?)` materializes any missing fallback and awaits the registered provider; without a provider it returns the fallback. Concurrent refreshes reserve their session-local revision before waiting for fallback durability, so a newer call supersedes an older call before either can invert provider completion order.
+Automatic provider work starts only after the main loop has a current logged provider/model route. A newly appended `request/header` starts pending work directly; when the header is unchanged, the frozen loop-built `llm/stream` request starts it after matching the folded route. Generation then runs independently of the agent response, and a completion joins whichever turn is open at acceptance time or uses the zero-step append path. Explicit `refresh(session, signal?)` materializes any missing fallback and awaits the registered provider; without a provider it returns the fallback. Caller cancellation during fallback flush does not roll back the durable append, but `refresh()` rechecks the signal and rejects instead of returning success. Concurrent refreshes reserve their session-local revision before waiting for fallback durability, so a newer call supersedes an older call before either can invert provider completion order.

 The first-message provider schedules once when a fresh session first creates its fallback. An automatic failure does not reschedule on later prompts; `refresh()` is the retry path. The all-messages provider schedules after every eligible human prompt and passes all eligible messages through that revision, including seeded history. Its newer revision aborts and supersedes older pending or active work.

@@ -24,7 +24,7 @@ Status: implemented

 只有人类来源的 `user/message` 事件中的文本块才符合条件。空提示词、仅含控制字符的提示词和非文本提示词会等待下一条合格消息。服务从提示词路径调度首个回退标题而不等待其完成，随后规范化空白和控制序列，应用已配置的单词数和 UTF-8 字节限制且不拆分代码点，并记录第一条消息的 seq。

-自动提供方工作会等待相应的 `request/header` 记录主请求的准确提供方和模型路由，然后独立于 agent 响应运行。完成结果在被接受时加入当时开放的轮次，否则使用零步骤追加路径。显式调用 `refresh(session, signal?)` 会生成尚缺的回退标题并等待已注册的提供方；没有提供方时则返回回退标题。并发刷新会在等待回退标题持久化完成前预留会话本地修订号，因此在任何调用有机会造成提供方完成顺序倒置之前，较新的调用就会取代较早的调用。
+仅当主循环存在已记录在日志中的当前提供方/模型路由时，自动提供方工作才会启动。`request/header` 新追加到日志时，会直接启动待执行工作；如果请求头没有变化，则由循环构建且已冻结的 `llm/stream` 请求会先与折叠所得的路由匹配，再启动该工作。随后，生成工作独立于 agent 响应运行；完成结果在被接受时加入当时开放的轮次，否则使用零步骤追加路径。显式调用 `refresh(session, signal?)` 会生成尚缺的回退标题并等待已注册的提供方；没有提供方时则返回回退标题。调用方在回退标题刷写期间取消调用不会回滚这次持久化追加，但 `refresh()` 会重新检查取消信号，并让调用以拒绝结束，而非返回成功。并发刷新会在等待回退标题持久化完成前预留会话本地修订号，因此在任何调用有机会造成提供方完成顺序倒置之前，较新的调用就会取代较早的调用。

 首消息提供方仅在新会话首次创建回退标题时调度一次。自动执行失败后，后续提示词不会重新调度；`refresh()` 是重试路径。全部消息提供方会在每条合格且由人类发出的提示词后调度，并传入截至该修订的所有合格消息，包括预置历史记录。较新的修订会中止并取代更早的待执行或活跃工作。

@@ -877,7 +877,7 @@ export interface Config {
 }
 ```

-Source: [`packages/session-title/session-title/src/index.ts:63`](../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session-title/session-title/src/index.ts:64`](../packages/session-title/session-title/src/index.ts)

 ## `@deepseek-ai/dsh-session-title-all-messages-llm`

@@ -1007,7 +1007,7 @@ get(session: Session): SessionTitleSnapshot | undefined
 * 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.
+ * @param signal - optional caller cancellation; an in-progress fallback append may finish durably before rejection.
 * @returns latest accepted title, or `undefined` when no eligible text exists.
 */
 async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>
@@ -1023,7 +1023,7 @@ register(provider: SessionTitleProvider): () => Promise<void>

 Types: [Session](../core-data-structures/session.md) · [SessionTitleProvider](../core-data-structures/session-title.md) · [SessionTitleSnapshot](../core-data-structures/session-title.md)

-Source: [`packages/session-title/session-title/src/index.ts:235`](../../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session-title/session-title/src/index.ts:236`](../../packages/session-title/session-title/src/index.ts)

 ## `ctx.skills` — `SkillService`

@@ -30,7 +30,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:71`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:54`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `goal/changed` | `emit` | [`packages/goal/goal/src/types.ts:167`](../packages/goal/goal/src/types.ts) | [`goal`](../packages/goal/goal) (`emit`) | [`goal-session`](../packages/goal/goal-session) |
-| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:44`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`invariants`](../packages/support/invariants), [`llm-replay`](../packages/support/llm-replay) |
+| `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:44`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`invariants`](../packages/support/invariants), [`llm-replay`](../packages/support/llm-replay), [`session-title`](../packages/session-title/session-title) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title) |
 | `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`goal-session`](../packages/goal/goal-session), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`workspace-context`](../packages/context/workspace-context) |
@@ -390,7 +390,7 @@ Source: [`packages/sandbox/sandbox-policy/src/session-mode.ts:34`](../packages/s

 Types: [SessionTitleEventData](core-data-structures/session-title.md)

-Source: [`packages/session-title/session-title/src/index.ts:89`](../packages/session-title/session-title/src/index.ts)
+Source: [`packages/session-title/session-title/src/index.ts:90`](../packages/session-title/session-title/src/index.ts)

 #### `session/title-llm-request` — log-only

@@ -481,7 +481,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
      },
      {
        signature: 'async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined>',
-        jsDoc: '/**\n * Explicitly retry the registered provider, or materialize the built-in\n * fallback when no provider is registered.\n * @param session - exact live session to refresh.\n * @param signal - optional caller cancellation.\n * @returns latest accepted title, or `undefined` when no eligible text exists.\n */',
+        jsDoc: '/**\n * Explicitly retry the registered provider, or materialize the built-in\n * fallback when no provider is registered.\n * @param session - exact live session to refresh.\n * @param signal - optional caller cancellation; an in-progress fallback append may finish durably before rejection.\n * @returns latest accepted title, or `undefined` when no eligible text exists.\n */',
      },
      {
        signature: 'register(provider: SessionTitleProvider): () => Promise<void>',
@@ -7,10 +7,10 @@ Only text blocks from human `user/message` events are eligible. The first eligib
 ## 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.
+- `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; cancellation does not roll back a fallback append already entering durability.
 - `register(provider)` installs the sole optional provider and returns its awaitable Cordis effect disposer. A second registration throws immediately; disposal aborts pending and active calls, waits for their settlement, and only then permits another provider to 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. Concurrent explicit refreshes reserve their order before fallback durability waits, so only the newest call may reach the provider. Service teardown cancels queued work and drains calls that ignore cancellation before unloading completes.
+Automatic work never delays the main agent response. A provider starts only after a loop-built request's exact route matches the current logged `request/header`, including when the unchanged header needs no new snapshot. 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. Concurrent explicit refreshes reserve their order before fallback durability waits, so only the newest call may reach the provider. Service teardown cancels queued work and drains calls that ignore cancellation before unloading completes.

 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.

@@ -7,6 +7,7 @@ import { Context, FiberState, Service, type Fiber } from 'cordis'
 import z from 'schemastery'
 import type { Branded } from '@deepseek-ai/dsh-brand'
 import { deepFreeze } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm'
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
 import { fallbackSessionTitle, normalizeSessionTitle } from './normalize.ts'

@@ -287,6 +288,10 @@ export class SessionTitleService extends Service {
          break
      }
    })
+    ctx.on('llm/stream', (options, next) => {
+      this.onMainRequest(options)
+      return next()
+    }, { global: true, prepend: true })
    ctx.on('session/disposed', (session) => {
      const state = this.work.get(session)
      if (state === undefined) return
@@ -308,7 +313,7 @@ export class SessionTitleService extends Service {
   * 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.
+   * @param signal - optional caller cancellation; an in-progress fallback append may finish durably before rejection.
   * @returns latest accepted title, or `undefined` when no eligible text exists.
   */
  async refresh(session: Session, signal?: AbortSignal): Promise<SessionTitleSnapshot | undefined> {
@@ -321,7 +326,9 @@ export class SessionTitleService extends Service {
    const messages = collectSessionTitleMessages(session.events)
    const latest = messages.at(-1)
    if (registration === undefined || registration.closing || latest === undefined) {
-      return this.ensureFallback(session)
+      const fallback = await this.ensureFallback(session)
+      signal?.throwIfAborted()
+      return fallback
    }
    const state = this.stateFor(session)
    const revision = this.supersede(state, 'explicit title refresh superseded older generation')
@@ -399,11 +406,37 @@ export class SessionTitleService extends Service {
    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,
    }
+    this.startPending(session, state, pending, route)
+  }
+
+  /** Start unchanged-route work from the frozen loop request after its header fold is current. */
+  private onMainRequest(options: GenerateOptions): void {
+    if (!this.serviceActive() || options.sessionId === undefined || !Object.isFrozen(options)) return
+    const session = this.ctx.sessions.get(options.sessionId)
+    const state = session === undefined ? undefined : this.work.get(session)
+    const pending = state?.pending
+    if (session === undefined || state === undefined || pending === undefined) return
+    const boundary = session.events.findLast(event => event.type === 'step/start' || event.type === 'step/end')
+    const route = session.requestHeader()?.config
+    if (boundary?.type !== 'step/start'
+      || boundary.seq <= pending.throughSeq
+      || route?.provider !== options.provider
+      || route.model !== options.model) return
+    this.startPending(session, state, pending, { provider: options.provider, model: options.model })
+  }
+
+  /** Consume one pending revision and schedule its non-blocking provider call. */
+  private startPending(
+    session: Session,
+    state: SessionTitleWorkState,
+    pending: PendingAutomaticWork,
+    route: SessionTitleModelProvenance,
+  ): void {
+    delete state.pending
    this.defer(async () => {
      if (this.registration !== pending.registration
        || pending.registration.closing
@@ -1,5 +1,6 @@
 import { Context } from 'cordis'
 import { describe, expect, it, vi } from 'vitest'
+import LlmService, { deepFreeze } from '@deepseek-ai/dsh-llm'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
 import SessionTitleService, {
  SessionTitleProviderId,
@@ -265,6 +266,95 @@ describe('SessionTitleService provider lifecycle', () => {
    expect(ctx.sessionTitle.get(session)?.title).toBe('Newest complete title')
  })

+  it('runs an all-messages revision when the next main request reuses its logged header', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const requests: SessionTitleProviderRequest[] = []
+    ctx.sessionTitle.register({
+      id: SessionTitleProviderId('unchanged-route'),
+      automatic: 'all-user-messages',
+      async generate(request) {
+        requests.push(request)
+        return {
+          title: `Revision ${requests.length}`,
+          messageSeqs: request.messages.map(message => message.seq),
+        }
+      },
+    })
+    const session = ctx.sessions.create(SessionId('unchanged-route'))
+    session.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const first = appendHumanPrompt(session, 'First routed prompt')
+    await settle()
+    session.append('step/start', { turn: 1, step: 1 })
+    appendRoute(session)
+    await settle()
+    session.append('step/end', { turn: 1, step: 1 })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+    session.append('turn/start', {
+      turn: 2,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const second = appendHumanPrompt(session, 'Second prompt on the same route')
+    await settle()
+    session.append('step/start', { turn: 2, step: 1 })
+    void ctx.llm.stream(deepFreeze({
+      provider: 'main-route',
+      model: 'chat-model',
+      messages: session.deriveMessages(),
+      sessionId: session.id,
+    }))
+    await settle()
+
+    expect(session.events.filter(event => event.type === 'request/header')).toHaveLength(1)
+    expect(requests).toHaveLength(2)
+    expect(requests[1]).toMatchObject({
+      messages: [
+        { seq: first.seq, text: 'First routed prompt' },
+        { seq: second.seq, text: 'Second prompt on the same route' },
+      ],
+      route: { provider: 'main-route', model: 'chat-model' },
+    })
+  })
+
+  it('ignores model streams that are not a matching loop request', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SessionTitleService, CONFIG)
+    const generate = vi.fn(async (request: SessionTitleProviderRequest): Promise<SessionTitleProviderResult> => ({
+      title: 'Unexpected title',
+      messageSeqs: request.messages.map(message => message.seq),
+    }))
+    ctx.sessionTitle.register({
+      id: SessionTitleProviderId('request-filter'),
+      automatic: 'all-user-messages',
+      generate,
+    })
+    const options = { provider: 'main-route', model: 'chat-model', messages: [] }
+
+    void ctx.llm.stream(deepFreeze(options))
+    void ctx.llm.stream(deepFreeze({ ...options, sessionId: SessionId('missing') }))
+    const quiet = ctx.sessions.create(SessionId('quiet'))
+    void ctx.llm.stream(deepFreeze({ ...options, sessionId: quiet.id }))
+    const pending = ctx.sessions.create(SessionId('unmatched-boundary'))
+    pending.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    appendHumanPrompt(pending, 'Wait for a matching request boundary')
+    await settle()
+    void ctx.llm.stream(deepFreeze({ ...options, sessionId: pending.id }))
+    await settle()
+
+    expect(generate).not.toHaveBeenCalled()
+  })
+
  it('contains automatic failures but lets explicit refresh reject', async () => {
    const ctx = new Context()
    await ctx.plugin(SessionStore)
@@ -162,6 +162,37 @@ describe('SessionTitleService configuration and refresh boundaries', () => {
    expect(disposeSignal?.aborted).toBe(true)
  })

+  it('rejects fallback refresh cancellation that arrives during durability flush', async () => {
+    const ctx = await setup()
+    const seed = new Session(SessionId('fallback-cancel-seed'))
+    seed.append('turn/start', {
+      turn: 1,
+      trigger: { kind: 'message', source: { kind: 'user' } },
+    })
+    const source = appendPrompt(seed, 'Persist this fallback despite caller cancellation')
+    seed.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    const session = ctx.sessions.create(SessionId('fallback-cancel'), { seed: seed.events })
+    const flushStarted = deferred<undefined>()
+    const releaseFlush = deferred<undefined>()
+    ctx.on('session/flush', async (subject) => {
+      if (subject !== session) return
+      flushStarted.resolve(undefined)
+      await releaseFlush.promise
+    })
+    const controller = new AbortController()
+
+    const refresh = ctx.sessionTitle.refresh(session, controller.signal)
+    await flushStarted.promise
+    controller.abort(new Error('cancelled while fallback flushed'))
+    releaseFlush.resolve(undefined)
+
+    await expect(refresh).rejects.toThrow('cancelled while fallback flushed')
+    expect(ctx.sessionTitle.get(session)).toMatchObject({
+      messageSeqs: [source.seq],
+      source: { kind: 'fallback' },
+    })
+  })
+
  it('reserves overlapping refresh order before fallback durability settles', async () => {
    const ctx = new Context()
    await ctx.plugin(SessionStore)