actgate 0.2.0__tar.gz → 0.3.0__tar.gz

{actgate-0.2.0 → actgate-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: actgate
-Version: 0.2.0
+Version: 0.3.0
 Summary: Local intent ledger and MCP tool-call proxy with approval gate
 License-Expression: MIT
 Project-URL: Repository, https://github.com/kartsan03/actgate
@@ -27,6 +27,7 @@ Dynamic: license-file
 # ActGate
 
 [![ci](https://github.com/kartsan03/actgate/actions/workflows/ci.yml/badge.svg)](https://github.com/kartsan03/actgate/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/actgate.svg)](https://pypi.org/project/actgate/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
@@ -40,6 +41,12 @@ only after approve.
 
 ## Install
 
+```
+pip install actgate
+```
+
+Dev:
+
 ```
 pip install -e .[dev]
 ```
@@ -49,6 +56,7 @@ pip install -e .[dev]
 ```
 actgate init
 actgate propose --tool shell.exec --args '{"cmd":"ls"}' --blast-tags fs.read
+actgate pending
 actgate dry-run <intent_id>
 actgate approve <intent_id>
 actgate verify
@@ -64,6 +72,8 @@ actgate init
 actgate mcp --upstream python -m some_mcp_server
 ```
 
+Use the same `--root` (or the same working directory) for `init`, `approve`/`deny`, and `mcp`, so they share one ledger.
+
 Flow:
 
 1. Client `tools/list` is forwarded to upstream. Only `tools/call` is gated;
@@ -78,11 +88,24 @@ Flow:
 Bare `verify` checks hash-chain integrity only. Set `ACTGATE_SEAL_KEY` for
 optional HMAC seals, or pass `verify --require-seal`.
 
+
+## Human loop (HITL)
+
+Typical MCP approval loop:
+
+1. Client hits `actgate mcp --upstream ...` and gets `ACTGATE_PENDING`.
+2. Human: `actgate pending` (or `actgate pending --watch`) to see undecided proposes.
+3. `actgate approve <intent_id>` or `actgate deny <intent_id>`.
+4. Client retries the same `tools/call`; proxy executes once.
+
+`pending` is the propose-without-decision queue. `--watch` polls (default 1s) and
+prints newly pending intents as JSON until Ctrl-C (clean exit 0).
+
 ## Exit codes
 
 | Code | Meaning |
 |------|---------|
-| 0 | ok (propose, approve, verify clean, show/list) |
+| 0 | ok (propose, approve, verify clean, show/list/pending) |
 | 1 | deny recorded, or verify found a broken chain / bad seal |
 | 2 | setup error (missing ledger, bad path, invalid args) |
 

{actgate-0.2.0 → actgate-0.3.0}/README.md

@@ -1,6 +1,7 @@
 # ActGate
 
 [![ci](https://github.com/kartsan03/actgate/actions/workflows/ci.yml/badge.svg)](https://github.com/kartsan03/actgate/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/actgate.svg)](https://pypi.org/project/actgate/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
@@ -14,6 +15,12 @@ only after approve.
 
 ## Install
 
+```
+pip install actgate
+```
+
+Dev:
+
 ```
 pip install -e .[dev]
 ```
@@ -23,6 +30,7 @@ pip install -e .[dev]
 ```
 actgate init
 actgate propose --tool shell.exec --args '{"cmd":"ls"}' --blast-tags fs.read
+actgate pending
 actgate dry-run <intent_id>
 actgate approve <intent_id>
 actgate verify
@@ -38,6 +46,8 @@ actgate init
 actgate mcp --upstream python -m some_mcp_server
 ```
 
+Use the same `--root` (or the same working directory) for `init`, `approve`/`deny`, and `mcp`, so they share one ledger.
+
 Flow:
 
 1. Client `tools/list` is forwarded to upstream. Only `tools/call` is gated;
@@ -52,11 +62,24 @@ Flow:
 Bare `verify` checks hash-chain integrity only. Set `ACTGATE_SEAL_KEY` for
 optional HMAC seals, or pass `verify --require-seal`.
 
+
+## Human loop (HITL)
+
+Typical MCP approval loop:
+
+1. Client hits `actgate mcp --upstream ...` and gets `ACTGATE_PENDING`.
+2. Human: `actgate pending` (or `actgate pending --watch`) to see undecided proposes.
+3. `actgate approve <intent_id>` or `actgate deny <intent_id>`.
+4. Client retries the same `tools/call`; proxy executes once.
+
+`pending` is the propose-without-decision queue. `--watch` polls (default 1s) and
+prints newly pending intents as JSON until Ctrl-C (clean exit 0).
+
 ## Exit codes
 
 | Code | Meaning |
 |------|---------|
-| 0 | ok (propose, approve, verify clean, show/list) |
+| 0 | ok (propose, approve, verify clean, show/list/pending) |
 | 1 | deny recorded, or verify found a broken chain / bad seal |
 | 2 | setup error (missing ledger, bad path, invalid args) |
 

{actgate-0.2.0 → actgate-0.3.0}/actgate/__init__.py

@@ -1,3 +1,3 @@
 """ActGate: local IntentLedger and MCP tool-call proxy."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{actgate-0.2.0 → actgate-0.3.0}/actgate/cli.py

@@ -4,9 +4,11 @@ from __future__ import annotations
 
 import argparse
 import json
+import math
 import sys
+import time
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable
 
 from actgate import __version__
 from actgate.core.intent import Intent, IntentError, build_intent
@@ -205,6 +207,65 @@ def cmd_list(args: argparse.Namespace) -> int:
     return 0
 
 
+def collect_pending(ledger: Ledger) -> list[dict[str, Any]]:
+    """Propose events with no approve/deny yet (HITL queue)."""
+    seen: dict[str, dict[str, Any]] = {}
+    for entry in ledger.read_entries():
+        iid = entry.get("intent_id")
+        if not iid:
+            continue
+        row = seen.setdefault(
+            iid,
+            {
+                "intent_id": iid,
+                "tool": None,
+                "seq": entry["seq"],
+                "ts": entry.get("ts"),
+                "intent": None,
+            },
+        )
+        if entry.get("action") == "propose":
+            intent = entry.get("intent") or {}
+            row["tool"] = intent.get("tool")
+            row["intent"] = intent
+            row["seq"] = entry["seq"]
+            row["ts"] = entry.get("ts")
+        elif entry.get("action") in ("approve", "deny"):
+            row["_decided"] = True
+    rows = [r for r in seen.values() if not r.pop("_decided", False) and r.get("intent") is not None]
+    return sorted(rows, key=lambda r: r["seq"])
+
+
+def cmd_pending(args: argparse.Namespace) -> int:
+    try:
+        ledger = _ledger_from_args(args)
+        if not ledger.exists():
+            raise LedgerError(f"ledger not found: {ledger.path}")
+    except LedgerError as exc:
+        _eprint(str(exc))
+        return 2
+
+    if not getattr(args, "watch", False):
+        print(json.dumps(collect_pending(ledger), indent=2))
+        return 0
+
+    interval = float(getattr(args, "interval", 1.0))
+    if not math.isfinite(interval) or interval <= 0:
+        _eprint("--interval must be a finite number > 0")
+        return 2
+    sleep_fn: Callable[[float], None] = getattr(args, "_sleep", time.sleep)
+    seen: set[str] = set()
+    try:
+        while True:
+            rows = collect_pending(ledger)
+            fresh = [r for r in rows if r["intent_id"] not in seen]
+            for r in rows:
+                seen.add(r["intent_id"])
+            if fresh:
+                print(json.dumps(fresh, indent=2), flush=True)
+            sleep_fn(interval)
+    except KeyboardInterrupt:
+        return 0
 
 
 def cmd_mcp(args: argparse.Namespace) -> int:
@@ -220,6 +281,7 @@ def cmd_mcp(args: argparse.Namespace) -> int:
         _eprint(str(exc))
         return 2
 
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="actgate",
@@ -272,6 +334,23 @@ def build_parser() -> argparse.ArgumentParser:
     p_list = sub.add_parser("list", help="list intents and status")
     p_list.set_defaults(func=cmd_list)
 
+    p_pend = sub.add_parser(
+        "pending",
+        help="list undecided proposes (HITL queue); optional --watch",
+    )
+    p_pend.add_argument(
+        "--watch",
+        action="store_true",
+        help="poll and print newly pending intents until Ctrl-C",
+    )
+    p_pend.add_argument(
+        "--interval",
+        type=float,
+        default=1.0,
+        help="watch poll interval seconds (default: 1)",
+    )
+    p_pend.set_defaults(func=cmd_pending)
+
     p_mcp = sub.add_parser(
         "mcp",
         help="stdio MCP proxy: gate tools/call until ledger approve",

{actgate-0.2.0 → actgate-0.3.0}/actgate.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: actgate
-Version: 0.2.0
+Version: 0.3.0
 Summary: Local intent ledger and MCP tool-call proxy with approval gate
 License-Expression: MIT
 Project-URL: Repository, https://github.com/kartsan03/actgate
@@ -27,6 +27,7 @@ Dynamic: license-file
 # ActGate
 
 [![ci](https://github.com/kartsan03/actgate/actions/workflows/ci.yml/badge.svg)](https://github.com/kartsan03/actgate/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/actgate.svg)](https://pypi.org/project/actgate/)
 [![Python](https://img.shields.io/badge/python-3.10%2B-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
@@ -40,6 +41,12 @@ only after approve.
 
 ## Install
 
+```
+pip install actgate
+```
+
+Dev:
+
 ```
 pip install -e .[dev]
 ```
@@ -49,6 +56,7 @@ pip install -e .[dev]
 ```
 actgate init
 actgate propose --tool shell.exec --args '{"cmd":"ls"}' --blast-tags fs.read
+actgate pending
 actgate dry-run <intent_id>
 actgate approve <intent_id>
 actgate verify
@@ -64,6 +72,8 @@ actgate init
 actgate mcp --upstream python -m some_mcp_server
 ```
 
+Use the same `--root` (or the same working directory) for `init`, `approve`/`deny`, and `mcp`, so they share one ledger.
+
 Flow:
 
 1. Client `tools/list` is forwarded to upstream. Only `tools/call` is gated;
@@ -78,11 +88,24 @@ Flow:
 Bare `verify` checks hash-chain integrity only. Set `ACTGATE_SEAL_KEY` for
 optional HMAC seals, or pass `verify --require-seal`.
 
+
+## Human loop (HITL)
+
+Typical MCP approval loop:
+
+1. Client hits `actgate mcp --upstream ...` and gets `ACTGATE_PENDING`.
+2. Human: `actgate pending` (or `actgate pending --watch`) to see undecided proposes.
+3. `actgate approve <intent_id>` or `actgate deny <intent_id>`.
+4. Client retries the same `tools/call`; proxy executes once.
+
+`pending` is the propose-without-decision queue. `--watch` polls (default 1s) and
+prints newly pending intents as JSON until Ctrl-C (clean exit 0).
+
 ## Exit codes
 
 | Code | Meaning |
 |------|---------|
-| 0 | ok (propose, approve, verify clean, show/list) |
+| 0 | ok (propose, approve, verify clean, show/list/pending) |
 | 1 | deny recorded, or verify found a broken chain / bad seal |
 | 2 | setup error (missing ledger, bad path, invalid args) |
 

{actgate-0.2.0 → actgate-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "actgate"
-version = "0.2.0"
+version = "0.3.0"
 description = "Local intent ledger and MCP tool-call proxy with approval gate"
 readme = "README.md"
 license = "MIT"

{actgate-0.2.0 → actgate-0.3.0}/tests/test_actgate.py

@@ -149,3 +149,74 @@ def test_forged_consistent_chain_verifies_without_seal(root: Path) -> None:
     assert main(["verify"]) == 0
     assert verify_ledger(ledger).ok
     assert main(["verify", "--require-seal"]) == 1
+
+def test_pending_empty(root: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["pending"]) == 0
+    out = json.loads(capsys.readouterr().out)
+    assert out == []
+
+
+def test_pending_with_propose(root: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["propose", "--tool", "shell.exec", "--args", '{"cmd":"ls"}']) == 0
+    capsys.readouterr()
+    assert main(["pending"]) == 0
+    rows = json.loads(capsys.readouterr().out)
+    assert len(rows) == 1
+    assert rows[0]["tool"] == "shell.exec"
+    assert rows[0]["intent_id"]
+
+
+def test_pending_clears_after_approve(root: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["propose", "--tool", "t", "--args", "{}"]) == 0
+    iid = Ledger.open(root=root).read_entries()[0]["intent_id"]
+    capsys.readouterr()
+    assert main(["pending"]) == 0
+    assert len(json.loads(capsys.readouterr().out)) == 1
+    assert main(["approve", iid]) == 0
+    capsys.readouterr()
+    assert main(["pending"]) == 0
+    assert json.loads(capsys.readouterr().out) == []
+
+
+def test_pending_watch_deterministic(root: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    from actgate.cli import build_parser, cmd_pending
+
+    assert main(["propose", "--tool", "watch.me", "--args", '{"n":1}']) == 0
+    capsys.readouterr()
+    n = {"i": 0}
+
+    def fake_sleep(_interval: float) -> None:
+        n["i"] += 1
+        if n["i"] == 1:
+            assert main(["propose", "--tool", "watch.two", "--args", '{"n":2}']) == 0
+            return
+        raise KeyboardInterrupt
+
+    args = build_parser().parse_args(["pending", "--watch", "--interval", "0.01"])
+    args._sleep = fake_sleep
+    assert cmd_pending(args) == 0
+    out = capsys.readouterr().out
+    # two flushed JSON arrays
+    assert "watch.me" in out
+    assert "watch.two" in out
+    assert n["i"] == 2
+
+
+def test_pending_clears_after_deny(root: Path, capsys: pytest.CaptureFixture[str]) -> None:
+    assert main(["propose", "--tool", "t", "--args", "{}"]) == 0
+    iid = Ledger.open(root=root).read_entries()[0]["intent_id"]
+    capsys.readouterr()
+    assert main(["pending"]) == 0
+    assert len(json.loads(capsys.readouterr().out)) == 1
+    assert main(["deny", iid]) == 1
+    capsys.readouterr()
+    assert main(["pending"]) == 0
+    assert json.loads(capsys.readouterr().out) == []
+
+
+def test_pending_watch_rejects_invalid_interval(root: Path) -> None:
+    assert main(["pending", "--watch", "--interval", "0"]) == 2
+    assert main(["pending", "--watch", "--interval", "-1"]) == 2
+    assert main(["pending", "--watch", "--interval", "nan"]) == 2
+    assert main(["pending", "--watch", "--interval", "inf"]) == 2
+