Skip to content

feat(javascript): mirror Python snapshotting on BashTool #1301

@chaliy

Description

@chaliy

Context

Python snapshotting landed in #1298: Bash and BashTool now expose snapshot(), restore_snapshot(), and from_snapshot(...), with docs/tests covering round-trip, reset+restore, empty snapshots, invalid data, and constructor-kwargs preservation.

Node already has snapshot support on Bash (snapshot(), restoreSnapshot(), Bash.fromSnapshot(data, options?)), but BashTool still has no equivalent surface. That leaves the bindings out of parity for stateful agent workflows built on the tool-contract wrapper.

Current gap

  • crates/bashkit-js/wrapper.ts: Bash has snapshot APIs; BashTool does not
  • crates/bashkit-js/src/lib.rs: native Bash exposes snapshot APIs; native BashTool does not
  • crates/bashkit-js/README.md: no snapshot/restore section today, unlike the Python README after feat(python): add snapshot restore support #1298

What to implement

Add snapshot/restore support to BashTool in the JS bindings, mirroring the Python API shape and existing Node Bash behavior:

const tool = new BashTool();
const blob = tool.snapshot();               // Uint8Array
tool.restoreSnapshot(blob);                 // void
const restored = BashTool.fromSnapshot(blob /*, options? */);

fromSnapshot() should follow the same configuration semantics as the constructor/new instance path: build the instance with caller-provided options first, then restore snapshot bytes into that configured instance so limits and identity settings survive.

Acceptance criteria

  • BashTool.snapshot() returns Uint8Array bytes containing serialized interpreter state
  • BashTool.restoreSnapshot(data) restores state from bytes produced by snapshot()
  • BashTool.fromSnapshot(data, options?) creates a new BashTool instance from snapshot bytes
  • fromSnapshot() preserves constructor options like username, hostname, maxCommands, and maxLoopIterations
  • Round-trip works: variables, files, and CWD survive snapshot()fromSnapshot()
  • restoreSnapshot() after reset() works correctly
  • Empty snapshot from a fresh instance round-trips correctly
  • Invalid/corrupted snapshot data throws BashError / JS-visible error, not a panic
  • JS integration tests cover BashTool snapshot round-trip, reset+restore, empty snapshot, and invalid snapshot cases
  • crates/bashkit-js/README.md gets a Snapshot/Restore section matching current behavior

Reference

  • Python parity PR: #1298
  • Existing Node Bash implementation: crates/bashkit-js/src/lib.rs, crates/bashkit-js/wrapper.ts

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions