refactor: add gateway sessions.create lifecycle seam by jalehman · Pull Request #93691 · openclaw/openclaw

jalehman · 2026-06-16T15:52:47Z

Summary

Add a narrow file-backed session accessor operation for gateway sessions.create lifecycle creation. The gateway now delegates session entry creation, transcript header initialization, rollback on transcript failure, and normalized sessionFile persistence to createSessionEntryWithTranscript(...) while keeping key resolution, model validation, command/plugin hooks, initial chat send, responses, and session-change events in the gateway layer.

Tracker

Part of the Path 3 session/transcript SQLite migration tracker: #88838

Scope

Add createSessionEntryWithTranscript(...) to src/config/sessions/session-accessor.ts.
Route gateway sessions.create lifecycle storage through that accessor seam.
Preserve current file-backed JSON store plus JSONL transcript behavior and user-visible error shape for transcript initialization failures.
Add focused accessor, gateway create, and boundary-guard coverage.

Out of scope: SQLite schema/runtime flip, reset/delete lifecycle work, public plugin SDK semantic changes, doctor migrations, and runtime fallback/dual-read behavior.

SQLite Follow-up

The SQLite adapter should implement createSessionEntryWithTranscript(...) as one transaction: create or update the session row, initialize transcript/header identity for the resulting session id, persist normalized transcript identity, and fail without leaving a partial session entry when transcript initialization fails.

Verification

node scripts/run-vitest.mjs src/config/sessions/session-accessor.test.ts src/gateway/server.sessions.create.test.ts test/scripts/check-session-accessor-boundary.test.ts
node scripts/check-session-accessor-boundary.mjs
git diff --check
node scripts/run-oxlint.mjs scripts/check-session-accessor-boundary.mjs src/config/sessions/session-accessor.ts src/config/sessions/session-accessor.test.ts src/gateway/server-methods/sessions.ts src/gateway/server.sessions.create.test.ts test/scripts/check-session-accessor-boundary.test.ts
node scripts/run-tsgo.mjs -p tsconfig.core.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/core.tsbuildinfo
node scripts/run-tsgo.mjs -p test/tsconfig/tsconfig.test.src.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/test-src.tsbuildinfo
.agents/skills/autoreview/scripts/autoreview --mode local --no-web-search --thinking codex=low

Real behavior proof

Behavior addressed: sessions.create on a live gateway creates a session entry and initializes its transcript through the new accessor-owned lifecycle path.

Real environment tested: Local live OpenClaw gateway running from /Users/phaedrus/Projects/clawdbot after building the PR and restarting the LaunchAgent-backed gateway on PR head 02334d4afcd537d0f6072dde42ceb5ed5eb0f771. The PR was later rebased conflict-free to 0d3c543dc36630e67c6319b77f942941de263d12; the rebased branch keeps the same session lifecycle patch and passed focused tests plus Crabbox proof.

Exact steps or command run after this patch:

cd /Users/phaedrus/Projects/clawdbot
pnpm build
pnpm openclaw gateway restart
pnpm openclaw --version
pnpm openclaw gateway call sessions.create --json --params '{"key":"proof-93691-session-create","agentId":"main","label":"PR 93691 sessions.create proof"}'
pnpm openclaw gateway call sessions.list --json
pnpm openclaw gateway call sessions.describe --json --params '{"key":"agent:main:proof-93691-session-create"}'
pnpm openclaw gateway call sessions.delete --json --params '{"key":"agent:main:proof-93691-session-create"}'

Evidence after fix: pnpm openclaw --version reported OpenClaw 2026.6.9 (02334d4), and the gateway /readyz and /healthz endpoints were ready/live. The sessions.create gateway call returned ok with key agent:main:proof-93691-session-create, session id 0a779131-9c42-4fcb-8a8c-cd75eb503770, and transcript file /Users/phaedrus/.openclaw/agents/main/sessions/0a779131-9c42-4fcb-8a8c-cd75eb503770.jsonl. Follow-up sessions.list and sessions.describe found the created session, and the persisted session row plus transcript JSONL header matched that session id. Cleanup via sessions.delete returned ok/deleted and archived the transcript.

