stargate-cli 1.0.0__py3-none-any.whl

stargate/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

stargate/agent.py

@@ -0,0 +1,194 @@
+"""Running one agent for one role: retries, the token budget it spends, and
+the fingerprint that tells a repeated failure from a new one."""
+from __future__ import annotations
+
+import re
+import shlex
+import time
+from pathlib import Path
+
+from .config import (
+    agent_command,
+    agent_entry,
+    agent_env,
+    expand_test_command,
+    parse_usage,
+    retry_settings,
+    token_cap,
+)
+from .core import (
+    RunContext,
+    StargateError,
+    print_output,
+    run_process,
+    termination_requested,
+    wait_for_termination,
+)
+
+FINGERPRINT_LINES = 20
+
+
+def _role_label(ctx: RunContext, role: str) -> str:
+    if ctx.mode == "fanout-task":
+        return f"task {ctx.slug}/{role}"
+    return role
+
+
+def record_usage(ctx: RunContext, role: str, transcript: str) -> None:
+    """Charge one completed attempt, including one the vendor rejected late."""
+    used = parse_usage(
+        transcript, agent_entry(ctx.config, role).get("usage_pattern")
+    )
+    ctx.tokens_used += used
+    if used:
+        cap = token_cap(ctx.config)
+        budget = f" of {cap:,}" if cap else ""
+        print_output(
+            f"\n[{_role_label(ctx, role)}] reported {used:,} tokens; "
+            f"{ctx.tokens_used:,}{budget} used so far."
+        )
+
+
+def attempt_log_path(output_path: Path, attempt: int) -> Path:
+    # Attempt one keeps the historical path, so retries-off runs retain the
+    # same artifacts while later failures cannot overwrite its evidence.
+    suffix = "" if attempt == 1 else f".attempt-{attempt}"
+    return output_path.with_name(output_path.name + suffix + ".log")
+
+
+def failure_fingerprint(error: StargateError, trace: str) -> tuple[str, str]:
+    """Normalize per-attempt noise without interpreting vendor error text."""
+    # The prefix is ours and distinguishes timeout from a non-zero exit. The
+    # rest includes attempt-specific trace paths and the full command, neither
+    # of which says whether another attempt has a chance of succeeding.
+    reason = str(error).split(" (", 1)[0]
+    tail = "\n".join(trace.strip().splitlines()[-FINGERPRINT_LINES:])
+    return re.sub(r"\d+", "#", reason), re.sub(r"\d+", "#", tail)
+
+
+def invoke_agent(
+    ctx: RunContext,
+    role: str,
+    prompt: str,
+    cwd: Path,
+    output_path: Path,
+) -> str:
+    """Run one agent and return its FINAL MESSAGE, not its stdout.
+
+    The distinction matters: `codex exec` streams the whole session — reasoning,
+    every command it ran, a token footer — to stdout. Forwarding that as {plan}
+    or {review} makes each hop pay for the previous hop's trace. An agent whose
+    command contains "{output}" is handed a file path to write its last message
+    to, and that file is what gets forwarded; its stdout is kept as a .log.
+
+    Retries stay inside this single invocation so no completed role is replayed.
+    Each attempt has its own trace, both for debugging and to count any usage
+    the failed process reported exactly once.
+    """
+    cmd = agent_command(ctx.config, role)
+    writes_final = any("{output}" in part for part in cmd)
+    # Expand {output} first so those literal characters inside a configured
+    # test command cannot unexpectedly become a path.
+    cmd = [part.replace("{output}", str(output_path)) for part in cmd]
+    cmd = expand_test_command(cmd, ctx.test_command)
+    timeout = float(ctx.config.get("settings", {}).get("agent_timeout_seconds", 1800))
+    env = agent_env(agent_entry(ctx.config, role))
+    retries, backoff = retry_settings(ctx.config)
+    attempts = retries + 1
+    previous_failure: tuple[str, str] | None = None
+    process_label = (
+        _role_label(ctx, role) if ctx.mode == "fanout-task" else None
+    )
+    role_label = _role_label(ctx, role)
+
+    for attempt in range(1, attempts + 1):
+        if termination_requested():
+            raise StargateError("Orchestrator is terminating.")
+        log_path = attempt_log_path(output_path, attempt)
+        # Starting this attempt would replace the same path anyway. Removing
+        # it first prevents a termination race before Popen from charging an
+        # earlier invocation's transcript as this attempt's usage.
+        log_path.unlink(missing_ok=True)
+        trace_prefix = f"[{process_label}] " if process_label else ""
+        print_output(
+            f"{trace_prefix}trace: tail -f {shlex.quote(str(log_path))}"
+        )
+
+        # A retry or explicitly redone stage must not inherit an earlier
+        # answer and pass the output contract after writing nothing.
+        if writes_final and output_path.exists():
+            output_path.unlink()
+
+        started = time.monotonic()
+        try:
+            proc = run_process(
+                [*cmd, prompt], cwd, timeout=timeout or None, log_path=log_path,
+                env=env, output_label=process_label,
+            )
+        except OSError as exc:
+            # A process that cannot be started will fail the same way after a
+            # backoff; unlike an agent exit, it never made a remote request.
+            raise StargateError(
+                f"Could not start the agent for role '{role}': {exc}"
+            ) from exc
+        except KeyboardInterrupt:
+            trace = log_path.read_text() if log_path.exists() else ""
+            record_usage(ctx, role, trace)
+            raise
+        except StargateError as exc:
+            trace = log_path.read_text() if log_path.exists() else ""
+            if termination_requested():
+                record_usage(ctx, role, trace)
+                raise
+            if retries:
+                record_usage(ctx, role, trace)
+                print_output(
+                    f"\n[{role_label}] attempt {attempt} of {attempts} "
+                    f"failed: {exc}"
+                )
+            else:
+                # Keeping retries disabled must preserve the original failure
+                # path, including terminal output and token accounting.
+                raise
+
+            if attempt == attempts:
+                raise
+
+            fingerprint = failure_fingerprint(exc, trace)
+            if fingerprint == previous_failure:
+                remaining = attempts - attempt
+                print_output(
+                    f"[{role_label}] failed identically twice; not retrying "
+                    f"{remaining} more time(s)."
+                )
+                raise
+            previous_failure = fingerprint
+
+            wait = backoff * 2 ** (attempt - 1)
+            print_output(
+                f"[{role_label}] retrying in {wait:g}s "
+                f"(attempt {attempt + 1} of {attempts})."
+            )
+            if wait_for_termination(wait):
+                raise StargateError("Orchestrator is terminating.") from None
+            continue
+
+        transcript = proc.stdout or ""
+        print_output(
+            f"\n[{role_label}] exit {proc.returncode} in "
+            f"{time.monotonic() - started:.0f}s"
+        )
+        record_usage(ctx, role, transcript)
+        break
+
+    if not writes_final:
+        output_path.write_text(transcript)
+        return transcript
+
+    final = output_path.read_text() if output_path.exists() else ""
+    if not final.strip():
+        raise StargateError(
+            f"Agent for role '{role}' declares {{output}} but wrote nothing to "
+            f"{output_path}. Check that its CLI supports the flag you passed."
+        )
+    return final

