agent-sdk-ts parity: Persistence file layout/constants + cross-process locks (deferred)

[enyst]

agent-sdk-ts is basically a transpilation of the original python SDK that we can find at enyst/agent-sdk (it’s a fork for our use). Clone yourself agent-sdk so you have the original codebase and you can understand the code deeply before transpiling.

Gap

Python persistence is multi-process safe (FIFO locks) and has defined constants + diffing utilities. TS FileStore appends to events.jsonl with no locking, making it vulnerable to corruption if multiple processes/sessions write concurrently.

TS location

• packages/agent-sdk-ts/src/sdk/runtime/persistence.ts (FileStore)

Python reference

• openhands-sdk/openhands/sdk/conversation/persistence_const.py
• openhands-sdk/openhands/sdk/conversation/fifo_lock.py
• openhands-sdk/openhands/sdk/conversation/serialization_diff.py
• openhands-sdk/openhands/sdk/conversation/event_store.py

Implementation plan

1. Add a lock abstraction for filesystem persistence (cross-process).
2. Decide on file layout: keep JSONL or adopt per-event files; document invariants.
3. Port minimal diffing utilities for state snapshots.
4. Add tests (concurrent writers).

Acceptance criteria

• Concurrent LocalConversation sessions cannot corrupt persistence files.

[enyst]

Dependency notes (stacking / merge order)

Blocked by: (none)

Rationale / why it’s stacked this way:
This is a good candidate to implement early / in parallel.

Likely blocks: (none)