feat(sessions): add export and import subcommands to move sessions between machines#321
Open
mvanhorn wants to merge 1 commit into
Open
feat(sessions): add export and import subcommands to move sessions between machines#321mvanhorn wants to merge 1 commit into
mvanhorn wants to merge 1 commit into
Conversation
…tween machines acpx sessions export <name> --output <path> writes a self-contained portable archive: format_version, agent, cwd (normalized relative to home), session state, and history. acpx sessions import <archive> reverses it: generates a fresh record_id, rewrites cwd against the destination machine's home (or --cwd override), preserves agent and state and history. Export refuses to run when the session is locked by a live queue owner (error: session-locked, exit 2) -- close the session first with acpx sessions close. Import generates a new record_id even when the source record_id already exists locally so re-importing to the source machine doesn't collide. Closes the 'Session export/import' item from the ACP coverage roadmap (docs/2026-02-19-acp-coverage-roadmap.md). Use cases: laptop -> workstation handoff for in-progress agent work, postmortem session sharing with teammates, debugging recordings.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
acpx sessions export <name> --output <path>andacpx sessions import <archive>. Export writes a self-contained portable JSON archive withformat_version,agent,cwd_relative(normalized to home), full session state, and the per-session NDJSON history. Import generates a freshrecord_id, rewritescwdagainst the destination machine's home (or--cwdoverride), and preserves agent + state + history.docs/2026-02-19-acp-coverage-roadmap.md.code: "session-locked"). Runacpx sessions closefirst. Imports always get a freshrecord_id, so re-importing to the source machine never collides with the original entry.docs/2026-02-27-acpx-session-model.md.Why this matters
acpx persists sessions per cwd in
~/.acpx/sessions/<record_id>.json. Once a session exists it survives across invocations, but it does not survive across machines. Moving an in-progress debug session from laptop to workstation, or sharing a session for a postmortem, requires manually copying the session JSON plus its sidecar.stream.lockand history files — and the absolute paths embedded inside (cwd, log file references) need rewriting for the destination.Three concrete use cases this unlocks:
debug.jsonto a teammate. Theyacpx sessions import debug.jsonand have your exact session.Demo
Simulated demo:
The demo shows the laptop-to-workstation handoff: export on the laptop produces
debug.jsonwithrecord_id,agent,cwd_relative, history-event count, andformat_version. Import on the workstation generates a newrecord_id, rewritescwdagainst the destination's home directory, preserves agent + history, and records theimported_fromprovenance.Testing
corepack pnpm typecheckcorepack pnpm lint(oxlint + oxfmt + flow-schema-terms + persisted-key-casing all clean)corepack pnpm test— 671 tests pass; newsrc/session/__tests__/export-import.test.tscovers:--cwd <path>on import rewrites the destination cwdcode: "session-locked", exit 2format_versionfails with a clear error naming the supported versionrecord_ideven when the sourcerecord_idalready exists locally