Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: address model experience review

Browse Source
This commit is contained in:
Tianyi Cui
2026-07-12 02:55:26 +08:00
parent a08485fc80
commit b5cd511f35
64 changed files with 443 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
packages/session-persistence/session-persistence/README.md
View File

@@ -4,12 +4,6 @@ The abstract durable session-persistence seam (`ctx.sessionPersistence`). Define
The persisted unit IS the existing `SessionEvent` (event-sourced model — the log is the single source of truth), so there is no parallel "persisted message" type. Metadata that is NOT replayable conversation state (format version, cwd, lineage, seed boundary) travels separately as `SessionHeader`, owned by `dsh-session` and re-exported here.
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| Resumed conversation history | This seam adds no prompt or schema. Resume restores stored surface events as message history; stored request headers reconstruct earlier calls, while the new loop composes the current system prompt, tools, and session prefix for its next request. Crash repair inserts an error result for each unanswered tool call. | Zero tokens during ordinary persistence. Resume restores retained history cost and pays the current request envelope normally; crash repair can add small error-result tokens that keep the provider transcript valid. |
## Service API (`ctx.sessionPersistence`)
| Method | Contract |
@@ -56,6 +50,12 @@ Three backends run these suites: an in-memory reference (in `tests/`), `dsh-sess
Re-exported from `dsh-session`: `SessionHeader` (immutable session metadata: `version`, `id`, `createdAt`, `cwd?`, `parentSession?`, `seedLength?`).
## Model Experience
| Context surface | What the model sees | Token effect |
|---|---|---|
| Resumed conversation history | This seam adds no prompt or schema. Resume restores stored surface events as message history; stored request headers reconstruct earlier calls, while the new loop composes the current system prompt, tools, and session prefix for its next request. Crash repair inserts an error result for each unanswered tool call. | Zero tokens during ordinary persistence. Resume restores retained history cost and pays the current request envelope normally; crash repair can add small error-result tokens that keep the provider transcript valid. |
## Known Limitations and Deferred Work
- **No deletion or retention surface** — the seam is `create`/`append`/`load`/`list` only; pruning stored sessions is out-of-band backend maintenance.