refactor: use canonical transcript reader identity#89581
Conversation
|
Codex review: needs maintainer review before merge. Reviewed June 19, 2026, 12:17 PM ET / 16:17 UTC. Summary PR surface: Source +182, Tests +84, Other +19. Total +285 across 31 files. Reproducibility: not applicable. as a bug reproduction; this is a refactor. The PR body provides a real Gateway proof path for chat.history and chat.message.get against a seeded persisted session, plus focused regression coverage for the reader resolver. Review metrics: none identified. Stored data model Root-cause cluster Members:
Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything. Merge readiness Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch. Rank-up moves:
Risk before merge
Maintainer options:
Next step before merge
Security Review detailsBest possible solution: Land this refactor only after exact-head checks finish green and a maintainer accepts it as the reader-identity slice of #88838. Do we have a high-confidence way to reproduce the issue? Not applicable as a bug reproduction; this is a refactor. The PR body provides a real Gateway proof path for chat.history and chat.message.get against a seeded persisted session, plus focused regression coverage for the reader resolver. Is this the best way to solve the issue? Yes, this is the right layer for the migration slice: centralizing read identity in resolveSessionTranscriptReadTarget and the reader facade avoids keeping file-path identity at each caller. Final acceptance still needs a maintainer because the invariant crosses session-state surfaces. AGENTS.md: found and applied where relevant. Codex review notes: model internal, reasoning high; reviewed against ffd8c6e5d9ab. Label changesLabel justifications:
Evidence reviewedPR surface: Source +182, Tests +84, Other +19. Total +285 across 31 files. View PR surface stats
What I checked:
Likely related people:
What the crustacean ranks mean
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics. How this review workflow works
|
|
This refactor shape looks good overall. I would add one targeted regression around the new scoped reader seam: if the caller already passes |
a0e06d4 to
8432a1b
Compare
|
Follow-up for this branch's wave-2 rebase: the resolver's |
efbe88d to
7ffe706
Compare
cb112eb to
57aa52c
Compare
6c13413 to
52501b4
Compare
|
@clawsweeper re-review Refreshed onto current upstream main, fixed the supplied |
4f96ea4 to
e19a331
Compare
|
@clawsweeper re-review Final pushed head is |
|
🦞🧹 I asked ClawSweeper to review this item again. |
e19a331 to
156564f
Compare
|
@clawsweeper re-review Final pushed head is |
|
🦞🧹 I asked ClawSweeper to review this item again. |
609b405 to
6b17c71
Compare
* refactor: use canonical transcript reader identity * refactor: keep transcript reader dependency storage-neutral
What
Routes transcript reader projections through a canonical transcript read scope instead of letting callers identify reads by transcript file path or basename. This keeps the implementation file-backed today while making reader callers storage-neutral for the Path 3 SQLite migration.
Why
The transcript identity contract in #88838 needs
sessionKeyand the resolved session entry to be the stable runtime identity. This follow-up updates the reader side of the stack so later SQLite-backed validation can prove reader behavior without reintroducing file-path identity assumptions.Changes
src/config/sessions/session-accessor.tssrc/gateway/session-transcript-readers.tsscripts/check-session-accessor-boundary.mjsscripts/check-session-transcript-reader-boundary.mjssrc/gateway/server-methods/chat.tssrc/gateway/server-methods/sessions.tssrc/gateway/sessions-history-http.tssrc/gateway/session-history-state.tssrc/gateway/session-utils.tssrc/agents/tools/sessions-list-tool.tssrc/agents/subagent-announce-output.tssrc/tui/embedded-backend.tsTesting
Final pushed head:
156564f6885ef35b3856da2e5500900021cbb76a, rebased onto82ae81f3bf1d97a3b5686872ad1420238afeb703.node scripts/check-session-accessor-boundary.mjsnode scripts/check-session-transcript-reader-boundary.mjsgit diff --checkpnpm exec oxfmt --check --threads=1 $(git diff --name-only upstream/main)node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfonode scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test.tsbuildinfonode scripts/run-vitest.mjs src/agents/subagent-announce-output.test.ts src/config/sessions/session-accessor.test.ts src/gateway/session-transcript-readers.test.ts test/scripts/check-session-transcript-reader-boundary.test.ts test/scripts/check-session-accessor-boundary.test.ts test/scripts/ci-workflow-guards.test.ts src/tui/embedded-backend.test.ts src/agents/tools/embedded-gateway-stub.test.ts src/agents/subagent-orphan-recovery.test.ts src/gateway/server.sessions.reset-hooks.test.ts src/gateway/server-methods/artifacts.test.ts src/gateway/server-methods/sessions-files.test.ts src/gateway/session-history-state.test.ts src/gateway/sessions-history-http.revocation.test.ts src/gateway/managed-image-attachments.test.tsOPENCLAW_VITEST_INCLUDE_FILE=/tmp/pr89581-subagents-include.json OPENCLAW_VITEST_SHARD_NAME=agentic-agents-core-subagents OPENCLAW_VITEST_MAX_WORKERS=2 pnpm exec node scripts/test-projects.mjs test/vitest/vitest.agents-core.config.tsOPENCLAW_VITEST_INCLUDE_FILE=/tmp/pr89581-tools-include.json OPENCLAW_VITEST_SHARD_NAME=agentic-agents-core-tools OPENCLAW_VITEST_MAX_WORKERS=2 pnpm exec node scripts/test-projects.mjs test/vitest/vitest.agents-core.config.tsOPENCLAW_VITEST_SHARD_NAME=auto-reply-core-top-level OPENCLAW_VITEST_MAX_WORKERS=2 pnpm exec node scripts/test-projects.mjs test/vitest/vitest.auto-reply-core.config.ts test/vitest/vitest.auto-reply-top-level.config.ts.agents/skills/autoreview/scripts/autoreview --mode branch --base upstream/main --engine codex --thinking codex=low --no-web-searchnode scripts/crabbox-wrapper.mjs job run changed(provider=azure, leasecbx_af11c215e76b, runrun_e5df054b2e36, exit 0, command time 6m33.327s). The final head delta is covered by exact-head local ratchets, focused checks, autoreview, and Gateway proof below.Real behavior proof
Behavior addressed: Gateway transcript reader RPCs resolve the current transcript through canonical
sessionKeyplus loaded session entry identity instead of relying on caller-owned transcript file paths. Explicit transcript-file reads without agent identity are also preserved.Real environment tested: Local foreground Gateway from final PR head
156564f6885ef35b3856da2e5500900021cbb76a(OpenClaw 2026.6.8 (156564f)) on macOS, isolatedOPENCLAW_STATE_DIR=/tmp/openclaw-pr89581-proof, loopback port18981, auth modenone.Exact steps or command run after this patch:
Evidence after fix:
/healthzreturned{"ok":true,"status":"live"};/readyzreturned{"ready":true,"failing":[]...}; Gateway health returned default agentdevwith sessions path/tmp/openclaw-pr89581-proof/agents/dev/sessions/sessions.json;chat.historyreturnedsessionId: "proof-session-89581"and two messages with idsproof-user-1andproof-assistant-1;chat.message.getreturnedok: trueand assistant contentPath 3 transcript reader proof response; persistedsessions.jsonpointedagent:dev:path3-proofatproof-session-89581.jsonl, and that transcript contained the two JSONL message records.Observed result after fix: The real Gateway read-only chat/history APIs successfully projected a persisted transcript through the canonical session key/entry path on the pushed head. The focused regression coverage also proves supplied
sessionEntryavoids store reload, explicit transcript-file reads still work without invented agent identity, and the migrated files satisfy both Path 3 session reader CI ratchets.What was not tested: Future SQLite flip behavior, doctor migration behavior, external SDK compatibility, paired mutating Gateway RPCs such as
sessions.createover device scopes, and broad cross-OS/package install lanes on the final SHA.