Observed result after fix: Live gateway session creation produced a persisted session entry and initialized transcript identity through the patched sessions.create lifecycle path; no partial session entry was left after cleanup.

What was not tested: This live proof used the current file-backed store on the local macOS gateway. It did not test the future SQLite adapter/runtime flip, reset lifecycle work, public plugin SDK semantic changes, doctor migrations, or dual-read/fallback behavior. The post-rebase head 0d3c543dc36630e67c6319b77f942941de263d12 was not reloaded onto the live gateway, but it was covered by focused tests and Crabbox after the conflict-free rebase.

clawsweeper · 2026-06-16T16:19:49Z

Codex review: needs real behavior proof before merge. Reviewed June 16, 2026, 7:45 PM ET / 23:45 UTC.

Summary
Adds createSessionEntryWithTranscript to the session accessor, routes gateway sessions.create storage and transcript initialization through it, and extends accessor, gateway, and boundary-guard coverage.

PR surface: Source +58, Tests +122, Other +53. Total +233 across 6 files.

Reproducibility: not applicable. This is an internal migration/refactor PR, so the review path is source inspection plus focused accessor/gateway/boundary coverage rather than a failing current-main bug reproduction.

Review metrics: 1 noteworthy metric.

Internal session accessor surface: 1 operation added. The new operation becomes part of the permanent session/transcript migration seam, so maintainers should review the contract before merge.

Stored data model
Persistent data-model change detected: serialized state: src/config/sessions/session-accessor.test.ts, serialized state: src/config/sessions/session-accessor.ts, serialized state: src/gateway/server-methods/sessions.ts, serialized state: src/gateway/server.sessions.create.test.ts, unknown-data-model-change: src/config/sessions/session-accessor.test.ts, unknown-data-model-change: src/config/sessions/session-accessor.ts, and 2 more. Confirm migration or upgrade compatibility proof before merge.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
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:

Refresh against current main and rerun or clear checks-node-core-tooling.
[P2] Make the file-backed transcript-before-store-save ordering an explicit maintainer-accepted tradeoff or adjust it before merge.

Risk before merge

[P1] The new file-backed helper creates the transcript header inside the store writer callback before sessions.json save completes, so a later store-save failure can leave an unreferenced transcript artifact; that appears low-blast-radius but should be an explicit maintainer acceptance for this session-state seam.
[P1] The branch is behind current main by one commit and the live check set has one failing tooling shard that looks unrelated to this diff; land readiness still needs exact-head refresh and rerun/clearance.

Maintainer options:

Refresh exact-head proof (recommended)
Rebase or refresh against current main, rerun the focused accessor/gateway/boundary checks, and clear the failing tooling shard before merge.
Accept the file-backed ordering edge
Maintainers can accept the small orphan-transcript risk as transitional if the staged seam is preferred over keeping lifecycle composition in the gateway.

Next step before merge

[P1] No ClawSweeper repair lane: this is a protected maintainer-labeled PR with no concrete patch defect; maintainers should decide the session-state ordering risk and clear exact-head checks.

Security
Cleared: No concrete security or supply-chain concern found; the diff touches internal TS code, tests, and a local boundary guard without workflow, lockfile, dependency-source, secret, or publish-permission changes.

Review details

Best possible solution:

Land a refreshed exact-head version that keeps gateway creation on the accessor seam, preserves current file-backed JSON/JSONL behavior, and leaves the SQLite transaction implementation tracked by #88838.

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

Not applicable. This is an internal migration/refactor PR, so the review path is source inspection plus focused accessor/gateway/boundary coverage rather than a failing current-main bug reproduction.

Is this the best way to solve the issue?

Yes, mostly. Moving gateway sessions.create entry and transcript lifecycle into the session accessor is the narrow owner-boundary shape for the Path 3 seam, with the remaining decision being whether maintainers accept the file-backed write-order edge before merge.

AGENTS.md: found and applied where relevant.

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

Label changes

Label changes:

