smol-symphony 0.1.0

package/WORKFLOW.md

@@ -0,0 +1,269 @@
+---
+# WORKFLOW.md — symphony dispatched against smol-symphony itself.
+#
+# Run with:
+#
+#   npx symphony WORKFLOW.md
+#
+# Defaults assume a fully local setup: the per-issue workspace clones from this
+# repo's `.git` directory, the agent has no network credentials, and on
+# mark_done the host writes a `git format-patch` bundle to
+# `.symphony/patches/<branch>.patch` for human review.
+#
+# To opt into the remote PR flow, export before launching:
+#
+#   SYMPHONY_REPO=owner/smol-symphony \
+#   SYMPHONY_BASE_BRANCH=main \
+#   npx symphony WORKFLOW.md
+#
+# `gh` on the host must be authenticated (`gh auth status` clean). The token
+# never enters the VM.
+#
+# Every section and option is documented in WORKFLOW.template.md.
+
+tracker:
+  kind: local
+  root: ./issues
+  active_states:
+    - Todo
+    - In Progress
+  terminal_states:
+    - Done
+    - Cancelled
+
+polling:
+  interval_ms: 5000
+
+workspace:
+  root: ./.symphony/workspaces
+
+hooks:
+  timeout_ms: 120000
+
+  # Clone smol-symphony into the fresh per-issue workspace from a strictly local
+  # source (no creds needed). The agent receives a working git repo with full
+  # history on the configured base branch, plus a per-issue branch checked out.
+  # All network remotes are stripped so any `git push`/`git fetch` from inside
+  # the VM fails closed.
+  after_create: |
+    set -eu
+    SOURCE_REPO="${SYMPHONY_SOURCE_REPO:-${PWD}/../../..}"
+    BASE="${SYMPHONY_BASE_BRANCH:-main}"
+    ISSUE_ID="$(basename "$PWD")"
+    BRANCH="agent/${ISSUE_ID}"
+
+    if [ ! -d "${SOURCE_REPO}/.git" ]; then
+      echo "after_create: SOURCE_REPO=${SOURCE_REPO} is not a git repo" >&2
+      exit 1
+    fi
+
+    # `git clone --local` hardlinks .git/objects when possible; fast and disk-cheap.
+    # `--no-tags` keeps the local refspec minimal; `--branch` lands on the right base.
+    git clone --local --no-tags --branch "${BASE}" "${SOURCE_REPO}" .
+
+    # Strip all remotes. The agent will see no network targets at all.
+    for remote in $(git remote); do
+      git remote remove "${remote}"
+    done
+    git config --local --unset credential.helper 2>/dev/null || true
+
+    # If SYMPHONY_REPO is set, restore an `origin` pointing at the GitHub remote
+    # so the after_run hook can push. The URL is the canonical HTTPS form (no
+    # token); auth comes from the host's `gh`, which never enters the VM.
+    if [ -n "${SYMPHONY_REPO:-}" ]; then
+      git remote add origin "https://github.com/${SYMPHONY_REPO}.git"
+      gh auth setup-git 2>/dev/null || true
+      git fetch --no-tags origin "${BASE}:refs/remotes/origin/${BASE}" || true
+    fi
+
+    git config --local user.name  "symphony-agent"
+    git config --local user.email "agent@symphony.local"
+
+    git checkout -b "${BRANCH}"
+
+    echo "workspace ready: base=${BASE} branch=${BRANCH} source=${SOURCE_REPO}"
+
+  # Runs after every attempt. Gated on the issue file being in Done/ (i.e. the
+  # agent has called symphony.mark_done). Two outputs:
+  #   - If SYMPHONY_REPO is set: push branch + open (or update) a PR via gh.
+  #   - Else (local-only mode): write the agent's work as a git format-patch
+  #     bundle into ./.symphony/patches/<branch>.patch for human review.
+  after_run: |
+    set -eu
+    BASE="${SYMPHONY_BASE_BRANCH:-main}"
+    ISSUE_ID="$(basename "$PWD")"
+    BRANCH="agent/${ISSUE_ID}"
+    TRACKER_ROOT="${SYMPHONY_TRACKER_ROOT:-$PWD/../../../issues}"
+    PATCHES_DIR="${SYMPHONY_PATCHES_DIR:-$PWD/../../../.symphony/patches}"
+
+    if [ ! -f "${TRACKER_ROOT}/Done/${ISSUE_ID}.md" ]; then
+      echo "issue ${ISSUE_ID} not in Done/ yet; skipping handoff"
+      exit 0
+    fi
+    if ! git rev-parse --verify "${BRANCH}" >/dev/null 2>&1; then
+      echo "no branch ${BRANCH}; nothing to hand off"
+      exit 0
+    fi
+
+    # Resolve the ref the agent diverged from. In remote mode origin/${BASE}
+    # exists (after_create's `git fetch`). In local-only mode we kept the local
+    # ${BASE} branch alive (`git clone --branch ${BASE}` creates it at the
+    # original tip; `git checkout -b ${BRANCH}` does not remove it). That tip
+    # is exactly where the agent diverged from.
+    if git rev-parse --verify "origin/${BASE}" >/dev/null 2>&1; then
+      MERGE_BASE="origin/${BASE}"
+    elif git rev-parse --verify "${BASE}" >/dev/null 2>&1; then
+      MERGE_BASE="${BASE}"
+    else
+      echo "could not resolve merge base (no origin/${BASE} or local ${BASE})" >&2
+      exit 1
+    fi
+
+    if [ -z "$(git log --oneline "${MERGE_BASE}..${BRANCH}" 2>/dev/null)" ]; then
+      echo "no new commits on ${BRANCH}; nothing to hand off"
+      exit 0
+    fi
+
+    # The mark_done MCP tool persists its title + summary into a structured
+    # markdown file at <staging>/mark_done.md. The staging dir is inside .git/
+    # when the workspace has its own clone; .symphony-runtime/ otherwise.
+    MARKDONE=""
+    if [ -f .git/symphony-runtime/mark_done.md ]; then
+      MARKDONE=.git/symphony-runtime/mark_done.md
+    elif [ -f .symphony-runtime/mark_done.md ]; then
+      MARKDONE=.symphony-runtime/mark_done.md
+    fi
+    if [ -n "${MARKDONE}" ]; then
+      TITLE="$(sed -n '1 s/^# //p' "${MARKDONE}")"
+      BODY="$(tail -n +3 "${MARKDONE}")"
+    else
+      TITLE="${ISSUE_ID}"
+      BODY="Symphony run for ${ISSUE_ID}."
+    fi
+
+    if [ -n "${SYMPHONY_REPO:-}" ]; then
+      # Remote PR mode.
+      git push -u origin "${BRANCH}"
+      if gh pr view "${BRANCH}" >/dev/null 2>&1; then
+        echo "PR already exists for ${BRANCH}; pushed updates"
+      else
+        gh pr create \
+          --base "${BASE}" \
+          --head "${BRANCH}" \
+          --title "${ISSUE_ID}: ${TITLE}" \
+          --body "${BODY}"
+      fi
+    else
+      # Local-only mode: bundle the diff for human review.
+      mkdir -p "${PATCHES_DIR}"
+      OUT="${PATCHES_DIR}/$(echo "${BRANCH}" | tr '/' '_').patch"
+      git format-patch --stdout "${MERGE_BASE}..${BRANCH}" > "${OUT}"
+      echo "wrote patch bundle: ${OUT}"
+      echo "  apply with:  git -C <target-repo> am ${OUT}"
+    fi
+
+agent:
+  max_concurrent_agents: 1
+  max_turns: 6
+  max_retry_backoff_ms: 120000
+
+acp:
+  # Selecting "claude" is enough: symphony reads ~/.claude/.credentials.json on
+  # the host, stages a copy into the workspace's runtime dir, and auto-generates
+  # a launch command that places the file at the adapter's expected path inside
+  # the VM before exec'ing claude-agent-acp. Set `command` only to override.
+  adapter: claude
+  shell: bash
+  prompt_timeout_ms: 1800000
+  read_timeout_ms: 30000
+  stall_timeout_ms: 300000
+
+smolvm:
+  from: ./.vm/symphony.smolmachine.smolmachine
+  cpus: 2
+  mem_mib: 4096
+  net: true
+  # No volume mounts. Workspace is auto-mounted by the runner. Credentials are
+  # staged into the workspace by symphony and copied into ~/.claude by the
+  # auto-derived acp.command. The tracker is reached only through the symphony
+  # MCP server.
+  volumes: []
+  forward_env:
+    - OPENAI_API_KEY
+    - ANTHROPIC_API_KEY
+
+server:
+  port: 8787
+  # Bound to all interfaces because access is gated by tailscale, not by the
+  # HTTP server itself. The endpoint has no auth; only expose it inside a
+  # trusted network boundary.
+  host: 0.0.0.0
+
+mcp:
+  # The VM's loopback transparently reaches the host's loopback in smolvm, so
+  # 127.0.0.1 from inside the VM hits the host's listener. Override only if
+  # your VMM has a different host alias.
+  host: 127.0.0.1
+---
+You are working on **smol-symphony**, a TypeScript orchestrator that dispatches
+coding agents into per-issue smolvm microVMs and talks to them over the Agent
+Client Protocol (ACP). Your workspace is a fresh clone of this repo.
+
+Issue: **{{ issue.identifier }} — {{ issue.title }}**
+State: {{ issue.state }}
+{% if issue.priority -%}Priority: {{ issue.priority }}{%- endif %}
+{% if issue.labels.size > 0 -%}Labels: {% for l in issue.labels %}{{ l }}{% unless forloop.last %}, {% endunless %}{% endfor %}{%- endif %}
+
+{% if issue.description -%}
+Description:
+
+{{ issue.description }}
+{%- endif %}
+
+Orientation:
+
+- This is the smol-symphony codebase. Start by reading `README.md` and
+  `PRODUCT.md` if you haven't seen them. `SPEC.md` is the long-form design
+  spec. `CLAUDE.md` (if present) has any standing instructions for this repo.
+- Source lives under `src/`. Tests live under `tests/`. Run `npm test` and
+  `npm run typecheck` before declaring work done.
+- You are on a per-issue branch (`agent/{{ issue.identifier }}`) checked out
+  from the configured base branch. Commit your work locally. You do **not**
+  have network credentials; pushing is the host's job, after you mark done.
+
+Workflow:
+
+1. Read enough of the codebase to understand the change you need to make.
+2. Make the smallest correct change. Add or update tests where the change is
+   testable. Run `npm run typecheck` and `npm test`; both must pass.
+3. Commit your work to the per-issue branch with a short message.
+4. Call `symphony.mark_done({ title, summary })`:
+   - `title`: a single line in imperative voice, ≤72 chars. Becomes the
+     PR/commit title.
+   - `summary`: a one- to three-paragraph narrative of what you did and why,
+     plus any follow-ups you noticed but didn't do. Becomes the PR body.
+   This is the only way to signal completion; nothing else will move the issue
+   out of an active state.
+
+If you genuinely cannot proceed — ambiguous requirements, missing context that
+only a human can supply, a design decision that needs human input — call
+`symphony.request_human_steering({ question, context })` instead of guessing.
+Your turn will end immediately and the human's response will arrive as your
+next prompt.
+
+Steering tips:
+
+- The operator's dashboard already shows the original issue title and body
+  alongside your question. Do **not** restate or paraphrase the issue body in
+  `question`; ask the specific thing you need answered.
+- Use `context` for facts the operator wouldn't otherwise see: what you've
+  inspected, what you've already tried, what constraint is forcing the
+  question.
+
+{% if attempt -%}
+This is continuation/retry attempt {{ attempt }}. Inspect the workspace before
+making new edits; your previous run may have left commits on the branch. Check
+`git log agent/{{ issue.identifier }}` to see what's there. If the work is
+already complete, call `symphony.mark_done` with an appropriate title and
+summary and stop.
+{%- endif %}

