regent-cli 0.4.0__tar.gz → 0.6.0__tar.gz

{regent_cli-0.4.0 → regent_cli-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: regent-cli
-Version: 0.4.0
+Version: 0.6.0
 Summary: Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project.
 Author-email: Flavio Alvim <flavioalvim@gmail.com>
 License: MIT
@@ -48,7 +48,17 @@ the JSON subcommands — `regent status` (control + lock + the executable contro
 matrix as `workspace.verdict`), `regent activity
 start|resume|suspend|conclude|heartbeat|takeover`, `regent stop request|check`. Hosts
 seeded by older versions upgrade automatically on `regent init` (known-version manifest;
-unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI.
+unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI. Conduction
+phase 1 mechanizes the two most error-prone sub-steps: `regent advisor consult
+--prompt-file … --artifact … --linkage …` (read-only sandboxed consultation with the
+REQ-003 §5 evidence pair generated by the command, fail-closed verdict expectation) and
+`regent gate run --command … --declared-in <plan> --artifact … --linkage …` (verbatim
+provenance check, process-group-killing timeout, integral output preserved). Conduction
+phase 2 adds `regent turn run`: one supervised, CONFINED `claude -p` turn — the agent may
+only write inside a declared envelope (a PreToolUse hook denies the rest), the supervisor
+proves what changed via git (blob shas vs authenticated post events) and commits through a
+private index with a HEAD compare-and-swap. The agent never commits; a violation, a
+tampered log or a red gate never yields a product commit.
 
 Development: `PYTHONPATH=src python3 -m unittest discover -s tests`; packaging gate:
 `bash scripts/gate-package.sh`. Canonical skill content lives in `src/regent/templates/`

{regent_cli-0.4.0 → regent_cli-0.6.0}/README.md

@@ -32,7 +32,17 @@ the JSON subcommands — `regent status` (control + lock + the executable contro
 matrix as `workspace.verdict`), `regent activity
 start|resume|suspend|conclude|heartbeat|takeover`, `regent stop request|check`. Hosts
 seeded by older versions upgrade automatically on `regent init` (known-version manifest;
-unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI.
+unknown local edits are preserved as conflicts). The advisor requires the `codex` CLI. Conduction
+phase 1 mechanizes the two most error-prone sub-steps: `regent advisor consult
+--prompt-file … --artifact … --linkage …` (read-only sandboxed consultation with the
+REQ-003 §5 evidence pair generated by the command, fail-closed verdict expectation) and
+`regent gate run --command … --declared-in <plan> --artifact … --linkage …` (verbatim
+provenance check, process-group-killing timeout, integral output preserved). Conduction
+phase 2 adds `regent turn run`: one supervised, CONFINED `claude -p` turn — the agent may
+only write inside a declared envelope (a PreToolUse hook denies the rest), the supervisor
+proves what changed via git (blob shas vs authenticated post events) and commits through a
+private index with a HEAD compare-and-swap. The agent never commits; a violation, a
+tampered log or a red gate never yields a product commit.
 
 Development: `PYTHONPATH=src python3 -m unittest discover -s tests`; packaging gate:
 `bash scripts/gate-package.sh`. Canonical skill content lives in `src/regent/templates/`

{regent_cli-0.4.0 → regent_cli-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "regent-cli"
-version = "0.4.0"
+version = "0.6.0"
 description = "Autonomous conduction and mediated adversarial deliberation between AI agents, pluggable into any project."
 readme = "README.md"
 requires-python = ">=3.10"

{regent_cli-0.4.0 → regent_cli-0.6.0}/src/regent/__init__.py

@@ -1,3 +1,3 @@
 """regent — autonomous conduction and mediated adversarial deliberation between AI agents."""
 
-__version__ = "0.4.0"
+__version__ = "0.6.0"

{regent_cli-0.4.0 → regent_cli-0.6.0}/src/regent/activity_cli.py

@@ -24,6 +24,10 @@ _EXIT_BY_CODE = {
     "NOT_SUSPENDED": 2, "ACTIVITY_OPEN": 2,
     "TOKEN_MISMATCH": 3, "LOCK_HELD": 3, "LOCK_SUSPECT": 3, "BUSY": 3,
     "CONFLICT": 3, "UNATTRIBUTABLE": 3, "CORRUPT_CONTROL": 4, "IO": 5,
+    "ADVISOR_FAILED": 3, "ADVISOR_UNAVAILABLE": 2, "GATE_RED": 3, "PROVENANCE": 3,
+    "TURN_VIOLATION": 3, "TURN_TAMPERED": 3, "TURN_FAILED": 3, "NOT_ACTIVE": 2,
+    "STEP_MISMATCH": 2, "ARTIFACT_OUTSIDE_REGENT": 2, "STEP_ALREADY_DONE": 2,
+    "WORKTREE_DIRTY": 3,
 }
 
 
@@ -91,6 +95,42 @@ def build_parser(sub) -> None:
     p.add_argument("--reason", default=None)
     stop_sub.add_parser("check")
 
+    p_advisor = sub.add_parser("advisor", help="mechanized advisor consultation")
+    p_advisor.add_argument("--project", default=None)
+    advisor_sub = p_advisor.add_subparsers(dest="advisor_command", required=True)
+    p = advisor_sub.add_parser("consult")
+    p.add_argument("--prompt-file", required=True, dest="prompt_file")
+    p.add_argument("--artifact", required=True)
+    p.add_argument("--linkage", required=True)
+    p.add_argument("--timeout", type=float, default=600.0)
+    p.add_argument("--expect-verdict", default=None, dest="expect_verdict")
+
+    p_turn = sub.add_parser("turn", help="supervised confined production turn")
+    p_turn.add_argument("--project", default=None)
+    turn_sub = p_turn.add_subparsers(dest="turn_command", required=True)
+    p = turn_sub.add_parser("run")
+    p.add_argument("--prompt-file", required=True, dest="prompt_file")
+    p.add_argument("--envelope", action="append", required=True)
+    p.add_argument("--gate-envelope", action="append", default=[],
+                   dest="gate_envelope")
+    p.add_argument("--gate-command", required=True, dest="gate_command")
+    p.add_argument("--declared-in", required=True, dest="declared_in")
+    p.add_argument("--step", required=True)
+    p.add_argument("--artifact-dir", required=True, dest="artifact_dir")
+    p.add_argument("--linkage", required=True)
+    p.add_argument("--timeout", type=float, default=900.0)
+    p.add_argument("--claude-bin", default="claude", dest="claude_bin")
+
+    p_gate = sub.add_parser("gate", help="mechanized gate execution")
+    p_gate.add_argument("--project", default=None)
+    gate_sub = p_gate.add_subparsers(dest="gate_command", required=True)
+    p = gate_sub.add_parser("run")
+    p.add_argument("--command", required=True, dest="gate_cmd")
+    p.add_argument("--declared-in", required=True, dest="declared_in")
+    p.add_argument("--artifact", required=True)
+    p.add_argument("--linkage", required=True)
+    p.add_argument("--timeout", type=float, default=1800.0)
+
     p_control = sub.add_parser("control",
                                help="control.json attributability helpers")
     p_control.add_argument("--project", default=None)
@@ -120,6 +160,67 @@ def run(args, out=None) -> int:
         if args.command == "control":
             return _run_control_explain(service, root, out,
                                         since_version=args.since_version)
+        if args.command == "advisor":
+            from .conduction.consult import AdvisorUnavailable, run_consult
+            from .conduction.evidence import EvidenceConflict
+            try:
+                result = run_consult(root, prompt_file=Path(args.prompt_file),
+                                     artifact=Path(args.artifact),
+                                     linkage=args.linkage, timeout=args.timeout,
+                                     expect_verdict=args.expect_verdict)
+            except AdvisorUnavailable as exc:
+                return _fail("ADVISOR_UNAVAILABLE", {"reason": str(exc)}, out)
+            except EvidenceConflict as exc:
+                return _fail("CONFLICT", {"paths": exc.paths}, out)
+            if not result["ok"]:
+                return _fail("ADVISOR_FAILED",
+                             {"outcome": result["outcome"],
+                              "exit_code": result["exit_code"],
+                              "verdict": result["verdict"],
+                              "artifact": result["artifact"]}, out)
+            return _emit(result, 0, out)
+        if args.command == "turn":
+            from .conduction.turn import TurnError, run_turn
+            from .conduction.gate import ProvenanceError
+            from .conduction.evidence import EvidenceConflict
+            try:
+                result = run_turn(
+                    root, prompt_file=Path(args.prompt_file),
+                    envelope=args.envelope, gate_envelope=args.gate_envelope,
+                    gate_command=args.gate_command,
+                    declared_in=Path(args.declared_in), step=args.step,
+                    artifact_dir=Path(args.artifact_dir), linkage=args.linkage,
+                    timeout=args.timeout, claude_bin=args.claude_bin)
+            except TurnError as exc:
+                return _fail(exc.code, exc.detail, out)
+            except ProvenanceError as exc:
+                return _fail("PROVENANCE", {"reason": str(exc)}, out)
+            except EvidenceConflict as exc:
+                return _fail("CONFLICT", {"paths": exc.paths}, out)
+            if not result["ok"]:
+                code = ({"TURN_VIOLATION": "TURN_VIOLATION",
+                         "TURN_TAMPERED": "TURN_TAMPERED",
+                         "GATE_RED": "GATE_RED"}.get(result["outcome"], "TURN_FAILED"))
+                return _fail(code, {"outcome": result["outcome"],
+                                    "artifact": result["artifact"]}, out)
+            return _emit(result, 0, out)
+        if args.command == "gate":
+            from .conduction.gate import ProvenanceError, run_gate
+            from .conduction.evidence import EvidenceConflict
+            try:
+                result = run_gate(root, command=args.gate_cmd,
+                                  declared_in=Path(args.declared_in),
+                                  artifact=Path(args.artifact),
+                                  linkage=args.linkage, timeout=args.timeout)
+            except ProvenanceError as exc:
+                return _fail("PROVENANCE", {"reason": str(exc)}, out)
+            except EvidenceConflict as exc:
+                return _fail("CONFLICT", {"paths": exc.paths}, out)
+            if not result["ok"]:
+                return _fail("GATE_RED", {"outcome": result["outcome"],
+                                          "exit_code": result["exit_code"],
+                                          "artifact": result["artifact"]}, out)
+            return _emit(result, 0, out)
         return _fail("USAGE", f"unknown command {args.command!r}", out)
     except ActivityError as exc:
         return _fail(exc.code, exc.detail, out)

regent_cli-0.6.0/src/regent/conduction/__init__.py

@@ -0,0 +1,7 @@
+"""regent.conduction — conduction phase 1 (PLAN-003): mechanized advisor
+consultations and gate runs with automated, fail-closed evidence."""
+
+from .consult import run_consult
+from .gate import run_gate
+
+__all__ = ["run_consult", "run_gate"]

regent_cli-0.6.0/src/regent/conduction/confine.py

@@ -0,0 +1,79 @@
+"""Confined-turn composition (PLAN-004 STEP-02).
+
+Builds an immutable per-turn PRIVATE dir (outside the repo) with a generated
+settings.json that wires the Pre/PostToolUse hooks to a private copy of
+hookscript.py, and returns the `claude -p` argv + minimal environment. The
+launch inherits NO config (`--setting-sources ""`), restricts tools, and forces
+acceptEdits (the confinement IS the hook's deny; dontAsk would deny even
+in-envelope writes — empirical IMP-003 lesson).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import shutil
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+
+ALLOWED_TOOLS = "Read,Write,Edit,MultiEdit"
+ENV_ALLOWLIST = ("PATH", "HOME", "LANG", "LC_ALL")
+
+
+@dataclass
+class ConfinedTurn:
+    private_dir: Path
+    settings_path: Path
+    event_log: Path
+    secret: str
+    envelope: list[str]
+
+    def cleanup(self) -> None:
+        shutil.rmtree(self.private_dir, ignore_errors=True)
+
+
+def compose(*, envelope: list[str], claude_bin: str = "claude") -> ConfinedTurn:
+    private_dir = Path(tempfile.mkdtemp(prefix="regent-turn-"))
+    hook_copy = private_dir / "hookscript.py"
+    shutil.copy(Path(__file__).with_name("hookscript.py"), hook_copy)
+    event_log = private_dir / "events.log"
+    secret = secrets.token_hex(32)
+    envelope = [str(Path(p).resolve()) for p in envelope]
+
+    hook_cmd = f"{_python()} {hook_copy}"
+    settings = {
+        "hooks": {
+            "PreToolUse": [{"hooks": [{"type": "command", "command": hook_cmd}]}],
+            "PostToolUse": [{"hooks": [{"type": "command", "command": hook_cmd}]}],
+        }
+    }
+    settings_path = private_dir / "settings.json"
+    settings_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    # Freeze the composition (read-only) so nothing mutates it mid-turn.
+    for path in (hook_copy, settings_path):
+        path.chmod(0o400)
+    return ConfinedTurn(private_dir, settings_path, event_log, secret, envelope)
+
+
+def launch_argv(turn: ConfinedTurn, *, prompt: str,
+                claude_bin: str = "claude") -> list[str]:
+    return [claude_bin, "-p", prompt,
+            "--setting-sources", "",              # inherit NOTHING
+            "--settings", str(turn.settings_path),
+            "--tools", ALLOWED_TOOLS,
+            "--permission-mode", "acceptEdits"]
+
+
+def launch_env(turn: ConfinedTurn) -> dict[str, str]:
+    env = {k: os.environ[k] for k in ENV_ALLOWLIST if k in os.environ}
+    env["REGENT_TURN_SECRET"] = turn.secret
+    env["REGENT_ENVELOPE"] = json.dumps(turn.envelope)
+    env["REGENT_EVENT_LOG"] = str(turn.event_log)
+    return env
+
+
+def _python() -> str:
+    import sys
+    return sys.executable or "python3"

regent_cli-0.6.0/src/regent/conduction/consult.py

@@ -0,0 +1,98 @@
+"""`regent advisor consult` — mechanized advisor consultation (PLAN-003).
+
+Ports the IMP-003-proven CodexConsultAdapter: read-only sandboxed `codex exec`
+with the REQ-003 §5 evidence tuple generated BY THE COMMAND, not by executor
+discipline. Sandbox flags are mandatory and not configurable. Every terminal
+outcome (SUCCESS/TIMEOUT/FAILURE) leaves the evidence pair complete.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+from .evidence import EvidenceSet, header
+from .process import SubprocessRunner
+
+DEFAULT_VERDICT_RE = (r"^(CONCORDA|DISCORDA.*|APROVADO( COM RESSALVAS)?|"
+                      r"REPROVADO|QUITADAS|PENDENTES.*)$")
+
+
+class AdvisorUnavailable(Exception):
+    pass
+
+
+def run_consult(root: Path, *, prompt_file: Path, artifact: Path, linkage: str,
+                timeout: float = 600.0, expect_verdict: str | None = None,
+                runner=None, codex_bin: str = "codex") -> dict:
+    root = Path(root)
+    prompt_bytes = Path(prompt_file).read_bytes()  # byte-faithful (no newline
+    # translation — read_text would normalize CRLF)
+    prompt_text = prompt_bytes.decode("utf-8", errors="replace")
+    evidence = EvidenceSet(Path(artifact),
+                           {"prompt": Path(str(artifact) + "-PROMPT.md")})
+    evidence.precheck()
+
+    if runner is None:
+        if shutil.which(codex_bin) is None:
+            raise AdvisorUnavailable(f"'{codex_bin}' not found on PATH")
+        runner = SubprocessRunner()
+
+    # ONE cleanup guard around the WHOLE operation (sibling publish, temp
+    # file, execution and the main publish): any exception — OSError,
+    # EvidenceConflict from a no-clobber race on the main artifact, anything —
+    # removes the already-published siblings. Only a completed write_main
+    # (terminal outcome) leaves the pair behind.
+    try:
+        evidence.write_sibling("prompt", prompt_bytes)  # byte-identical copy
+        fd, msg_file = tempfile.mkstemp(prefix="regent-consult-", suffix=".txt")
+        os.close(fd)
+        try:
+            argv = [codex_bin, "--ask-for-approval", "never",
+                    "--sandbox", "read-only",  # MANDATORY, not configurable
+                    "exec", "--cd", str(root), "-o", msg_file, prompt_text]
+            result = runner.run(argv, cwd=str(root), timeout=timeout)
+            try:
+                last_message = Path(msg_file).read_text(encoding="utf-8",
+                                                        errors="replace")
+            except OSError:
+                last_message = ""
+        finally:
+            try:
+                os.unlink(msg_file)
+            except OSError:
+                pass
+
+        if result.timed_out:
+            outcome = "TIMEOUT"
+        elif result.exit_code != 0:
+            outcome = "FAILURE"
+        else:
+            outcome = "SUCCESS"
+
+        body = last_message if last_message.strip() else result.output
+        pattern = (expect_verdict if expect_verdict is not None
+                   else DEFAULT_VERDICT_RE)
+        verdict = _extract_verdict(body, pattern)
+        evidence.write_main(header(outcome, result.exit_code, linkage,
+                                   verdict=verdict), body)
+    except BaseException:
+        evidence.cleanup_orphans()
+        raise
+
+    verdict_ok = verdict is not None if expect_verdict is not None else True
+    return {"ok": outcome == "SUCCESS" and verdict_ok, "outcome": outcome,
+            "verdict": verdict, "exit_code": result.exit_code,
+            "artifact": str(evidence.main),
+            "prompt_copy": str(evidence.siblings["prompt"])}
+
+
+def _extract_verdict(body: str, pattern: str) -> str | None:
+    import re
+    for line in reversed(body.splitlines()):
+        line = line.strip()
+        if line:
+            return line if re.fullmatch(pattern, line) else None
+    return None

regent_cli-0.6.0/src/regent/conduction/evidence.py

@@ -0,0 +1,101 @@
+"""Atomic evidence sets for conduction artifacts (PLAN-003 contracts).
+
+An evidence SET (main artifact + siblings such as the prompt copy or the
+FULL.log) has ONE atomic contract: every path is pre-checked BEFORE anything
+is written (any pre-existing member = conflict — evidence is never
+overwritten); siblings are committed first (tmp+replace each), the main
+artifact last; every terminal outcome leaves the set complete; a non-terminal
+failure removes the orphan siblings written so far.
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from pathlib import Path
+
+from ..protocol.audit import utcnow
+
+
+class EvidenceConflict(Exception):
+    def __init__(self, paths: list[str]) -> None:
+        super().__init__(f"evidence already exists: {paths}")
+        self.paths = paths
+
+
+def atomic_write(path: Path, content: "str | bytes") -> None:
+    """Atomic NO-CLOBBER publish: os.link fails with EEXIST if the target
+    appeared meanwhile (closes the precheck→publish TOCTOU — evidence is never
+    overwritten, not even by a concurrent writer)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f".{path.name}.tmp-{uuid.uuid4().hex}")
+    payload = content.encode("utf-8") if isinstance(content, str) else content
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o644)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(payload)
+        os.link(tmp, path)  # atomic no-clobber (EEXIST if raced)
+    except OSError as exc:
+        import errno as _errno
+        if exc.errno == _errno.EEXIST:
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+            raise EvidenceConflict([str(path)]) from None
+        try:
+            tmp.unlink()
+        except OSError:
+            pass
+        raise
+    tmp.unlink()
+
+
+class EvidenceSet:
+    def __init__(self, main: Path, siblings: dict[str, Path]) -> None:
+        self.main = Path(main)
+        self.siblings = {k: Path(v) for k, v in siblings.items()}
+        self._written: list[Path] = []
+
+    def precheck(self) -> None:
+        existing = [str(p) for p in (self.main, *self.siblings.values())
+                    if p.exists() or p.is_symlink()]
+        if existing:
+            raise EvidenceConflict(existing)
+
+    def write_sibling(self, key: str, content: "str | bytes") -> Path:
+        path = self.siblings[key]
+        try:
+            atomic_write(path, content)
+        except (OSError, EvidenceConflict):
+            self.cleanup_orphans()
+            raise
+        self._written.append(path)
+        return path
+
+    def write_main(self, header: dict, body: str) -> Path:
+        lines = ["---"]
+        for key, value in header.items():
+            lines.append(f"{key}: {value if value is not None else 'null'}")
+        lines.append("---")
+        content = "\n".join(lines) + "\n\n" + body
+        try:
+            atomic_write(self.main, content)
+        except (OSError, EvidenceConflict):
+            self.cleanup_orphans()
+            raise
+        return self.main
+
+    def cleanup_orphans(self) -> None:
+        for path in self._written:
+            try:
+                path.unlink()
+            except OSError:
+                pass
+
+
+def header(outcome: str, exit_code: int | None, linkage: str, **extra) -> dict:
+    base = {"outcome": outcome, "exit_code": exit_code,
+            "timestamp": utcnow(), "linkage": linkage}
+    base.update(extra)
+    return base

regent_cli-0.6.0/src/regent/conduction/gate.py

@@ -0,0 +1,71 @@
+"""`regent gate run` — mechanized gate execution (PLAN-003).
+
+The gate command is NEVER invented by regent: it must appear VERBATIM in the
+plan artifact referenced by --declared-in (provenance is checked, not
+trusted). Full output is always preserved: <=200 KiB inline in the artifact;
+above that, header+tail with DECLARED truncation plus the integral output in
+<artifact>-FULL.log, all under one atomic evidence-set contract.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .evidence import EvidenceSet, header
+from .process import SubprocessRunner
+
+TAIL_LIMIT = 200 * 1024
+
+
+class ProvenanceError(Exception):
+    pass
+
+
+def run_gate(root: Path, *, command: str, declared_in: Path, artifact: Path,
+             linkage: str, timeout: float = 1800.0, runner=None) -> dict:
+    root = Path(root)
+    if not command.strip():
+        raise ProvenanceError("empty gate command is never declared")
+    declared_text = Path(declared_in).read_text(encoding="utf-8",
+                                                errors="replace")
+    if command not in declared_text:
+        raise ProvenanceError(
+            f"gate command not declared verbatim in {declared_in}")
+
+    evidence = EvidenceSet(Path(artifact),
+                           {"full": Path(str(artifact) + "-FULL.log")})
+    evidence.precheck()
+    if runner is None:
+        runner = SubprocessRunner()
+
+    # ONE cleanup guard around execution + both publishes (see consult.py).
+    try:
+        result = runner.run(["bash", "-c", command], cwd=str(root),
+                            timeout=timeout)
+        raw = result.output_bytes
+        output_bytes = len(raw)
+        truncated = output_bytes > TAIL_LIMIT
+
+        if result.timed_out:
+            outcome = "TIMEOUT"
+        elif result.exit_code == 0:
+            outcome = "GREEN"
+        else:
+            outcome = "RED"
+
+        if truncated:
+            evidence.write_sibling("full", raw)  # integral RAW BYTES first
+            tail = raw[-TAIL_LIMIT:].decode("utf-8", errors="replace")
+            body = (f"[truncated: full output is {output_bytes} bytes — see "
+                    f"{evidence.siblings['full'].name}; tail follows]\n" + tail)
+        else:
+            body = raw.decode("utf-8", errors="replace")
+        evidence.write_main(header(outcome, result.exit_code, linkage,
+                                   command=command, output_bytes=output_bytes,
+                                   truncated=truncated), body)
+    except BaseException:
+        evidence.cleanup_orphans()
+        raise
+
+    return {"ok": outcome == "GREEN", "outcome": outcome,
+            "exit_code": result.exit_code, "artifact": str(evidence.main)}