stargate/agents.yaml

@@ -0,0 +1,148 @@
+version: 5
+
+# claude -p --output-format text already prints only the final message, so the
+# Claude roles need no {output} placeholder.
+#
+# NOT --permission-mode plan: under it Claude Code saves the plan to a file in
+# ~/.claude/plans and prints only a summary, so the orchestrator would forward
+# a fraction of the plan without noticing. --disallowedTools keeps the same
+# read-only guarantee (the architect runs in the real repo, not the worktree)
+# while leaving the answer on stdout.
+#
+# --disallowedTools takes <tools...>, so it would swallow the prompt stargate
+# appends last. Ending these commands with --model is what stops it; keep a
+# non-variadic option last in any Claude command you write here.
+agents:
+  architect:
+    command:
+      - claude
+      - -p
+      - --output-format
+      - text
+      - --disallowedTools
+      - Edit Write NotebookEdit
+      - --model
+      - opus
+    # A prose reply proves only that credentials work. This exercises reading,
+    # which the role is allowed to do despite its editing tools being disabled.
+    probe: "Read the file {probe_file} and reply with its contents, nothing else."
+    probe_expect: read
+    # Per-agent environment, merged over the orchestrator's own. A null value
+    # REMOVES the variable: an ANTHROPIC_API_KEY exported globally shadows the
+    # CLI's claude.ai login, and this is how one agent opts out of it without
+    # unsetting it for everything else. Values are never printed by doctor.
+    # env:
+    #   ANTHROPIC_API_KEY: null
+
+  # "{output}" is replaced with a file path; whatever the agent writes there is
+  # what gets forwarded to the next role. Without it, codex exec's entire
+  # session trace would become the next prompt.
+  developer:
+    command:
+      - codex
+      - exec
+      - --sandbox
+      - workspace-write
+      - --output-last-message
+      - "{output}"
+    # The implementer's real job depends on editing, so the billable probe
+    # creates a file in stargate's throwaway repository, never in yours.
+    probe: "Create the file {probe_file} containing exactly OK, then reply OK."
+    probe_expect: write
+    # codex exec ends its stdout with "tokens used\n7,967".
+    usage_pattern: 'tokens used\s+([\d,]+)'
+
+  reviewer:
+    command:
+      - claude
+      - -p
+      - --output-format
+      - text
+      - --disallowedTools
+      - Edit Write NotebookEdit
+      # Print mode otherwise denies arbitrary execution, leaving the reviewer
+      # able only to trust the pasted test report. This grant follows the exact
+      # command stargate runs and is dropped when none was approved. It is not
+      # on the architect because that role runs in the real repository.
+      - --allowedTools
+      - Bash({test_command})
+      - --model
+      - opus
+    probe: "Read the file {probe_file} and reply with its contents, nothing else."
+    probe_expect: read
+
+  fixer:
+    command:
+      - codex
+      - exec
+      - --sandbox
+      - workspace-write
+      - --output-last-message
+      - "{output}"
+    probe: "Create the file {probe_file} containing exactly OK, then reply OK."
+    probe_expect: write
+    # codex exec ends its stdout with "tokens used\n7,967".
+    usage_pattern: 'tokens used\s+([\d,]+)'
+
+workflow:
+  architect: architect
+  developer: developer
+  reviewer: reviewer
+  fixer: fixer
+
+settings:
+  max_review_loops: 2
+
+  # Fan-out is opt-in with `stargate run --fan-out`. The architect may create
+  # at most this many DAG nodes, and no more than this many ready nodes run at
+  # once. Parallel agents may overshoot max_task_tokens together before the
+  # scheduler gets control back.
+  max_fanout_tasks: 8
+  max_parallel_tasks: 2
+
+  # Empty means: don't run a test command automatically or grant it to an
+  # agent command that declares {test_command}.
+  # Examples:
+  # test_command: "pytest -q"
+  # test_command: "swift test"
+  # test_command: "npm test"
+  test_command: ""
+
+  # When test_command is empty, inspect the repository in this order: a Make
+  # test target, package.json script, Cargo, Go, Swift, then explicit pytest
+  # signals. All matches are shown. "report" is deliberately safest because a
+  # detected command is one the user never approved; "auto" runs the first
+  # match after every developer/fixer pass, and "off" skips detection.
+  test_command_detection: report
+
+  # Worktrees live outside the repository by default:
+  # <repo-parent>/.stargate-worktrees/<repo-name>/<run-id>
+  worktree_root: ""
+
+  # Directory of custom <role>.md prompts. Overrides are per-file: drop a
+  # single reviewer.md here and the other four still use the defaults.
+  # Lookup order: this, then ~/.config/stargate/prompts/, then the packaged
+  # prompts. A relative path resolves against the repo you run in.
+  # See `stargate init-prompts` and `stargate doctor`.
+  prompts_dir: ""
+
+  # Stop the run once the agents have reported this many tokens in total.
+  # 0 or unset = no limit. Only counts what an agent's usage_pattern extracts,
+  # and is only checked BETWEEN phases -- a single runaway invocation still
+  # overshoots. For a real in-flight cap, put a vendor flag in the command:
+  # claude has --max-budget-usd, codex has no equivalent today.
+  max_task_tokens: 0
+
+  # A probe is meant to be a quick liveness check, so it does not inherit the
+  # much longer agent timeout.
+  probe_timeout_seconds: 120
+
+  # Hard limits so a stuck agent or test suite cannot hang the run forever.
+  agent_timeout_seconds: 1800
+  test_timeout_seconds: 900
+
+  # Retries apply to non-zero agent exits and timeouts. Each wait doubles, and
+  # every attempt keeps its own trace and contributes any reported token usage.
+  # 0 retries preserves the historical single-attempt behavior.
+  agent_retries: 0
+  agent_retry_backoff_seconds: 10

