smol-symphony 0.1.0 → 0.3.0

package/AGENTS.md

@@ -1,35 +1,96 @@
 # AGENTS.md
 
-Standing instructions for any AI agent (Claude Code, Codex, OpenCode, etc.)
-working on this repo. Short list; keep it that way.
+Standing instructions and a small map for any AI agent (Claude Code, Codex,
+OpenCode, etc.) working on this repo. Keep it short.
+
+## Where things live
+
+Layout is functional-core / imperative-shell (FCIS): pure decision logic in
+`src/core/`, all effects + wiring in `src/shell/`, shared types in `src/types/`.
+`npm run lint:arch` enforces the import direction (core never reaches the shell;
+only the composition root `src/shell/main.ts` may import core).
+
+- `src/shell/main.ts` — the composition root (top-level wiring). The per-issue
+  dispatch lifecycle runs in `src/shell/orchestrator-loop.ts` (poll-and-dispatch;
+  owns the live RunningEntry map the Done-state action context is built from) and
+  the reconcilers (`src/shell/main-reconcilers*.ts`, `reconciler-loop.ts`); pure
+  scheduling/reconcile decisions live in `src/core/schedule/` + `src/core/reconcile/`.
+- `src/shell/runner-loop.ts` (+ `runner-loop-turn.ts`) — the per-issue attempt
+  pipeline (imperative shell); pure turn / dispatch-config / injection logic lives
+  in `src/core/runner/`, and the typed `actions:` block runs through
+  `src/core/actions/` + `src/shell/actions-runner.ts`.
+- `src/core/mcp/` + `src/shell/main-mcp.ts` (runtime in
+  `src/shell/server/mcp-runtime.ts`) — MCP tools exposed to in-VM agents
+  (`symphony.transition`, `symphony.request_human_steering`,
+  `symphony.propose_issue`).
+- `src/core/workflow/parse.ts` (+ `derive.ts`, `validate.ts`) — workflow file
+  parser, loaded via `src/shell/adapter/workflow-loader.ts`; the contract
+  `WORKFLOW.template.yaml` documents.
+- `src/core/issue/` + `src/shell/interp/tracker*.ts` — local markdown tracker
+  (pure front-matter parse in core; disk scan/read/write in the shell
+  interpreters). Only kind today.
+- `src/shell/interp/acp*.ts` + `scripts/vm-agent.mjs` — host↔VM ACP transport
+  (host-side interpreter over the `/acp` WebSocket served by
+  `src/shell/server/http.ts`; `vm-agent.mjs` is the in-VM guest launcher).
+- `images/agents/` — the agent rootfs image (Node + the ACP coding-agent CLIs +
+  the in-VM `/opt/symphony/vm-agent.mjs` launcher), built **once** via
+  `npm run build:image`. Selected by `WORKFLOW.yaml`'s `gondolin.image` (a build
+  id or `name:tag` ref). See `images/agents/README.md`.
+- `src/core/http/` + `src/shell/main-http*.ts` (listener in
+  `src/shell/server/http.ts`) — HTTP dashboard + MCP endpoint listener.
+- `WORKFLOW.yaml` — canonical workflow this repo dispatches against itself.
+- `WORKFLOW.template.yaml` — annotated reference for workflow file syntax.
+- Handoff (push + PR) is documented in `README.md` § "After-run handoff".
 
 ## Workflow template stays in sync
 
-The repo ships two workflow files:
-
-- `WORKFLOW.md` — the canonical workflow used to dispatch agents against this
-  project.
-- `WORKFLOW.template.md` — the annotated reference covering every supported
-  option, its type, default, and example.
-
 **When you change anything that affects workflow file syntax or semantics,
-update `WORKFLOW.template.md` in the same commit.** Concretely:
+update `WORKFLOW.template.yaml` in the same commit.** Concretely:
 
 - Adding a new YAML key under `tracker:`, `polling:`, `workspace:`, `hooks:`,
-  `agent:`, `acp:`, `smolvm:`, `server:`, or `mcp:` → document it in the
+  `agent:`, `acp:`, `gondolin:`, `server:`, or `mcp:` → document it in the
   matching section of the template.
 - Renaming or removing a key → rename or remove it in the template too.
-- Changing a default value in `src/workflow.ts` (or whichever parser becomes
-  authoritative) → update the `Default:` annotation in the template.
-- Introducing a new top-level section → add a new section block to the
-  template.
-- Adding a new hook env var or Liquid context field → list it in the template
-  alongside the existing ones (under `hooks:` or under the prompt-body
-  comment).
+- Changing a default value in `src/core/workflow/parse.ts` → update the
+  `Default:` annotation in the template.
+- Adding a new typed action-context variable (`$branch`, `$pr_title`, …) or
+  Liquid prompt-context field → list it in the template alongside the existing
+  ones.
 
 If you find the template already drifted from the parser at the start of your