add P2: This is a bounded internal migration/refactor PR for session creation state, with limited immediate user-facing blast radius.
add merge-risk: 🚨 session-state: The diff changes how session entries and transcript headers are created and rolled back, so merge risk is tied to session/transcript state consistency.
add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The contributor proof gate is not applied because this is a protected maintainer-labeled migration PR; the PR body lists focused local verification and CI mostly passed, with one unrelated-looking tooling shard still to clear.

Label justifications:

P2: This is a bounded internal migration/refactor PR for session creation state, with limited immediate user-facing blast radius.
merge-risk: 🚨 session-state: The diff changes how session entries and transcript headers are created and rolled back, so merge risk is tied to session/transcript state consistency.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The contributor proof gate is not applied because this is a protected maintainer-labeled migration PR; the PR body lists focused local verification and CI mostly passed, with one unrelated-looking tooling shard still to clear.

Evidence reviewed

PR surface:

Source +58, Tests +122, Other +53. Total +233 across 6 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	2	161	103	+58
Tests	3	122	0	+122
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	1	54	1	+53
Total	6	337	104	+233

What I checked:

Protected maintainer label: Live PR metadata shows the PR is open, non-draft, mergeable but unstable, and labeled maintainer, which blocks cleanup closure and routes it to explicit maintainer handling. (02334d4afcd5)
Accessor seam added: The PR adds createSessionEntryWithTranscript, which prepares an entry, initializes the transcript header, normalizes sessionFile, and writes the entry through the file-backed session store seam. (src/config/sessions/session-accessor.ts:382, 02334d4afcd5)
Gateway create path routed through seam: Gateway sessions.create now calls createSessionEntryWithTranscript and keeps parent/model validation and response handling in the gateway layer. (src/gateway/server-methods/sessions.ts:1474, 02334d4afcd5)
Focused tests cover success and transcript failure rollback: The PR adds accessor-level creation/rollback coverage plus a gateway sessions.create rollback test for transcript initialization failure. (src/gateway/server.sessions.create.test.ts:263, 02334d4afcd5)
Boundary ratchet extended: The boundary script now flags legacy writer calls inside the gateway sessions.create handler and includes the new violation set in the guard's aggregate result. (scripts/check-session-accessor-boundary.mjs:248, 02334d4afcd5)
Canonical tracker remains open: The linked tracker is open and describes this work as part of the staged Path 3 session/transcript SQLite migration, with the accessor seam intended as the permanent internal domain boundary.

Likely related people:

jalehman: Authored and merged the earlier session accessor seam and transcript writer seam work, owns the linked Path 3 tracker updates, and authored this active lifecycle-seam slice. (role: feature owner and recent area contributor; confidence: high; commits: fee584a07404, f206cb79e6d3, 00a75db4280b; files: src/config/sessions/session-accessor.ts, src/gateway/server-methods/sessions.ts, scripts/check-session-accessor-boundary.mjs)

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.

@vincentkoc

