refactor: route transcript writers through session seam by jalehman · Pull Request #89123 · openclaw/openclaw

jalehman · 2026-06-01T15:01:38Z

What

Path 3 / PR 3.1b transcript writers route core transcript turn append/touch/update behavior and runtime transcript rewrite callers through the session accessor/runtime transcript seam while preserving current file-backed transcript behavior. Refs #88838.

Final head: 24a00380ff1f62f989f8c694475dc93f804e7da1.

Why

This keeps writer-domain granularity separated from the later SQLite storage flip: file-backed runtime behavior remains canonical now, while runtime writers expose operation-sized transaction boundaries SQLite can implement next.

Changes

Add transcript turn writer operation
Route assistant, user, gateway, and command writes
Route runtime transcript rewrites by scoped identity
Preserve explicit file-backed rewrite target fallback
Preserve lock, suffix guard, update identity
Ratchet migrated writers off file helpers

SQLite Adapter Instructions

Implement transcript turn writes as one backend-owned transaction: append transcript row(s), update session sessionFile/activity metadata when requested, then publish after commit.
Implement runtime transcript rewrites as one backend-owned transaction: resolve the runtime transcript target, enforce allowedRewriteSuffixEntryIds, replace/replay the active suffix, persist appended/replayed rows, then publish after commit.
Preserve sessionId, normalized sessionKey, agentId, and the explicit current file-backed target fallback while the file backend remains active.
Keep rewriteTranscriptEntriesInSessionFile(...) as a named artifact/migration boundary only, not a runtime caller API.
Do not add runtime JSON fallback, doctor migration, schema changes, or plugin SDK surface in this PR.

Testing

node scripts/run-vitest.mjs src/config/sessions/session-accessor.test.ts src/config/sessions/transcript.test.ts src/agents/command/attempt-execution.cli.test.ts src/gateway/server.chat.gateway-server-chat.test.ts src/gateway/server.chat.gateway-server-chat-b.test.ts src/gateway/server-methods/server-methods.test.ts src/agents/embedded-agent-runner/context-engine-maintenance.test.ts src/agents/embedded-agent-runner/transcript-rewrite.test.ts test/scripts/check-session-accessor-boundary.test.ts passed 4 shards / 441 tests.
node scripts/check-session-accessor-boundary.mjs passed.
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.core.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core-test-pr89123-after-review-final.tsbuildinfo passed.
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.extensions.test.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/extensions-test-pr89123-after-review.tsbuildinfo passed.
git diff --check passed.
Targeted oxlint on changed TS/JS files passed.
Targeted oxfmt --check --threads=1 on changed TS/JS files passed.
Autoreview first reported one accepted finding on owned batch publication metadata; fixed it, and rerun reported autoreview clean: no accepted/actionable findings reported.

Real behavior proof

Behavior addressed: Transcript writer domain operations preserve file-backed behavior after the rebase: a live Gateway agent turn persists the user plus assistant transcript rows under the session target, and chat.inject appends/touches/publishes the assistant-only transcript row without breaking parent ordering.
Real environment tested: Local macOS 15.6.1 arm64 checkout at /Users/phaedrus/Projects/clawdbot, Node 24.15.0, OpenClaw Gateway LaunchAgent restarted from branch codex/pr89123-refresh at final SHA 24a00380ff1f62f989f8c694475dc93f804e7da1, Gateway ws://127.0.0.1:18789.
Exact steps or command run after this patch:
- pnpm openclaw gateway restart && pnpm openclaw status
- pnpm openclaw agent --session-key agent:main:pr89123-real-proof-24a00380-20260616-1324 --message "Real behavior proof for PR 89123 final SHA 24a00380. Reply with exactly: PR89123 final transcript writer domain operation live proof OK" --timeout 300 --json
- pnpm openclaw gateway call chat.inject --json --timeout 30000 --params '{"sessionKey":"agent:main:pr89123-real-proof-24a00380-20260616-1324","agentId":"main","message":"PR89123 final transcript writer domain operation gateway inject live proof OK","label":"PR89123 24a00380 writer-domain proof"}'
- Node inspection of ~/.openclaw/agents/main/sessions/sessions.json and /Users/phaedrus/.openclaw/agents/main/sessions/12216caf-251d-423b-8bfb-143ab60324a2.jsonl.
Evidence after fix: Gateway status reported Git codex/pr89123-refresh · @ 24a00380 and Gateway service LaunchAgent installed · loaded · running (pid 3058). The agent command returned status: "ok", runId: "51a96dbd-0abb-401a-a4aa-8d3aac02a00a", sessionId: "12216caf-251d-423b-8bfb-143ab60324a2", session file /Users/phaedrus/.openclaw/agents/main/sessions/12216caf-251d-423b-8bfb-143ab60324a2.jsonl, and visible text PR89123 final transcript writer domain operation live proof OK. The inject command returned ok: true, messageId: "0f688968-75ba-4d48-821b-58d06b207d6b". Direct transcript inspection showed rowCount: 7, messageCount: 3, user row aa49ffaf -> 84bccbb4, assistant row 022de27c -> aa49ffaf, and injected assistant row 0f688968-75ba-4d48-821b-58d06b207d6b -> 022de27c; session metadata showed status: "done", updatedAt: 1781640747689, and lastInteractionAt: 1781640738724.
Observed result after fix: The locally running OpenClaw instance persisted the final-SHA live user/assistant turn, then appended the Gateway-injected assistant transcript row in order, with parent ids chained through the prior assistant response and the session registry still pointing at the same transcript file.
What was not tested: Full release, Docker, cross-OS, packaged install, and external channel adapters beyond the local Gateway/agent runtime.

