roundtable-cli 0.4.0__py3-none-any.whl

roundtable/models.py

@@ -0,0 +1,202 @@
+"""Plan data model: Plan -> Phase -> Task.
+
+The plan manifest (``plan.json``) is the source of truth for status, model
+assignments, and task dependencies. These pydantic models (de)serialize it and
+enforce structural invariants (unique ids, intra-phase deps, no cycles).
+"""
+
+from __future__ import annotations
+
+import re
+from enum import Enum
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+from .errors import RoundtableError
+
+
+class Status(str, Enum):
+    pending = "pending"
+    in_progress = "in_progress"
+    waiting = "waiting"
+    done = "done"
+    failed = "failed"
+    skipped = "skipped"
+
+
+class AgentRef(BaseModel):
+    """How to run a role: which configured CLI agent, and which model it uses.
+
+    ``agent`` names an entry in the config ``agents`` map (for ``provider: cli``);
+    ``model`` is the model token passed to that agent's ``{model}`` placeholder
+    (e.g. ``opus-4.8``, ``gemini-3.5-flash``). For ``provider: litellm`` there is
+    no separate command, so ``model`` (falling back to ``agent``) is the litellm
+    model string.
+
+    Accepts either an object ``{agent, model}`` or a shorthand string on input:
+    ``"opencode:mimo-v2.5-pro"`` -> ``agent=opencode, model=mimo-v2.5-pro``, and a
+    bare ``"claude"`` -> ``agent=claude`` (no model). Always serializes as an
+    object so the manifest is explicit.
+    """
+
+    model_config = ConfigDict(protected_namespaces=())
+
+    agent: str = ""
+    model: str = ""
+
+    @model_validator(mode="before")
+    @classmethod
+    def _coerce(cls, v: object) -> object:
+        if isinstance(v, str):
+            s = v.strip()
+            if ":" in s:
+                a, m = s.split(":", 1)
+                return {"agent": a.strip(), "model": m.strip()}
+            return {"agent": s}
+        return v
+
+    def __bool__(self) -> bool:
+        return bool(self.agent or self.model)
+
+    def __str__(self) -> str:
+        return f"{self.agent}:{self.model}" if self.model else self.agent
+
+
+_SLUG_RE = re.compile(r"[^a-z0-9]+")
+
+
+def slugify(text: str, max_len: int = 40) -> str:
+    """Lowercase, hyphenated, filesystem-safe slug."""
+    s = _SLUG_RE.sub("-", text.strip().lower()).strip("-")
+    if len(s) > max_len:
+        s = s[:max_len].rstrip("-")
+    return s or "item"
+
+
+class Task(BaseModel):
+    id: str
+    title: str
+    slug: str = ""
+    description: str = ""
+    runner: AgentRef = Field(default_factory=AgentRef)  # choosable (agent, model) for this task; backfilled if empty
+    depends_on: list[str] = Field(default_factory=list)
+    status: Status = Status.pending
+    result_path: str | None = None
+    validate_command: list[str] | None = None  # run after execution; non-zero exit = failure
+    requires_approval: bool = False  # pause and wait for `roundtable resume` before executing
+
+    @model_validator(mode="after")
+    def _default_slug(self) -> Task:
+        if not self.slug:
+            self.slug = slugify(self.title)
+        return self
+
+
+class Phase(BaseModel):
+    id: str
+    index: int = 0
+    title: str
+    slug: str = ""
+    objective: str = ""
+    runner: AgentRef = Field(default_factory=AgentRef)  # choosable (agent, model) for this phase orchestrator
+    tasks: list[Task] = Field(default_factory=list)
+    status: Status = Status.pending
+    summary_path: str | None = None
+    validate_command: list[str] | None = None  # runs after all tasks succeed; non-zero exit fails the phase
+
+    @model_validator(mode="after")
+    def _default_slug(self) -> Phase:
+        if not self.slug:
+            self.slug = slugify(self.title)
+        return self
+
+    @property
+    def dir_name(self) -> str:
+        return f"phase-{self.index:02d}-{self.slug}"
+
+    def task_dir_name(self, task: Task, task_index: int) -> str:
+        return f"task-{task_index:02d}-{task.slug}"
+
+    def topological_order(self, external_ids: set[str] | None = None) -> list[Task]:
+        """Tasks ordered so intra-phase dependencies precede dependents.
+
+        ``external_ids`` are task ids defined in *other* phases that this phase's
+        tasks may depend on (cross-phase deps). They are treated as already
+        satisfied and don't participate in intra-phase ordering. Raises
+        RoundtableError on unknown dep ids or intra-phase cycles.
+        """
+        external_ids = external_ids or set()
+        by_id = {t.id: t for t in self.tasks}
+        for t in self.tasks:
+            for dep in t.depends_on:
+                if dep not in by_id and dep not in external_ids:
+                    raise RoundtableError(
+                        f"task {t.id!r} depends on unknown task {dep!r} in phase {self.id!r}"
+                    )
+        ordered: list[Task] = []
+        seen: set[str] = set()
+        visiting: set[str] = set()
+
+        def visit(t: Task) -> None:
+            if t.id in seen:
+                return
+            if t.id in visiting:
+                raise RoundtableError(f"dependency cycle detected at task {t.id!r}")
+            visiting.add(t.id)
+            for dep in t.depends_on:
+                if dep in by_id:  # only intra-phase deps affect ordering
+                    visit(by_id[dep])
+            visiting.discard(t.id)
+            seen.add(t.id)
+            ordered.append(t)
+
+        for t in self.tasks:
+            visit(t)
+        return ordered
+
+
+class Plan(BaseModel):
+    goal: str
+    created_at: str = ""
+    main_runner: AgentRef = Field(default_factory=AgentRef)  # choosable (agent, model) for the main orchestrator
+    runners: dict[str, AgentRef] = Field(default_factory=dict)  # role defaults snapshot
+    phases: list[Phase] = Field(default_factory=list)
+    status: Status = Status.pending
+    approved: bool = False
+
+    @model_validator(mode="after")
+    def _check_unique_ids(self) -> Plan:
+        pids = [p.id for p in self.phases]
+        if len(pids) != len(set(pids)):
+            raise RoundtableError("duplicate phase ids in plan")
+        # Task ids are unique across the WHOLE plan — cross-phase deps reference
+        # tasks by id, so ids must be globally resolvable. Phase list order is the
+        # execution order; a dep may only reference the same or an earlier phase.
+        all_ids: set[str] = set()
+        task_phase_pos: dict[str, int] = {}
+        for i, p in enumerate(self.phases):
+            for t in p.tasks:
+                if t.id in all_ids:
+                    raise RoundtableError(f"duplicate task id {t.id!r} in plan")
+                all_ids.add(t.id)
+                task_phase_pos[t.id] = i
+        for i, p in enumerate(self.phases):
+            # Intra-phase cycle check; cross-phase ids are allowed as externals.
+            p.topological_order(external_ids=all_ids)
+            for t in p.tasks:
+                for dep in t.depends_on:
+                    if dep not in all_ids:
+                        raise RoundtableError(f"task {t.id!r} depends on unknown task {dep!r}")
+                    if task_phase_pos[dep] > i:
+                        raise RoundtableError(
+                            f"task {t.id!r} depends on {dep!r} in a later phase; "
+                            "cross-phase dependencies must reference an earlier phase"
+                        )
+        return self
+
+    def task_by_id(self, task_id: str) -> tuple[Phase, Task] | None:
+        for p in self.phases:
+            for t in p.tasks:
+                if t.id == task_id:
+                    return p, t
+        return None

