Merge: short essential memory per stage; full history on demand
This commit is contained in:
+6
-4
@@ -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
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
|
||||
@@ -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/`.
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -58,10 +58,12 @@ explicitly asks to manage a schedule; scheduling alone is not workflow authoring
|
||||
## Turns and artifacts
|
||||
|
||||
Each visit has `input.md` (the run prompt; later visits add the previous body), `memory.md`
|
||||
(completed turns), `output.md`, and `private/`. Every run also has one shared
|
||||
(short essential memory inlined in the prompt: task, previous stage's `# handoff`,
|
||||
outcome ledger, changed files; 4 KB cap), `history.md` (completed turns in full,
|
||||
read on demand), `output.md`, and `private/`. Every run also has one shared
|
||||
`public/` directory, addressed by its absolute path; files there are visible to
|
||||
later stages and are the stage's real artifacts. `input.md`, `memory.md`,
|
||||
`output.md` and `session.html` are system evidence for auditing, not stage
|
||||
`history.md`, `output.md` and `session.html` are system evidence for auditing, not stage
|
||||
output.
|
||||
|
||||
## References
|
||||
|
||||
@@ -41,8 +41,9 @@ nonterminal edge. Without `on`, entering beyond the cap fails before execution.
|
||||
Global 30-step/five-visits-per-stage safety limits still apply.
|
||||
|
||||
A model stage reads its turn's `input.md` (the run prompt on the first visit,
|
||||
the previous turn's output afterwards) and `memory.md` (completed turns with the
|
||||
files each added to `public/`). The `memory` block is retired: it no longer
|
||||
the previous turn's output afterwards), its inlined, capped `memory.md` (task,
|
||||
previous stage's `# handoff`, outcome ledger, changed files) and, on demand,
|
||||
`history.md` (completed turns in full with the files each added to `public/`). The `memory` block is retired: it no longer
|
||||
selects fields or replaces previous output for model stages, and old definitions
|
||||
that contain one parse but ignore it. Reviewers therefore see the previous
|
||||
turn's output and the accumulated memory rather than a field projection.
|
||||
|
||||
@@ -4,8 +4,8 @@ Definitions are Markdown made only of `# stage KEY` headings and fenced blocks.
|
||||
Scheduling belongs to separate saved run configurations, not `# settings` or
|
||||
schedule blocks in the definition. No unrelated prose outside blocks. The first
|
||||
stage receives the run prompt in its `input.md`; later stages receive
|
||||
the previous turn's output. Every visit also gets a `memory.md` of completed
|
||||
turns. There are no stage `input`, `output`, or `memory` blocks: the model reads
|
||||
the previous turn's output. Every visit also gets a short `memory.md` (essential
|
||||
memory, inlined in the prompt) and a full `history.md` of completed turns. There are no stage `input`, `output`, or `memory` blocks: the model reads
|
||||
the turn files and writes free-form markdown, and only the `# outcome` section is
|
||||
interpreted. Read `references/control.md` for runner-enforced limits.
|
||||
|
||||
@@ -46,13 +46,34 @@ prompts/outputs. Read `references/control.md` for the exact format.
|
||||
|
||||
## Result format
|
||||
|
||||
Each visit gets `input.md`, `memory.md`, `output.md` and `private/` in
|
||||
`<run>/stages/<seq>-<stage>/`, plus the run-level shared `public/`. The model
|
||||
reads input and memory and returns the complete `output.md` markdown. The only
|
||||
required section is the outcome heading, followed by one of the stage's declared
|
||||
edge words:
|
||||
Each visit gets `input.md`, `memory.md`, `history.md`, `output.md` and
|
||||
`private/` in `<run>/stages/<seq>-<stage>/`, plus the run-level shared
|
||||
`public/`. What a stage receives:
|
||||
|
||||
- `memory.md` (essential, hard cap 4 KB, always inlined in the prompt): the run
|
||||
task, the previous stage's handoff with its outcome and public/ additions, a
|
||||
one-line-per-stage outcome ledger (latest visit; a revisit is marked) and the
|
||||
server-captured changed files. A stage must be able to work from this alone.
|
||||
- `input.md` (on demand): the full run task and the previous turn's full output.
|
||||
- `history.md` (on demand, never inlined): every completed turn in full, the
|
||||
format `memory.md` had before essential memory existed.
|
||||
|
||||
Stages with `read` are told the two on-demand paths; stages without it get
|
||||
`input.md` inlined too (capped at 32 KB) but never `history.md`.
|
||||
|
||||
The previous stage's handoff is its `# handoff` section (any level, up to the
|
||||
next heading of the same or higher level); without one the server uses the head
|
||||
of its output, marked as such. Either is truncated to fit with a pointer to
|
||||
`input.md`, so nothing depends on the model following the convention. The
|
||||
prompt asks every stage to start its output with a short handoff: what it did,
|
||||
files changed, open issues or findings. The only required section is the
|
||||
outcome heading, followed by one of the stage's declared edge words:
|
||||
|
||||
````markdown
|
||||
# handoff
|
||||
|
||||
Fixed both review findings in cache.go; tests pass. No open issues.
|
||||
|
||||
# outcome
|
||||
|
||||
success
|
||||
|
||||
@@ -225,16 +225,17 @@ file diffs: current capture is server-owned. Do not promise full files/rollback.
|
||||
## Retained stage artifacts
|
||||
|
||||
Every model visit gets a file-based turn under the data directory
|
||||
(`<data>/artifacts/<run>/stages/<seq>-<stage>/`) with `input.md`, `memory.md`,
|
||||
`output.md` and `private/`; `public/` is run-level and shared by every stage.
|
||||
(`<data>/artifacts/<run>/stages/<seq>-<stage>/`) with `input.md`, `memory.md`
|
||||
(capped essential memory, inlined), `history.md` (full earlier turns, read on
|
||||
demand), `output.md` and `private/`; `public/` is run-level and shared by every stage.
|
||||
The root is configurable and defaults next to the database. The writable
|
||||
`private/` and shared `public/` directories are stated in the agent prompt for
|
||||
every harness, and `PIPELINES_ARTIFACTS_DIR` points at the turn directory for a
|
||||
locally spawned Pi process. OpenCode V2 tools run inside the shared serve
|
||||
process, so there the prompt, not the environment, is the reliable carrier.
|
||||
Turn-local files belong in `private/`; reports, logs and screenshots for later
|
||||
stages belong in `public/`. The server owns `input.md`, `memory.md` and
|
||||
`output.md` and never asks the model to write them directly.
|
||||
stages belong in `public/`. The server owns `input.md`, `memory.md`,
|
||||
`history.md` and `output.md` and never asks the model to write them directly.
|
||||
|
||||
After the visit the server makes one bounded inventory of the turn and public
|
||||
directories and records each file's name, size, content type (extension, sniff
|
||||
@@ -242,8 +243,9 @@ fallback) and a relative url; these appear under each step's `artifacts` in
|
||||
`inspect RUN_ID --json` and the TUI's `A` artifacts view, which groups them by
|
||||
stage and visit, marks images and shows the recorded count,
|
||||
capture-pending/not-recorded wording and partial-capture notes. Public entries
|
||||
carry a `public/` prefix. `input.md`, `memory.md` and `output.md` are the primary
|
||||
artifacts of every model visit.
|
||||
carry a `public/` prefix. `input.md`, `memory.md`, `history.md` and `output.md`
|
||||
are the primary artifacts of every model visit. To see what a late stage was
|
||||
given, read its `memory.md`; `history.md` is the full record it could consult.
|
||||
`GET /artifacts/<run>/<step>/<name>` serves the bytes (correct Content-Type and
|
||||
Content-Length, HEAD, and Range/206/416 via `http.ServeContent`), refusing
|
||||
traversal, absolute paths, symlink escapes and unknown runs/steps. A pre-turn
|
||||
|
||||
@@ -88,7 +88,7 @@ func (r *runner) scanArtifacts(runID int64, sequence int, directory string, publ
|
||||
}
|
||||
// Mandatory runtime evidence must not disappear behind hundreds of private
|
||||
// captures/public deliverables in the bounded inventory.
|
||||
for _, name := range []string{"input.md", "memory.md", "output.md", "session.html"} {
|
||||
for _, name := range []string{"input.md", "memory.md", "history.md", "output.md", "session.html"} {
|
||||
full := path.Join(rel, name)
|
||||
if info, err := root.Lstat(full); err == nil && info.Mode().IsRegular() && info.Mode()&fs.ModeSymlink == 0 && info.Size() <= maxArtifactFileBytes {
|
||||
add(full, name, info)
|
||||
|
||||
@@ -972,7 +972,7 @@ type runState struct {
|
||||
artifactDirs []string
|
||||
// prompt is the original run prompt; lastOutput is the previous visit's
|
||||
// markdown and turns is every completed turn in order. Together they render
|
||||
// the next model visit's input.md and memory.md.
|
||||
// the next model visit's input.md, memory.md and history.md.
|
||||
prompt string
|
||||
lastOutput string
|
||||
turns []turn.MemoryEntry
|
||||
@@ -1018,7 +1018,7 @@ func rebuildRunState(detail *protocol.RunDetail, decided protocol.RunStep) *runS
|
||||
state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence}
|
||||
}
|
||||
state.completed++
|
||||
state.turns = append(state.turns, turn.MemoryEntry{Stage: step.Stage, Visit: state.visits[step.Stage], Output: turnOutput(step.Output), PublicFiles: added})
|
||||
state.turns = append(state.turns, turn.MemoryEntry{Stage: step.Stage, Visit: state.visits[step.Stage], Outcome: step.Outcome, Output: turnOutput(step.Output), PublicFiles: added})
|
||||
state.lastOutput = turnOutput(step.Output)
|
||||
}
|
||||
// Seed the UI-surface accumulator from the persisted evidence so a
|
||||
@@ -1062,7 +1062,7 @@ func rebuildRetryState(detail *protocol.RunDetail, failed protocol.RunStep, hand
|
||||
state.memory[step.Stage] = memoryValue{output: values, sequence: step.Sequence}
|
||||
}
|
||||
state.completed++
|
||||
state.turns = append(state.turns, turn.MemoryEntry{Stage: step.Stage, Visit: state.visits[step.Stage], Output: turnOutput(step.Output), PublicFiles: added})
|
||||
state.turns = append(state.turns, turn.MemoryEntry{Stage: step.Stage, Visit: state.visits[step.Stage], Outcome: step.Outcome, Output: turnOutput(step.Output), PublicFiles: added})
|
||||
state.lastOutput = turnOutput(step.Output)
|
||||
}
|
||||
state.recordPersistedStep(step)
|
||||
@@ -1735,8 +1735,8 @@ func (r *runner) runLoop(ctx context.Context, id int64, graph protocol.Graph, na
|
||||
return
|
||||
}
|
||||
useAgent := stage.EffectiveType(def.Type) == stage.ModelType && (len(tools) > 0 || !explicitTools)
|
||||
// Every model visit gets a file-based turn: input.md and memory.md are
|
||||
// written before execution, output.md after it. Creation is part of the
|
||||
// Every model visit gets a file-based turn: input.md, memory.md and
|
||||
// history.md are written before execution, output.md after it. Creation is part of the
|
||||
// protocol, so an unusable turn directory fails the run instead of
|
||||
// silently degrading to the retired JSON envelope.
|
||||
artifactsDir := ""
|
||||
|
||||
@@ -0,0 +1,114 @@
|
||||
package server
|
||||
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"git.a-wan.net/alan/pipelines/internal/pipeline"
|
||||
"git.a-wan.net/alan/pipelines/internal/protocol"
|
||||
"git.a-wan.net/alan/pipelines/internal/stage"
|
||||
"git.a-wan.net/alan/pipelines/internal/turn"
|
||||
)
|
||||
|
||||
// TestFeedbackLoopRevisitGetsReviewerHandoffInEssentialMemory runs a real
|
||||
// 4-stage pipeline with a review loop (plan, code, review -> changes -> code,
|
||||
// review, land) and checks what each visit's memory.md and history.md hold:
|
||||
// memory.md stays within its cap and leads the re-entered code stage with the
|
||||
// reviewer's handoff, while history.md keeps every earlier turn in full.
|
||||
func TestFeedbackLoopRevisitGetsReviewerHandoffInEssentialMemory(t *testing.T) {
|
||||
ctx, cancel := context.WithCancel(context.Background())
|
||||
defer cancel()
|
||||
store, err := pipeline.Open(filepath.Join(t.TempDir(), "loop.db"))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
defer store.Close()
|
||||
source := strings.Replace(pipeline.Template([]string{"plan", "code", "review", "land"}, true), "success -> land\n", "success -> land\nchanges -> code\n", 1)
|
||||
if _, err := store.Submit(ctx, "loop", source); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
items, err := store.List(ctx)
|
||||
if err != nil || len(items) != 1 {
|
||||
t.Fatalf("submit/list: %+v %v", items, err)
|
||||
}
|
||||
runner, err := newRunner(ctx, store)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
filler := strings.Repeat("Long log line with commands, output and reasoning.\n", 200)
|
||||
type seen struct{ memory, history string }
|
||||
visits := map[string][]seen{}
|
||||
reviews := 0
|
||||
runner.execute = func(_ context.Context, def stage.Definition, _ stage.Values) (stage.Result, error) {
|
||||
memory, err := os.ReadFile(def.Turn.Memory)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
history, err := os.ReadFile(def.Turn.History)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
visits[def.Key] = append(visits[def.Key], seen{string(memory), string(history)})
|
||||
body := "# handoff\n\n" + def.Key + " handoff\n\n# log\n\n" + def.Key + " full log\n" + filler
|
||||
outcome := "success"
|
||||
if def.Key == "review" {
|
||||
reviews++
|
||||
if reviews == 1 {
|
||||
outcome = "changes"
|
||||
body = "# notes\n\n" + filler + "\n# handoff\n\nFINDING: lock leaks on the error path in cache.go.\n"
|
||||
}
|
||||
}
|
||||
return stage.Result{Outcome: outcome, Output: stage.Values{"markdown": body}}, nil
|
||||
}
|
||||
run, err := runner.start(protocol.Message{PipelineID: items[0].ID, Version: 1, RequestKey: "loop", Workspace: t.TempDir(), Input: map[string]any{"prompt": "Add a cache."}})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
runner.wg.Wait()
|
||||
detail, err := store.GetRun(ctx, run.ID)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if detail.Status != "succeeded" || len(detail.Steps) != 6 {
|
||||
t.Fatalf("run = %q steps=%d: %+v", detail.Status, len(detail.Steps), detail.RunSummary)
|
||||
}
|
||||
for key, list := range visits {
|
||||
for i, visit := range list {
|
||||
if len(visit.memory) > turn.EssentialCap {
|
||||
t.Fatalf("%s visit %d memory.md is %d bytes, over the cap", key, i+1, len(visit.memory))
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(visits["code"]) != 2 {
|
||||
t.Fatalf("code ran %d times, want 2", len(visits["code"]))
|
||||
}
|
||||
revisit := visits["code"][1]
|
||||
for _, want := range []string{
|
||||
"Add a cache.",
|
||||
"## Previous stage: review · visit 1 · outcome changes",
|
||||
"FINDING: lock leaks on the error path in cache.go.",
|
||||
"- code · visit 1 · outcome success (this stage's previous visit; detail in history.md)",
|
||||
} {
|
||||
if !strings.Contains(revisit.memory, want) {
|
||||
t.Fatalf("re-entered code memory.md missing %q:\n%s", want, revisit.memory)
|
||||
}
|
||||
}
|
||||
if strings.Contains(revisit.memory, "Long log line") {
|
||||
t.Fatalf("re-entered code memory.md carried a full log:\n%s", revisit.memory)
|
||||
}
|
||||
for _, want := range []string{"## plan · visit 1", "plan full log", "## code · visit 1", "code full log", "## review · visit 1", "FINDING: lock leaks"} {
|
||||
if !strings.Contains(revisit.history, want) {
|
||||
t.Fatalf("re-entered code history.md missing %q", want)
|
||||
}
|
||||
}
|
||||
land := visits["land"][0]
|
||||
if !strings.Contains(land.memory, "## Previous stage: review · visit 2 · outcome success") || !strings.Contains(land.memory, "review handoff") {
|
||||
t.Fatalf("land memory.md lacks the last review handoff:\n%s", land.memory)
|
||||
}
|
||||
if len(land.history) < 10*len(land.memory) {
|
||||
t.Fatalf("land history %d bytes vs memory %d bytes: essential memory is not compact", len(land.history), len(land.memory))
|
||||
}
|
||||
}
|
||||
@@ -38,7 +38,7 @@ func TestTurnsAccumulateMemoryAndListFilesAsArtifacts(t *testing.T) {
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var secondInput, secondMemory string
|
||||
var secondInput, secondMemory, secondHistory string
|
||||
runner.execute = func(_ context.Context, def stage.Definition, _ stage.Values) (stage.Result, error) {
|
||||
if def.Turn.Input == "" || def.Turn.Memory == "" || def.Turn.Output == "" || def.Turn.Private == "" || def.Turn.Public == "" {
|
||||
t.Fatalf("runner did not provide the turn paths: %+v", def.Turn)
|
||||
@@ -63,6 +63,14 @@ func TestTurnsAccumulateMemoryAndListFilesAsArtifacts(t *testing.T) {
|
||||
t.Fatal(err)
|
||||
}
|
||||
secondMemory = string(data)
|
||||
if def.Turn.History == "" {
|
||||
t.Fatalf("runner did not provide the history path: %+v", def.Turn)
|
||||
}
|
||||
data, err = os.ReadFile(def.Turn.History)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
secondHistory = string(data)
|
||||
if _, err := os.Stat(filepath.Join(def.Turn.Private, "secret.txt")); !os.IsNotExist(err) {
|
||||
t.Fatalf("a later turn received an earlier private file: %v", err)
|
||||
}
|
||||
@@ -93,11 +101,19 @@ func TestTurnsAccumulateMemoryAndListFilesAsArtifacts(t *testing.T) {
|
||||
t.Fatalf("second input.md = %q, want the run task and the previous turn's output", secondInput)
|
||||
}
|
||||
for _, want := range []string{"## first · visit 1", "first body", "Files added to public/:\n- public/shared.txt"} {
|
||||
if !strings.Contains(secondHistory, want) {
|
||||
t.Fatalf("second history.md missing %q:\n%s", want, secondHistory)
|
||||
}
|
||||
}
|
||||
for _, want := range []string{"# Essential memory", "original task", "## Previous stage: first · visit 1 · outcome success", "first body", "Added to public/: public/shared.txt", "- first · visit 1 · outcome success"} {
|
||||
if !strings.Contains(secondMemory, want) {
|
||||
t.Fatalf("second memory.md missing %q:\n%s", want, secondMemory)
|
||||
}
|
||||
}
|
||||
for _, name := range []string{"input.md", "memory.md", "output.md"} {
|
||||
if len(secondMemory) > turn.EssentialCap {
|
||||
t.Fatalf("memory.md is %d bytes, over the %d cap", len(secondMemory), turn.EssentialCap)
|
||||
}
|
||||
for _, name := range []string{"input.md", "memory.md", "history.md", "output.md"} {
|
||||
if _, ok := artifactNamed(detail.Steps[1].Artifacts, name); !ok {
|
||||
t.Fatalf("second visit did not list %s: %+v", name, detail.Steps[1].Artifacts)
|
||||
}
|
||||
@@ -125,7 +141,7 @@ func TestRebuildRunStateRestoresPublicFileLists(t *testing.T) {
|
||||
},
|
||||
}
|
||||
state := rebuildRunState(detail, protocol.RunStep{Sequence: 2, Stage: "second", Output: map[string]any{"markdown": "second body\n"}})
|
||||
memory := turn.RenderMemory(state.turns)
|
||||
memory := turn.RenderHistory(state.turns)
|
||||
for _, want := range []string{
|
||||
"## first · visit 1",
|
||||
"Files added to public/:\n- public/a.png",
|
||||
@@ -157,7 +173,7 @@ func TestRebuildRetryStateRestoresPublicFileLists(t *testing.T) {
|
||||
"prefix_provenance": []any{map[string]any{"stage": "first", "sequence": float64(1)}},
|
||||
}
|
||||
state := rebuildRetryState(detail, detail.Steps[1], handoff)
|
||||
memory := turn.RenderMemory(state.turns)
|
||||
memory := turn.RenderHistory(state.turns)
|
||||
if !strings.Contains(memory, "Files added to public/:\n- public/report.pdf") {
|
||||
t.Fatalf("retry memory lost the inherited public file list:\n%s", memory)
|
||||
}
|
||||
@@ -248,7 +264,7 @@ func TestRetryCarriesPublicFilesAcrossAttempts(t *testing.T) {
|
||||
t.Fatalf("transitive retry did not carry the public file: %q %v", data, err)
|
||||
}
|
||||
paths := runner.turnPaths(second.ID, 2, "b")
|
||||
memory, err := os.ReadFile(paths.MemoryPath)
|
||||
memory, err := os.ReadFile(paths.HistoryPath)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
@@ -40,14 +40,16 @@ func stageTurnPaths(paths turn.Paths) stage.TurnPaths {
|
||||
Dir: paths.TurnDir,
|
||||
Input: paths.InputPath,
|
||||
Memory: paths.MemoryPath,
|
||||
History: paths.HistoryPath,
|
||||
Output: paths.OutputPath,
|
||||
Private: paths.PrivateDir,
|
||||
Public: paths.PublicDir,
|
||||
}
|
||||
}
|
||||
|
||||
// prepareTurn creates the visit layout and writes the model's input.md and
|
||||
// memory.md before the visit starts. A failure here is a run failure: the file
|
||||
// prepareTurn creates the visit layout and writes the model's input.md,
|
||||
// memory.md (essential memory, capped at turn.EssentialCap) and history.md (every
|
||||
// completed turn in full) before the visit starts. A failure here is a run failure: the file
|
||||
// protocol is the stage contract, not best-effort evidence.
|
||||
//
|
||||
// retryInput is the complete merged input for a selected-stage retry and nil for
|
||||
@@ -59,12 +61,23 @@ func (r *runner) prepareTurn(paths turn.Paths, state *runState, retryInput stage
|
||||
return err
|
||||
}
|
||||
input := turnInputWithRetry(state.turnInput(), retryInput)
|
||||
memory := turn.RenderMemory(state.turns)
|
||||
if err := os.WriteFile(paths.InputPath, []byte(input), 0o600); err != nil {
|
||||
return fmt.Errorf("write %s: %w", paths.InputPath, err)
|
||||
}
|
||||
if err := os.WriteFile(paths.MemoryPath, []byte(memory), 0o600); err != nil {
|
||||
return fmt.Errorf("write %s: %w", paths.MemoryPath, err)
|
||||
history := turn.RenderHistory(state.turns)
|
||||
memory := turn.RenderEssential(turn.Essential{
|
||||
Task: state.prompt,
|
||||
StageKey: paths.StageKey,
|
||||
Entries: state.turns,
|
||||
ChangedFiles: state.capturedList(),
|
||||
InputPath: paths.InputPath,
|
||||
HistoryPath: paths.HistoryPath,
|
||||
})
|
||||
for _, file := range []struct{ path, content string }{
|
||||
{paths.InputPath, input},
|
||||
{paths.MemoryPath, memory},
|
||||
{paths.HistoryPath, history},
|
||||
} {
|
||||
if err := os.WriteFile(file.path, []byte(file.content), 0o600); err != nil {
|
||||
return fmt.Errorf("write %s: %w", file.path, err)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@@ -126,6 +139,7 @@ func (s *runState) recordTurn(step protocol.RunStep, publicFiles []string) {
|
||||
s.turns = append(s.turns, turn.MemoryEntry{
|
||||
Stage: step.Stage,
|
||||
Visit: s.visits[step.Stage],
|
||||
Outcome: step.Outcome,
|
||||
Output: output,
|
||||
PublicFiles: publicFiles,
|
||||
})
|
||||
|
||||
@@ -209,7 +209,7 @@ func (c *AgentClient) Generate(ctx context.Context, config ModelConfig, prompt s
|
||||
|
||||
// artifactsPrompt tells an agent stage where it may write the files it
|
||||
// produces. The turn directory itself belongs to the server: input.md,
|
||||
// memory.md and output.md are written by the runner and output.md comes from
|
||||
// memory.md, history.md and output.md are written by the runner and output.md comes from
|
||||
// the model's final message. The only writable artifact scopes are this
|
||||
// visit's private/ directory and the run's shared public/ directory, matching
|
||||
// the exact paths permissionRules grants. It is empty when the runtime provided
|
||||
@@ -231,7 +231,7 @@ func artifactsPrompt(directory string, access ArtifactAccess) string {
|
||||
fmt.Fprintf(&b, " Save artifacts for later stages under %s; files there are shared by the run.", access.WriteShared)
|
||||
}
|
||||
if writable {
|
||||
b.WriteString(" Do not write input.md, memory.md or output.md yourself; the server owns those and writes output.md from your final message.")
|
||||
b.WriteString(" Do not write input.md, memory.md, history.md or output.md yourself; the server owns those and writes output.md from your final message.")
|
||||
} else {
|
||||
b.WriteString(" The server records the turn files as artifacts.")
|
||||
}
|
||||
|
||||
@@ -36,7 +36,7 @@ func TestArtifactsPromptStatesWritableScopes(t *testing.T) {
|
||||
"/data/artifacts/1/2",
|
||||
"/data/artifacts/1/2/private",
|
||||
"/data/artifacts/1/public",
|
||||
"do not write input.md, memory.md or output.md",
|
||||
"do not write input.md, memory.md, history.md or output.md",
|
||||
} {
|
||||
if !strings.Contains(strings.ToLower(prompt), strings.ToLower(want)) {
|
||||
t.Fatalf("prompt missing %q: %q", want, prompt)
|
||||
|
||||
@@ -8,6 +8,7 @@ import (
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
"unicode/utf8"
|
||||
|
||||
"git.a-wan.net/alan/pipelines/internal/turn"
|
||||
)
|
||||
@@ -57,52 +58,54 @@ func modelPrompt(def Definition, spec ModelSpec, input Values) (string, error) {
|
||||
toolsLine = "This call has these stage tools: " + strings.Join(tools, ", ") + "."
|
||||
}
|
||||
|
||||
// Essential memory (memory.md) is short and capped, so it is inlined for
|
||||
// every stage: the stage needs no read call to start, and each model call
|
||||
// re-sends only this bounded context. The full history (history.md) is
|
||||
// never inlined; a stage with the read tool is pointed at it and at input.md
|
||||
// for on-demand detail.
|
||||
memory, readErr := os.ReadFile(def.Turn.Memory)
|
||||
if readErr != nil {
|
||||
return "", fmt.Errorf("model stage %s: read turn memory: %w", def.Key, readErr)
|
||||
}
|
||||
var b strings.Builder
|
||||
// Receiving runtime context must not require adding filesystem tools to a
|
||||
// web-only (or otherwise restricted) stage. Inline it whenever read is not
|
||||
// declared, without widening the harness's permissions or changing a workflow.
|
||||
if !slices.Contains(tools, "read") {
|
||||
memory, readErr := os.ReadFile(def.Turn.Memory)
|
||||
if readErr != nil {
|
||||
return "", fmt.Errorf("model stage %s: read turn memory: %w", def.Key, readErr)
|
||||
canRead := slices.Contains(tools, "read")
|
||||
switch {
|
||||
case !canRead && len(tools) == 0:
|
||||
b.WriteString("This call has no tools, so the server included the turn files below.\n\n")
|
||||
case !canRead:
|
||||
b.WriteString("The read tool is not enabled, so the server included the turn files below. Use this supplied context; no extra filesystem access is needed.\n\n")
|
||||
}
|
||||
writeTurnFile(&b, "memory.md", def.Turn.Memory, capInline(string(memory), turn.EssentialCap, def.Turn.Memory))
|
||||
if canRead {
|
||||
b.WriteString("Rely on this essential memory first. Read on demand only, when you need more detail:\n")
|
||||
fmt.Fprintf(&b, "- Input (full run task and previous stage output): %s\n", def.Turn.Input)
|
||||
if def.Turn.History != "" {
|
||||
fmt.Fprintf(&b, "- History (every earlier turn in full; large): %s\n", def.Turn.History)
|
||||
}
|
||||
b.WriteString("\n")
|
||||
} else {
|
||||
input, readErr := os.ReadFile(def.Turn.Input)
|
||||
if readErr != nil {
|
||||
return "", fmt.Errorf("model stage %s: read turn input: %w", def.Key, readErr)
|
||||
}
|
||||
if len(tools) == 0 {
|
||||
b.WriteString("This call has no tools, so the server included the turn files below.\n\n")
|
||||
} else {
|
||||
b.WriteString("The read tool is not enabled, so the server included the turn files below. Use this supplied context; no extra filesystem access is needed.\n\n")
|
||||
}
|
||||
fmt.Fprintf(&b, "# memory.md (%s)\n\n%s", def.Turn.Memory, string(memory))
|
||||
if len(memory) > 0 && !strings.HasSuffix(string(memory), "\n") {
|
||||
b.WriteString("\n")
|
||||
}
|
||||
b.WriteString("\n")
|
||||
fmt.Fprintf(&b, "# input.md (%s)\n\n%s", def.Turn.Input, string(input))
|
||||
if len(input) > 0 && !strings.HasSuffix(string(input), "\n") {
|
||||
b.WriteString("\n")
|
||||
}
|
||||
b.WriteString("\n")
|
||||
} else {
|
||||
b.WriteString("Read these two files before working:\n")
|
||||
fmt.Fprintf(&b, "- Memory: %s\n", def.Turn.Memory)
|
||||
fmt.Fprintf(&b, "- Input: %s\n\n", def.Turn.Input)
|
||||
b.WriteString("Memory is the accumulated markdown of the run's completed turns, including the files each turn added to public/. Input is the run prompt on the first visit and the previous visit's output afterwards. Read both files before acting.\n\n")
|
||||
writeTurnFile(&b, "input.md", def.Turn.Input, capInline(string(input), InlineInputCap, def.Turn.Input))
|
||||
}
|
||||
b.WriteString("Stage instructions:\n\n")
|
||||
b.WriteString(strings.TrimSpace(spec.Prompt))
|
||||
if changed := serverChangedFiles(input); len(changed) > 0 {
|
||||
b.WriteString("\n\nServer-captured changed files for this run (verified from the workspace, not a model claim):\n")
|
||||
for _, name := range changed {
|
||||
for i, name := range changed {
|
||||
if i == maxPromptChangedFiles {
|
||||
fmt.Fprintf(&b, "- ... and %d more\n", len(changed)-i)
|
||||
break
|
||||
}
|
||||
fmt.Fprintf(&b, "- %s\n", name)
|
||||
}
|
||||
b.WriteString("\nUse this list to distinguish this run's work from pre-existing dirty files.")
|
||||
}
|
||||
b.WriteString("\n\nProduce ")
|
||||
b.WriteString(def.Turn.Output)
|
||||
b.WriteString(" as markdown; return its complete content as your final message (the server writes that file). The only required section is the outcome, for example:\n\n# outcome\n")
|
||||
b.WriteString(" as markdown; return its complete content as your final message (the server writes that file). Start it with a short # handoff section (at most about 1 KB): what you did, files changed, and open issues or findings the next stage must act on. The next stage receives only that section as essential memory; the rest of your output stays in history. The only required section is the outcome, for example:\n\n# handoff\n...\n\n# outcome\n")
|
||||
b.WriteString(preferredOutcome(outcomes))
|
||||
fmt.Fprintf(&b, "\n\nAllowed outcomes: %s.\n\nEverything else is free-form markdown for the next stage and the operator. The server does not parse or validate any other section. Return the complete output.md content as your final message; do not wrap it in a JSON envelope.\n", strings.Join(outcomes, ", "))
|
||||
fmt.Fprintf(&b, "\nExecution time: %s. Timezone: %s.\n", time.Now().Format(time.RFC3339), time.Local.String())
|
||||
@@ -118,6 +121,37 @@ func modelPrompt(def Definition, spec ModelSpec, input Values) (string, error) {
|
||||
// serverChangedFiles reads the runner's reserved changed-path list from stage
|
||||
// input, accepting the []string the runner supplies and the []any JSON decoding
|
||||
// produces for a replayed handoff. Other values are ignored.
|
||||
// InlineInputCap bounds input.md when it is inlined for a stage without the
|
||||
// read tool. Such a stage cannot read on demand, so the cap is generous; it only
|
||||
// stops one pathological previous output from dominating every call.
|
||||
const InlineInputCap = 32 << 10
|
||||
|
||||
// maxPromptChangedFiles bounds the bound server_changed_files list in the
|
||||
// prompt; the complete list stays in the stage input.
|
||||
const maxPromptChangedFiles = 50
|
||||
|
||||
// writeTurnFile embeds one server-written turn file under a heading naming it.
|
||||
func writeTurnFile(b *strings.Builder, name, path, content string) {
|
||||
fmt.Fprintf(b, "# %s (%s)\n\n%s", name, path, content)
|
||||
if content != "" && !strings.HasSuffix(content, "\n") {
|
||||
b.WriteString("\n")
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
|
||||
// capInline keeps the head of content within limit bytes (at a rune boundary)
|
||||
// and names the file holding the rest.
|
||||
func capInline(content string, limit int, path string) string {
|
||||
if len(content) <= limit {
|
||||
return content
|
||||
}
|
||||
cut := limit
|
||||
for cut > 0 && !utf8.RuneStart(content[cut]) {
|
||||
cut--
|
||||
}
|
||||
return content[:cut] + fmt.Sprintf("\n\n_[truncated: %d of %d bytes shown; full file at %s]_\n", cut, len(content), path)
|
||||
}
|
||||
|
||||
func serverChangedFiles(input Values) []string {
|
||||
raw, ok := input["server_changed_files"]
|
||||
if !ok {
|
||||
|
||||
@@ -0,0 +1,60 @@
|
||||
package stage
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"git.a-wan.net/alan/pipelines/internal/turn"
|
||||
)
|
||||
|
||||
// TestModelPromptInlinesEssentialMemoryAndPointsAtHistory: every stage gets the
|
||||
// capped essential memory inline; the full history is never inlined, and a
|
||||
// stage with read is pointed at input.md and history.md for on-demand detail.
|
||||
func TestModelPromptInlinesEssentialMemoryAndPointsAtHistory(t *testing.T) {
|
||||
for _, toolset := range []string{"read\nedit", "websearch", ""} {
|
||||
t.Run(strings.ReplaceAll(toolset, "\n", "-"), func(t *testing.T) {
|
||||
def := turnDefinition(t)
|
||||
def.Blocks["tools"] = toolset
|
||||
def.Turn.History = filepath.Join(def.Turn.Dir, "history.md")
|
||||
files := map[string]string{
|
||||
def.Turn.Memory: "# Essential memory\n\nreviewer finding: lock leak\n" + strings.Repeat("m", 2*turn.EssentialCap),
|
||||
def.Turn.Input: "full previous output\n",
|
||||
def.Turn.History: "FULL HISTORY BODY\n",
|
||||
}
|
||||
for path, content := range files {
|
||||
if err := os.WriteFile(path, []byte(content), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
spec, err := (ModelStage{}).Spec(def)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
prompt, err := modelPrompt(def, spec, nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !strings.Contains(prompt, "reviewer finding: lock leak") || !strings.Contains(prompt, "_[truncated: ") {
|
||||
t.Fatalf("essential memory not inlined with its cap: %q", prompt)
|
||||
}
|
||||
if strings.Contains(prompt, strings.Repeat("m", turn.EssentialCap+1)) {
|
||||
t.Fatal("inlined memory exceeded its cap")
|
||||
}
|
||||
if strings.Contains(prompt, "FULL HISTORY BODY") {
|
||||
t.Fatal("history.md was inlined")
|
||||
}
|
||||
if !strings.Contains(prompt, "# handoff") {
|
||||
t.Fatal("prompt does not ask for a handoff section")
|
||||
}
|
||||
canRead := strings.Contains(toolset, "read")
|
||||
if got := strings.Contains(prompt, def.Turn.History); got != canRead {
|
||||
t.Fatalf("history path named = %v, want %v: %q", got, canRead, prompt)
|
||||
}
|
||||
if got := strings.Contains(prompt, "full previous output"); got == canRead {
|
||||
t.Fatalf("input.md inlined = %v with read = %v", got, canRead)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -237,7 +237,7 @@ func TestAgentGeneratePromptCarriesToolsEditScopeAndShellCommands(t *testing.T)
|
||||
def.Turn.Output,
|
||||
def.Turn.Private,
|
||||
def.Turn.Public,
|
||||
"Do not write input.md, memory.md or output.md",
|
||||
"Do not write input.md, memory.md, history.md or output.md",
|
||||
} {
|
||||
if !strings.Contains(promptBody, want) {
|
||||
t.Fatalf("agent prompt missing %q: %s", want, promptBody)
|
||||
|
||||
@@ -10,14 +10,17 @@ import (
|
||||
// Values are runtime data, not the prose output contract in a definition.
|
||||
type Values map[string]any
|
||||
|
||||
// TurnPaths is the runtime-provided file layout for one model visit. Input and
|
||||
// memory are read by the model; Output is written by the server from the model's
|
||||
// TurnPaths is the runtime-provided file layout for one model visit. Memory is
|
||||
// the short essential memory the prompt inlines; Input and History are the full
|
||||
// previous output and run history, read only on demand (History is empty for
|
||||
// callers that predate it). Output is written by the server from the model's
|
||||
// returned markdown. Private belongs to this visit; Public is shared by every
|
||||
// stage in the run.
|
||||
type TurnPaths struct {
|
||||
Dir string
|
||||
Input string
|
||||
Memory string
|
||||
History string
|
||||
Output string
|
||||
Private string
|
||||
Public string
|
||||
|
||||
@@ -0,0 +1,325 @@
|
||||
package turn
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
"unicode/utf8"
|
||||
)
|
||||
|
||||
// EssentialCap is the hard byte cap on a visit's memory.md (essential memory).
|
||||
// It is small on purpose: the file is inlined into every model call of the
|
||||
// visit, so its size is paid once per call. Everything else stays on disk in
|
||||
// history.md and input.md, read only on demand.
|
||||
const EssentialCap = 4096
|
||||
|
||||
const (
|
||||
essentialLedgerLines = 10
|
||||
essentialFileLines = 8
|
||||
essentialLineCap = 100
|
||||
// essentialHandoffMin is the least room a previous stage's handoff gets
|
||||
// when the task also needs more than half of the remaining budget.
|
||||
essentialHandoffMin = 1024
|
||||
)
|
||||
|
||||
// Essential is everything RenderEssential needs for one visit's memory.md.
|
||||
type Essential struct {
|
||||
// Task is the run prompt.
|
||||
Task string
|
||||
// StageKey is the stage about to run; it marks a revisit.
|
||||
StageKey string
|
||||
// Entries are the completed turns in order (the same slice history.md is
|
||||
// rendered from).
|
||||
Entries []MemoryEntry
|
||||
// ChangedFiles is the run's server-captured changed-path list.
|
||||
ChangedFiles []string
|
||||
// InputPath and HistoryPath are named as the on-demand detail.
|
||||
InputPath string
|
||||
HistoryPath string
|
||||
}
|
||||
|
||||
// RenderEssential renders a visit's essential memory: the task, the previous
|
||||
// stage's handoff, a one-line-per-stage outcome ledger and the changed files.
|
||||
// The result never exceeds EssentialCap bytes. The previous stage's handoff is
|
||||
// its "# handoff" section when it wrote one, otherwise the head of its output;
|
||||
// either is truncated with a pointer to the full text, so the file stays useful
|
||||
// whether or not a model followed the handoff convention.
|
||||
func RenderEssential(e Essential) string {
|
||||
var fixed strings.Builder
|
||||
fixed.WriteString("# Essential memory\n\n")
|
||||
fixed.WriteString("Short handoff for this visit; enough for most work.")
|
||||
if e.InputPath != "" || e.HistoryPath != "" {
|
||||
fixed.WriteString(" Read on demand only:")
|
||||
if e.InputPath != "" {
|
||||
fmt.Fprintf(&fixed, " %s (full task and previous stage output)", e.InputPath)
|
||||
}
|
||||
if e.HistoryPath != "" {
|
||||
if e.InputPath != "" {
|
||||
fixed.WriteString(";")
|
||||
}
|
||||
fmt.Fprintf(&fixed, " %s (every earlier turn in full)", e.HistoryPath)
|
||||
}
|
||||
fixed.WriteString(".")
|
||||
}
|
||||
fixed.WriteString("\n")
|
||||
|
||||
var tail strings.Builder
|
||||
if ledger := renderLedger(e.Entries, e.StageKey); ledger != "" {
|
||||
tail.WriteString("\n## Stage ledger\n\n")
|
||||
tail.WriteString(ledger)
|
||||
}
|
||||
if files := renderFiles(e.ChangedFiles); files != "" {
|
||||
tail.WriteString("\n## Changed files (server-captured)\n\n")
|
||||
tail.WriteString(files)
|
||||
}
|
||||
|
||||
taskHeading := "\n## Task\n\n"
|
||||
task := strings.TrimSpace(demoteHeadings(strings.TrimSpace(e.Task)))
|
||||
if task == "" {
|
||||
task = "_(no task text)_"
|
||||
}
|
||||
var handoffHeading, handoff string
|
||||
if n := len(e.Entries); n > 0 {
|
||||
previous := e.Entries[n-1]
|
||||
title := capLine(fmt.Sprintf("%s · visit %d%s", oneLine(previous.Stage), previous.Visit, outcomeSuffix(previous.Outcome)), 2*essentialLineCap)
|
||||
handoffHeading = "\n## Previous stage: " + title + "\n\n"
|
||||
var source string
|
||||
handoff, source = previousHandoff(previous.Output)
|
||||
handoffHeading += source
|
||||
if public := sortedUnique(previous.PublicFiles); len(public) > 0 {
|
||||
handoff += "\n\nAdded to public/: " + capLine(strings.Join(public, ", "), 2*essentialLineCap)
|
||||
}
|
||||
}
|
||||
|
||||
// Budget what is left after the fixed parts between the task and the
|
||||
// handoff. Unused room on either side flows to the other.
|
||||
reserve := 2 * len(truncationNote(EssentialCap, EssentialCap, "input.md"))
|
||||
budget := EssentialCap - fixed.Len() - tail.Len() - len(taskHeading) - len(handoffHeading) - 2 - reserve
|
||||
if budget < 0 {
|
||||
budget = 0
|
||||
}
|
||||
handoffBudget, taskBudget := 0, budget
|
||||
if handoffHeading != "" {
|
||||
half := budget / 2
|
||||
if half < essentialHandoffMin {
|
||||
half = min(essentialHandoffMin, budget)
|
||||
}
|
||||
switch {
|
||||
case len(task) <= budget-half:
|
||||
handoffBudget = budget - len(task)
|
||||
case len(handoff) <= half:
|
||||
handoffBudget = len(handoff)
|
||||
default:
|
||||
handoffBudget = half
|
||||
}
|
||||
taskBudget = budget - min(handoffBudget, len(handoff))
|
||||
}
|
||||
|
||||
var b strings.Builder
|
||||
b.WriteString(fixed.String())
|
||||
b.WriteString(taskHeading)
|
||||
b.WriteString(truncateWithNote(task, taskBudget, "input.md"))
|
||||
b.WriteString("\n")
|
||||
if handoffHeading != "" {
|
||||
b.WriteString(handoffHeading)
|
||||
b.WriteString(truncateWithNote(handoff, handoffBudget, "input.md"))
|
||||
b.WriteString("\n")
|
||||
} else {
|
||||
b.WriteString("\nThis is the first stage of the run; there is no earlier turn.\n")
|
||||
}
|
||||
b.WriteString(tail.String())
|
||||
out := b.String()
|
||||
if len(out) > EssentialCap {
|
||||
// Pathological input (very long stage keys or paths); never exceed the
|
||||
// cap even if the section budgets could not absorb it.
|
||||
out = truncateWithNote(out, EssentialCap-len(truncationNote(len(out), len(out), "history.md")), "history.md") + "\n"
|
||||
if len(out) > EssentialCap {
|
||||
out = cutAtRune(out, EssentialCap)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// HandoffSection returns the body of the first "handoff" heading (any ATX
|
||||
// level, outside fenced code) up to the next heading of the same or a higher
|
||||
// level, trimmed. ok is false when there is no such heading or it is empty.
|
||||
func HandoffSection(markdown string) (string, bool) {
|
||||
lines := markdownLines(markdown)
|
||||
var fence fenceState
|
||||
start, level := -1, 0
|
||||
end := len(markdown)
|
||||
for i, line := range lines {
|
||||
if fence.open() {
|
||||
if fence.closes(line.text) {
|
||||
fence = fenceState{}
|
||||
}
|
||||
continue
|
||||
}
|
||||
if marker, ok := openingFence(line.text); ok {
|
||||
fence = marker
|
||||
continue
|
||||
}
|
||||
lvl, text, isHeading := atxHeading(line.text)
|
||||
if !isHeading {
|
||||
continue
|
||||
}
|
||||
if start < 0 {
|
||||
if strings.EqualFold(text, "handoff") {
|
||||
start, level = line.next, lvl
|
||||
}
|
||||
continue
|
||||
}
|
||||
if lvl <= level {
|
||||
end = lines[i-1].next
|
||||
break
|
||||
}
|
||||
}
|
||||
if start < 0 {
|
||||
return "", false
|
||||
}
|
||||
section := strings.TrimSpace(markdown[start:end])
|
||||
return section, section != ""
|
||||
}
|
||||
|
||||
func previousHandoff(output string) (string, string) {
|
||||
if section, ok := HandoffSection(output); ok {
|
||||
return strings.TrimSpace(demoteHeadings(section)), ""
|
||||
}
|
||||
body := strings.TrimSpace(demoteHeadings(output))
|
||||
if body == "" {
|
||||
return "_(no output)_", ""
|
||||
}
|
||||
return body, "_(no `# handoff` section; showing the start of its output)_\n\n"
|
||||
}
|
||||
|
||||
func renderLedger(entries []MemoryEntry, current string) string {
|
||||
if len(entries) == 0 {
|
||||
return ""
|
||||
}
|
||||
type latest struct {
|
||||
entry MemoryEntry
|
||||
order int
|
||||
}
|
||||
byStage := map[string]*latest{}
|
||||
order := []string{}
|
||||
for i, entry := range entries {
|
||||
if item, ok := byStage[entry.Stage]; ok {
|
||||
item.entry, item.order = entry, i
|
||||
continue
|
||||
}
|
||||
byStage[entry.Stage] = &latest{entry: entry, order: i}
|
||||
order = append(order, entry.Stage)
|
||||
}
|
||||
var b strings.Builder
|
||||
skipped := 0
|
||||
if len(order) > essentialLedgerLines {
|
||||
skipped = len(order) - essentialLedgerLines
|
||||
order = order[skipped:]
|
||||
}
|
||||
if skipped > 0 {
|
||||
fmt.Fprintf(&b, "- … %d earlier stages in history.md\n", skipped)
|
||||
}
|
||||
for _, key := range order {
|
||||
item := byStage[key]
|
||||
line := fmt.Sprintf("%s · visit %d%s", oneLine(key), item.entry.Visit, outcomeSuffix(item.entry.Outcome))
|
||||
if key == current {
|
||||
line += " (this stage's previous visit; detail in history.md)"
|
||||
}
|
||||
b.WriteString("- ")
|
||||
b.WriteString(capLine(line, essentialLineCap))
|
||||
b.WriteString("\n")
|
||||
}
|
||||
fmt.Fprintf(&b, "\n%d turns completed.\n", len(entries))
|
||||
return b.String()
|
||||
}
|
||||
|
||||
func renderFiles(files []string) string {
|
||||
files = sortedUnique(files)
|
||||
if len(files) == 0 {
|
||||
return ""
|
||||
}
|
||||
var b strings.Builder
|
||||
shown := files
|
||||
if len(shown) > essentialFileLines {
|
||||
shown = shown[:essentialFileLines]
|
||||
}
|
||||
for _, name := range shown {
|
||||
b.WriteString("- ")
|
||||
b.WriteString(capLine(oneLine(name), essentialLineCap))
|
||||
b.WriteString("\n")
|
||||
}
|
||||
if more := len(files) - len(shown); more > 0 {
|
||||
fmt.Fprintf(&b, "- … and %d more\n", more)
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
|
||||
func outcomeSuffix(outcome string) string {
|
||||
if outcome == "" {
|
||||
return ""
|
||||
}
|
||||
return " · outcome " + oneLine(outcome)
|
||||
}
|
||||
|
||||
func atxHeading(text string) (int, string, bool) {
|
||||
trimmed := strings.TrimLeft(text, " ")
|
||||
if len(text)-len(trimmed) > 3 {
|
||||
return 0, "", false
|
||||
}
|
||||
level := 0
|
||||
for level < len(trimmed) && trimmed[level] == '#' {
|
||||
level++
|
||||
}
|
||||
if level < 1 || level > 6 {
|
||||
return 0, "", false
|
||||
}
|
||||
rest := trimmed[level:]
|
||||
if rest != "" && rest[0] != ' ' && rest[0] != '\t' {
|
||||
return 0, "", false
|
||||
}
|
||||
return level, strings.TrimSpace(strings.TrimRight(strings.TrimSpace(rest), "#")), true
|
||||
}
|
||||
|
||||
func oneLine(text string) string {
|
||||
return strings.Join(strings.Fields(text), " ")
|
||||
}
|
||||
|
||||
func capLine(text string, limit int) string {
|
||||
if len(text) <= limit {
|
||||
return text
|
||||
}
|
||||
return cutAtRune(text, limit-len("…")) + "…"
|
||||
}
|
||||
|
||||
func truncationNote(shown, total int, where string) string {
|
||||
return fmt.Sprintf("\n\n_[truncated: %d of %d bytes shown; full text in %s]_", shown, total, where)
|
||||
}
|
||||
|
||||
// truncateWithNote returns text unchanged when it fits limit, otherwise its
|
||||
// head cut at a line (or rune) boundary followed by a pointer to the full text.
|
||||
func truncateWithNote(text string, limit int, where string) string {
|
||||
if len(text) <= limit {
|
||||
return text
|
||||
}
|
||||
if limit < 0 {
|
||||
limit = 0
|
||||
}
|
||||
head := cutAtRune(text, limit)
|
||||
if i := strings.LastIndexByte(head, '\n'); i > limit/2 {
|
||||
head = head[:i]
|
||||
}
|
||||
head = strings.TrimRight(head, " \t\n")
|
||||
return head + truncationNote(len(head), len(text), where)
|
||||
}
|
||||
|
||||
func cutAtRune(text string, limit int) string {
|
||||
if limit <= 0 {
|
||||
return ""
|
||||
}
|
||||
if len(text) <= limit {
|
||||
return text
|
||||
}
|
||||
for limit > 0 && !utf8.RuneStart(text[limit]) {
|
||||
limit--
|
||||
}
|
||||
return text[:limit]
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
package turn
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func paragraph(label string, bytes int) string {
|
||||
line := label + ": detail about the change, the reasoning, the commands run and their output.\n"
|
||||
return strings.Repeat(line, bytes/len(line)+1)
|
||||
}
|
||||
|
||||
// feedbackLoopEntries is a 4-stage run with a revisit: plan, code, review sends
|
||||
// the work back, and code is about to run its second visit.
|
||||
func feedbackLoopEntries() []MemoryEntry {
|
||||
return []MemoryEntry{
|
||||
{Stage: "plan", Visit: 1, Outcome: "success", Output: "# handoff\n\nPlan: add the cache layer in two steps.\n\n# plan\n\n" + paragraph("plan", 5000)},
|
||||
{Stage: "code", Visit: 1, Outcome: "success", Output: "# handoff\n\nImplemented cache.go; tests pass.\n\n# log\n\n" + paragraph("code", 9000), PublicFiles: []string{"public/coverage.html"}},
|
||||
{Stage: "review", Visit: 1, Outcome: "changes_requested", Output: "# summary\n\nLong preamble.\n\n" + paragraph("review", 7000) + "\n# Handoff\n\n## Findings\n\n1. cache.go:42 leaks the lock on the error path.\n2. Missing test for eviction.\n\n# appendix\n\n" + paragraph("appendix", 3000)},
|
||||
}
|
||||
}
|
||||
|
||||
func TestEssentialMemoryRevisitShowsReviewerFindingsWithinCap(t *testing.T) {
|
||||
entries := feedbackLoopEntries()
|
||||
changed := []string{}
|
||||
for i := range 20 {
|
||||
changed = append(changed, fmt.Sprintf("internal/cache/file%02d.go", i))
|
||||
}
|
||||
memory := RenderEssential(Essential{
|
||||
Task: "# Goal\n\nAdd a cache to the lookup service.",
|
||||
StageKey: "code",
|
||||
Entries: entries,
|
||||
ChangedFiles: changed,
|
||||
InputPath: "/run/stages/04-code/input.md",
|
||||
HistoryPath: "/run/stages/04-code/history.md",
|
||||
})
|
||||
if len(memory) > EssentialCap {
|
||||
t.Fatalf("essential memory is %d bytes, over the %d cap:\n%s", len(memory), EssentialCap, memory)
|
||||
}
|
||||
for _, want := range []string{
|
||||
"### Goal",
|
||||
"Add a cache to the lookup service.",
|
||||
"## Previous stage: review · visit 1 · outcome changes_requested",
|
||||
"cache.go:42 leaks the lock on the error path.",
|
||||
"Missing test for eviction.",
|
||||
"- plan · visit 1 · outcome success",
|
||||
"- code · visit 1 · outcome success (this stage's previous visit; detail in history.md)",
|
||||
"- review · visit 1 · outcome changes_requested",
|
||||
"3 turns completed.",
|
||||
"- internal/cache/file00.go",
|
||||
"- … and 12 more",
|
||||
"/run/stages/04-code/history.md",
|
||||
"/run/stages/04-code/input.md",
|
||||
} {
|
||||
if !strings.Contains(memory, want) {
|
||||
t.Fatalf("essential memory missing %q:\n%s", want, memory)
|
||||
}
|
||||
}
|
||||
// The findings come before the ledger: they are the first thing a
|
||||
// re-entered stage reads after the task.
|
||||
if strings.Index(memory, "leaks the lock") > strings.Index(memory, "## Stage ledger") {
|
||||
t.Fatalf("reviewer findings are not prominent:\n%s", memory)
|
||||
}
|
||||
for _, unwanted := range []string{"Long preamble.", "appendix:", "code: detail", "plan: detail"} {
|
||||
if strings.Contains(memory, unwanted) {
|
||||
t.Fatalf("essential memory carried non-handoff text %q:\n%s", unwanted, memory)
|
||||
}
|
||||
}
|
||||
|
||||
// The full, previous behaviour stays reachable through history.md.
|
||||
history := RenderHistory(entries)
|
||||
for _, want := range []string{"## plan · visit 1", "## code · visit 1", "## review · visit 1", "Long preamble.", "appendix: detail", "public/coverage.html"} {
|
||||
if !strings.Contains(history, want) {
|
||||
t.Fatalf("history missing %q", want)
|
||||
}
|
||||
}
|
||||
if len(history) < 5*len(memory) {
|
||||
t.Fatalf("history (%d) is not much larger than essential memory (%d)", len(history), len(memory))
|
||||
}
|
||||
}
|
||||
|
||||
func TestEssentialMemoryFallsBackToTruncatedOutputWithPointer(t *testing.T) {
|
||||
entries := []MemoryEntry{{Stage: "code", Visit: 1, Outcome: "success", Output: "Started with the parser.\n" + paragraph("work", 20000)}}
|
||||
memory := RenderEssential(Essential{Task: "Fix the parser.", StageKey: "review", Entries: entries, InputPath: "in.md", HistoryPath: "hist.md"})
|
||||
if len(memory) > EssentialCap {
|
||||
t.Fatalf("essential memory is %d bytes, over the cap", len(memory))
|
||||
}
|
||||
for _, want := range []string{"Fix the parser.", "no `# handoff` section", "Started with the parser.", "_[truncated:", "full text in input.md]_"} {
|
||||
if !strings.Contains(memory, want) {
|
||||
t.Fatalf("fallback memory missing %q:\n%s", want, memory)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestEssentialMemoryCapsEveryPart(t *testing.T) {
|
||||
long := strings.Repeat("x", 300)
|
||||
entries := []MemoryEntry{}
|
||||
for i := range 30 {
|
||||
entries = append(entries, MemoryEntry{Stage: fmt.Sprintf("stage-%02d-%s", i, long), Visit: 1, Outcome: long, Output: "# handoff\n\n" + paragraph("h", 9000), PublicFiles: []string{"public/" + long}})
|
||||
}
|
||||
files := []string{}
|
||||
for i := range 200 {
|
||||
files = append(files, fmt.Sprintf("%03d/%s", i, long))
|
||||
}
|
||||
memory := RenderEssential(Essential{Task: paragraph("task", 50000), StageKey: "next", Entries: entries, ChangedFiles: files, InputPath: "/in.md", HistoryPath: "/history.md"})
|
||||
if len(memory) > EssentialCap {
|
||||
t.Fatalf("essential memory is %d bytes, over the %d cap", len(memory), EssentialCap)
|
||||
}
|
||||
for _, want := range []string{"## Task", "task: detail", "## Previous stage:", "h: detail", "earlier stages in history.md", "and 192 more"} {
|
||||
if !strings.Contains(memory, want) {
|
||||
t.Fatalf("capped memory missing %q:\n%s", want, memory)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestEssentialMemoryFirstVisit(t *testing.T) {
|
||||
memory := RenderEssential(Essential{Task: "Do it.", StageKey: "plan", InputPath: "in.md", HistoryPath: "hist.md"})
|
||||
for _, want := range []string{"## Task\n\nDo it.", "first stage of the run"} {
|
||||
if !strings.Contains(memory, want) {
|
||||
t.Fatalf("first-visit memory missing %q:\n%s", want, memory)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestHandoffSection(t *testing.T) {
|
||||
cases := []struct {
|
||||
name, markdown, want string
|
||||
ok bool
|
||||
}{
|
||||
{"absent", "# summary\n\ntext\n", "", false},
|
||||
{"empty", "# handoff\n\n# next\n", "", false},
|
||||
{"stops at same level", "# handoff\nkeep\n## sub\nalso keep\n# other\ndrop\n", "keep\n## sub\nalso keep", true},
|
||||
{"lower level runs to end", "# a\n## Handoff ##\nkeep\n", "keep", true},
|
||||
{"fenced heading ignored", "```\n# handoff\nno\n```\n# handoff\nyes\n", "yes", true},
|
||||
{"crlf", "# handoff\r\nkeep\r\n# next\r\n", "keep", true},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
got, ok := HandoffSection(tc.markdown)
|
||||
if ok != tc.ok || got != tc.want {
|
||||
t.Fatalf("%s: HandoffSection = %q, %v; want %q, %v", tc.name, got, ok, tc.want, tc.ok)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// TestEssentialMemorySizeOnRealisticRun records what a late stage receives on
|
||||
// a realistic run, before (memory.md was the full history and the stage was
|
||||
// told to read it and input.md) and after (only the capped essential memory is
|
||||
// inlined; input.md and history.md are on demand).
|
||||
func TestEssentialMemorySizeOnRealisticRun(t *testing.T) {
|
||||
task := "Add retry with backoff to the uploader, keep the public API, and add tests.\n" + paragraph("task", 1200)
|
||||
entries := []MemoryEntry{
|
||||
{Stage: "plan", Visit: 1, Outcome: "success", Output: "# handoff\n\nTwo-step plan; see Plan.\n\n# Plan\n\n" + paragraph("plan", 3500)},
|
||||
{Stage: "code", Visit: 1, Outcome: "success", Output: "# handoff\n\nAdded backoff.go and tests.\n\n# Log\n\n" + paragraph("code", 6500)},
|
||||
{Stage: "review", Visit: 1, Outcome: "changes_requested", Output: "# handoff\n\n1. jitter unbounded. 2. no cancel test.\n\n# Review\n\n" + paragraph("review", 4500)},
|
||||
{Stage: "code", Visit: 2, Outcome: "success", Output: "# handoff\n\nFixed both findings.\n\n# Log\n\n" + paragraph("code2", 5000)},
|
||||
{Stage: "review", Visit: 2, Outcome: "success", Output: "# handoff\n\nApproved; land it.\n\n# Review\n\n" + paragraph("review2", 3000)},
|
||||
}
|
||||
history := RenderHistory(entries)
|
||||
input := RenderInput(task, entries[len(entries)-1].Output)
|
||||
memory := RenderEssential(Essential{Task: task, StageKey: "land", Entries: entries, ChangedFiles: []string{"uploader/backoff.go", "uploader/backoff_test.go"}, InputPath: "input.md", HistoryPath: "history.md"})
|
||||
before := len(history) + len(input)
|
||||
t.Logf("late stage context: before %d bytes (memory.md %d + input.md %d), after %d bytes inlined (input.md %d and history.md %d on demand)", before, len(history), len(input), len(memory), len(input), len(history))
|
||||
if len(memory) > EssentialCap || len(memory)*5 > before {
|
||||
t.Fatalf("essential memory %d bytes is not a large reduction from %d", len(memory), before)
|
||||
}
|
||||
}
|
||||
@@ -19,7 +19,7 @@ func TestLayoutRenderAndParseRoundTrip(t *testing.T) {
|
||||
if err := os.WriteFile(paths.InputPath, []byte(input), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
memory := RenderMemory([]MemoryEntry{{
|
||||
memory := RenderHistory([]MemoryEntry{{
|
||||
Stage: "implementer",
|
||||
Visit: 1,
|
||||
Output: "first visit result",
|
||||
|
||||
+16
-12
@@ -18,9 +18,12 @@ type Paths struct {
|
||||
TurnDir string
|
||||
InputPath string
|
||||
MemoryPath string
|
||||
OutputPath string
|
||||
PrivateDir string
|
||||
PublicDir string
|
||||
// HistoryPath is the full accumulated history; MemoryPath is the short,
|
||||
// capped essential memory that is inlined into the prompt.
|
||||
HistoryPath string
|
||||
OutputPath string
|
||||
PrivateDir string
|
||||
PublicDir string
|
||||
}
|
||||
|
||||
// Layout returns the deterministic paths for a stage turn. The sequence is
|
||||
@@ -28,15 +31,16 @@ type Paths struct {
|
||||
func Layout(runDir string, sequence int, stageKey string) Paths {
|
||||
turnDir := filepath.Join(runDir, "stages", fmt.Sprintf("%02d-%s", sequence, stageKey))
|
||||
return Paths{
|
||||
RunDir: runDir,
|
||||
Sequence: sequence,
|
||||
StageKey: stageKey,
|
||||
TurnDir: turnDir,
|
||||
InputPath: filepath.Join(turnDir, "input.md"),
|
||||
MemoryPath: filepath.Join(turnDir, "memory.md"),
|
||||
OutputPath: filepath.Join(turnDir, "output.md"),
|
||||
PrivateDir: filepath.Join(turnDir, "private"),
|
||||
PublicDir: filepath.Join(runDir, "public"),
|
||||
RunDir: runDir,
|
||||
Sequence: sequence,
|
||||
StageKey: stageKey,
|
||||
TurnDir: turnDir,
|
||||
InputPath: filepath.Join(turnDir, "input.md"),
|
||||
MemoryPath: filepath.Join(turnDir, "memory.md"),
|
||||
HistoryPath: filepath.Join(turnDir, "history.md"),
|
||||
OutputPath: filepath.Join(turnDir, "output.md"),
|
||||
PrivateDir: filepath.Join(turnDir, "private"),
|
||||
PublicDir: filepath.Join(runDir, "public"),
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -9,15 +9,16 @@ import (
|
||||
func TestLayoutIsDeterministic(t *testing.T) {
|
||||
runDir := filepath.Join(t.TempDir(), "run")
|
||||
want := Paths{
|
||||
RunDir: runDir,
|
||||
Sequence: 2,
|
||||
StageKey: "implementer",
|
||||
TurnDir: filepath.Join(runDir, "stages", "02-implementer"),
|
||||
InputPath: filepath.Join(runDir, "stages", "02-implementer", "input.md"),
|
||||
MemoryPath: filepath.Join(runDir, "stages", "02-implementer", "memory.md"),
|
||||
OutputPath: filepath.Join(runDir, "stages", "02-implementer", "output.md"),
|
||||
PrivateDir: filepath.Join(runDir, "stages", "02-implementer", "private"),
|
||||
PublicDir: filepath.Join(runDir, "public"),
|
||||
RunDir: runDir,
|
||||
Sequence: 2,
|
||||
StageKey: "implementer",
|
||||
TurnDir: filepath.Join(runDir, "stages", "02-implementer"),
|
||||
InputPath: filepath.Join(runDir, "stages", "02-implementer", "input.md"),
|
||||
MemoryPath: filepath.Join(runDir, "stages", "02-implementer", "memory.md"),
|
||||
HistoryPath: filepath.Join(runDir, "stages", "02-implementer", "history.md"),
|
||||
OutputPath: filepath.Join(runDir, "stages", "02-implementer", "output.md"),
|
||||
PrivateDir: filepath.Join(runDir, "stages", "02-implementer", "private"),
|
||||
PublicDir: filepath.Join(runDir, "public"),
|
||||
}
|
||||
got := Layout(runDir, 2, "implementer")
|
||||
if got != want {
|
||||
|
||||
@@ -22,23 +22,27 @@ func RenderInput(prompt string, previousOutput string) string {
|
||||
return "# Run task\n\n" + demoteHeadings(task) + "\n\n# Previous turn output\n\n" + previousOutput
|
||||
}
|
||||
|
||||
// MemoryEntry is one completed turn in a later turn's memory file. Output is
|
||||
// the turn's markdown body, without the outcome section. PublicFiles are paths
|
||||
// relative to the run directory, so the public prefix is retained.
|
||||
// MemoryEntry is one completed turn in a later turn's history.md and essential
|
||||
// memory.md. Output is the turn's markdown body, without the outcome section.
|
||||
// Outcome is the routed outcome word, empty when it is not known (an inherited
|
||||
// retry prefix). PublicFiles are paths relative to the run directory, so the
|
||||
// public prefix is retained.
|
||||
type MemoryEntry struct {
|
||||
Stage string
|
||||
Visit int
|
||||
Outcome string
|
||||
Output string
|
||||
PublicFiles []string
|
||||
}
|
||||
|
||||
// RenderMemory renders completed turns in the order supplied. Each turn's body
|
||||
// RenderHistory renders a visit's history.md (the optional full memory, which
|
||||
// was memory.md before essential memory existed). It renders completed turns in the order supplied. Each turn's body
|
||||
// is embedded with its own headings demoted two levels, so the turn's "## Stage ·
|
||||
// visit N" stays the structural section and a body heading can never look like a
|
||||
// sibling turn (or like the system-written file list). The file list is
|
||||
// system-written from PublicFiles, sorted and deduplicated, so the result is
|
||||
// deterministic.
|
||||
func RenderMemory(entries []MemoryEntry) string {
|
||||
func RenderHistory(entries []MemoryEntry) string {
|
||||
var b strings.Builder
|
||||
for i, entry := range entries {
|
||||
if i > 0 {
|
||||
|
||||
@@ -28,7 +28,7 @@ func TestRenderInputLaterTurnKeepsTheTaskAndThePreviousOutput(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestRenderMemory(t *testing.T) {
|
||||
func TestRenderHistory(t *testing.T) {
|
||||
entries := []MemoryEntry{
|
||||
{
|
||||
Stage: "planner",
|
||||
@@ -48,18 +48,18 @@ func TestRenderMemory(t *testing.T) {
|
||||
"## reviewer · visit 2\n\n" +
|
||||
"No public files.\n\n" +
|
||||
"Files added to public/:\n- _(none)_\n"
|
||||
if got := RenderMemory(entries); got != want {
|
||||
t.Fatalf("RenderMemory() = %q, want %q", got, want)
|
||||
if got := RenderHistory(entries); got != want {
|
||||
t.Fatalf("RenderHistory() = %q, want %q", got, want)
|
||||
}
|
||||
if again := RenderMemory(entries); again != want {
|
||||
t.Fatalf("RenderMemory() is not deterministic: %q", again)
|
||||
if again := RenderHistory(entries); again != want {
|
||||
t.Fatalf("RenderHistory() is not deterministic: %q", again)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRenderMemoryDemotesBodyHeadingsButNotFences(t *testing.T) {
|
||||
func TestRenderHistoryDemotesBodyHeadingsButNotFences(t *testing.T) {
|
||||
output := "## Notes\n\n```md\n# outcome success\n```\n\n#### Deep\n\nlast line without newline"
|
||||
entries := []MemoryEntry{{Stage: "build", Visit: 3, Output: output, PublicFiles: []string{"public/report.md"}}}
|
||||
got := RenderMemory(entries)
|
||||
got := RenderHistory(entries)
|
||||
if !strings.Contains(got, "#### Notes") {
|
||||
t.Fatalf("body heading was not demoted:\n%s", got)
|
||||
}
|
||||
@@ -77,8 +77,8 @@ func TestRenderMemoryDemotesBodyHeadingsButNotFences(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestRenderMemoryEmpty(t *testing.T) {
|
||||
if got := RenderMemory(nil); got != "" {
|
||||
t.Fatalf("RenderMemory(nil) = %q, want empty", got)
|
||||
func TestRenderHistoryEmpty(t *testing.T) {
|
||||
if got := RenderHistory(nil); got != "" {
|
||||
t.Fatalf("RenderHistory(nil) = %q, want empty", got)
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user