turn: add file-based stage turn foundation

This commit is contained in:
2026-10-19 20:06:18 +01:00
parent 23809051e9
commit 7b6bd71dd8
7 changed files with 624 additions and 0 deletions
+47
View File
@@ -0,0 +1,47 @@
# Stage turns
Stage turns are file-based. Each visit gets its own directory under the run:
```
<run>/stages/01-implementer/input.md
<run>/stages/01-implementer/memory.md
<run>/stages/01-implementer/output.md
<run>/stages/01-implementer/private/
<run>/public/
```
`internal/turn.Layout` derives those paths deterministically (the sequence is
zero-padded to two digits). `Paths.Ensure` creates the turn, private and public
directories idempotently; it never deletes or rewrites existing files.
The first turn's `input.md` is the run prompt. A later turn's input is the
previous turn's output under a `# Previous turn output` heading. Memory is
plain markdown: one `## <stage> · visit <n>` section per completed turn, with
that turn's output verbatim followed by a system-written list of files added to
`public/`. List entries are relative to the run directory, sorted, and unique.
Input, memory and output are stored per turn, and private artifacts stay in the
turn's `private/` directory while shared artifacts go to the run-level
`public/` directory.
## Outcome-only output contract
A turn's `output.md` must contain exactly one outcome section and may contain any
markdown after it. The outcome section is an ATX heading named `outcome` (any
level) followed by the first non-blank line, which must be exactly one of the
stage's allowed outcome words:
```md
## outcome
success
# Result
The rest of the output is the body, preserved verbatim.
```
Matching trims whitespace and compares case-insensitively, returning the
canonical allowed spelling. Text before the heading is ignored. Headings and
words inside fenced code blocks (triple backticks or tildes) are ignored, so a
diff or code sample cannot add a false outcome. Missing, duplicate, empty, or unknown
outcomes are explicit errors; the parser never guesses, repairs the text, or
looks for any other section.
+52
View File
@@ -0,0 +1,52 @@
// Package turn owns the file layout and markdown contracts for file-based
// stage turns. It deliberately has no dependency on the server, protocol or
// stage packages: callers persist and execute turns, while this package keeps
// their paths and plain-markdown shapes deterministic.
package turn
import (
"fmt"
"os"
"path/filepath"
)
// Paths is the complete on-disk layout for one stage visit.
type Paths struct {
RunDir string
Sequence int
StageKey string
TurnDir string
InputPath string
MemoryPath string
OutputPath string
PrivateDir string
PublicDir string
}
// Layout returns the deterministic paths for a stage turn. The sequence is
// zero-padded to two digits; longer sequences keep all of their digits.
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"),
}
}
// Ensure creates the turn, private and run-level public directories. It is
// idempotent and never removes or rewrites anything already present.
func (p Paths) Ensure() error {
for _, dir := range []string{p.TurnDir, p.PrivateDir, p.PublicDir} {
if err := os.MkdirAll(dir, 0o700); err != nil {
return fmt.Errorf("turn: create %s: %w", dir, err)
}
}
return nil
}
+70
View File
@@ -0,0 +1,70 @@
package turn
import (
"os"
"path/filepath"
"testing"
)
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"),
}
got := Layout(runDir, 2, "implementer")
if got != want {
t.Fatalf("Layout() = %#v, want %#v", got, want)
}
if again := Layout(runDir, 2, "implementer"); again != got {
t.Fatalf("Layout() is not deterministic: %#v then %#v", got, again)
}
}
func TestLayoutSupportsLongSequences(t *testing.T) {
got := Layout("/runs/one", 123, "review")
want := filepath.Join("/runs/one", "stages", "123-review")
if got.TurnDir != want {
t.Fatalf("TurnDir = %q, want %q", got.TurnDir, want)
}
}
func TestPathsEnsureIsIdempotentAndPreservesFiles(t *testing.T) {
paths := Layout(t.TempDir(), 1, "build")
if err := paths.Ensure(); err != nil {
t.Fatalf("Ensure() error: %v", err)
}
for _, dir := range []string{paths.TurnDir, paths.PrivateDir, paths.PublicDir} {
info, err := os.Stat(dir)
if err != nil {
t.Fatalf("stat %s: %v", dir, err)
}
if !info.IsDir() {
t.Fatalf("%s is not a directory", dir)
}
}
kept := filepath.Join(paths.PrivateDir, "keep.txt")
if err := os.WriteFile(kept, []byte("preserve me"), 0o600); err != nil {
t.Fatal(err)
}
if err := paths.Ensure(); err != nil {
t.Fatalf("second Ensure() error: %v", err)
}
body, err := os.ReadFile(kept)
if err != nil {
t.Fatalf("read preserved file: %v", err)
}
if string(body) != "preserve me" {
t.Fatalf("preserved file = %q", body)
}
if _, err := os.Stat(paths.InputPath); !os.IsNotExist(err) {
t.Fatalf("Ensure() should not create the input file, stat error = %v", err)
}
}
+170
View File
@@ -0,0 +1,170 @@
package turn
import (
"errors"
"fmt"
"strings"
)
var (
// ErrEmptyOutput means the turn produced no markdown at all.
ErrEmptyOutput = errors.New("turn output: empty")
// ErrMissingOutcome means no outcome heading and value were found.
ErrMissingOutcome = errors.New("turn output: missing outcome")
// ErrDuplicateOutcome means more than one outcome heading was found.
ErrDuplicateOutcome = errors.New("turn output: duplicate outcome")
// ErrOutcomeNotAllowed means the value was not one of the declared words.
ErrOutcomeNotAllowed = errors.New("turn output: outcome not allowed")
)
// ParseOutput extracts the single outcome section from a turn's markdown.
//
// A heading whose text is "outcome" (any ATX level) is followed by the first
// non-blank line, which must contain exactly one allowed word. Matching is
// trim-and-lower-case, and the canonical spelling from allowedOutcomes is
// returned. Everything after that value line is the body, preserved byte for
// byte. Text before the outcome heading is ignored. Headings and values inside
// fenced code blocks are never considered.
func ParseOutput(markdown string, allowedOutcomes []string) (Outcome string, Body string, err error) {
if strings.TrimSpace(markdown) == "" {
return "", "", ErrEmptyOutput
}
lines := markdownLines(markdown)
var headings []int
var fence fenceState
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
}
if isOutcomeHeading(line.text) {
headings = append(headings, i)
}
}
switch len(headings) {
case 0:
return "", "", ErrMissingOutcome
case 1:
default:
return "", "", fmt.Errorf("%w: found %d outcome headings", ErrDuplicateOutcome, len(headings))
}
heading := headings[0]
value := heading + 1
for value < len(lines) && strings.TrimSpace(lines[value].text) == "" {
value++
}
if value == len(lines) {
return "", "", fmt.Errorf("%w: outcome heading has no value", ErrMissingOutcome)
}
word := strings.TrimSpace(lines[value].text)
canonical, ok := allowedOutcome(word, allowedOutcomes)
if !ok {
return "", "", fmt.Errorf("%w: %q", ErrOutcomeNotAllowed, word)
}
return canonical, markdown[lines[value].next:], nil
}
func allowedOutcome(word string, outcomes []string) (string, bool) {
key := strings.ToLower(word)
for _, outcome := range outcomes {
outcome = strings.TrimSpace(outcome)
if outcome != "" && strings.ToLower(outcome) == key {
return outcome, true
}
}
return "", false
}
type markdownLine struct {
text string
next int
}
// markdownLines records each line's content without its line ending and the
// byte position immediately after that line ending. Body slices therefore keep
// CRLF and every other byte exactly as supplied.
func markdownLines(markdown string) []markdownLine {
lines := make([]markdownLine, 0, strings.Count(markdown, "\n")+1)
for start := 0; start < len(markdown); {
next := len(markdown)
text := markdown[start:]
if relative := strings.IndexByte(markdown[start:], '\n'); relative >= 0 {
next = start + relative + 1
text = markdown[start : start+relative]
}
lines = append(lines, markdownLine{
text: strings.TrimSuffix(text, "\r"),
next: next,
})
if next == len(markdown) {
break
}
start = next
}
return lines
}
func isOutcomeHeading(text string) bool {
text = strings.TrimSpace(text)
hashes := 0
for hashes < len(text) && text[hashes] == '#' {
hashes++
}
if hashes == 0 || hashes == len(text) {
return false
}
// Markdown ATX headings require whitespace between the marker and text.
if text[hashes] != ' ' && text[hashes] != '\t' {
return false
}
return strings.EqualFold(strings.TrimSpace(text[hashes:]), "outcome")
}
type fenceState struct {
char byte
length int
}
func (f fenceState) open() bool {
return f.length > 0
}
func (f fenceState) closes(text string) bool {
char, length, ok := fenceMarker(text)
if !ok || char != f.char || length < f.length {
return false
}
trimmed := strings.TrimLeft(text, " \t")
return strings.TrimSpace(trimmed[length:]) == ""
}
func openingFence(text string) (fenceState, bool) {
char, length, ok := fenceMarker(text)
if !ok {
return fenceState{}, false
}
return fenceState{char: char, length: length}, true
}
func fenceMarker(text string) (byte, int, bool) {
trimmed := strings.TrimLeft(text, " \t")
if len(trimmed) < 3 || (trimmed[0] != '`' && trimmed[0] != '~') {
return 0, 0, false
}
char := trimmed[0]
length := 0
for length < len(trimmed) && trimmed[length] == char {
length++
}
if length < 3 {
return 0, 0, false
}
return char, length, true
}
+137
View File
@@ -0,0 +1,137 @@
package turn
import (
"errors"
"testing"
)
func TestParseOutput(t *testing.T) {
allowed := []string{"success", "blocked", "rejected"}
tests := []struct {
name string
input string
outcome string
body string
err error
}{
{
name: "leading commentary is ignored and trailing section is body",
input: "Checking the work first.\n\n## outcome\nsuccess\n\n# Result\n\nThe work is complete.\n",
outcome: "success",
body: "\n# Result\n\nThe work is complete.\n",
},
{
name: "diff embedding an outcome line cannot confuse the parser",
input: "# outcome\nblocked\n\n```diff\n+# outcome success\n+unrelated change\n```\n",
outcome: "blocked",
body: "\n```diff\n+# outcome success\n+unrelated change\n```\n",
},
{
name: "fenced headings before the real outcome are ignored",
input: "```md\n# outcome\nfailed\n```\n\n~~~\n## outcome\nrejected\n~~~\n\n# outcome\nSUCCESS\n\nbody",
outcome: "success",
body: "\nbody",
},
{
name: "CRLF line endings",
input: "leading\r\n\r\n## outcome\r\n\r\nsuccess\r\n\r\nbody\r\n",
outcome: "success",
body: "\r\nbody\r\n",
},
{
name: "arbitrary markdown body is preserved exactly",
input: "# outcome\nsuccess\n\n## Heading\n\n- item\n\n```go\nfmt.Println(\"hi\")\n```\n\n# outcome is discussed here\n",
outcome: "success",
body: "\n## Heading\n\n- item\n\n```go\nfmt.Println(\"hi\")\n```\n\n# outcome is discussed here\n",
},
{
name: "duplicate outcome",
input: "# outcome\nsuccess\n\n# outcome\nblocked\n",
err: ErrDuplicateOutcome,
},
{
name: "duplicate inside a fence is ignored",
input: "```\n# outcome\nsuccess\n```\n\n# outcome\nblocked\n",
outcome: "blocked",
},
{
name: "unknown outcome word",
input: "# outcome\nmaybe\n",
err: ErrOutcomeNotAllowed,
},
{
name: "extra text on the outcome line",
input: "# outcome\nsuccess please\n",
err: ErrOutcomeNotAllowed,
},
{
name: "value inside a fence is not an outcome value",
input: "# outcome\n```\nsuccess\n```\n",
err: ErrOutcomeNotAllowed,
},
{
name: "empty output",
input: "",
err: ErrEmptyOutput,
},
{
name: "whitespace-only output",
input: " \r\n\t\n",
err: ErrEmptyOutput,
},
{
name: "missing outcome heading",
input: "# Result\nsuccess\n",
err: ErrMissingOutcome,
},
{
name: "outcome heading without a value",
input: "# outcome\n\n",
err: ErrMissingOutcome,
},
{
name: "fenced outcome is not a real outcome",
input: "```\n# outcome\nsuccess\n```\n",
err: ErrMissingOutcome,
},
}
for _, test := range tests {
t.Run(test.name, func(t *testing.T) {
outcome, body, err := ParseOutput(test.input, allowed)
if test.err != nil {
if !errors.Is(err, test.err) {
t.Fatalf("error = %v, want %v", err, test.err)
}
if outcome != "" || body != "" {
t.Fatalf("error result = (%q, %q), want empty", outcome, body)
}
return
}
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if outcome != test.outcome || body != test.body {
t.Fatalf("ParseOutput() = (%q, %q), want (%q, %q)", outcome, body, test.outcome, test.body)
}
})
}
}
func TestParseOutputReturnsCanonicalOutcome(t *testing.T) {
outcome, body, err := ParseOutput("#### Outcome\n\n Success \n\nrest", []string{" success ", "blocked"})
if err != nil {
t.Fatalf("ParseOutput() error: %v", err)
}
if outcome != "success" {
t.Fatalf("outcome = %q, want canonical %q", outcome, "success")
}
if body != "\nrest" {
t.Fatalf("body = %q, want %q", body, "\nrest")
}
}
func TestParseOutputRequiresWhitespaceAfterHeadingMarker(t *testing.T) {
if _, _, err := ParseOutput("#outcome\nsuccess\n", []string{"success"}); !errors.Is(err, ErrMissingOutcome) {
t.Fatalf("error = %v, want missing outcome", err)
}
}
+74
View File
@@ -0,0 +1,74 @@
package turn
import (
"fmt"
"sort"
"strings"
)
// RenderInput renders the markdown a turn receives. The first turn receives the
// run prompt as-is. Later turns receive the previous turn's output verbatim
// under a heading; prompt is not repeated.
func RenderInput(prompt string, previousOutput string) string {
if strings.TrimSpace(previousOutput) == "" {
return prompt
}
return "# 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.
type MemoryEntry struct {
Stage string
Visit int
Output string
PublicFiles []string
}
// RenderMemory renders completed turns in the order supplied. Each turn's output
// is embedded verbatim; the file list is system-written from PublicFiles and is
// sorted and deduplicated so the result is deterministic.
func RenderMemory(entries []MemoryEntry) string {
var b strings.Builder
for i, entry := range entries {
if i > 0 {
b.WriteString("\n")
}
fmt.Fprintf(&b, "## %s · visit %d\n\n", entry.Stage, entry.Visit)
if entry.Output != "" {
b.WriteString(entry.Output)
if !strings.HasSuffix(entry.Output, "\n") {
b.WriteString("\n")
}
b.WriteString("\n")
}
b.WriteString("Files added to public/:\n")
files := sortedUnique(entry.PublicFiles)
if len(files) == 0 {
b.WriteString("- _(none)_\n")
continue
}
for _, file := range files {
b.WriteString("- ")
b.WriteString(file)
b.WriteString("\n")
}
}
return b.String()
}
func sortedUnique(values []string) []string {
if len(values) == 0 {
return nil
}
sorted := append([]string(nil), values...)
sort.Strings(sorted)
unique := sorted[:0]
for _, value := range sorted {
if len(unique) == 0 || unique[len(unique)-1] != value {
unique = append(unique, value)
}
}
return unique
}
+74
View File
@@ -0,0 +1,74 @@
package turn
import (
"strings"
"testing"
)
func TestRenderInputFirstTurnIsTheRunPrompt(t *testing.T) {
prompt := "# Task\n\nImplement the thing.\n"
if got := RenderInput(prompt, ""); got != prompt {
t.Fatalf("first turn input = %q, want prompt verbatim", got)
}
if got := RenderInput(prompt, " \r\n\t"); got != prompt {
t.Fatalf("blank previous output should behave as the first turn, got %q", got)
}
}
func TestRenderInputLaterTurnShowsOnlyPreviousOutput(t *testing.T) {
previous := "## Result\n\n- changed `internal/turn`\n\n```diff\n+new line\n```\n"
got := RenderInput("the original prompt", previous)
want := "# Previous turn output\n\n" + previous
if got != want {
t.Fatalf("later turn input = %q, want %q", got, want)
}
if strings.Contains(got, "the original prompt") {
t.Fatal("later turn input repeated the run prompt")
}
}
func TestRenderMemory(t *testing.T) {
entries := []MemoryEntry{
{
Stage: "planner",
Visit: 1,
Output: "# Plan\n\nDo the work.",
PublicFiles: []string{"public/b.md", "public/a.md", "public/a.md"},
},
{
Stage: "reviewer",
Visit: 2,
Output: "No public files.\n",
},
}
want := "## planner · visit 1\n\n" +
"# Plan\n\nDo the work.\n\n" +
"Files added to public/:\n- public/a.md\n- public/b.md\n\n" +
"## 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 again := RenderMemory(entries); again != want {
t.Fatalf("RenderMemory() is not deterministic: %q", again)
}
}
func TestRenderMemoryEmbedsOutputVerbatim(t *testing.T) {
output := "## Notes\n\n```md\n# outcome success\n```\n\nlast line without newline"
entries := []MemoryEntry{{Stage: "build", Visit: 3, Output: output, PublicFiles: []string{"public/report.md"}}}
got := RenderMemory(entries)
if !strings.Contains(got, output) {
t.Fatalf("output was not embedded verbatim:\n%s", got)
}
if !strings.Contains(got, "- public/report.md\n") {
t.Fatalf("public file list missing:\n%s", got)
}
}
func TestRenderMemoryEmpty(t *testing.T) {
if got := RenderMemory(nil); got != "" {
t.Fatalf("RenderMemory(nil) = %q, want empty", got)
}
}