roundtable/prompts.py

@@ -0,0 +1,205 @@
+"""System prompts for each agent role.
+
+Kept terse and explicit. The planner prompt pins the exact JSON contract the
+``Plan`` model expects; the rest produce Markdown.
+"""
+
+from __future__ import annotations
+
+PLANNER_SYSTEM = """\
+You are the PLANNER. Turn the user's goal into a complete, executable plan.
+
+Break the work into ordered PHASES, each a meaningful milestone. A phase holds
+one or more TASKS. Tasks may depend on earlier tasks in the SAME phase, or on
+tasks in an EARLIER phase (reference them by id) — never on a later phase.
+
+Right-size tasks. One task = one coherent unit of work a single agent finishes
+end to end, including the edits it implies. Do NOT split one logical change
+across tasks — "add the flag", then "implement it", then "test it" for one small
+feature is ONE task, not three. Prefer the fewest tasks that cleanly cover the
+goal; more tasks means more cost and coordination, not more quality.
+
+Output ONLY a single JSON object (no prose, no code fences) with this shape:
+{
+  "goal": "<one-line restatement>",
+  "phases": [
+    {
+      "id": "p1",
+      "title": "<short phase title>",
+      "objective": "<what this phase achieves>",
+      "runner": {"agent": "<cli>", "model": "<model>"},
+      "tasks": [
+        {
+          "id": "p1-t1",
+          "title": "<short task title>",
+          "description": "<concrete, actionable definition of the work>",
+          "runner": {"agent": "<cli>", "model": "<model>"},
+          "depends_on": ["p1-..."],
+          "validate_command": ["<cmd>", "<arg>"]
+        }
+      ]
+    }
+  ]
+}
+
+Rules:
+- ids: phases p1,p2,...; tasks <phase>-t1,<phase>-t2,... (task ids unique plan-wide).
+- depends_on may reference task ids in the SAME phase or any EARLIER phase
+  (never a later phase); no cycles.
+- Each "runner" picks the CLI + model that runs that phase/task. Choose ONLY
+  from the ALLOWED (agent:model) pairs provided: split each "agent:model" into
+  {"agent": ..., "model": ...}. When unsure use the given role defaults.
+- VERIFY WITH validate_command, NOT with a task. "validate_command" (optional,
+  on a task or a phase) is an argv list run in the project root; a non-zero exit
+  fails that task/phase. Use it to check work — tests, build, typecheck, lint.
+  NEVER create a task whose job is to "run the tests"/"run pytest"/"verify":
+  that is what validate_command is for. A phase-level validate_command is the
+  phase completion gate (e.g. the full test suite after its tasks finish).
+- Don't over-phase. For a small change, ONE phase whose implementation task
+  carries a test validate_command is enough — do not split "implement" and
+  "test" into separate phases.
+- Keep phases in execution order. Be specific and concrete; right-size — do not
+  over-split.
+"""
+
+PHASE_DEFINE_SYSTEM = """\
+You are a PHASE ORCHESTRATOR preparing one task for a sub-agent. Write a precise
+work definition the agent can execute without further questions.
+
+Output Markdown with sections:
+- **Objective**: What the task must achieve.
+- **Steps**: Numbered, concrete steps.
+- **Inputs/Context**: What the agent should read or reference.
+- **Expected Output Artifacts**: Specific files, sections, or deliverables the
+  agent must produce (not just "do the work" — name the artifact).
+- **Acceptance Criteria**: How to verify the work is correct.
+
+Be concrete. Do not do the work yourself; define it.
+{project_context}"""
+
+TASK_EXEC_SYSTEM = """\
+You are a TASK AGENT executing a work definition inside a project.
+
+Your working directory is the project root. You have access to the project's
+files and can read/edit them directly. Use the tools available to you (file
+editing, terminal commands, etc.) to complete the work.
+
+Output Markdown with:
+1. A brief summary of what you did.
+2. The concrete work product (code written/modified, content, analysis, etc.).
+3. Any assumptions made and remaining risks.
+
+If you cannot complete the work, explain clearly what went wrong and why.
+{project_context}"""
+
+PHASE_SUMMARY_SYSTEM = """\
+You are a PHASE ORCHESTRATOR. Summarize the completed phase for the MAIN
+ORCHESTRATOR. Be concise and decision-useful: what was accomplished, key
+outputs, decisions, and anything Main needs for documentation or later phases.
+Do NOT paste full task transcripts; synthesize.
+"""
+
+MAIN_KICKOFF_SYSTEM = """\
+You are the MAIN ORCHESTRATOR. Write a short project overview document to seed
+the docs: the goal, the phase roadmap, and how progress will be tracked.
+Output Markdown.
+"""
+
+MAIN_INTEGRATE_SYSTEM = """\
+You are the MAIN ORCHESTRATOR maintaining the project documentation. Given a
+completed phase summary, write a concise progress entry capturing what changed
+and any decisions worth recording. Output a short Markdown entry only.
+"""
+
+MAIN_FINALIZE_SYSTEM = """\
+You are the MAIN ORCHESTRATOR. All phases are complete. Write a final report:
+goal, what was delivered per phase, notable decisions, and follow-ups.
+Output Markdown.
+"""
+
+MAP_ARCH_SYSTEM = """\
+You are a STAFF ENGINEER mapping an unfamiliar codebase. From the provided
+codebase digest (a pruned file tree plus key file contents), write a clear
+architecture overview that makes the project understandable fast.
+
+Output Markdown with sections: Purpose, Tech stack, Module / component map (a
+table of path -> responsibility), Data / control flow, Entry points & how to run,
+Notable conventions, Risks / unknowns. Cite real file paths from the digest. Be
+concrete; do NOT invent files or behavior. Mark anything you are unsure of as an
+explicit assumption rather than stating it as fact.
+"""
+
+MAP_PRD_SYSTEM = """\
+You are a PRODUCT ENGINEER reverse-engineering a PRD (product requirements
+document) from an existing codebase digest and its architecture overview. Infer
+what the product does and why it exists FROM THE CODE — do not invent a roadmap.
+
+Output Markdown with sections: Summary, Problem / Goals, Users, Current Features &
+Capabilities (each derived from concrete code, with file paths), Non-functional
+constraints, Out of scope / not yet built, and Open questions & assumptions.
+
+This PRD is REVERSE-ENGINEERED and may be wrong: clearly flag every inference in
+the "Open questions & assumptions" section. State up top that a human must review
+and edit this document before it is used to drive planning.
+"""
+
+PHASE_REPLAN_SYSTEM = """\
+You are a PHASE ORCHESTRATOR. A task in your phase has failed. Adapt the
+remaining tasks so the phase can still achieve its objective.
+
+Review the failed task and its output, then return a JSON object mapping task IDs
+(from the remaining tasks list) to updated descriptions. Only include tasks that
+genuinely need adjustment given the failure. Return an empty object if no changes
+are needed.
+
+Output ONLY a single JSON object (no prose, no code fences):
+{"<task_id>": "<updated description>", ...}
+"""
+
+PLAN_IMPORT_SYSTEM = """\
+You are importing an EXISTING plan or requirements/PRD document. Convert it into
+the roundtable plan JSON WITHOUT inventing or dropping scope: preserve the author's
+phases, tasks, and steps as faithfully as possible; only structure them and fill
+in ids, dependencies, and model assignments.
+
+Output ONLY a single JSON object (no prose, no code fences) with this shape:
+{
+  "goal": "<one-line restatement>",
+  "phases": [
+    {
+      "id": "p1", "title": "...", "objective": "...",
+      "runner": {"agent": "<cli>", "model": "<model>"},
+      "tasks": [
+        {
+          "id": "p1-t1", "title": "...", "description": "...",
+          "runner": {"agent": "<cli>", "model": "<model>"},
+          "depends_on": ["p1-..."]
+        }
+      ]
+    }
+  ]
+}
+
+Rules: ids p1,p2,... and <phase>-t1,... (unique plan-wide); depends_on may
+reference the same or an earlier phase (never a later one); no cycles; each
+"runner" picks a CLI + model ONLY from the ALLOWED (agent:model)
+pairs (split "agent:model" into {"agent": ..., "model": ...}; default to the
+given role defaults). Keep the author's ordering.
+"""
+
+
+def render_prompt(template: str, *, project_context: str = "") -> str:
+    """Interpolate prompt template variables.
+
+    Currently supports ``{project_context}`` — inserted as a clearly labelled
+    block when non-empty, omitted entirely when empty.
+    """
+    ctx_block = ""
+    if project_context:
+        ctx_block = (
+            "\n\nPROJECT CONTEXT (provided by the user — use this to inform your work):\n"
+            + project_context.strip()
+            + "\n"
+        )
+    return template.replace("{project_context}", ctx_block)
+