-task, fix it as part of your change. The template is the contract for what
-operators can write; an out-of-date template is a bug, not paperwork.
+task, fix it as part of your change. An out-of-date template is a bug, not
+paperwork.
+
+## Where behavior belongs: orchestrator, typed actions, the image
+
+State-machine logic — new transitions, anything that mutates tracker files the
+orchestrator wrote, anything the runner must re-detect afterward — belongs in
+the orchestrator (the runner / MCP deciders in `src/core/**`, wired through
+`src/shell/**`) behind typed APIs with tests. It is not an extension point you bolt on from the outside.
+
+Repo-local glue that fires on a transition (push the branch, open a PR) belongs
+in a state's typed `actions:` block — declarative records like `push_branch`,
+`create_pr_if_missing`, and `run_in_vm` that the action executor runs against a
+fixed context (`$branch`, `$base_branch`, `$pr_title`, `$pr_body_file`,
+`$repo`). See `states.Done.actions` in `WORKFLOW.yaml` for the canonical
+push-branch + open-PR pair, and `WORKFLOW.template.yaml` for the full kind list.
+
+Per-VM tooling — the CLIs and runtimes the agent needs at runtime — belongs in
+the agent image under `images/agents/`, baked once via `npm run build:image`.
+Canonical workspace setup (clone, base checkout, `agent/<id>` branch cut,
+remote stripping) is owned by the orchestrator's TypeScript `setupWorkspaceDir`;
+the surviving shell `hooks:` (`after_create` / `before_run` / `before_remove`)
+are only for additional repo-local prep on top of that, never for state-machine
+behavior.
+
+If you find yourself adding a `SYMPHONY_*` env var so a shell hook can reach
+into orchestrator-owned state, or writing a hook the runner then has to
+re-detect via a post-hook scan, that is the signal the logic is on the wrong
+side of the seam — surface it as a typed call (a transition, an MCP tool, or a
+typed action) instead. Issue bodies sometimes sketch a shell-shaped solution
+under an `after_run:` heading; `after_run` is no longer a hook kind (it was
+replaced by the typed `actions:` block above), so treat that as a sketch to
+re-express, not a directive.
 
 ## Build, test, and check before declaring done
 
@@ -37,30 +98,55 @@ operators can write; an out-of-date template is a bug, not paperwork.
 - `npm test` — must pass.
 - `npm run build` — must pass.
 
-Run all three before calling `symphony.mark_done`.
-
-## Handoff: patch bundle vs. pull request
+Run all three before calling `symphony.transition` into a terminal state.
 
-`after_run` in `WORKFLOW.md` ships in two modes:
+## Filing tracker issues
 
-- **Patch bundle (default).** Writes `git format-patch` to
-  `.symphony/patches/<branch>.patch` for human review. No remote needed.
-  This is what fires when no GitHub remote is wired up.
-- **Pull request.** Triggered when `SYMPHONY_REPO=<owner>/<repo>` is exported
-  before launch AND the working repo has an `origin` remote. The hook then
-  pushes the per-issue branch and runs `gh pr create`. `gh auth status` must
-  be clean on the host; the token never enters the VM.
-
-To switch this project to PR mode:
+When asked to file an issue against this repo's own tracker (the local Markdown
+tracker at `~/.symphony/trackers/smol-symphony/<state>/`), POST to the running
+symphony HTTP server rather than hand-writing the file or guessing the next
+identifier:
 
 ```
-git remote add origin git@github.com:<owner>/smol-symphony.git
-git push -u origin main
-SYMPHONY_REPO=<owner>/smol-symphony npx symphony WORKFLOW.md
+curl -s -X POST http://127.0.0.1:8787/api/v1/issues \
+  -H "content-type: application/json" \
+  --data-binary @/tmp/issue.json
+```
+
+Body shape (from `decideCreateIssue` in `src/core/http/decisions.ts`):
+
+```json
+{
+  "title": "required, non-empty",
+  "state": "Todo",              // optional; defaults to first declared active state
+  "identifier": "108",          // optional; auto-picked as next free integer
+  "description": "markdown body, written below the YAML front matter",
+  "priority": 2,                // optional integer; omitted ⇒ no `priority:` key
+  "labels": ["refactor"],       // optional
+  "blocked_by": ["107"]         // optional
+}
 ```
 
-`SYMPHONY_BASE_BRANCH` (default `main`) overrides the base the agent branches
-from and the PR opens against.
+State must be a declared non-terminal state (`active` or `holding`); terminals
+are closed to direct creation. The server stamps `created_at` / `updated_at`,
+allocates the next free numeric identifier when one isn't supplied, and writes
+`<tracker.root>/<state>/<identifier>.md`. Response is `201` with
+`{ path, identifier, state }`. Conflicts (duplicate identifier, bad state) come
+back as `400`/`409` with a typed error code.
+
+The HTTP server (`server.port` in `WORKFLOW.yaml`, currently `8787`) is unauthenticated
+inside the trusted tailscale boundary — no bearer, no CSRF on JSON POSTs from curl.
+If the server isn't running, hand-writing `~/.symphony/trackers/smol-symphony/<state>/<n>.md`
+with the same YAML front-matter shape (`id`, `identifier`, `title`, `created_at`,
+`updated_at`, optional `priority`/`labels`) is equivalent — see existing files
+under `Done/` for canonical examples.
+
+Issue bodies on this tracker follow a four-section shape: **Problem** (what's
+wrong / why now), **Change** (concrete edits, with file paths and line ranges
+where known), **allowed_paths** (the workspace scope the dispatched agent is
+permitted to touch), **Acceptance** (the checks that must pass before
+`symphony.transition` into a terminal state). Look at recent `Done/*.md` for the
+shape — these are the prompts the dispatched agent sees, so be specific.
 
 ## Don't write to generated state
 
@@ -69,5 +155,5 @@ Skip these when staging commits unless the user asks:
 - `.agents/`, `.claude/`, `.impeccable/` — local tooling state.
 - `issues*/Done/`, `issues*/Cancelled/`, `issues*/In Progress/` — runtime
   tracker artifacts from prior symphony runs.
-- `.symphony/` — workspaces, patch bundles, runtime caches.
+- `.symphony/` — workspaces, runtime caches.
 - `skills-lock.json` — auto-generated.