…5651) (#1038) * refactor(agents): hide update plan gating helper * fix(e2e): keep live plugin pack paths local * refactor(agents): drop mcp fetch type re-export * refactor(agents): hide mcp oauth redirect classifier * refactor(agents): remove catalog browse timer test hooks * refactor(agents): hide execution contract resolver * fix(e2e): reject unsafe Docker pack names * clawdbot-d02.1.9.1.31: add sessions.create lifecycle seam (openclaw#93691) * refactor(agents): hide assistant stream delivery types * refactor(agents): hide message handler helpers * fix: clean agent lint failures * refactor(agents): hide compaction reconcile wrapper * refactor(agents): hide context cache reset helper * refactor(agents): hide copilot routing constants * refactor(agents): hide subagent outcome helpers * refactor(agents): hide tool mutation helpers * refactor(agents): hide transport error extractor * refactor(agents): remove video task status wrappers * refactor(agents): hide custom api source id helper * refactor(agents): hide docs path helpers * fix(codex): sync app-server dynamic tool protocol * refactor(agents): hide timeout seconds helper * fix(gemini): bridge OAuth profiles into CLI runtime * fix: persist Gemini CLI auth homes * fix: preserve Gemini CLI project binding * fix: scope CLI auth epochs to agent stores * fix: fail closed on unstaged Gemini profiles * fix: preserve runtime auth alias scope * fix: keep CLI auth fallback scoped * fix: accept Google API keys for Gemini CLI * fix: honor Google auth order for Gemini CLI * test: type Gemini CLI auth refresh mock * fix: forward pinned Gemini CLI auth for validation * fix: bind Gemini CLI epochs to profile homes * fix: keep CLI prepare credentials private * fix: ignore stale auto auth for Gemini CLI * fix: stage resolved Gemini OAuth profiles * fix: clear ambient Google ADC for Gemini CLI * fix: stage adopted Gemini OAuth credentials * fix: isolate Gemini CLI system auth settings * fix: enforce Gemini CLI profile auth precedence * fix: keep Gemini CLI system settings per run * fix: clean Gemini bundle settings on prepare failure * fix: preserve ambient Gemini system auth * fix: honor inherited Gemini auth policy * test: fix Gemini CLI auth test types * test: narrow Gemini CLI setup agent dir * fix: pass prepared CLI env to spawned process * fix: expose CLI runtime env diagnostics * fix: load staged Gemini CLI auth profiles * fix: log Gemini CLI runtime env activation * fix: select CLI auth profile for runtime prep * fix: keep CLI env diagnostics opt-in * fix: align Gemini CLI home path * fix: add CLI empty response diagnostics * fix: parse Gemini CLI stream output * fix: allow Gemini CLI file edits * docs: update Gemini CLI backend defaults * fix: use OpenClaw temp root for Gemini CLI settings * fix: clean up Gemini CLI backend checks * fix: keep Gemini CLI auth out of warmup * refactor(agents): hide cleanup timeout helpers * refactor(agents): hide stale run cutoff * refactor(agents): hide compaction timeout internals * refactor(agents): remove stale compaction grace helper * refactor(agents): hide idle timeout default * refactor(plugins): hide cleanup timeout internals * refactor(qqbot): hide response timeout default * refactor(feishu): hide timeout config type * refactor(browser): hide cdp reachability defaults * docs: add Gemini CLI auth changelog entry * refactor(agents): hide context window thresholds * refactor(agents): hide fallback skip cache internals * fix(agents): tolerate uncloneable adjusted tool params * refactor(cli): hide compile cache and media internals * fix(slack): preserve completed native progress titles * refactor(acp): hide test helper internals * refactor(tests): hide helper-only types * refactor(tests): hide gateway state helper types * fix(deps): remediate Dependabot alerts (openclaw#93857) Merged via squash. Prepared head SHA: 51ece24 Co-authored-by: vincentkoc <[email protected]> Co-authored-by: vincentkoc <[email protected]> Reviewed-by: @vincentkoc * refactor(commands): hide doctor harness mocks * refactor(commands): hide doctor e2e mock internals * refactor(commands): hide doctor service install mock * refactor(commands): hide gateway readiness types * refactor(commands): hide health summary internals * refactor(commands): trim health type reexports * refactor(commands): trim migrate option reexports * refactor(commands): trim backup type exports * test(codex): refresh dynamic tool snapshots * refactor(commands): hide onboarding install result * fix(ui): harden chromium test runner * refactor(commands): hide status task helper types * refactor(commands): trim setup type reexports * fix(slack): recognize MiniMax mm: namespaced reasoning tags in monitor preview (openclaw#93874) * refactor(commands): hide doctor repair helper types * feat(providers): add ClawRouter managed proxy * docs(providers): document ClawRouter integration * chore(providers): align ClawRouter package version * fix(providers): preserve ClawRouter native replay policies * chore(deps): register ClawRouter workspace * fix(providers): consume canonical ClawRouter catalog field * fix(providers): restore ClawRouter native runtime routes * fix(providers): isolate ClawRouter runtime credentials * fix(providers): cover ClawRouter runtime auth paths * fix(providers): preserve ClawRouter catalog model ids * fix(providers): require runnable ClawRouter Gemini routes * fix(providers): route ClawRouter direct streams * fix(providers): apply wrappers to direct streams * fix(providers): wrap direct fallback streams * fix(providers): compose ClawRouter native auth * fix(providers): align ClawRouter package boundary * fix(sdk): refresh plugin api baseline * refactor(commands): hide doctor utility types * refactor(commands): hide doctor state helper types * refactor(commands): trim doctor probe type exports * refactor(commands): trim setup barrel type exports * fix(macos): preserve approvals migration data (openclaw#93880) Merged via squash. Prepared head SHA: a8a0dd0 Co-authored-by: vincentkoc <[email protected]> Co-authored-by: vincentkoc <[email protected]> Reviewed-by: @vincentkoc * refactor(flows): hide setup helper types * refactor(commands): trim custom provider type reexports * fix(cron): reject invalid absolute timestamps (openclaw#93903) * fix(cron): reject invalid absolute timestamps * fix(cron): preserve ISO end of day --------- Co-authored-by: Vincent Koc <[email protected]> * refactor(commands): hide custom provider helper types * fix(update): use configured npm registry for update metadata (openclaw#93879) Merged via squash. Prepared head SHA: ae8bbb0 Co-authored-by: vincentkoc <[email protected]> Co-authored-by: vincentkoc <[email protected]> Reviewed-by: @vincentkoc * refactor(commands): trim status type exports * refactor(commands): hide doctor helper types * refactor(commands): hide migrate helper types * refactor(config): hide local helper types * revert(providers): remove ClawRouter provider * refactor(config): hide session helper types * refactor(gateway): hide local helper types * refactor(gateway): hide websocket helper types * refactor(infra): hide local helper types --------- Co-authored-by: Vincent Koc <[email protected]> Co-authored-by: Josh Lehman <[email protected]> Co-authored-by: Shakker <[email protected]> Co-authored-by: Jason O'Neal <[email protected]> Co-authored-by: Vincent Koc <[email protected]> Co-authored-by: Alix-007 <[email protected]> Co-authored-by: ronan-dandelion-cult <[email protected]> Co-authored-by: Claude Opus 4.8 (1M context) <[email protected]>

…3691)

