From f65799a236ab206e3daa033e065e469baddbd4d6 Mon Sep 17 00:00:00 2001 From: Yichen Jiang Date: Wed, 16 Sep 2026 20:05:48 +0800 Subject: [PATCH] docs(session): clarify blank-state projection guarantees --- ...ervations-and-projection-owned-client-state.i18n.yaml | 2 +- ...-observations-and-projection-owned-client-state.zh.md | 2 +- apps/web/tests/workspace-management.e2e.ts | 1 + packages/api/session-controller/README.i18n.yaml | 2 +- packages/api/session-controller/README.md | 2 +- .../session-controller/src/client/sessions/lineage.ts | 2 +- .../session-controller/src/client/sessions/manager.ts | 3 ++- .../session-controller/src/client/sessions/service.ts | 8 ++++---- .../api/session-controller/tests/session.client.spec.ts | 9 +++++++++ 9 files changed, 21 insertions(+), 10 deletions(-) diff --git a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml index 2418f0b77d..b81de50a5f 100644 --- a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml +++ b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.i18n.yaml @@ -3,4 +3,4 @@ # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.md 2026-08-25-session-observations-and-projection-owned-client-state.md: 88a4cbed008ebbb8f6733c5c55b68b9781309820 -2026-08-25-session-observations-and-projection-owned-client-state.zh.md: 9dd6ce9e2243b535c614cd5ad0862384a4536623 +2026-08-25-session-observations-and-projection-owned-client-state.zh.md: f5bd374a9e35282cb8aef03339ea95f2132f0c82 diff --git a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md index 9dd6ce9e22..f5bd374a9e 100644 --- a/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md +++ b/.agents/notes/implemented/architecture/2026-08-25-session-observations-and-projection-owned-client-state.zh.md @@ -120,7 +120,7 @@ Client 本地交互状态也继续留在本地:loading 和 error 状态、打 ### 领域应用 -- **Title 与 list metadata。** Cached projection hints 可以渲染已有 title,并判断 blankness 或 recency。Hints 缺失时这些事实保持未知;listing 期间只有有界小日志策略可以解析它们。 Client 使用当前 metadata projection 对账列表行:非空白事实会将 Session 排除在空白复用之外,较晚的 prompt 时间用于最近活动排序。过期列表响应不能覆盖较新的 history 或 control projection。 +- **Title 与 list metadata。** Cached projection hints 可以渲染已有 title,并判断 blankness 或 recency。Hints 缺失时这些事实保持未知;listing 期间只有有界小日志策略可以解析它们。Client 使用当前 metadata projection 对账列表行:非空白事实会将 Session 排除在空白复用之外,较晚的 prompt 时间用于最近活动排序。过期列表响应不能覆盖较新的 history 或 control projection。 - **Model selection。** `model/selection` 记录完整 provider、model 和可选 reasoning effort。`modelSelection` 区分上一请求使用的 route,以及等待 request header 消费的较晚 selection。 - **Agent preset。** Projection 从不可变 Session metadata 初始化,并随 preset-selection event 推进。对于现有 Session,缺失或 `null` 值不会替换成部署默认值。 - **Subagent identity。** `subagent` unit 仍是唯一 descriptor interpreter。Listing 从共享 corpus 获得 candidate,并通过 live state、projection cache 或 observation 解析值,不自行扫描 event。 diff --git a/apps/web/tests/workspace-management.e2e.ts b/apps/web/tests/workspace-management.e2e.ts index 6525d6fd2d..6f1a7f99db 100644 --- a/apps/web/tests/workspace-management.e2e.ts +++ b/apps/web/tests/workspace-management.e2e.ts @@ -771,6 +771,7 @@ describe('web e2e: New Session after an outdated blank cache', () => { const stored = await scaffold.ctx.sessionPersistence.stat(id) if (stored === undefined) throw new Error('seeded Session is missing') // A durable log may advance after its last blank projection checkpoint. + // An unregistered Session writes only the checkpoint, leaving the persisted log intact. const blank = scaffold.ctx.sessions.prepare(id, { eventState: 'detached', seed: [], meta: stored.header, inheritedEventCount: SessionLogOffset(0), }) diff --git a/packages/api/session-controller/README.i18n.yaml b/packages/api/session-controller/README.i18n.yaml index f92d06f911..40d9d29e75 100644 --- a/packages/api/session-controller/README.i18n.yaml +++ b/packages/api/session-controller/README.i18n.yaml @@ -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 packages/api/session-controller/README.md -README.md: ac83c31a83afb02f0b4afc3b9d35170b0eeb3b5f +README.md: 18a7567bed620254a44a9f0629154f8b13a34c26 README.zh.md: fc2d26b793e1888a64ff043bb2ba3043acded728 diff --git a/packages/api/session-controller/README.md b/packages/api/session-controller/README.md index ac83c31a83..18a7567bed 100644 --- a/packages/api/session-controller/README.md +++ b/packages/api/session-controller/README.md @@ -30,7 +30,7 @@ The Client journal validates exact V3 event envelopes before publishing follow s Each endpoint states its activation policy. List reads only stored headers and projection-cache rows: it never calls per-session stat or opens a cold Session body. A current-format cache identity may supply every list hint; a lifecycle-matching predecessor cache may supply only its version-compatible title as a stale display fact, never as an authoritative fold seed. Search, attachment, history pages, log following, skill discovery, and workspace-path opening can inspect persistence without activating an Agent; `canOpenWorkspacePath()` reports native-opening availability without addressing a Session. Cancellation requires live state; queue mutation, model, rename, prompt, and file-reference operations may resolve or resume an ordinary Session. Prompt rejects content with neither non-whitespace text nor an attachment before resolving the Agent or appending Session events; queue edits accept only non-empty text content. Prompt admission consumes opaque receipts from the injected [`fileUploads`](../../client/file-upload/README.md) Host service and resolves every same-Agent receipt before sending the complete ordered content list through `ctx.attachments`. Prompt retries whose `requestId` is already queued or logged return the original acceptance without inserting another message. Create and fork are the only operations that create a new Agent directly. The service applies one preset-aware resume policy and subagent ownership fence to its own methods and to the Typert Agent and Session lookups used by other Remote namespaces. Queue mutation has one narrow exception: a live child whose current projected identity is continuable and comes from its own non-seed suffix accepts the ordinary Edit, Remove, and QueueDock Steer actions across both inbox destinations. One-shot, missing, unknown, corrupt, seed-only, or cold children remain rejected without resume. The skill catalog uses a live Agent when present or the recorded preset's standing scope when cold, so listing never starts an Agent. The authenticated delivery routes use `workspaceDesktop()` for the serving Host name and file-manager behavior. `openWorkspacePath({ path, action: "reveal" })` delegates file-manager navigation to the native adapter; omitting `action` opens the default application. -Client list rows and resident Sessions use the current `sessionListMetadata` projection to reject stale blank-session hints; recency is the later of the summary timestamp and the projected last user prompt. An opened conversation therefore cannot be reused by New Session because an older list response still marks it blank. +Client list rows and resident Sessions use the current `sessionListMetadata` projection to reject stale blank-session hints; recency is the later of the summary timestamp and the projected last user prompt. An opened conversation is therefore not reused by New Session even when an older list response still marks it blank. Client list refreshes retain unchanged row objects and reuse the items array when order and values match. Cache membership checks use a per-refresh ID set, so reconciliation grows linearly with the current list and retained cache sizes. diff --git a/packages/api/session-controller/src/client/sessions/lineage.ts b/packages/api/session-controller/src/client/sessions/lineage.ts index 09551369b6..31b68739c3 100644 --- a/packages/api/session-controller/src/client/sessions/lineage.ts +++ b/packages/api/session-controller/src/client/sessions/lineage.ts @@ -19,7 +19,7 @@ export interface SessionListEntry { title?: string updatedAt: number running: boolean - /** Empty-log bit mirrored from the summary; lists hide blank sessions (filtering stays with the consumer). */ + /** Summary blankness reconciled with `sessionListMetadata`; lists hide blank sessions (filtering stays with the consumer). */ blank: boolean parentSessionId?: SessionId /** Coarse durable origin for navigation filtering; not a continuation capability. */ diff --git a/packages/api/session-controller/src/client/sessions/manager.ts b/packages/api/session-controller/src/client/sessions/manager.ts index 3439494fa7..152ad92fd7 100644 --- a/packages/api/session-controller/src/client/sessions/manager.ts +++ b/packages/api/session-controller/src/client/sessions/manager.ts @@ -334,6 +334,7 @@ export class SessionManager { store = new ProjectionValueStore() const projections = store store.subscribeAny(() => { + // Newer history or control metadata corrects a resident Session's stale list hint. if (projections.values().sessionListMetadata?.blank === false) { this.sessions.get(sessionId)?.handleBlank(false) } @@ -481,7 +482,7 @@ export class SessionManager { this.listPhase = 'ready' // Covers the empty-mutations pull (a plain baseline carries no edge). this.syncCompletedNotifications() - // Push running/blank bits down to instantiated Sessions (the list is the authoritative summary source). + // Sessions reconcile list blank hints with their current metadata projection. for (const s of this.summaries) { const session = this.sessions.get(s.sessionId) if (session === undefined) continue diff --git a/packages/api/session-controller/src/client/sessions/service.ts b/packages/api/session-controller/src/client/sessions/service.ts index d1d840c513..3759415d72 100644 --- a/packages/api/session-controller/src/client/sessions/service.ts +++ b/packages/api/session-controller/src/client/sessions/service.ts @@ -50,10 +50,10 @@ export interface SessionSummary { /** Finished while not selected and not yet opened — the sidebar's green "done" reminder. Absent = false. */ completed?: boolean /** - * Empty-log bit (host summary derivation mirror). New Session reuses a blank - * one targeting the same workspace. Filtering stays with the consumer: the - * store carries every row, while the Workspace browser shows only the - * selected blank entry. + * Blankness from the Host summary reconciled with `sessionListMetadata`. + * New Session reuses a blank one targeting the same workspace. Filtering + * stays with the consumer: the store carries every row, while the Workspace + * browser shows only the selected blank entry. */ blank: boolean updatedAt: number diff --git a/packages/api/session-controller/tests/session.client.spec.ts b/packages/api/session-controller/tests/session.client.spec.ts index 9607c670f0..1a4fb322bf 100644 --- a/packages/api/session-controller/tests/session.client.spec.ts +++ b/packages/api/session-controller/tests/session.client.spec.ts @@ -48,6 +48,15 @@ describe('Session open', () => { expect(session.getSnapshot()).toMatchObject({ blank: false, running: true }) }, COLD_BOOT_TIMEOUT_MS) + it('rejects a blank list hint when current metadata records a started conversation', async ({ mock, start }) => { + const session = await sessionBench(mock, start, SID) + session.projections.apply('sessionListMetadata', { blank: false, lastPromptAt: 1200 }, SessionSeq(8)) + + session.handleBlank(true) + + expect(session.getSnapshot()).toMatchObject({ blank: false, promptAttempted: false, running: false }) + }) + it('installs the tail page: cold → loading → open with window and nodes in place', async ({ mock, start }) => { const session = await sessionBench(mock, start, SID) const page = plainTurn(SessionSeq(10), 3, '问', '答')