feat: expose durable session id match selection helpers by 100yenadmin · Pull Request #79970 · openclaw/openclaw

100yenadmin · 2026-05-09T20:28:22Z

Summary

Implements the first narrow public discovery seam from the SQLite companion-fit stack.

This PR exposes the existing alias-aware session-id selection logic through a reusable public helper and adds a richer run-id resolution result that preserves ambiguity instead of collapsing everything to string | undefined.

Why this is better

This helps OpenClaw core and downstream consumers in a generic way:

duplicate sessionId matches now have one canonical selection policy instead of each caller guessing
ambiguity becomes a first-class outcome rather than being flattened into a cache miss
run-id lookups can preserve both store-key and request-key shape without redoing the conversion logic
the public seam stays narrow and extraction-only; it does not introduce a new lineage table or LCM-specific projection

Scope

Included:

public SessionIdMatchSelection re-export on openclaw/plugin-sdk/session-store-runtime
new resolveSessionKeySelectionForRun(...) helper in gateway code
compatibility wrapper preserved for existing resolveSessionKeyForRun(...) callers
targeted gateway/session-id tests and plugin SDK API baseline refresh

Not included:

transcript cursor/frontier work from #79904
typed transcript projections from #79905
broader lineage family projections beyond the minimal selection seam

Review Follow-up

This PR now preserves active-run semantics in the richer resolver too.

Fix:

resolveSessionKeySelectionForRun(...) now checks getAgentRunContext(runId)?.sessionKey before the store scan, matching the existing behavior already preserved by resolveSessionKeyForRun(...)

Why this was necessary:

gateway paths can register active run context before the store scan is meaningful
consumers adopting the richer helper should not regress from a resolvable active run to { kind: "none" }

Primary follow-up files:

src/gateway/server-session-key.ts
src/gateway/server-session-key.test.ts

Real Behavior Proof

Runtime proof from a direct module invocation on the PR branch:

{
  "selection": {
    "kind": "selected",
    "storeSessionKey": "agent:retired:acp:run-live",
    "requestSessionKey": "acp:run-live"
  },
  "direct": "agent:retired:acp:run-live"
}

That proof shows:

the rich resolver returns a selected result from active run context
the legacy direct resolver still returns the same canonical store key

Validation

cd /Volumes/LEXAR/repos/openclaw-79903-session-lineage
OPENCLAW_TEST_PROJECTS_SERIAL=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=120000 \
  node scripts/run-vitest.mjs \
  src/sessions/session-id-resolution.test.ts \
  src/gateway/server-session-key.test.ts

cd /Volumes/LEXAR/repos/openclaw-79903-session-lineage
pnpm plugin-sdk:api:gen

Observed locally:

2 files passed, 15 tests passed
plugin SDK API baseline regenerated cleanly

Stack placement

This PR is the narrow lineage/discovery seam in the companion-fit stack.

Related stack:

base refactor: openclaw/openclaw#78595
upstream companion umbrella: openclaw/openclaw#79902
tracked issue: openclaw/openclaw#79903
sibling replay seam: openclaw/openclaw#79972
downstream identity follow-up: Martian-Engineering/lossless-claw#642

Why this is separate:

OpenClaw owns canonical selection policy
Lossless Claw can later map richer family and segment identity on top without pushing that storage model into OpenClaw core

Issue

Refs openclaw/openclaw#79903.

clawsweeper · 2026-05-09T20:31:45Z

Codex review: found issues before merge.

Summary
The branch exports session-id match selection helpers through the plugin SDK, adds a richer gateway run-id selection helper, updates targeted tests/API baseline, and carries the broader SQLite runtime-state refactor/docs surface.

Reproducibility: not applicable. as a user bug because this is a new public helper feature. For the patch finding, yes: source inspection shows a normal call sequence where resolveSessionKeyForRun registers a request-shaped context key and the new rich resolver can later report that same value as storeSessionKey.

Real behavior proof
Sufficient (live_output): The updated PR body includes copied after-fix JSON output from a direct module invocation on the PR branch showing the rich resolver and legacy resolver behavior for active context.

Next step before merge
This protected security-labeled XL PR needs maintainer/security review and branch cleanup; the remaining work is not a safe autonomous repair lane.

Security
Needs attention: Needs security review because the branch is security-labeled and changes broad durable runtime state far beyond the helper seam.

Review findings

[P2] Return the real store key from active selections — src/gateway/server-session-key.ts:118-119

Review details

Best possible solution:

Land a narrow, security-reviewed public selection seam after the SQLite storage boundary is settled, preserving distinct store/request key semantics and keeping companion-specific lineage models outside core.

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

Not applicable as a user bug because this is a new public helper feature. For the patch finding, yes: source inspection shows a normal call sequence where resolveSessionKeyForRun registers a request-shaped context key and the new rich resolver can later report that same value as storeSessionKey.