openclaw-barnacle Bot added gateway Gateway runtime scripts Repository scripts size: M maintainer Maintainer-authored PR labels Jun 16, 2026

jalehman mentioned this pull request Jun 16, 2026

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

Closed

jalehman marked this pull request as ready for review June 16, 2026 23:05

jalehman force-pushed the clawdbot-d02.1.9.1.33/31b-session-create-lifecycle-seam branch from 64ff5e3 to 02334d4 Compare June 16, 2026 23:21

clawdbot-d02.1.9.1.31: add sessions.create lifecycle seam

0d3c543

jalehman force-pushed the clawdbot-d02.1.9.1.33/31b-session-create-lifecycle-seam branch from 02334d4 to 0d3c543 Compare June 17, 2026 00:00

jalehman merged commit cf64a9c into main Jun 17, 2026
169 of 170 checks passed

jalehman deleted the clawdbot-d02.1.9.1.33/31b-session-create-lifecycle-seam branch June 17, 2026 02:01

This was referenced Jun 17, 2026

Ecosystem Digest — 2026-06-17 Haderach-Ram/openclaw-radar#49

Open

Ecosystem Digest — 2026-06-17 Haderach-Ram/openclaw-radar#50

Closed

Ecosystem Digest — 2026-06-17 Haderach-Ram/openclaw-radar#51

Closed

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jun 17, 2026

clawdbot-d02.1.9.1.31: add sessions.create lifecycle seam (openclaw#9…

25f1a08

…3691)

crh-code pushed a commit to crh-code/openclaw that referenced this pull request Jun 18, 2026

clawdbot-d02.1.9.1.31: add sessions.create lifecycle seam (openclaw#9…

caa9ac5

…3691)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

refactor: add gateway sessions.create lifecycle seam#93691

refactor: add gateway sessions.create lifecycle seam#93691
jalehman merged 1 commit into
mainfrom
clawdbot-d02.1.9.1.33/31b-session-create-lifecycle-seam

jalehman commented Jun 16, 2026 •

edited

Loading

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 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Tracker

Scope

SQLite Follow-up

Verification

Real behavior proof

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 16, 2026 •

edited

Loading

clawsweeper Bot commented Jun 16, 2026 •

edited

Loading