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] }