stargate/cli.py

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import signal
+import sys
+from pathlib import Path
+from typing import Any
+
+from .config import (
+    PROJECT_CONFIG,
+    commit_enabled,
+    init_config,
+    init_prompts,
+    load_config,
+    resolve_config,
+    validate_publication_request,
+)
+from .core import StargateError, Terminated, repo_root, terminate_active_processes
+from .doctor import doctor
+from .run import REDOABLE_STAGES, clean_runs, list_runs
+from .source import fetch_task
+from .stages import orchestrate
+
+
+def _positive_int(value: str) -> int:
+    try:
+        parsed = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("must be a positive integer") from exc
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return parsed
+
+
+def _validate_run_arguments(parser: argparse.ArgumentParser, args: argparse.Namespace) -> None:
+    """Reject run-only flag combinations before reserving any run artifacts."""
+    if args.from_url is not None and args.task is not None:
+        parser.error("--from cannot be combined with a task argument")
+    if args.from_url is None and not args.task:
+        parser.error("a task description or --from URL is required")
+    if args.fan_out and args.no_commit:
+        parser.error("--no-commit cannot be combined with --fan-out")
+    if args.pr and args.no_commit:
+        parser.error("--pr cannot be combined with --no-commit")
+    if not args.fan_out and args.max_parallel_tasks is not None:
+        parser.error("--max-parallel-tasks requires --fan-out")
+
+
+def _saved_run_mode(repo: Path, run_id: str) -> str | None:
+    """Read enough state for flag validation; the run loader owns bad-state errors."""
+    state_path = repo / ".stargate" / "runs" / run_id / "state.json"
+    try:
+        state = json.loads(state_path.read_text())
+    except (OSError, ValueError):
+        return None
+    if not isinstance(state, dict):
+        return None
+    mode = state["mode"] if "mode" in state else "linear"
+    return mode if mode in ("linear", "fanout") else None
+
+
+def _validate_resume_arguments(
+    parser: argparse.ArgumentParser,
+    args: argparse.Namespace,
+    repo: Path,
+) -> None:
+    """Reject mode-specific resume flags when saved state identifies the mode."""
+    if args.pr and args.no_commit:
+        parser.error("--pr cannot be combined with --no-commit")
+    mode = _saved_run_mode(repo, args.run_id)
+    if mode == "fanout":
+        if args.redo:
+            parser.error("--redo is not supported for fan-out runs")
+        if args.no_commit:
+            parser.error("--no-commit is not supported for fan-out runs")
+    elif mode == "linear" and args.max_parallel_tasks is not None:
+        parser.error("--max-parallel-tasks is only supported for fan-out runs")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="stargate",
+        description="Tiny vendor-agnostic multi-agent orchestrator.",
+    )
+    parser.add_argument(
+        "--config",
+        default=None,
+        help=f"Complete standalone config. Without it, ./{PROJECT_CONFIG}, "
+        "the user config and packaged defaults are layered.",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    doctor_parser = sub.add_parser(
+        "doctor", help="Check local CLI dependencies and configuration."
+    )
+    doctor_parser.add_argument(
+        "--probe", action="store_true",
+        help="Make one real, potentially billable call to each unique agent.",
+    )
+    sub.add_parser(
+        "init-config",
+        help="Copy the packaged agents.yaml to ~/.config/stargate/agents.yaml.",
+    )
+    sub.add_parser(
+        "init-prompts",
+        help="Copy the packaged prompts to ~/.config/stargate/prompts/ so they "
+        "can be edited without touching the install.",
+    )
+    sub.add_parser(
+        "list", aliases=["runs"],
+        help="List the runs recorded in this repository, newest first."
+    )
+    clean = sub.add_parser(
+        "clean", help="Remove a run's merged branches, clean worktrees and artifacts."
+    )
+    clean.add_argument("run_id", nargs="?", help="Run ID shown by 'stargate list'.")
+    clean.add_argument(
+        "--all", action="store_true", dest="all_runs",
+        help="Clean every recorded run that passes the safety checks, skipping the rest.",
+    )
+
+    run = sub.add_parser("run", help="Plan, implement, review and fix a task.")
+    run.add_argument("task", nargs="?", help="Feature/bug/task description.")
+    run.add_argument(
+        "--from", dest="from_url", metavar="URL",
+        help="Read the task from the configured source for this URL's host. "
+        "Cannot be combined with a task argument; rejected before a run is created.",
+    )
+    run.add_argument(
+        "--fan-out",
+        action="store_true",
+        help="Split the task into a DAG and run ready tasks concurrently. "
+        "Requires settings.commit: true and cannot be combined with --no-commit.",
+    )
+    run.add_argument(
+        "--base-ref",
+        default=None,
+        help="Git ref to branch from. Defaults to the current branch/ref.",
+    )
+    run.add_argument(
+        "--name",
+        default=None,
+        help="Short name for the branch and run id, e.g. --name 'passkey auth'. "
+        "Overrides the name the architect suggests.",
+    )
+
+    resume = sub.add_parser(
+        "resume",
+        help="Continue a run that failed partway, reusing its plan, worktree, "
+        "config and prompts.",
+        description="Continue a run that failed partway, reusing its saved state. "
+        "Fan-out mode is restored automatically; resume has no --fan-out switch.",
+    )
+    resume.add_argument("run_id", help="Run ID, as printed by the original run.")
+    resume.add_argument(
+        "--redo", action="append", default=[], choices=REDOABLE_STAGES,
+        metavar="STAGE",
+        help="Run this completed stage again instead of skipping it "
+        f"({', '.join(REDOABLE_STAGES)}). Repeatable. Linear runs only; "
+        "fan-out resumes reject this option.",
+    )
+
+    run.add_argument(
+        "--no-commit",
+        action="store_true",
+        help="Leave a linear run's work uncommitted in its worktree. Cannot be "
+        "combined with --fan-out; that error is reported before a run is created.",
+    )
+    resume.add_argument(
+        "--no-commit",
+        action="store_true",
+        help="Leave a resumed linear run's work uncommitted in its worktree. "
+        "Fan-out resumes reject this option.",
+    )
+
+    for parser_ in (run, resume):
+        parser_.add_argument(
+            "--pr", action="store_true",
+            help="After an APPROVED result, push the run's branch and open a pull "
+            "request with pull_request.command. Never implied by configuration; "
+            "resume requires it again. Resuming a finished run re-runs review at "
+            "token cost and may replace the recorded verdict.",
+        )
+        parser_.add_argument(
+            "--max-review-loops",
+            type=int,
+            default=None,
+            help="Override settings.max_review_loops.",
+        )
+        parser_.add_argument(
+            "--max-parallel-tasks",
+            type=_positive_int,
+            default=None,
+            help=(
+                "Override settings.max_parallel_tasks. Requires --fan-out; linear "
+                "runs reject this option."
+                if parser_ is run
+                else "Override settings.max_parallel_tasks when resuming a fan-out "
+                "run; linear resumes reject this option."
+            ),
+        )
+    return parser
+
+
+def install_signal_handlers() -> None:
+    """Turn catchable termination into the existing resumable failure path."""
+    handled = [
+        signum for name in ("SIGINT", "SIGTERM", "SIGHUP")
+        if (signum := getattr(signal, name, None)) is not None
+    ]
+
+    def terminate(signum: int, _frame: Any) -> None:
+        # One shot lets a second signal terminate even if cleanup gets stuck.
+        for handled_signum in handled:
+            signal.signal(handled_signum, signal.SIG_DFL)
+        terminate_active_processes()
+        raise Terminated(signum)
+
+    for signum in handled:
+        signal.signal(signum, terminate)
+
+
+def main() -> int:
+    script_dir = Path(__file__).resolve().parent
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.command == "run":
+        _validate_run_arguments(parser, args)
+
+    if args.command == "init-config":
+        return init_config(script_dir)
+    if args.command == "init-prompts":
+        return init_prompts(script_dir)
+
+    try:
+        if args.command in ("run", "resume"):
+            # The shared handler also kills agents owned by fan-out workers.
+            install_signal_handlers()
+
+        if args.command == "resume":
+            _validate_resume_arguments(parser, args, repo_root(Path.cwd()))
+
+        if args.command in ("list", "runs"):
+            return list_runs(repo_root(Path.cwd()))
+        if args.command == "clean":
+            return clean_runs(repo_root(Path.cwd()), args.run_id, args.all_runs)
+
+        config_paths = resolve_config(args.config, script_dir)
+        config, layers = load_config(config_paths)
+        if args.command == "doctor":
+            return doctor(
+                config,
+                layers,
+                script_dir,
+                probe=args.probe,
+                explicit_config=args.config is not None,
+            )
+        if args.command in ("run", "resume"):
+            if (
+                args.command == "run"
+                and args.fan_out
+                and not commit_enabled(config)
+            ):
+                raise StargateError(
+                    "Fan-out requires settings.commit: true; no run was created."
+                )
+            if args.command == "run":
+                validate_publication_request(config, requested=args.pr)
+                if args.from_url is not None:
+                    args.task = fetch_task(config, args.from_url, Path.cwd())
+                    print(f"Task read from {args.from_url} ({len(args.task.splitlines())} lines)")
+            return orchestrate(args, script_dir, config)
+        parser.error("Unknown command")
+        return 2
+    except StargateError as exc:
+        print(f"\nERROR: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt as exc:
+        signum = getattr(exc, "signum", signal.SIGINT)
+        message = "Interrupted" if signum == signal.SIGINT else "Terminated"
+        print(f"\n{message}.", file=sys.stderr)
+        return 128 + int(signum)