Is this the best way to solve the issue?

No. The helper direction is plausible, but this landing shape is not the best yet because it bundles the seam into a broad security-sensitive SQLite refactor and the rich result can mislabel request keys as store keys.

Full review comments:

[P2] Return the real store key from active selections — src/gateway/server-session-key.ts:118-119
After resolveSessionKeyForRun resolves from the store, it registers active context with selection.requestSessionKey. A later resolveSessionKeySelectionForRun hits the active-context fast path first and returns that single context value as storeSessionKey, so callers can receive storeSessionKey: "acp:run-1" instead of the canonical agent:retired:acp:run-1 row key. Consumers using the rich result for store lookup or lineage will miss the row.
Confidence: 0.83

Overall correctness: patch is incorrect
Overall confidence: 0.8

Security concerns:

[medium] Route broad SQLite state rewrites through security review
The live PR API and file list show an XL branch that changes exec approvals, pairing/device state, migrations, SQLite stores, app/protocol surfaces, and docs while framed as a session-id helper. Permission semantics, migration idempotency, rollback behavior, and secret-adjacent durable state need owner/security sign-off before merge.
Confidence: 0.84

What I checked:

Current main internal helper: Current main already has the internal alias-aware resolveSessionIdMatchSelection and preferred-key policy. (src/sessions/session-id-resolution.ts:96, dd224c85603d)
Current main SDK gap: Current main session-store-runtime exports file-era session helpers and SessionEntry types, but not SessionIdMatchSelection or the selection helper functions requested by this PR. (src/plugin-sdk/session-store-runtime.ts:1, dd224c85603d)
PR SDK export: PR head adds resolvePreferredSessionKeyForSessionIdMatches, resolveSessionIdMatchSelection, and SessionIdMatchSelection to the public plugin SDK subpath. (src/plugin-sdk/session-store-runtime.ts:27, 43d86feb128d)
Follow-up fix present: PR head now checks active run context before the store scan in resolveSessionKeySelectionForRun, addressing the earlier ClawSweeper finding in that specific path. (src/gateway/server-session-key.ts:111, 43d86feb128d)
Protected broad PR: Live pull API reports security, triage: needs-real-behavior-proof, 2,174 changed files, 79,364 additions, 67,922 deletions, and mergeable_state: dirty. (43d86feb128d)
Review finding source: The rich active-context resolver returns the single context value as storeSessionKey, while the compatibility resolver can register request-shaped keys after store resolution. (src/gateway/server-session-key.ts:118, 43d86feb128d)

Likely related people:

steipete: Current-main blame for the central session-id, gateway run-key, and SDK runtime files points to Peter Steinberger, and the related database-first runtime PR is authored in this area. (role: active refactor owner / recent maintainer; confidence: high; commits: 9353febc9aa6, 6bd6f4d27c6d, 0d938748a54d; files: src/sessions/session-id-resolution.ts, src/gateway/server-session-key.ts, src/plugin-sdk/session-store-runtime.ts)
BunsDev: Prior related-review context ties the usage-family rollup commit to the continuity fields this helper seam is trying to expose. (role: lineage semantics contributor; confidence: medium; commits: d12c92c216ab; files: src/auto-reply/reply/session.ts, src/auto-reply/reply/agent-runner-session-reset.ts, src/gateway/server-methods/usage.ts)
gumadeiras: Prior related-review context connects this maintainer to custom session-store discovery hardening in the gateway matching path this PR builds on. (role: gateway session discovery contributor; confidence: medium; commits: 46f0bfc55b58; files: src/gateway/server-session-key.ts, src/sessions/session-id-resolution.ts)

Remaining risk / open question:

The PR is protected by the security label and rewrites broad runtime state, pairing, exec-approval, migration, app/protocol, and SQLite storage surfaces beyond the titled helper seam.
The branch is dirty/unmergeable against current main, so any final review needs conflict-resolution and touched-surface validation on the exact head that would merge.
The copied runtime proof covers the narrow active-context helper behavior, not the full security-sensitive SQLite runtime refactor carried by the branch.

Codex review notes: model gpt-5.5, reasoning high; reviewed against dd224c85603d.

100yenadmin · 2026-05-09T20:50:27Z

Architecture fit for this slice:

flowchart TD
    A["runId / sessionId input"] --> B["canonical session-id match selection"]
    B --> C["none"]
    B --> D["ambiguous"]
    B --> E["selected"]
    E --> F["gateway consumers"]
    E --> G["plugin-sdk consumers"]

Why this slice exists:

OpenClaw already has alias-aware session-id selection logic, but consumers should not have to rediscover or reimplement it
ambiguity is a real state, not just a failed lookup
this seam lets downstream code preserve selection semantics without demanding a larger lineage schema change yet

