Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
258 changes: 258 additions & 0 deletions docs/superpowers/plans/MC-69-plan.md

Large diffs are not rendered by default.

71 changes: 71 additions & 0 deletions docs/superpowers/specs/MC-69-design.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# MC-69 design: the runner gets `megoocolab.toml` created as a plan step, and reminds agents to keep it up to date

## Goal

When a task is planned in a repository that has no `megoocolab.toml` and whose checks need containers, the plan gets a first step that creates the file, so you approve it with the plan. Once the file exists, agents are reminded in every task to update it whenever new tests or commands need a service it does not declare. Mockup v2 shows both flows.

## Decisions

- **Created as a step in the task's plan** (your answer). The runner tells the planning agent the file is missing; the agent adds the step only when a check needs a container; you approve it with the plan; it is built and reviewed as its own commit. Rejected: creating it right away inside any writable run (arrives unannounced in a task about something else), and a task of its own on the board (needs server and web app changes, and checks keep sharing containers until it is merged).
- **Kept up to date** (your instruction of 18:50 UTC). Two reminders:
- the planning agent is told that a step adding a check or a command that needs a new service, port or variable changes the file in that same step;
- every writable run gets one more sentence in today's "Test services" section saying the same for its own work. This covers fix runs, freestyle chats and crons, which have no plan.
- **The file's format does not change.** It declares services (Compose files, ports, variables), not check commands. I read "new commands or tests require adding" as: a new check that needs a set, a port or a variable the file lacks. Check commands stay in the repository's own instructions (AGENTS.md, README), which the creating step updates. If you meant that the file should also list the commands, reject this design and say so: that is a format change.
- **Only the runner changes**, as in MC-52: the server does not know the file. The runner reads the worktree and adds text to the prompt.
- **The agent decides whether containers are needed**, from the repository itself (Compose files, CI configuration, README, test settings). If no check needs one, no step is added and nothing is created.
- **The format is written once** in the runner and used in three places: the two planning sections and `megoocolab-runner services --help`. A planning run is read-only and cannot run the command, so it gets the text in its prompt; writable runs are pointed to the command.
- **The planning section is added only to a new session.** A session resumed with your answer or your rejection already has it, so a rejection such as "drop that step" is not contradicted by a repeated instruction.

## Architecture

All in `runner/`:

- `internal/services/prompt.go`
- `Format` (new constant): the file's format in about ten lines, taken from the runner README's "Test services" section (the keys, the name rules, `${NAME}`, the reserved `MEGOO_SERVICES_` prefix, that a `.env` is not read).
- `PlanSection(worktree)` (new): the text for a planning run, one of three:
- **no file**: the repository has no `megoocolab.toml`; what the file gives (each worktree's own containers per check, on free ports, removed afterwards); find out how the checks get their services; if any check needs a container, make "Add megoocolab.toml" the plan's first step and say in the plan that the runner asked for it, not the design; the step writes the file (and a Compose file for the checks if the repository has none that fits), changes the repository's instructions for running checks to use `megoocolab-runner services run <name> -- <command>`, and proves each set by running its check through it; later steps run those checks the same way; if no check needs a container, add no step. Then `Format`.
- **file with sets**: the set names and descriptions, as today's section lists them; steps run commands that need them through `services run`; a step that adds a check or a command needing a service, a port or a variable the file does not declare changes `megoocolab.toml`, its Compose files and the repository's instructions in that same step. Then `Format`.
- **file with no sets**: the same rule, saying the file declares no services yet. No creation step is suggested.
- `PromptSection(worktree)` (changed): the existing section for writable runs gets the sentence "If your work adds a check or a command that needs a service, a port or a variable the file does not declare, add it to `megoocolab.toml` (and its Compose files) in the same commit, and run the new check through it. `megoocolab-runner services --help` describes the file." A worktree without the file, or with no sets, still gets nothing.
- `internal/jobs/manager.go`: next to today's call for writable runs, a read-only run with `role == "plan"` on a new session gets `PlanSection`. An error is written to the run's log and the run goes on, as today.
- `cmd/services.go`: the `services` command's long help shows `Format`.
- `runner/README.md`: the paragraph on what runs are told, in "Test services".

## Data and interfaces

- **No change** to the file's format, the server protocol, the database, the API or the web app. `role` is already sent in `run_start`; the runner starts using it.
- **New prompt text** for planning runs; one new sentence for writable runs.
- **`megoocolab-runner services --help`** prints the format.

## Error handling and edge cases

- **An invalid `megoocolab.toml`:** the error goes to the run's log and no section is added, as today. Text of an error never reaches a prompt.
- **What reaches the prompt from the file** stays as in MC-52: set names (checked against the name rule) and descriptions (one line, 200 characters at most).
- **You do not want the step:** reject the plan and say so. To stop the suggestion for a repository for good, commit an empty `megoocolab.toml`.
- **Two tasks planned before either is merged** both get the step. The second to merge has a conflict in the file, which the finish stage resolves like any other conflict.
- **Docker is missing on the runner's computer:** the step cannot prove the file; `services run` says so and the implementing agent asks you, as with any failing check.
- **The reviewers:** the step is in the approved plan and marked as asked for by the runner, so the step review and the final review do not treat it as work nobody asked for.
- **Other read-only runs** (brainstorm, the reviews, pull-request review) and Knowledge Base draft runs get nothing.
- **A plan session started by an older runner and resumed by the new one** does not get the section. It gets it at the next task.

## Testing

Tests are written first.

- **`runner/internal/services`** (`prompt_test.go`): the exact text of `PlanSection` for no file, a file with sets, a file with no sets, an invalid file (error, no text) and a file only in a parent folder (counts as no file); the new sentence in `PromptSection`; `Format` names every key the loader accepts.
- **`runner/internal/jobs`** (`services_test.go`, with the fake agent):
- a read-only run with role `plan` gets the "no file" section in a worktree without the file, and the "keep it up to date" section with it;
- read-only runs with another role, or none, get nothing;
- a resumed plan session gets nothing;
- a writable run with the file gets the new sentence, and one without the file still gets nothing.
- **`runner/cmd`:** `services --help` prints the format.
- **By hand before merging:** plan a task in a repository without the file whose tests need a database, and see the step in the plan; plan one in a repository whose tests need nothing, and see no step; in this repository, plan a task that adds a check needing a new service, and see the change to `megoocolab.toml` in that step.

## Out of scope

- Creating the file outside a plan: freestyle chats, crons and fix runs do not create it. They only keep an existing one up to date.
- Listing check commands in `megoocolab.toml`, or any other change to its format.
- Anything in the server or the web app: no setting, no notice that a project has no file, no task created automatically.
- Telling the brainstorm stage, so that designs mention the file.
- Checking by program whether the file is out of date. The agents are reminded; nothing enforces it.
- Adding the file to the other projects by hand: each gets it with its next planned task that needs it.
15 changes: 12 additions & 3 deletions runner/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,9 +169,18 @@ Services are removed in three places, so nothing keeps running:
removed. `services clean` does the same by hand.

Writable runs (implement, the fix roles, finish, freestyle, crons) in a worktree with `megoocolab.toml` get a
"Test services" section in their prompt that names the sets and the command. The runner puts its own folder first
on the agent's `PATH` and sets `MEGOO_SERVICES_DIR`, so the agent's checks and the runner share the same records.
Read-only runs get nothing.
"Test services" section in their prompt. It names the sets and the command, and asks the agent to add any service,
port or variable that new work needs to the file in the same commit. The runner puts its own folder first on the
agent's `PATH` and sets `MEGOO_SERVICES_DIR`, so the agent's checks and the runner share the same records.
`megoocolab-runner services --help` prints the file's format.

The first run of a planning session gets a section too. Without `megoocolab.toml`, the planning agent is asked to
find out whether any check needs a container, and if one does, to make "Add megoocolab.toml" the plan's first step.
That step writes the file, points the repository's check instructions at `services run` and proves each set. With
the file, the agent is told that a step adding a check that needs a new service, port or variable changes the file
in that same step. Both include the file's format, because a planning run cannot run commands. A plan session
continued with an answer or a rejection, the other read-only runs and Knowledge Base drafts get nothing. To stop
the suggestion for a repository, commit an empty `megoocolab.toml`.

The runner only removes Compose projects it recorded itself, and only names of the form `megoo-…-<8 hex>`. Other
containers, such as a MegooColab instance's `megoocolab-*` containers, are never touched.
Expand Down
1 change: 1 addition & 0 deletions runner/cmd/services.go
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ func newServicesCmd() *cobra.Command {
cmd := &cobra.Command{
Use: "services",
Short: "Start a worktree's test services for one command (megoocolab.toml)",
Long: "Start a worktree's test services for one command.\n\n" + services.Format,
}
cmd.AddCommand(newServicesRunCmd(), newServicesCleanCmd())
return cmd
Expand Down
11 changes: 11 additions & 0 deletions runner/cmd/services_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,17 @@ func runServices(t *testing.T, args ...string) (error, string, string) {
return err, stdout.String(), stderr.String()
}

func TestServicesHelpShowsTheFormat(t *testing.T) {
err, stdout, _ := runServices(t, "services", "--help")
if err != nil {
t.Fatalf("services --help = %v, want nil", err)
}
// Cobra trims the trailing whitespace of Long.
if !strings.Contains(stdout, strings.TrimSpace(services.Format)) {
t.Errorf("services --help does not show the format:\n%s", stdout)
}
}

func TestServicesRunExitsWithTheCommandsCode(t *testing.T) {
servicesEnv(t)
servicesWorktree(t)
Expand Down
10 changes: 1 addition & 9 deletions runner/internal/jobs/manager.go
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,6 @@ import (
"github.com/mmhy2003/megoocolab/runner/internal/mask"
"github.com/mmhy2003/megoocolab/runner/internal/policy"
"github.com/mmhy2003/megoocolab/runner/internal/protocol"
"github.com/mmhy2003/megoocolab/runner/internal/services"
"github.com/mmhy2003/megoocolab/runner/internal/startbranch"
"github.com/mmhy2003/megoocolab/runner/internal/tools"
"github.com/mmhy2003/megoocolab/runner/internal/worktree"
Expand Down Expand Up @@ -956,14 +955,7 @@ func (m *Manager) drive(r *run, rs protocol.RunStart, agent protocol.WelcomeAgen
return "cancelled", ""
}

text := sess.prompt
if kind == policy.Workspace && rs.Draft == nil {
section, err := services.PromptSection(wt)
if err != nil {
fmt.Fprintf(logf, "runner: services: %v\n", err)
}
text += section
}
text := sess.prompt + servicesPrompt(rs, kind, wt, logf)
prompt, err := r.content(text, rs.Images, imageData)
if err != nil {
return fail("images_failed", err)
Expand Down
29 changes: 29 additions & 0 deletions runner/internal/jobs/services.go
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ import (
"path/filepath"
"time"

"github.com/mmhy2003/megoocolab/runner/internal/policy"
"github.com/mmhy2003/megoocolab/runner/internal/protocol"
"github.com/mmhy2003/megoocolab/runner/internal/services"
)

Expand All @@ -18,6 +20,33 @@ const (
servicesSweepEvery = time.Hour
)

// rolePlan is the workflow role of a planning run (RunStart.Role).
const rolePlan = "plan"

// servicesPrompt is what a run's prompt gets about megoocolab.toml: a writable
// run the "Test services" section, the first run of a planning session the
// planning one, other runs (drafts, the other read-only roles, a continued
// planning session) nothing. An invalid file goes to the run's log and the
// run gets nothing.
func servicesPrompt(rs protocol.RunStart, kind policy.Kind, wt string, logf io.Writer) string {
var section func(string) (string, error)
switch {
case rs.Draft != nil:
return ""
case kind == policy.Workspace:
section = services.PromptSection
case kind == policy.ReadOnly && rs.Role == rolePlan && rs.ResumeSessionID == "":
section = services.PlanSection
default:
return ""
}
text, err := section(wt)
if err != nil {
fmt.Fprintf(logf, "runner: services: %v\n", err)
}
return text
}

// servicesDir is where this runner keeps the records of the service sets its
// runs start.
func (m *Manager) servicesDir() string { return filepath.Join(m.cacheRoot, "services") }
Expand Down
99 changes: 98 additions & 1 deletion runner/internal/jobs/services_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -57,11 +57,108 @@ func TestWritableRunGetsTheServicesSection(t *testing.T) {
t.Fatalf("finished = %+v", f)
}
r := e.readReport()
if len(r.Prompts) == 0 || !strings.Contains(r.Prompts[0], "## Test services") || !strings.Contains(r.Prompts[0], "`test`") {
if len(r.Prompts) == 0 || !strings.Contains(r.Prompts[0], "## Test services") || !strings.Contains(r.Prompts[0], "`test`") ||
!strings.Contains(r.Prompts[0], "`megoocolab-runner services --help` describes the file") {
t.Fatalf("prompts = %q", r.Prompts)
}
}

// planRun makes a run the read-only first run of a planning session.
func planRun(rs *protocol.RunStart) { rs.Policy, rs.Role = "read_only", "plan" }

func TestPlanRunGetsThePlanSection(t *testing.T) {
for _, tc := range []struct {
name string
files bool
parts []string
}{
{"without the file", false, []string{"This repository has no `megoocolab.toml`", "Add megoocolab.toml"}},
{"with the file", true, []string{"`test`", "changes `megoocolab.toml`"}},
} {
t.Run(tc.name, func(t *testing.T) {
e := newEnvWithCache(t, `[{"say":"done"}]`, 1, t.TempDir())
if tc.files {
commitFiles(t, e.repo, servicesFiles)
}
e.startRunWith("run-1", "MEG-1", planRun)
if f := e.finished("run-1"); f.Outcome != "completed" {
t.Fatalf("finished = %+v", f)
}
r := e.readReport()
if len(r.Prompts) == 0 {
t.Fatal("no prompt")
}
for _, part := range tc.parts {
if !strings.Contains(r.Prompts[0], part) {
t.Fatalf("prompt lacks %q: %q", part, r.Prompts[0])
}
}
want, err := services.PlanSection(e.worktree("MEG-1"))
if err != nil {
t.Fatal(err)
}
if r.Prompts[0] != "please"+want {
t.Fatalf("prompt = %q, want %q", r.Prompts[0], "please"+want)
}
})
}
}

func TestOtherReadOnlyRunsGetNoPlanSection(t *testing.T) {
for _, role := range []string{"", "brainstorm", "final_review", "pr_review"} {
t.Run("role "+role, func(t *testing.T) {
e := newEnvWithCache(t, `[{"say":"done"}]`, 1, t.TempDir())
e.startRunWith("run-1", "MEG-1", func(rs *protocol.RunStart) { rs.Policy, rs.Role = "read_only", role })
if f := e.finished("run-1"); f.Outcome != "completed" {
t.Fatalf("finished = %+v", f)
}
r := e.readReport()
if len(r.Prompts) == 0 || strings.Contains(r.Prompts[0], "## Test services") {
t.Fatalf("prompts = %q", r.Prompts)
}
})
}
}

func TestContinuedPlanSessionGetsNoSection(t *testing.T) {
t.Setenv("FAKEAGENT_SESSIONS_DIR", t.TempDir())
e := newEnvWithCache(t, twoTurns, 1, t.TempDir())
e.startRunWith("run-a", "MEG-1", func(rs *protocol.RunStart) { planRun(rs); rs.Prompt = "first turn" })
first := e.finished("run-a")
if first.Outcome != "completed" || first.SessionID == nil {
t.Fatalf("finished = %+v", first)
}
if r := e.finalReport(); len(r.Prompts) == 0 || !strings.Contains(r.Prompts[0], "## Test services") {
t.Fatalf("first prompts = %q", r.Prompts)
}

e.startRunWith("run-b", "MEG-1", func(rs *protocol.RunStart) {
planRun(rs)
rs.ResumeSessionID, rs.ResumePrompt = *first.SessionID, "continue please"
})
if f := e.finished("run-b"); f.Outcome != "completed" {
t.Fatalf("finished = %+v", f)
}
if r := e.finalReport(); !slices.Equal(r.Prompts, []string{"continue please"}) {
t.Fatalf("prompts = %q", r.Prompts)
}

t.Run("fallback", func(t *testing.T) {
t.Setenv("FAKEAGENT_SESSIONS_DIR", t.TempDir())
e := newEnvWithCache(t, twoTurns, 1, t.TempDir())
e.startRunWith("run-fb", "MEG-1", func(rs *protocol.RunStart) {
planRun(rs)
rs.Prompt, rs.ResumePrompt, rs.ResumeSessionID = "full prompt", "continue please", "fake-session-404"
})
if f := e.finished("run-fb"); f.Outcome != "completed" {
t.Fatalf("finished = %+v", f)
}
if r := e.finalReport(); !slices.Equal(r.Prompts, []string{"full prompt\n\ncontinue please"}) {
t.Fatalf("prompts = %q", r.Prompts)
}
})
}

func TestReadOnlyRunAndRunsWithoutTheFileGetNoSection(t *testing.T) {
for _, tc := range []struct {
name, policy string
Expand Down
Loading
Loading