Skip to content

feat(gateway): expose session resolve lineage#79962

Open
aliworksx08 wants to merge 1 commit intoopenclaw:mainfrom
aliworksx08:fix/session-resolve-lineage-79902
Open

feat(gateway): expose session resolve lineage#79962
aliworksx08 wants to merge 1 commit intoopenclaw:mainfrom
aliworksx08:fix/session-resolve-lineage-79902

Conversation

@aliworksx08
Copy link
Copy Markdown

@aliworksx08 aliworksx08 commented May 9, 2026

Summary

  • Problem: companion clients can resolve a session key through sessions.resolve, but they cannot ask the Gateway for canonical lineage metadata for rotated logical session families.
  • Why it matters: clients that need durable session continuity would otherwise need to inspect raw session rows and duplicate Gateway-owned lineage rules.
  • What changed: add includeLineage to sessions.resolve, return canonical lineage metadata when requested, and keep the embedded gateway stub on the same response shape.
  • What did NOT change (scope boundary): no SQLite/cursor-backed session history API is added here; this only exposes lineage for the existing resolver surface.

Change Type (select all)

  • Bug fix
  • Feature
  • Refactor required for the fix
  • Docs
  • Security hardening
  • Chore/infra

Scope (select all touched areas)

  • Gateway / orchestration
  • Skills / tool execution
  • Auth / tokens
  • Memory / storage
  • Integrations
  • API / contracts
  • UI / DX
  • CI/CD / infra

Linked Issue/PR

Real behavior proof (required for external PRs)

  • Behavior or issue addressed: sessions.resolve can now return canonical session lineage metadata for companion clients when includeLineage: true is supplied.
  • Real environment tested: local OpenClaw checkout, Node 22+, targeted Gateway RPC and embedded gateway tests.
  • Exact steps or command run after this patch:
    • pnpm test src/gateway/sessions-resolve.test.ts src/gateway/server.sessions.preview-resolve.test.ts src/gateway/protocol/index.test.ts src/agents/tools/embedded-gateway-stub.test.ts packages/sdk/src/index.e2e.test.ts
  • Evidence after fix: targeted tests pass across 3 Vitest shards: gateway resolver/RPC, agents embedded gateway stub, and SDK e2e protocol coverage.
  • Observed result after fix: resolving a session with includeLineage: true returns the canonical key plus lineage.familyKey, lineage.currentSessionId, ordered lineage.sessionIds, and predecessor/successor ids when present.
  • What was not tested: a live companion app consuming the new field.
  • Before evidence: existing sessions.resolve returned only { ok: true, key }.

Regression Test Plan (if applicable)

  • Coverage level that should have caught this:
    • Unit test
    • Seam / integration test
    • End-to-end test
    • Existing coverage already sufficient
  • Target test or file:
    • src/gateway/sessions-resolve.test.ts
    • src/gateway/server.sessions.preview-resolve.test.ts
    • src/agents/tools/embedded-gateway-stub.test.ts
  • Scenario the test should lock in: resolver and RPC callers return lineage only when includeLineage: true, preserve exact key resolution behavior, and keep embedded gateway responses aligned with the Gateway RPC surface.
  • Why this is the smallest reliable guardrail: the behavior lives in the resolver and Gateway RPC response serialization; targeted resolver/RPC tests prove the contract without requiring a full companion app.
  • Existing test that already covers this (if any): existing resolver tests covered key/sessionId/label resolution but not lineage output.
  • If no new test is added, why not: N/A.

User-visible / Behavior Changes

Gateway clients can now pass includeLineage: true to sessions.resolve to receive canonical session lineage metadata.

Repro + Verification

Environment

  • OS: local Linux checkout
  • Runtime/container: Node 22+, pnpm workspace
  • Model/provider: N/A
  • Integration/channel (if any): Gateway RPC / embedded gateway
  • Relevant config (redacted): test session store fixtures only

Steps

Resolve a stored session without includeLineage.
Resolve the same stored session with includeLineage: true.
Verify Gateway RPC and embedded gateway paths preserve the same response contract.

Expected

Default response remains { ok: true, key }.
includeLineage: true adds canonical lineage metadata when the session row has a session id.
Embedded gateway and Gateway RPC responses stay aligned.

Actual

Matches expected.

Evidence

  • Failing test/log before + passing after
  • Trace/log snippets
  • Screenshot/recording
  • Perf numbers (if relevant)
  • Verification run:
    pnpm exec oxfmt --check --threads=1 CHANGELOG.md src/gateway/sessions-resolve.ts src/gateway/sessions-resolve.test.ts src/gateway/server-methods/sessions.ts src/gateway/server.sessions.preview-resolve.test.ts src/gateway/protocol/schema/sessions.ts src/agents/tools/embedded-gateway-stub.ts src/agents/tools/embedded-gateway-stub.runtime.ts src/agents/tools/embedded-gateway-stub.test.ts docs/gateway/protocol.md docs/concepts/session.md
    pnpm test src/gateway/sessions-resolve.test.ts src/gateway/server.sessions.preview-resolve.test.ts src/gateway/protocol/index.test.ts src/agents/tools/embedded-gateway-stub.test.ts packages/sdk/src/index.e2e.test.ts
    git diff --check

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation app: web-ui App: web-ui gateway Gateway runtime agents Agent runtime and tooling size: M triage: mock-only-proof Candidate: PR proof only shows tests, mocks, snapshots, lint, typecheck, or CI. labels May 9, 2026
@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented May 9, 2026 •
edited
Loading