Why it was chosen before broader lineage work:

it is narrow, extraction-only, and generic
it improves OpenClaw-native consumers too
it is a prerequisite for LCM conversation continuity work, but it does not force LCM's own family/segment model into OpenClaw core

Stack placement:

companion umbrella: #79902
child issue: #79903
related downstream follow-up: Martian-Engineering/lossless-claw#642

Lossless Claw connection:

LCM later needs stable session-family continuity, but the first upstream step is a canonical selection seam
this keeps the boundary clean: OpenClaw owns selection policy, LCM owns its richer continuity model

100yenadmin · 2026-05-09T21:19:19Z

Follow-up on the live review finding:

addressed the active-run-context gap in resolveSessionKeySelectionForRun(...)
pushed in 43d86feb12
updated the PR body with direct runtime proof and refreshed validation counts

What changed:

the rich resolver now checks getAgentRunContext(runId)?.sessionKey before the store scan, matching the compatibility behavior already preserved by resolveSessionKeyForRun(...)
targeted tests now cover both store-shape and request-shape active run context

Runtime proof is now in the PR body and shows:

resolveSessionKeySelectionForRun("run-live") returns kind: "selected"
storeSessionKey stays canonical
requestSessionKey stays normalized for request-facing consumers

This keeps the seam extraction-only while preserving the actual runtime semantics gateway callers already depend on.

steipete added 30 commits May 9, 2026 18:01

test: read compaction successors from sqlite

429e1dd

test: read truncated transcripts from sqlite

5ac8878

refactor: append cli hook blocks through sqlite

a522ac0

test: read gateway compaction checkpoints from sqlite

6b7c14b

test: seed embedded e2e transcripts through sqlite

67d38b9

test: seed memory qa sessions through sqlite

cbc1fbb

test: seed commitment qa session through sqlite

2bebadf

test: seed stale subagent sessions through sqlite

b058082

test: seed active memory state through sqlite

80c5b35

test: assert crestodian audit through sqlite

cfc3687

test: seed commitment qa state through sqlite

12aa05b

refactor: store config audit in sqlite

80e2508

refactor: move restart handoff state to sqlite

1f845f7

refactor: store node host config in sqlite

b7cd488

refactor: store msteams delegated tokens in sqlite

1157ce6

refactor: store workspace setup state in sqlite

47b8d2a

refactor: store exec approvals in sqlite

3aa2381

refactor: clear restart sentinels from sqlite

8bf1da3

refactor: store config health in sqlite

1fc4e4c

refactor: stop reading legacy workspace state

6cd133a

refactor: allocate fresh sqlite transcript sessions

fc65a5e

refactor: compare transcript locators without filesystem probes

3cfa97f

docs: align trajectory capture with sqlite runtime

15bcd5c

refactor: keep legacy state migration in doctor path

2fff5bd

refactor: trim unused state migration logger

3d73a4e

refactor: log sqlite checkpoint failures

ec56cf5

refactor: drop legacy transcript path builders

79e5e67

refactor: stop exporting legacy session transcript dirs

f192db2

refactor: remove transcript jsonl import helper

767d407

refactor: parse sqlite transcript topics centrally

f172fc9

This was referenced May 9, 2026

fix: tighten SQLite runtime truth in session refactor #79971

Open

feat: add SQLite transcript frontier and delta API #79972

Open

fix: honor active run context in session key selection

43d86fe

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 9, 2026

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 9, 2026

100yenadmin mentioned this pull request May 10, 2026

feat: add typed SQLite transcript projections and rebuild helpers 100yenadmin/openclaw#1

Open

jetd1 mentioned this pull request May 10, 2026

[Bug]: memory-core and session-logs read tail-only JSONL as complete history when context engines rotate transcripts #80158

Closed

BradGroux mentioned this pull request May 10, 2026

WORKING: All Microsoft Issues and PRs (refresh) #74163

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: expose durable session id match selection helpers#79970

feat: expose durable session id match selection helpers#79970
100yenadmin wants to merge 409 commits intoopenclaw:mainfrom
100yenadmin:feat/openclaw-79903-session-lineage

100yenadmin commented May 9, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 9, 2026 •

edited

Loading

Uh oh!

100yenadmin commented May 9, 2026

Uh oh!

100yenadmin commented May 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

100yenadmin commented May 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why this is better

Scope

Review Follow-up

Real Behavior Proof

Validation

Stack placement

Issue

Uh oh!

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

Uh oh!

Uh oh!

100yenadmin commented May 9, 2026

Uh oh!

100yenadmin commented May 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

100yenadmin commented May 9, 2026 •

edited

Loading

clawsweeper Bot commented May 9, 2026 •

edited

Loading