roundtable/runctl.py

@@ -0,0 +1,212 @@
+"""Run control shared by the CLI, the MCP server, and the REST API.
+
+One place owns the ``run.pid`` protocol:
+
+* a live run writes its pid to ``.roundtable/runs/run.pid`` and clears it on exit;
+* starting a run (attached or detached) first checks for a live pid and refuses
+  to double-launch;
+* ``stop_run`` SIGTERMs the recorded pid's process group when possible.
+
+Detached launches (MCP / REST) spawn ``python -m roundtable.cli run`` in a new
+session so the run outlives the server that started it; its output is appended
+to ``.roundtable/runs/run.out`` for later inspection. Plan generation can likewise
+be launched detached (``start_plan``) since planning may take minutes.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+from pathlib import Path
+
+from .errors import RoundtableError
+from .store import Store
+
+
+def pid_alive(pid: int) -> bool:
+    """True if ``pid`` is a live process (or one we may not signal)."""
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True  # exists but owned by someone else — treat as alive
+
+
+def current_run_pid(store: Store) -> int | None:
+    """Pid of a live in-progress run, or None. Stale pid files are cleaned up.
+
+    The calling process itself never counts as "another run" — the run process
+    checks the pid file that its (MCP/REST) launcher may have already written.
+    """
+    pid = store.read_run_pid()
+    if pid is None or pid == os.getpid():
+        return None
+    if pid_alive(pid):
+        return pid
+    store.clear_run_pid()
+    return None
+
+
+def _detached(cmd: list[str], log_path: Path) -> subprocess.Popen:
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("a") as log:
+        return subprocess.Popen(
+            cmd,
+            stdout=log,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.DEVNULL,
+            start_new_session=True,  # detach: survive the launching server
+        )
+
+
+def start_run(store: Store, *, approve: bool = False) -> tuple[int | None, str]:
+    """Spawn a detached ``roundtable run``; returns ``(pid, message)``.
+
+    ``pid`` is None when the launch was refused (a run is already live).
+    """
+    existing = current_run_pid(store)
+    if existing is not None:
+        return None, (
+            f"run already in progress (pid={existing}); "
+            "stop it first or wait for it to finish"
+        )
+    cmd = [
+        sys.executable, "-m", "roundtable.cli", "run",
+        "--project", str(store.root), "--no-watch", "--no-dashboard",
+    ]
+    if approve:
+        cmd.append("--approve")
+    proc = _detached(cmd, store.runs_dir / "run.out")
+    store.write_run_pid(proc.pid)
+    return proc.pid, f"run started (pid={proc.pid})"
+
+
+def stop_run(store: Store) -> tuple[bool, str]:
+    """SIGTERM the recorded run pid/process group; returns ``(stopped, message)``."""
+    pid = store.read_run_pid()
+    if pid is None:
+        return False, "no run.pid found — no run appears to be in progress"
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        store.clear_run_pid()
+        return False, f"process {pid} is not running (stale pid file cleaned up)"
+    except PermissionError:
+        return False, f"cannot signal process {pid} (permission denied)"
+    target = f"process {pid}"
+    try:
+        pgid = os.getpgid(pid)
+        if pgid != os.getpgrp():
+            os.killpg(pgid, signal.SIGTERM)
+            target = f"process group {pgid}"
+        else:
+            os.kill(pid, signal.SIGTERM)
+    except ProcessLookupError:
+        store.clear_run_pid()
+        return False, f"process {pid} is not running (stale pid file cleaned up)"
+    except OSError as e:
+        return False, f"could not stop process {pid}: {e}"
+    return True, f"sent SIGTERM to {target}"
+
+
+def approve_hitl(store: Store, task_id: str) -> str:
+    """Approve a waiting HITL checkpoint so the paused run continues."""
+    checkpoint = store.hitl_path(task_id)
+    if not checkpoint.exists():
+        raise RoundtableError(
+            f"no pending approval checkpoint for task {task_id!r}; "
+            f"is the run paused and waiting at that task?"
+        )
+    try:
+        data = json.loads(checkpoint.read_text())
+    except (ValueError, OSError) as e:
+        raise RoundtableError(f"could not read checkpoint for task {task_id!r}: {e}") from e
+    if data.get("status") != "waiting":
+        raise RoundtableError(
+            f"task {task_id!r} checkpoint has status {data.get('status')!r}, expected 'waiting'"
+        )
+    data["status"] = "approved"
+    checkpoint.write_text(json.dumps(data))
+    return f"task {task_id!r} approved — run will continue"
+
+
+# --------------------------------------------------------------------------- #
+# Detached plan generation (planning can take minutes; the API must not block)
+# --------------------------------------------------------------------------- #
+def _plan_pid_path(store: Store) -> Path:
+    return store.runs_dir / "plan.pid"
+
+
+def _plan_log_path(store: Store) -> Path:
+    return store.runs_dir / "plan.log"
+
+
+def start_plan(
+    store: Store,
+    *,
+    goal: str | None = None,
+    prd: str | None = None,
+    plan_file: str | None = None,
+    model: str | None = None,
+) -> tuple[int | None, str]:
+    """Spawn a detached ``roundtable plan``; returns ``(pid, message)``."""
+    pid = plan_pid(store)
+    if pid is not None:
+        return None, f"plan generation already in progress (pid={pid})"
+    if not (goal or prd or plan_file):
+        raise RoundtableError("nothing to plan from: pass goal, prd, or plan_file")
+    cmd = [sys.executable, "-m", "roundtable.cli", "plan", "--project", str(store.root)]
+    if goal:
+        cmd += ["--goal", goal]
+    if prd:
+        cmd += ["--prd", prd]
+    if plan_file:
+        cmd += ["--plan", plan_file]
+    if model:
+        cmd += ["--model", model]
+    log = _plan_log_path(store)
+    try:
+        log.unlink()  # fresh log per generation
+    except OSError:
+        pass
+    proc = _detached(cmd, log)
+    store.runs_dir.mkdir(parents=True, exist_ok=True)
+    _plan_pid_path(store).write_text(str(proc.pid))
+    return proc.pid, f"plan generation started (pid={proc.pid})"
+
+
+def plan_pid(store: Store) -> int | None:
+    """Pid of a live detached plan generation, or None (stale files cleaned)."""
+    p = _plan_pid_path(store)
+    try:
+        pid = int(p.read_text().strip())
+    except (OSError, ValueError):
+        return None
+    if pid_alive(pid):
+        return pid
+    try:
+        p.unlink()
+    except OSError:
+        pass
+    return None
+
+
+def plan_status(store: Store) -> dict:
+    """Status of a detached plan generation: running flag, log tail, plan presence."""
+    log = _plan_log_path(store)
+    tail = ""
+    if log.exists():
+        try:
+            tail = log.read_text()[-2000:]
+        except OSError:
+            pass
+    return {
+        "running": plan_pid(store) is not None,
+        "has_plan": store.has_plan(),
+        "log_tail": tail,
+    }