package/WORKFLOW.template.md

@@ -0,0 +1,307 @@
+<!--
+WORKFLOW.template.md — annotated reference for symphony workflow files.
+
+A workflow file is a YAML front-matter block plus a Liquid-templated prompt
+body. The orchestrator parses the front matter into ServiceConfig (defined in
+src/types.ts) and renders the prompt body once per dispatched issue, with the
+Liquid context `{ issue, attempt }`.
+
+This document lists every supported section, every option within it, the
+parser default, and a small example. For a complete worked example, see
+WORKFLOW.md in this repo.
+
+Notation:
+  • Required keys are marked (required).
+  • Types: `string`, `int`, `bool`, `path` (string resolved relative to the
+    workflow file's directory unless absolute), `string[]`, `map<K, V>`.
+  • Defaults are what the parser writes when the key is absent.
+-->
+
+---
+# ─────────────────────────────────────────────────────────────────────────────
+# tracker — where issues come from.
+# ─────────────────────────────────────────────────────────────────────────────
+tracker:
+  # kind (required): 'local' or 'linear'.
+  #   local  — markdown files under `root`, one per issue, organized by state.
+  #   linear — Linear API (workspace + project_slug).
+  kind: local
+
+  # root (path): local-tracker only. Directory containing `<state>/<id>.md`
+  # files. Required when kind=local. Resolved relative to the workflow file
+  # if not absolute.
+  root: ./issues
+
+  # endpoint (string): linear-tracker only. API endpoint.
+  # Default: Linear's public GraphQL endpoint.
+  endpoint: https://api.linear.app/graphql
+
+  # api_key (string): linear-tracker only. Personal API key. Required for
+  # kind=linear. Pulled from $LINEAR_API_KEY if you use `$LINEAR_API_KEY`.
+  api_key: $LINEAR_API_KEY
+
+  # project_slug (string): linear-tracker only. Required for kind=linear.
+  project_slug: my-team/my-project
+
+  # active_states (string[]): states the orchestrator dispatches against.
+  # Default: [Todo, In Progress]
+  active_states:
+    - Todo
+    - In Progress
+
+  # terminal_states (string[]): states the orchestrator treats as complete;
+  # mark_done moves issues to the first listed state.
+  # Default: [Done]
+  terminal_states:
+    - Done
+    - Cancelled
+
+# ─────────────────────────────────────────────────────────────────────────────
+# polling — how often to poll the tracker.
+# ─────────────────────────────────────────────────────────────────────────────
+polling:
+  # interval_ms (int): tick interval, milliseconds.
+  # Default: 30000
+  interval_ms: 5000
+
+# ─────────────────────────────────────────────────────────────────────────────
+# workspace — per-issue working directory.
+# ─────────────────────────────────────────────────────────────────────────────
+workspace:
+  # root (path): parent directory holding `<issue-id>/` working trees.
+  # Default: $TMPDIR/symphony_workspaces
+  root: ./.symphony/workspaces
+
+# ─────────────────────────────────────────────────────────────────────────────
+# hooks — shell scripts the orchestrator runs at workspace lifecycle points.
+#
+# All hooks run on the HOST (not inside the VM), with cwd set to the per-issue
+# workspace path. Each hook is a multi-line shell snippet. Available env vars:
+#
+#   PWD                  — the workspace directory (cwd at hook start).
+#   SYMPHONY_ISSUE_ID    — the issue identifier.
+#   SYMPHONY_ISSUE_STATE — the issue's current state.
+#   SYMPHONY_ATTEMPT     — 1-based attempt counter.
+#   SYMPHONY_WORKFLOW    — absolute path to the workflow file.
+#
+# Plus any env var the operator exports before launching `symphony`. The
+# common pattern is to plumb tracker root / repo / base via env so the same
+# workflow file works against multiple repos. See WORKFLOW.md for an example.
+# ─────────────────────────────────────────────────────────────────────────────
+hooks:
+  # timeout_ms (int): max wall time for a single hook invocation.
+  # Default: 60000
+  timeout_ms: 120000
+
+  # after_create (string | null): runs right after the workspace directory is
+  # created, before the first dispatch. Use for git clone, dependency install,
+  # etc. Default: null.
+  after_create: |
+    set -eu
+    # ... your setup ...
+
+  # before_run (string | null): runs before each turn. Default: null. Use for
+  # cheap "make sure the workspace is sane" checks; expensive setup belongs in
+  # after_create.
+  before_run: |
+    set -eu
+    # ... pre-turn checks ...
+
+  # after_run (string | null): runs after each turn, regardless of outcome.
+  # Inspect cwd or the tracker to decide whether work is complete. Default: null.
+  after_run: |
+    set -eu
+    # ... post-turn handoff (push, format-patch, …) ...
+
+  # before_remove (string | null): runs before the workspace directory is
+  # deleted. Use to extract artifacts you want to keep. Default: null.
+  before_remove: |
+    set -eu
+    # ... rescue artifacts ...
+
+# ─────────────────────────────────────────────────────────────────────────────
+# agent — concurrency and turn budget.
+# ─────────────────────────────────────────────────────────────────────────────
+agent:
+  # max_concurrent_agents (int): cap on simultaneously-running agents across
+  # the whole workflow. Default: 10
+  max_concurrent_agents: 2
+
+  # max_turns (int): hard ceiling on autonomous turns per issue. Steering-reply
+  # turns are free; only autonomous turns count. Default: 20
+  max_turns: 6
+
+  # max_retry_backoff_ms (int): exponential backoff cap for retried dispatches
+  # after recoverable failures. Default: 300000
+  max_retry_backoff_ms: 120000
+
+  # max_concurrent_agents_by_state (map<string, int>): optional per-state
+  # concurrency cap. Sums must not exceed max_concurrent_agents. Default: {}.
+  max_concurrent_agents_by_state:
+    Todo: 1
+    In Progress: 1
+
+# ─────────────────────────────────────────────────────────────────────────────
+# acp — Agent Client Protocol adapter selection.
+# ─────────────────────────────────────────────────────────────────────────────
+acp:
+  # adapter (string): one of symphony's known profiles. The profile encodes the
+  # binary to launch and the host credential file to stage. Default: 'claude'.
+  #   claude   — claude-agent-acp; stages ~/.claude/.credentials.json
+  #   codex    — codex-acp;        stages ~/.codex/auth.json
+  adapter: claude
+
+  # command (string | null): optional shell override. When set, replaces the
+  # auto-generated launch command and OPTS OUT of credential staging — you
+  # become responsible for placing whatever credentials the adapter needs.
+  # Leave null for the supported zero-config flow. Default: null.
+  command: null
+
+  # shell (string): shell used to run the ACP launch command. Default: 'bash'.
+  shell: bash
+
+  # prompt_timeout_ms (int): max wall time for a single ACP `session/prompt`
+  # call (one symphony turn). Default: 3600000 (1 hour).
+  prompt_timeout_ms: 1800000
+
+  # read_timeout_ms (int): max time between bytes on the ACP stdio. Bumped from
+  # a small default because VM cold-boot + adapter startup can take ~10s on
+  # first use. Default: 30000
+  read_timeout_ms: 30000
+
+  # stall_timeout_ms (int): max time the adapter can be idle (no events) before
+  # the turn is killed and retried. Default: 300000
+  stall_timeout_ms: 300000
+
+# ─────────────────────────────────────────────────────────────────────────────
+# smolvm — microVM execution environment.
+# ─────────────────────────────────────────────────────────────────────────────
+smolvm:
+  # from (path | null): path to a packed .smolmachine.smolmachine artifact.
+  # Built once with `scripts/build-vm.sh`. Mutually exclusive with `image`.
+  # Default: null.
+  from: ./.vm/symphony.smolmachine.smolmachine
+
+  # image (string | null): container image to pull instead of a packed artifact.
+  # Mutually exclusive with `from`. Default: null.
+  image: null
+
+  # cpus (int): vCPU count per VM. Default: 2.
+  cpus: 2
+
+  # mem_mib (int): RAM per VM in MiB. Default: 2048.
+  mem_mib: 4096
+
+  # net (bool): whether the VM has outbound networking. Default: true.
+  # Setting false isolates the VM at the cost of breaking adapters that fetch
+  # tokens, models, or dependencies at run time.
+  net: true
+
+  # bin_path (path | null): legacy mount; host directory containing the codex
+  # binary, mounted read-only at /opt/codex. Default: null.
+  bin_path: null
+
+  # volumes (list): additional host:guest bind mounts. smolvm has a small
+  # per-VM mount cap (the workspace itself already consumes one slot), so keep
+  # this list small. Each entry: { host: path, guest: path, readonly?: bool }.
+  # Default: [].
+  volumes:
+    - host: ~/.cache/npm
+      guest: /root/.npm
+      readonly: false
+
+  # forward_env (string[]): host env vars forwarded into the VM exec.
+  # Default: [OPENAI_API_KEY, ANTHROPIC_API_KEY]
+  forward_env:
+    - OPENAI_API_KEY
+    - ANTHROPIC_API_KEY
+
+  # endpoint (string): smolvm server. unix:// or http:// URI.
+  # Default: unix://$XDG_RUNTIME_DIR/smolvm.sock (or /run/user/1000/smolvm.sock)
+  endpoint: unix:///run/user/1000/smolvm.sock
+
+# ─────────────────────────────────────────────────────────────────────────────
+# server — HTTP dashboard + MCP endpoint listener.
+# ─────────────────────────────────────────────────────────────────────────────
+server:
+  # port (int | null): when null, no HTTP server is started. `--port <n>` on
+  # the CLI overrides this. Default: null.
+  port: 8787
+
+  # host (string): bind address. Default: '127.0.0.1'. Bind to '0.0.0.0' only
+  # inside a trusted network boundary; the dashboard has no built-in auth.
+  host: 0.0.0.0
+
+# ─────────────────────────────────────────────────────────────────────────────
+# mcp — Model Context Protocol server exposed to in-VM agents.
+#
+# The orchestrator runs a JSON-RPC endpoint scoped to each active issue at
+# /api/v1/issues/<id>/mcp, gated by a per-dispatch bearer token. Two tools live
+# there:
+#
+#   • symphony.mark_done({ title, summary })
+#   • symphony.request_human_steering({ question, context? })
+# ─────────────────────────────────────────────────────────────────────────────
+mcp:
+  # enabled (bool): when false, the orchestrator refuses to dispatch (MCP is
+  # required for completion signaling). Default: true.
+  enabled: true
+
+  # host (string): hostname or IP the agent uses to reach the orchestrator
+  # from inside the smolvm. The port is resolved at runtime from the
+  # actually-bound HTTP server. Default: '127.0.0.1' (smolvm proxies VM
+  # loopback to host loopback; verified empirically).
+  host: 127.0.0.1
+
+  # host_url (string | null): full-URL override. When set, used verbatim and
+  # `host` + bound port are ignored. Use only when the VM cannot reach the
+  # orchestrator through the host gateway (e.g. bridge networking with a
+  # fixed reverse-proxy URL). Default: null.
+  host_url: null
+---
+<!--
+Liquid-templated prompt body. Rendered once per dispatched issue. Context:
+
+  issue.identifier   — the issue's external id (e.g. "DEMO-42").
+  issue.title        — issue title (string).
+  issue.state        — current state (string, matches active_states[]).
+  issue.description  — body text (string or empty).
+  issue.priority     — number or null.
+  issue.labels       — list of strings (lowercased).
+  attempt            — int, 1-based attempt counter; absent on first attempt.
+
+Available Liquid filters: standard Shopify Liquid plus `escape_once`.
+
+The body below is the literal prompt sent to the agent. Keep it specific to
+this workflow; orchestrator behavior (mark_done, request_human_steering) is
+the same no matter what you write here.
+-->
+
+You are picking up a single issue and shepherding it through the workflow.
+
+Issue: **{{ issue.identifier }} — {{ issue.title }}**
+State: {{ issue.state }}
+{% if issue.priority -%}Priority: {{ issue.priority }}{%- endif %}
+{% if issue.labels.size > 0 -%}Labels: {% for l in issue.labels %}{{ l }}{% unless forloop.last %}, {% endunless %}{% endfor %}{%- endif %}
+
+{% if issue.description -%}
+Description:
+
+{{ issue.description }}
+{%- endif %}
+
+Goals:
+
+1. Work in the current directory only; treat it as the issue workspace.
+2. Make the smallest correct change that satisfies the issue.
+3. Call `symphony.mark_done({ title, summary })` when done. This is the only
+   way to signal completion. The orchestrator atomically moves the issue file
+   to the terminal state and stops dispatching.
+4. If you cannot proceed without human input, call
+   `symphony.request_human_steering({ question, context? })`. Your turn ends
+   immediately; the human's reply arrives as your next prompt.
+
+{% if attempt -%}
+This is continuation/retry attempt {{ attempt }}. Inspect the workspace before
+making new edits; your previous run may have left state behind.
+{%- endif %}