64 lines
3.2 KiB
Markdown
64 lines
3.2 KiB
Markdown
# Context trim — design notes
|
|
|
|
## What's shipped
|
|
|
|
Worker sessions are now resumed across iterations with `claude --resume <sid>`,
|
|
and the session JSONL is surgically trimmed between rounds so Anthropic's
|
|
prefix cache stays warm without paying for irrelevant history.
|
|
|
|
- Agent declares a `KEEP: <paths>` line in `.loop/notes.md`.
|
|
- Yoke locates `~/.claude/projects/<cwd-slug>/<sid>.jsonl` and rewrites it
|
|
to retain only: bootstrap records, the initial user prompt, `Read`
|
|
tool_use/tool_result pairs for kept paths, and attachments. Drops:
|
|
`thinking`, intermediate `text`, every non-`Read` tool_use, `Read`s of
|
|
non-kept files, and the matching `tool_result`s. Re-links the
|
|
parent-uuid chain across the gaps; validates tool_use ↔ tool_result
|
|
pairing before commit; keeps a `.bak`.
|
|
- Judge (brute) and scoper (saga) always run fresh — independence per
|
|
behavioral-specification §2.1.
|
|
- `YOKE_DISABLE_SESSION_TRIM=1` is the escape hatch.
|
|
|
|
## What still needs adding
|
|
|
|
1. **Format-drift guard.** The Claude Code session JSONL is undocumented.
|
|
A future CLI release could rename a field, change content-block shape,
|
|
or move the file. The validator catches most damage post-trim, but
|
|
pre-trim we should fingerprint the format (e.g., known top-level keys
|
|
on bootstrap records) and bail if it drifts. Today we trust + bail on
|
|
validate-fail; a positive check would be safer.
|
|
|
|
2. **Recovery from `--resume` failure.** If Claude rejects the resumed
|
|
session (deleted, corrupted, version skew), the iteration aborts. We
|
|
should detect this from the spawn's exit/early stream error and
|
|
transparently retry once with no `--resume` (treat last_session_id as
|
|
stale).
|
|
|
|
3. **Sandboxed runs.** When `image` is set, the agent runs inside a
|
|
Docker container — the session JSONL lives in the container's home,
|
|
not the host's. Today `trim_worker_session` no-ops in that case
|
|
(silent). Either mount the session dir into the container, or run the
|
|
trim inside the container, or document the limitation.
|
|
|
|
4. **OpenCode backend.** Trim is Claude-specific. OpenCode users get
|
|
`--resume` benefits skipped (different session model). If OpenCode
|
|
becomes a first-class target, we need an analogous trim or a
|
|
reasoned-down equivalent.
|
|
|
|
5. **Fork policy.** v1 has no forking: the trim alone bounds growth.
|
|
But sessions still grow monotonically in the *kept* portion, and
|
|
long-running tasks will eventually want a hard reset. A
|
|
`context-fork-every N` directive (or agent-declared `RESET: TRUE`)
|
|
would let users break the conversation cleanly at stage boundaries.
|
|
|
|
6. **Periodic-agent isolation.** Periodics spawn fresh sessions but
|
|
share the project's session directory. If a periodic ever needed its
|
|
own resumable continuity (e.g., a reviewer agent that learns over
|
|
runs), today there's no separate session-id tracking for it.
|
|
|
|
7. **Saga handoff.** Across saga cycles the scoper is fresh and reads
|
|
`saga-log.md` to reconstruct context. A future variant could let the
|
|
*brute worker inside saga* keep its session across cycles when the
|
|
scoper produces a closely-related sub-plan — but only if the scoper
|
|
signals it (otherwise context bleeds between unrelated chunks).
|
|
|
|
Next steps involve creating some test vectors to help make behavior standardized
|