diff --git a/docs/cli.md b/docs/cli.md index b79b70e2..82d33fd9 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -789,6 +789,7 @@ files as that step's artifacts: ``` //stages/01-implementer/input.md //stages/01-implementer/memory.md +//stages/01-implementer/history.md //stages/01-implementer/output.md //stages/01-implementer/private/ //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 diff --git a/docs/harnesses-and-control.md b/docs/harnesses-and-control.md index 17d020a8..44c80230 100644 --- a/docs/harnesses-and-control.md +++ b/docs/harnesses-and-control.md @@ -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. diff --git a/docs/model-results.md b/docs/model-results.md index b157249f..65300f4a 100644 --- a/docs/model-results.md +++ b/docs/model-results.md @@ -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: ``` //stages/01-implementer/input.md //stages/01-implementer/memory.md +//stages/01-implementer/history.md //stages/01-implementer/output.md //stages/01-implementer/private/ //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 `## · visit ` 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 `## · visit ` 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 diff --git a/docs/notes/stage-turns.md b/docs/notes/stage-turns.md index f46aa29d..349f561e 100644 --- a/docs/notes/stage-turns.md +++ b/docs/notes/stage-turns.md @@ -6,6 +6,7 @@ the run's artifact root: ``` //stages/01-implementer/input.md //stages/01-implementer/memory.md +//stages/01-implementer/history.md //stages/01-implementer/output.md //stages/01-implementer/private/ //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 `## · visit ` 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 `## · visit ` 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/`. diff --git a/docs/stage-artifacts.md b/docs/stage-artifacts.md index b2da6462..596a0a49 100644 --- a/docs/stage-artifacts.md +++ b/docs/stage-artifacts.md @@ -12,6 +12,7 @@ The server creates this layout under the run's artifact root: ``` //stages/-/input.md //stages/-/memory.md +//stages/-/history.md //stages/-/output.md //stages/-/private/ //public/ @@ -22,7 +23,7 @@ directory holding the database (`/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. diff --git a/internal/author/skill/SKILL.md b/internal/author/skill/SKILL.md index b87bf8f1..81df2f67 100644 --- a/internal/author/skill/SKILL.md +++ b/internal/author/skill/SKILL.md @@ -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 diff --git a/internal/author/skill/references/control.md b/internal/author/skill/references/control.md index c1ed2820..5a441e09 100644 --- a/internal/author/skill/references/control.md +++ b/internal/author/skill/references/control.md @@ -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. diff --git a/internal/author/skill/references/format.md b/internal/author/skill/references/format.md index 68de8830..3321a2c5 100644 --- a/internal/author/skill/references/format.md +++ b/internal/author/skill/references/format.md @@ -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 -`/stages/-/`, 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 `/stages/-/`, 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 diff --git a/internal/author/skill/references/operations.md b/internal/author/skill/references/operations.md index 83a26bc6..a1f1d434 100644 --- a/internal/author/skill/references/operations.md +++ b/internal/author/skill/references/operations.md @@ -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 -(`/artifacts//stages/-/`) with `input.md`, `memory.md`, -`output.md` and `private/`; `public/` is run-level and shared by every stage. +(`/artifacts//stages/-/`) 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///` 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 diff --git a/internal/server/artifacts.go b/internal/server/artifacts.go index 88f152aa..77aa014d 100644 --- a/internal/server/artifacts.go +++ b/internal/server/artifacts.go @@ -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) diff --git a/internal/server/runner.go b/internal/server/runner.go index c00ad88a..e67e888f 100644 --- a/internal/server/runner.go +++ b/internal/server/runner.go @@ -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 := "" diff --git a/internal/server/turn_memory_test.go b/internal/server/turn_memory_test.go new file mode 100644 index 00000000..bf502ae0 --- /dev/null +++ b/internal/server/turn_memory_test.go @@ -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)) + } +} diff --git a/internal/server/turn_test.go b/internal/server/turn_test.go index 30904b6f..fe6d965a 100644 --- a/internal/server/turn_test.go +++ b/internal/server/turn_test.go @@ -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) } diff --git a/internal/server/turns.go b/internal/server/turns.go index be33dab1..913ce8de 100644 --- a/internal/server/turns.go +++ b/internal/server/turns.go @@ -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, }) diff --git a/internal/stage/agent.go b/internal/stage/agent.go index 7bf4599a..b7a57c1c 100644 --- a/internal/stage/agent.go +++ b/internal/stage/agent.go @@ -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.") } diff --git a/internal/stage/artifacts_test.go b/internal/stage/artifacts_test.go index 4ba31bfa..18daa5e3 100644 --- a/internal/stage/artifacts_test.go +++ b/internal/stage/artifacts_test.go @@ -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) diff --git a/internal/stage/model_prompt.go b/internal/stage/model_prompt.go index 6282246d..456bb5fd 100644 --- a/internal/stage/model_prompt.go +++ b/internal/stage/model_prompt.go @@ -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 { diff --git a/internal/stage/model_prompt_memory_test.go b/internal/stage/model_prompt_memory_test.go new file mode 100644 index 00000000..cf3efe81 --- /dev/null +++ b/internal/stage/model_prompt_memory_test.go @@ -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) + } + }) + } +} diff --git a/internal/stage/model_prompt_test.go b/internal/stage/model_prompt_test.go index da320a99..9fb4cba8 100644 --- a/internal/stage/model_prompt_test.go +++ b/internal/stage/model_prompt_test.go @@ -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) diff --git a/internal/stage/stage.go b/internal/stage/stage.go index f601bad1..648b6583 100644 --- a/internal/stage/stage.go +++ b/internal/stage/stage.go @@ -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 diff --git a/internal/turn/essential.go b/internal/turn/essential.go new file mode 100644 index 00000000..ce93ad6d --- /dev/null +++ b/internal/turn/essential.go @@ -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] +} diff --git a/internal/turn/essential_test.go b/internal/turn/essential_test.go new file mode 100644 index 00000000..f097b082 --- /dev/null +++ b/internal/turn/essential_test.go @@ -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) + } +} diff --git a/internal/turn/integration_test.go b/internal/turn/integration_test.go index efdb5ff6..48988822 100644 --- a/internal/turn/integration_test.go +++ b/internal/turn/integration_test.go @@ -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", diff --git a/internal/turn/layout.go b/internal/turn/layout.go index 18bb82f7..a1564503 100644 --- a/internal/turn/layout.go +++ b/internal/turn/layout.go @@ -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"), } } diff --git a/internal/turn/layout_test.go b/internal/turn/layout_test.go index 2fcfe8f6..9cb3fcab 100644 --- a/internal/turn/layout_test.go +++ b/internal/turn/layout_test.go @@ -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 { diff --git a/internal/turn/render.go b/internal/turn/render.go index a7e6955e..ad3ae69e 100644 --- a/internal/turn/render.go +++ b/internal/turn/render.go @@ -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 { diff --git a/internal/turn/render_test.go b/internal/turn/render_test.go index d0399085..a7b58b7c 100644 --- a/internal/turn/render_test.go +++ b/internal/turn/render_test.go @@ -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) } }