clawsweeper · 2026-06-01T15:03:07Z

Codex review: needs maintainer review before merge. Reviewed June 16, 2026, 4:38 PM ET / 20:38 UTC.

Summary
This PR routes transcript append, touch, publish, and runtime rewrite callers through the session accessor/runtime transcript seam while preserving the current file-backed transcript backend.

PR surface: Source +473, Tests +490, Other +46. Total +1009 across 27 files.

Reproducibility: not applicable. this is a refactor PR rather than a bug report. The PR body does include live Gateway/agent behavior proof for the changed transcript write path.

Review metrics: 1 noteworthy metric.

Transcript writer boundary ratchet: 6 files added. The changed guard makes these migrated production files fail CI if they reintroduce legacy transcript writer imports or calls.

Stored data model
Persistent data-model change detected: serialized state: src/agents/command/attempt-execution.cli.test.ts, serialized state: src/agents/embedded-agent-runner/transcript-rewrite.test.ts, serialized state: src/agents/sessions/session-manager.ts, serialized state: src/config/sessions/session-accessor.test.ts, serialized state: src/config/sessions/session-accessor.ts, serialized state: src/config/sessions/transcript-append.ts, and 14 more. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

none.

Risk before merge

[P1] Merging changes how user, assistant, Gateway-injected, and CLI/ACP transcript writes are batched, touched, and published, so session-state invariants need maintainer signoff even with green CI.
[P1] The boundary guard now enforces a new transcript-writer migration allowlist; a mistake there could affect future CI enforcement for this migration stack.

Maintainer options:

Land after session-state signoff (recommended)
Accept the staged migration risk once a maintainer confirms the append, rewrite, publish, and metadata-touch invariants stay file-backed and behavior-neutral.
Ask for broader runtime proof
If maintainers want more confidence before merge, require an additional packaged or cross-platform Gateway/agent transcript proof focused on persisted session metadata and parent ordering.

Next step before merge

No automated repair candidate: there is no discrete code defect, and the protected maintainer label plus session-state merge risk call for human merge review.

Security
Cleared: No dependency, lockfile, workflow, package, secret, permission, download, or publish surface is changed, and the live dependency guard is clear.

Review details

Best possible solution:

Land only after maintainer signoff on the session-state invariants, then continue the remaining SQLite storage migration under the broader tracker.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this is a refactor PR rather than a bug report. The PR body does include live Gateway/agent behavior proof for the changed transcript write path.

Is this the best way to solve the issue?

Yes, this is the right staged shape for the requested migration slice: it moves writer callers behind the accessor seam without flipping storage or adding runtime fallback. The safer alternative, flipping storage here, is intentionally left to the broader staged migration tracker.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 68363368be1e.

Label changes

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. The PR body gives final-head live Gateway and agent proof with commands, observed output, transcript row ordering, parent ids, and session metadata inspection.
add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body gives final-head live Gateway and agent proof with commands, observed output, transcript row ordering, parent ids, and session metadata inspection.