Codex review: needs real behavior proof before merge.

Summary
The PR adds an optional includeLineage parameter to sessions.resolve, returns lineage metadata from the Gateway and embedded stub, and updates protocol docs, Swift protocol models, changelog, and focused tests.

Reproducibility: not applicable. as a feature PR. Source inspection gives high confidence about the current behavior: main lacks includeLineage, and the proposed implementation can be evaluated against existing rotation fields and tests rather than a broken existing contract.

Real behavior proof
Needs real behavior proof before merge: The PR body reports targeted formatter and Vitest runs only, with no after-fix real Gateway or companion-client output/log/screenshot/recording attached. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, ask a maintainer to comment @clawsweeper re-review.

Next step before merge
Needs contributor real-behavior proof and maintainer API review before any repair automation; the code defect is narrow, but automation cannot supply the external contributor's runtime proof.

Security
Cleared: The diff does not add code execution, dependency, workflow, or secret-handling changes; lineage is exposed through the existing sessions.resolve read scope.

Review findings

  • [P2] Resolve historical family session ids — src/gateway/sessions-resolve.ts:274
Review details

Best possible solution:

Extend the sessionId match path to include usageFamilySessionIds, preserve existing visibility and ambiguity rules, add a regression resolving a predecessor id, then review the additive protocol shape against the linked companion-seam issues.

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

Not applicable as a feature PR. Source inspection gives high confidence about the current behavior: main lacks includeLineage, and the proposed implementation can be evaluated against existing rotation fields and tests rather than a broken existing contract.

Is this the best way to solve the issue?

No. Adding includeLineage to sessions.resolve is a reasonable surface, but the implementation should resolve archived family session ids as well as the current id before it can satisfy the rotated-lineage contract.

Full review comments:

  • [P2] Resolve historical family session ids — src/gateway/sessions-resolve.ts:274
    sessions.resolve({ sessionId, includeLineage: true }) still only succeeds after the match path finds the current entry.sessionId or store key. After reset or compaction, predecessor ids are stored in entry.usageFamilySessionIds, so asking for an archived id returns No session found instead of the canonical key and lineage promised by the new contract. Include family ids in the sessionId match path and add a regression resolving a predecessor id.
    Confidence: 0.88

Overall correctness: patch is incorrect
Overall confidence: 0.86

What I checked:

  • PR diff adds lineage serialization after session selection: The patch adds SessionsResolveLineage, successResult, and serializeSessionsResolveSuccess, then returns serialized lineage from sessions.resolve only after a session row has already been selected. (src/gateway/sessions-resolve.ts:274, 724dbb8bda7d)
  • Current selector misses archived family ids: Current main's sessionId match path only matches entry.sessionId or the store key, while reset/rotation stores predecessor ids in usageFamilySessionIds. (src/gateway/sessions-resolve.ts:86, 18aeac86a101)
  • Lineage persistence keeps old ids on rotation: Reset creates a new current sessionId while preserving the previous id in usageFamilySessionIds, so a predecessor lookup needs to scan that family array. (src/auto-reply/reply/agent-runner-session-reset.ts:65, 18aeac86a101)
  • Related issue asks for rotated session discovery: The linked narrower issue asks for resolving which canonical/current session key owns a given sessionId and for predecessor/successor family discovery across rotations.
  • Real behavior proof is test-only: The PR body lists targeted Vitest and formatter commands and explicitly says a live companion app was not tested; no terminal output, logs, recording, or live Gateway proof artifact is attached.

Likely related people:

  • steipete: Recent GitHub history shows fix: speed up exact session lookups on src/gateway/sessions-resolve.ts, and current-main blame for the extracted resolver path points to Peter Steinberger's recent session resolver work. (role: recent Gateway session resolver maintainer; confidence: high; commits: 0ea28ddb165d, 4264ba644658; files: src/gateway/sessions-resolve.ts, src/sessions/session-id-resolution.ts)
  • BunsDev: The usage lineage rollup commit preserves lineage through /new and /reset rotations and touched the session lineage fields that this PR exposes. (role: introduced adjacent lineage persistence behavior; confidence: high; commits: d12c92c216ab; files: src/auto-reply/reply/session.test.ts, src/gateway/server-methods/usage.sessions-usage.test.ts, src/gateway/server-methods/usage.ts)
  • vincentkoc: Recent gateway/type-surface history includes broad protocol and leaf type extraction work adjacent to adding a public Gateway contract field. (role: adjacent protocol and gateway type maintainer; confidence: medium; commits: 74e7b8d47b18; files: src/gateway/protocol/schema/sessions.ts, apps/shared/OpenClawKit/Sources/OpenClawProtocol/GatewayModels.swift)

Remaining risk / open question:

  • The new contract does not resolve predecessor session ids that live only in usageFamilySessionIds, so rotated-family consumers can still get No session found.
  • The PR has only test-command proof from the contributor; external PR policy still needs real after-fix behavior proof from a real Gateway or companion-client run.
  • This is a new public Gateway protocol surface tied to a broader companion-seam design, so maintainer API review is still needed.

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

Re-review progress:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

agents Agent runtime and tooling app: web-ui App: web-ui docs Improvements or additions to documentation gateway Gateway runtime size: M triage: mock-only-proof Candidate: PR proof only shows tests, mocks, snapshots, lint, typecheck, or CI.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Feature]: Add companion-friendly SQLite transcript/session seams on top of database-first runtime

1 participant

@aliworksx08