Merge: short essential memory per stage; full history on demand

This commit is contained in:
2026-11-04 13:01:16 +00:00
27 changed files with 912 additions and 128 deletions
+6 -4
View File
@@ -789,6 +789,7 @@ files as that step's artifacts:
```
<artifacts>/<run>/stages/01-implementer/input.md
<artifacts>/<run>/stages/01-implementer/memory.md
<artifacts>/<run>/stages/01-implementer/history.md
<artifacts>/<run>/stages/01-implementer/output.md
<artifacts>/<run>/stages/01-implementer/private/
<artifacts>/<run>/public/
@@ -796,10 +797,11 @@ files as that step's artifacts:
`input.md` is the run prompt on the first visit; later visits carry the run
prompt under `# Run task` followed by the previous visit's output body (without
its outcome section) under `# Previous turn output`. `memory.md` is the accumulated markdown of completed turns plus the
files each turn added to the shared `public/` directory. A text-only stage (an
explicit empty `tools` block) receives both files' contents in its prompt
instead, because it has no file-reading tool. The model returns the complete
its outcome section) under `# Previous turn output`. `memory.md` is the capped (4 KB) essential memory inlined in every prompt: task,
previous stage's `# handoff`, outcome ledger and changed files. `history.md` is
the accumulated markdown of completed turns plus the files each turn added to
the shared `public/` directory, read on demand. A stage without `read` also
receives `input.md` in its prompt (capped), because it has no file-reading tool. The model returns the complete
`output.md` markdown; only its `# outcome` section is interpreted by the server.
Everything else is free-form and preserved under the step's `markdown` output.
`private/` belongs to its own visit, while `public/` is shared by every stage in
+4 -3
View File
@@ -132,9 +132,10 @@ fire, which silently makes the reviewer's `rejected` control unreachable. The ru
already counts the visits and stops at the cap, so neither loop needs new server
code and no model counts visits.
The previous turn's output and the run's accumulated `memory.md` are handed to
each model stage as files; there is no `memory` map or field selection. Put the
facts later stages need in free-form headings. Only the `# outcome` section is
The previous turn's output (`input.md`), a capped essential `memory.md` (inlined)
and the run's full `history.md` are handed to each model stage as files; there
is no `memory` map or field selection. Put the facts the next stage needs in a
short `# handoff` section; it is what the next stage sees first. Only the `# outcome` section is
interpreted. Latest completed outputs are shared only within this run. Read
provenance and routing overrides are retained in SQLite and exposed in run
inspection/metadata.
+17 -8
View File
@@ -1,7 +1,7 @@
# Model turns, results and scoped tools
Model stages are file-based. Each visit reads `input.md` and `memory.md` and
returns the complete markdown for `output.md`. Only the outcome section is
Model stages are file-based. Each visit is given its capped essential
`memory.md` inline, may read `input.md` and `history.md` on demand, and returns the complete markdown for `output.md`. Only the outcome section is
interpreted; the rest is free-form text for the next stage and the operator.
## Turn files
@@ -11,6 +11,7 @@ Every model visit gets its own directory under the run's artifact root:
```
<artifacts>/<run>/stages/01-implementer/input.md
<artifacts>/<run>/stages/01-implementer/memory.md
<artifacts>/<run>/stages/01-implementer/history.md
<artifacts>/<run>/stages/01-implementer/output.md
<artifacts>/<run>/stages/01-implementer/private/
<artifacts>/<run>/public/
@@ -20,20 +21,28 @@ Every model visit gets its own directory under the run's artifact root:
prompt under a `# Run task` heading (its own headings demoted two levels) and
add the previous visit's body under a `# Previous turn output` heading, so
every stage sees what the run is for even when an earlier stage summarised.
- `memory.md` is one `## <stage> · visit <n>` section per completed turn: the
- `memory.md` is essential memory, hard-capped at 4 KB (`turn.EssentialCap`)
and inlined in every stage's prompt: the run task, the previous stage's
handoff (its `# handoff` section, else the head of its output) with outcome and
public/ additions, a one-line-per-stage outcome ledger and the server-captured
changed files. Every truncation names the file holding the full text.
- `history.md` is one `## <stage> · visit <n>` section per completed turn: the
turn body followed by a system-written, sorted list of the files that turn
added to `public/`.
added to `public/`. It is what `memory.md` used to be, and it is never inlined.
- `private/` belongs to one visit and is never handed to a later stage.
- `public/` is shared by every stage in the run.
The server writes `input.md` and `memory.md` before the model runs and
The server writes `input.md`, `memory.md` and `history.md` before the model runs and
`output.md` after it. All three are inventoried as step artifacts, together with
`private/` and the files in `public/`. See
[stage artifacts](stage-artifacts.md) for capture limits and URLs.
A text-only stage (an explicit empty `tools` block) cannot read files, so the
server embeds the contents of `input.md` and `memory.md` in its prompt instead.
A stage with tools receives the paths and reads them itself.
Every stage gets `memory.md` inline. A stage with `read` is given the paths of
`input.md` and `history.md` to read only when it needs more detail. A stage
without `read` cannot, so the server also inlines `input.md` (capped at 32 KB);
`history.md` is never inlined. Long runs used to resend the whole history on
every model call (19 KB average, 92 KB maximum in measured runs); the essential
file bounds that per-call cost.
## Output contract
+5 -2
View File
@@ -6,6 +6,7 @@ the run's artifact root:
```
<artifacts>/<run>/stages/01-implementer/input.md
<artifacts>/<run>/stages/01-implementer/memory.md
<artifacts>/<run>/stages/01-implementer/history.md
<artifacts>/<run>/stages/01-implementer/output.md
<artifacts>/<run>/stages/01-implementer/private/
<artifacts>/<run>/public/
@@ -19,8 +20,10 @@ directories idempotently; it never deletes or rewrites existing files.
prompt under a `# Run task` heading (headings demoted two levels) followed by
the previous visit's output body (without the outcome section) under a
`# Previous turn output` heading. Carrying the task forward means a stage that
only summarised its own work is never the sole carrier of what the run is for. `memory.md` is plain
markdown: one `## <stage> · visit <n>` section per completed turn, with that
only summarised its own work is never the sole carrier of what the run is for.
`memory.md` is essential memory (`turn.RenderEssential`, capped at 4 KB, inlined
in the prompt): task, previous stage's `# handoff` (or truncated output head),
outcome ledger and captured changed files. `history.md` is plain markdown: one `## <stage> · visit <n>` section per completed turn, with that
turn's body — its own ATX headings demoted two levels, so the turn heading stays
the structural one — followed by a system-written list of files it added to
`public/`.
+4 -3
View File
@@ -12,6 +12,7 @@ The server creates this layout under the run's artifact root:
```
<artifacts root>/<run>/stages/<seq>-<stage>/input.md
<artifacts root>/<run>/stages/<seq>-<stage>/memory.md
<artifacts root>/<run>/stages/<seq>-<stage>/history.md
<artifacts root>/<run>/stages/<seq>-<stage>/output.md
<artifacts root>/<run>/stages/<seq>-<stage>/private/
<artifacts root>/<run>/public/
@@ -22,7 +23,7 @@ directory holding the database (`<data directory>/artifacts`) and can be pointed
elsewhere with the server's `ArtifactsRoot` option. Only model stages get a turn
directory.
- `input.md`, `memory.md` and `output.md` are server-written turn files.
- `input.md`, `memory.md`, `history.md` and `output.md` are server-written turn files.
- `private/` belongs to this visit. It is writable by the stage and is never
handed to a later stage.
- `public/` is run-level and shared by every stage. Files are writable and
@@ -36,7 +37,7 @@ files.
The prompt names the turn directory, the writable `private/` directory and the
shared `public/` directory, and says that the server owns `input.md`,
`memory.md` and `output.md`. Those are the exact paths the tool permission rules
`memory.md`, `history.md` and `output.md`. Those are the exact paths the tool permission rules
grant. A Pi stage also receives `PIPELINES_ARTIFACTS_DIR`; OpenCode V2 tools run
inside the shared serve process, so its prompt is the reliable carrier.
@@ -54,7 +55,7 @@ server-relative `url`. Public entries carry a `public/` name prefix. The same
fields appear under each step's `artifacts` in `pipelines inspect RUN_ID --json`
and in the TUI.
`input.md`, `memory.md` and `output.md` are the primary artifacts of every model
`input.md`, `memory.md`, `history.md` and `output.md` are the primary artifacts of every model
visit. `private/` files are listed without a prefix; shared files are listed as
`public/...` on every visit that can see them.