Label justifications:

P2: This is a normal-priority internal refactor with broad session/gateway/agent coverage but no new public feature surface.
merge-risk: 🚨 session-state: The PR changes how transcript writes and rewrites are associated with session files, session keys, metadata touches, and transcript update events.
merge-risk: 🚨 automation: The PR changes the session accessor boundary guard that CI uses to enforce migration boundaries for transcript writer callers.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body gives final-head live Gateway and agent proof with commands, observed output, transcript row ordering, parent ids, and session metadata inspection.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body gives final-head live Gateway and agent proof with commands, observed output, transcript row ordering, parent ids, and session metadata inspection.

Evidence reviewed

PR surface:

Source +473, Tests +490, Other +46. Total +1009 across 27 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	17	983	510	+473
Tests	9	618	128	+490
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	1	54	8	+46
Total	27	1655	646	+1009

What I checked:

Live PR state: Live GitHub reports the PR is open, mergeable, clean, labeled maintainer, and has green relevant CI at head 24a0038. (24a00380ff1f)
Central writer seam: persistSessionTranscriptTurn resolves the target, appends the logical turn, touches session metadata when requested, and publishes transcript updates after the write path. (src/config/sessions/session-accessor.ts:476, 24a00380ff1f)
Lock and publication behavior: The new batch append path reuses owned transcript write context or takes the session write lock and append FIFO before publishing appended entries. (src/config/sessions/session-accessor.ts:555, 24a00380ff1f)
Migrated production callers: Assistant transcript, user-turn transcript, CLI/ACP turn, gateway inject, and runtime rewrite callers use the accessor/runtime seam rather than direct legacy writer helpers. (src/gateway/server-methods/chat-transcript-inject.ts:121, 24a00380ff1f)
Regression coverage: Focused tests cover turn append ordering, metadata touch, parentId chain preservation, rebound rejection, owned write publication, and runtime transcript rewrite by scoped identity. (src/config/sessions/session-accessor.test.ts:538, 24a00380ff1f)
Boundary guard: The session accessor boundary check now ratchets six migrated transcript writer files away from legacy transcript writer imports/calls. (scripts/check-session-accessor-boundary.mjs:96, 24a00380ff1f)

Likely related people:

