Skip to content

feat(sdk): resume durable agent sessions - #2477

Merged
limityan merged 2 commits into
GCWing:mainfrom
limityan:yanzhn/sdk-durable-sessions
Aug 25, 2026
Merged

feat(sdk): resume durable agent sessions#2477
limityan merged 2 commits into
GCWing:mainfrom
limityan:yanzhn/sdk-durable-sessions

Conversation

@limityan

Copy link
Copy Markdown
Collaborator

Summary

  • make explicit SDK sessions durable and resumable across managed Host restarts
  • restore persisted history through the existing Agent Runtime and bind the resumed session to the new connection-scoped model
  • unload durable sessions on Session.close() and Host shutdown without deleting history
  • keep client.query() transient and continue using the existing per-session writer lock for same-session exclusion

Why

The Host should be a replaceable process, not the owner of durable conversation state. An external application can now retain a session ID, restart its SDK client/Host, and resume that same session without introducing a machine-wide daemon or a second Agent Runtime.

API Lifetime On Host close
client.query() transient discarded
client.sessions.create() durable unloaded, history retained
client.sessions.resume(id) durable unloaded, history retained

Boundaries

  • no daemon or shared socket service
  • no Node-API, WASM/WASI, or custom tool surface
  • no npm or PyPI publication; the TypeScript package remains local-only
  • no changes to GUI, CLI, Server, or app-server routing

Compatibility

  • SDK Host protocol: v4
  • Runtime SDK API: v7
  • old clients fail closed through the existing version negotiation

Validation

  • cargo test --locked -p bitfun-sdk-host --test host_lifecycle (42 passed)
  • cargo test --locked -p bitfun-sdk-host --test protocol_contracts (8 passed)
  • cargo test --locked -p bitfun-sdk-host-app --test stdio_transport (10 passed)
  • cargo test --locked -p bitfun-sdk-host-app --test process_initialization (6 passed)
  • targeted Agent Runtime SDK tests (13 passed)
  • targeted Core SDK-profile and idle-eviction tests passed
  • pnpm --dir sdk/typescript test (65 passed, 1 platform skip)
  • TypeScript type-check passed
  • cargo check --locked --workspace --exclude bitfun-desktop passed
  • package-scoped Rust formatting and git diff --check passed

cargo test --locked --workspace --exclude bitfun-desktop stopped on the unrelated existing app-server test lightweight_client_negotiates_with_the_production_server because session/reloadContext was not advertised. This PR does not modify app-server files. The full Desktop workspace check also remains blocked by the absent generated src/mobile-web/dist directory, so neither baseline limitation was expanded into this PR.

Persist explicit SDK sessions across managed Host restarts and restore them through the existing Agent Runtime. Keep transient query behavior unchanged and preserve same-session writer exclusion.
@limityan
limityan merged commit bbe07ad into GCWing:main Aug 25, 2026
10 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant