kingwl
7ef21239ca
Providers stream token-sized deltas, so a session log stores hundreds of near-identical assistant/chunk lines whose JSON envelopes dwarf their payloads (~56x measured on a real DeepSeek session, 73% of file bytes). Add a lossless storage codec to dsh-session: packChunkRuns() folds each run of >=3 consecutive same-block delta chunks into one storage row -- text-chunks / reasoning-chunks / tool-call-chunks, bare slash-less tags like the header line's 'session' so rows cannot be confused with session events -- and decodeStorageRecord() expands rows back to the exact original events (seq0/time0 + dt gap array reconstruct every member's seq/time; tool-call rows carry the run-constant id/name). The encoder whitelists exact shapes and stores anything unrecognized verbatim; the decoder validates row-tagged values and fails loud on malformation. The JSONL backend gains a packChunks config (default false). Writing packs only when enabled -- default-off output stays byte-identical to the previous layout, so snapshot goldens are untouched. Reading is layout-blind: scanLog always decodes rows and now checks seq contiguity with a cursor instead of the line index, so packed, unpacked, and mixed files all load identically. Fixture readers (llm-replay parseSessionLog, acp-snapshot normalizeSessionLog) share the codec; the normalizer zeroes a row's time0/dt exactly like an event's time. The two demo bundles plumb packChunks from cordis.yml to the backend. Measured on a real coding session: 105 KB -> 42 KB (-60%), 475 lines -> 74, with reasoning/tool-call heavy sessions saving the most. Covered by example + fast-check round-trip codec tests, backend packed/mixed/torn- tail specs, and an end-to-end demo run loading a packed log through a default-config backend.
examples/ — ready-to-run demo bundles
Pre-composed plugin bundles a thin leaf cordis.yml loads instead of assembling the spine and a front door by hand. These are demo / reference packages — the -demo npm suffix marks each one as non-product surface, readable straight off the package name. The runnable leaves under the repo-root examples/ and the Python SDK runtime are the consumers; each is just its swappable backends plus one bundle entry.
| Package | npm name | Role |
|---|---|---|
agent-spine-demo/ |
@deepseek-ai/dsh-agent-spine-demo |
The executor-less/UI-less agent spine as one bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + invariants + tool-bash + tool-skill + agent-loop) |
stdio-demo/ |
@deepseek-ai/dsh-stdio-demo |
Terminal stdio chat app: the spine + console logger + readline UI + a pre-created main agent, with a boot bin |
acp-demo/ |
@deepseek-ai/dsh-acp-demo |
ACP server app: the spine + JSONL persistence + the acp bridge (no stdout logger), with a boot bin |
jsonrpc-demo/ |
@deepseek-ai/dsh-jsonrpc-demo |
Bin-only runtime that boots an external cordis.yml for the stdio JSON-RPC SDK client |
agent-spine-demo is the shared bundle; stdio-demo and acp-demo compose it with opposite front-door clusters (console logger + readline UI vs the stdout-owning ACP bridge) and own their boot bins. jsonrpc-demo mounts no composition of its own — it boots whatever tree the deployment's cordis.yml names, and is what the Python SDK runtime launches.
These are not product API. The spine pieces they bundle live in core/, the bridges/channels/boot-glue in ui/, and the swappable backends (LLM adapter, bash executor) in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.
Do not confuse this group with the repo-root examples/: that directory holds the runnable cordis.yml leaves; this group holds the bundles those leaves load.
The jsonrpc bin/exe names are legacy
jsonrpc-demo renamed like its siblings, but its bin is still dsh-jsonrpc-agent and the single-file executable is still dsh-jsonrpc-agent-pkg (referenced across the Python distribution). Those names are the SDK's runtime-startup surface; they are reconciled when the SDK unifies that startup flow, not by this move.