jalehman: Authored the open transcript-writer seam PR and the merged accessor-seam predecessor PR that this branch builds on. (role: feature owner and recent migration-stack author; confidence: high; commits: 24a00380ff1f, ef47dd610c87; files: src/config/sessions/session-accessor.ts, src/config/sessions/transcript.ts, src/sessions/user-turn-transcript.ts)
Peter Steinberger: Recent history on gateway chat and agent attempt execution shows repeated adjacent work around gateway/session behavior and agent runtime paths. (role: recent adjacent gateway/agent contributor; confidence: medium; commits: bc44ce2c8e11, 6688779d364b, 533bd000018a; files: src/gateway/server-methods/chat.ts, src/agents/command/attempt-execution.ts)
Ayaan Zaidi: History on attempt-execution shows prior fixes for persisting and normalizing CLI transcript turns, which are among the paths this PR migrates. (role: adjacent CLI transcript behavior contributor; confidence: medium; commits: b8ef507cc082, 3a3fae0eac0f; files: src/agents/command/attempt-execution.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

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

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

jalehman · 2026-06-16T20:42:52Z

@clawsweeper re-review

clawsweeper · 2026-06-16T20:42:59Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/27646929562
Updated: 2026-06-16T21:05:17.602Z

* clawdbot-d08: route transcript writers through accessor seam * fix: refresh transcript writer seam proofs * refactor: add transcript turn writer operation * fix: preserve transcript writer store targeting * fix: preserve transcript append lock ordering * refactor: guard transcript turn session rebound * clawdbot-d02.1.9.1.35: route transcript rewrites through runtime scope * fix: preserve transcript event append return type * fix: publish transcript turn owned entries

openclaw-barnacle Bot added gateway Gateway runtime agents Agent runtime and tooling size: S maintainer Maintainer-authored PR labels Jun 1, 2026

jalehman mentioned this pull request Jun 1, 2026

Track core session/transcript SQLite migration via accessor seam #88838

Closed

jalehman mentioned this pull request Jun 1, 2026

refactor: add session accessor seam #88840

Closed

jalehman marked this pull request as draft June 1, 2026 18:10

jalehman force-pushed the clawdbot-9c3/session-accessor-seam branch from f18f99c to b39023f Compare June 4, 2026 20:31

jalehman force-pushed the clawdbot-d08/31b-transcript-writer-seam branch from 3634f87 to d7ae319 Compare June 4, 2026 20:36

jalehman force-pushed the clawdbot-d08/31b-transcript-writer-seam branch from d7ae319 to 8ee86ca Compare June 4, 2026 21:24

jalehman changed the base branch from clawdbot-9c3/session-accessor-seam to clawdbot-9c3-ce2/session-accessor-gateway-entry June 4, 2026 21:24

jalehman force-pushed the clawdbot-9c3-ce2/session-accessor-gateway-entry branch from 1c31222 to 4b0e698 Compare June 4, 2026 21:31

clawsweeper Bot added rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. and removed rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. labels Jun 4, 2026

jalehman force-pushed the clawdbot-9c3-ce2/session-accessor-gateway-entry branch from a13e0eb to 890d5e3 Compare June 4, 2026 22:37

jalehman mentioned this pull request Jun 8, 2026

fix: make sqlite session entry writes atomic #91491

Closed

jalehman force-pushed the clawdbot-9c3-ce2/session-accessor-gateway-entry branch from 890d5e3 to b496b4b Compare June 10, 2026 22:16

jalehman force-pushed the clawdbot-d08/31b-transcript-writer-seam branch from 8ee86ca to 0db3096 Compare June 11, 2026 05:03

clawsweeper Bot removed the rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. label Jun 11, 2026

jalehman force-pushed the clawdbot-d08/31b-transcript-writer-seam branch from 9d501b4 to de72b58 Compare June 16, 2026 04:59

clawsweeper Bot removed rating: 🧂 unranked krab Not merge-ready due to missing proof or serious correctness/safety concerns. status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask. labels Jun 16, 2026

jalehman added 9 commits June 16, 2026 12:29

clawdbot-d08: route transcript writers through accessor seam

0e0c1bf

fix: refresh transcript writer seam proofs

b6643fc

refactor: add transcript turn writer operation

8e248fb

fix: preserve transcript writer store targeting

a733b11

fix: preserve transcript append lock ordering

1746e6f

refactor: guard transcript turn session rebound

042acd8

clawdbot-d02.1.9.1.35: route transcript rewrites through runtime scope

ee35ab1

fix: preserve transcript event append return type

9428e97

fix: publish transcript turn owned entries

24a0038

jalehman force-pushed the clawdbot-d08/31b-transcript-writer-seam branch from c049ecb to 24a0038 Compare June 16, 2026 20:11

jalehman merged commit 00a75db into main Jun 16, 2026
194 of 196 checks passed

jalehman deleted the clawdbot-d08/31b-transcript-writer-seam branch June 16, 2026 20:59

github-actions Bot mentioned this pull request Jun 16, 2026

📡 Upstream Digest — 2026-06-16 22:06 UTC curtismercier/openclaw-mods#1090

Open

This was referenced Jul 1, 2026

gateway: support user-role chat.inject with idempotent replays #81513

Draft

fix: drop stale operational alerts from transcript mirror #66150

Closed

fix(agents): retry gap-fill tail read to avoid flush-race duplicate assistant messages [AI] #93907

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor: route transcript writers through session seam#89123

refactor: route transcript writers through session seam#89123
jalehman merged 9 commits into
mainfrom
clawdbot-d08/31b-transcript-writer-seam

jalehman commented Jun 1, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 1, 2026 •

edited

Loading

Uh oh!

jalehman commented Jun 16, 2026

Uh oh!

clawsweeper Bot commented Jun 16, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

jalehman commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Changes

SQLite Adapter Instructions

Testing

Real behavior proof

Uh oh!

clawsweeper Bot commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jalehman commented Jun 16, 2026

Uh oh!

clawsweeper Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

jalehman commented Jun 1, 2026 •

edited

Loading

clawsweeper Bot commented Jun 1, 2026 •

edited

Loading

clawsweeper Bot commented Jun 16, 2026 •

edited

Loading