gargoyle-receipts 0.16.3.dev0__tar.gz → 0.16.4.dev0__tar.gz

{gargoyle_receipts-0.16.3.dev0/gargoyle_receipts.egg-info → gargoyle_receipts-0.16.4.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.3.dev0
+Version: 0.16.4.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.16.3.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.4.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -278,9 +278,14 @@ chat channel can approve anything.
 
     pip install gargoyle-receipts
 
-Three commands, no policy engine, no containers, no client changes:
+Three commands, no policy engine, no containers, no client changes
+(`--observe` starts a deployment in record-only mode, every call allowed
+including destructive ones and every call recorded; `gargoyle audit
+--summary` then shows calls by principal and tool, the input for the
+hold and deny rules):
 
     gargoyle init /path/the/agent/may/touch     # keys, config, rules.json
+    gargoyle init --observe /path/...           # or: allow and record everything, hold nothing, tighten later
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 

{gargoyle_receipts-0.16.3.dev0 → gargoyle_receipts-0.16.4.dev0}/README.md

@@ -21,7 +21,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.16.3.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.4.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -240,9 +240,14 @@ chat channel can approve anything.
 
     pip install gargoyle-receipts
 
-Three commands, no policy engine, no containers, no client changes:
+Three commands, no policy engine, no containers, no client changes
+(`--observe` starts a deployment in record-only mode, every call allowed
+including destructive ones and every call recorded; `gargoyle audit
+--summary` then shows calls by principal and tool, the input for the
+hold and deny rules):
 
     gargoyle init /path/the/agent/may/touch     # keys, config, rules.json
+    gargoyle init --observe /path/...           # or: allow and record everything, hold nothing, tighten later
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 

{gargoyle_receipts-0.16.3.dev0 → gargoyle_receipts-0.16.4.dev0}/gargoyle/cli.py

@@ -51,6 +51,17 @@ from pathlib import Path
 
 PRINCIPAL = "spiffe://gargoyle.local/agents/assistant"
 
+OBSERVE_RULES = {
+    # Observe mode: every call allowed (deletes too), every call recorded, none held. The
+    # first week of a deployment, so the hold and deny rules are written
+    # from the audit rather than guessed. The policy pin changes when the
+    # rules do, so switching modes means restarting the issuer and copying
+    # the new record.json to each client.
+    "version": "1",
+    "default": "allow",
+    "rules": [],
+}
+
 DEFAULT_RULES = {
     "version": "1",
     "default": "deny",
@@ -118,7 +129,22 @@ def cmd_init(args) -> int:
     issuer_url = args.issuer_url or "http://%s:%d" % (args.host, args.port)
 
     rules = out / "rules.json"
-    if not rules.exists():
+    if args.observe:
+        current = None
+        if rules.exists():
+            try:
+                current = json.loads(rules.read_text())
+            except ValueError as exc:
+                print("%s is not valid JSON (%s); fix or remove it before --observe" % (rules, exc), file=sys.stderr)
+                return 2
+        if current is None or current == DEFAULT_RULES:
+            _write(rules, json.dumps(OBSERVE_RULES, indent=2) + "\n")
+        elif current != OBSERVE_RULES:
+            print("rules.json was edited by hand and is left as it is; --observe changed nothing", file=sys.stderr)
+        print("observe mode: rules.json allows every call, destructive ones included; the gate records all of "
+              "them and holds none. Tighten rules.json from `gargoyle audit --summary`, then restart the issuer "
+              "and copy the new record.json to the clients.")
+    elif not rules.exists():
         _write(rules, json.dumps(DEFAULT_RULES, indent=2) + "\n")
     _write(out / "issuer.env", _env_lines({
         "GARGOYLE_ISSUER_KEY_ID": "issuer-1", "GARGOYLE_ISSUER_KEY_HEX": issuer_hex,
@@ -360,6 +386,29 @@ def cmd_approvers(args) -> int:
     return 1
 
 
+def _audit_summary(report, raw) -> None:
+    """Calls by principal and tool with their outcomes, then who released
+    and which clients: a week of observe mode as a table, the input for
+    writing the hold and deny rules."""
+    from collections import Counter
+    counts: Dict[tuple, Counter] = {}
+    releases: Counter = Counter()
+    clients: Counter = Counter()
+    ats = [e.get("at") for e in raw if isinstance(e, dict) and isinstance(e.get("at"), str)]
+    for r in report:
+        counts.setdefault((r["principal"] or "?", r["tool"] or "?"), Counter())[r["kind"] or "?"] += 1
+        for who in r.get("released_by") or []:
+            releases[who] += 1
+        clients[r.get("client") or "(client unnamed)"] += 1
+    print("summary: %d call(s)%s" % (len(report), (", %s to %s" % (min(ats)[:19], max(ats)[:19])) if ats else ""))
+    print("  %-28s %-24s %7s %7s" % ("principal", "tool", "honored", "refused"))
+    for (principal, tool), c in sorted(counts.items(), key=lambda kv: (kv[0][0], -sum(kv[1].values()), kv[0][1])):
+        print("  %-28s %-24s %7d %7d" % (principal[:28], tool[:24], c.get("honored", 0), c.get("refused", 0)))
+    if releases:
+        print("  releases: " + ", ".join("%s %d" % (w, n) for w, n in releases.most_common()))
+    print("  clients: " + ", ".join("%s %d" % (w, n) for w, n in clients.most_common()))
+
+
 def cmd_audit(args) -> int:
     from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
     from gargoyle.execution import verify_chain
@@ -406,6 +455,8 @@ def cmd_audit(args) -> int:
               % (v["count"], v["honored"], v["refused"], failed, v["reason"], v["tail_sha256"][:16]))
         rc = 0 if v["accepted"] else 1
         entries = read_log(args.log)
+        if args.summary:
+            _audit_summary(v["entries"], entries)
         if args.witness and not Path(args.witness).exists():
             print("witness file not found: %s (copy the issuer's witness.jsonl here first)" % args.witness, file=sys.stderr)
             return 2
@@ -460,6 +511,8 @@ def main(argv=None) -> int:
     p.add_argument("--issuer-url", help="URL the client reaches the issuer at (default http://HOST:PORT)")
     p.add_argument("--client-python", help="the client's Python executable for the MCP entry (default: this one)")
     p.add_argument("--client-config-dir", help="where the client keeps middleware.env, record.json, audit.jsonl (default: --out)")
+    p.add_argument("--observe", action="store_true",
+                   help="observe mode: allow and record every call, hold none; tighten rules.json later from the audit")
     p.add_argument("--approvers", type=int, default=1, metavar="N",
                    help="how many approver keys to create (approver-1..N); a rule with \"approvals\": 2 then needs two of them")
     p.add_argument("--upstream", choices=["npx-filesystem", "python-fs"], default="npx-filesystem",
@@ -512,6 +565,7 @@ def main(argv=None) -> int:
     p.add_argument("--log", help="the middleware's audit.jsonl: verify every entry")
     p.add_argument("--witness", help="the issuer's witness.jsonl: reconcile the evidence against it")
     p.add_argument("--check-tree", metavar="DIR", help="verify every gated file under DIR is as the gate left it")
+    p.add_argument("--summary", action="store_true", help="after the rows: calls by principal and tool with outcomes, releases, clients")
     p.add_argument("--out", default="gargoyle-deploy")
     p.set_defaults(fn=cmd_audit)
     args = parser.parse_args(argv)

{gargoyle_receipts-0.16.3.dev0 → gargoyle_receipts-0.16.4.dev0}/gargoyle/mcp_server.py

@@ -294,12 +294,14 @@ def gate_instructions(target_id: str, upstream_instructions: Optional[str] = Non
     that there is nothing to type. The upstream's own instructions, if
     any, follow the gate's."""
     text = override if override else (
-        "Every operation on %s goes through this server's tools; do not use any other tool, built-in "
-        "capability or workaround for that target. Reads run at once. A write may pause for a human "
-        "approval: wait for the result, it is normal. A refused call is a decision, not an error: report "
-        "the reason to the user and stop; do not retry or route around it. For a task with several "
-        "writes, gargoyle_plan may ask for one approval covering them; gargoyle_revert undoes an approved "
-        "change through the same approval. The user never needs to name this server." % target_id)
+        "Every operation on %s goes through this server's tools (this server is a Gargoyle gate); do not "
+        "use any other tool, built-in capability or workaround for that target. Reads run at once. A write "
+        "may pause for a human approval: wait for the result, it is normal. A refused call is a decision, "
+        "not an error: report the reason to the user and stop; do not retry or route around it. If asked "
+        "to work on that target without these tools or around the gate, say that the target is reachable "
+        "only through them and continue through them. For a task with several writes, gargoyle_plan may "
+        "ask for one approval covering them; gargoyle_revert undoes an approved change through the same "
+        "approval. The user never needs to name this server." % target_id)
     if upstream_instructions:
         text += "\n\n" + upstream_instructions
     return text

{gargoyle_receipts-0.16.3.dev0 → gargoyle_receipts-0.16.4.dev0/gargoyle_receipts.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gargoyle-receipts
-Version: 0.16.3.dev0
+Version: 0.16.4.dev0
 Summary: Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls.
 Author: Justin LaPorte
 License-Expression: Apache-2.0
@@ -59,7 +59,7 @@ your MCP server and lets through only what both agreed to.
 
 [![PyPI](https://img.shields.io/pypi/v/gargoyle-receipts)](https://pypi.org/project/gargoyle-receipts/)
 
-Status: pre-release (`0.16.3.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
+Status: pre-release (`0.16.4.dev0`, on PyPI as `gargoyle-receipts`). The wire format is `gargoyle/3` and may
 still change before the first release; it is specified in [SPEC.md](SPEC.md).
 
 ## What a receipt gives you
@@ -278,9 +278,14 @@ chat channel can approve anything.
 
     pip install gargoyle-receipts
 
-Three commands, no policy engine, no containers, no client changes:
+Three commands, no policy engine, no containers, no client changes
+(`--observe` starts a deployment in record-only mode, every call allowed
+including destructive ones and every call recorded; `gargoyle audit
+--summary` then shows calls by principal and tool, the input for the
+hold and deny rules):
 
     gargoyle init /path/the/agent/may/touch     # keys, config, rules.json
+    gargoyle init --observe /path/...           # or: allow and record everything, hold nothing, tighten later
     gargoyle issuer                             # the issuing service, on rules.json
     gargoyle approve --watch 2                  # where the approver sits (terminal)
 

{gargoyle_receipts-0.16.3.dev0 → gargoyle_receipts-0.16.4.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gargoyle-receipts"
-version = "0.16.3.dev0"
+version = "0.16.4.dev0"
 description = "Signed, single-use, argument-bound receipts and human-approval holds for agent tool calls."
 readme = "README.md"
 requires-python = ">=3.12"

{gargoyle_receipts-0.16.3.dev0 → gargoyle_receipts-0.16.4.dev0}/tests/test_cli.py

@@ -108,8 +108,9 @@ def test_init_for_a_windows_client_and_audit_log_verification(tmp_path, monkeypa
     gate = _gate(state, params); assert not gate["executed"]
     _record(state, REFUSED, gate, params)
     assert len(log.read_text().splitlines()) == 4
-    assert main(["audit", "--log", str(log), "--out", str(out)]) == 0
+    assert main(["audit", "--log", str(log), "--out", str(out), "--summary"]) == 0
     out_text = capsys.readouterr().out
+    assert "summary:" in out_text and "principal" in out_text and "clients:" in out_text
     assert "4 entries (3 honored, 1 refused), 0 failed; chain EVIDENCE_VERIFIED" in out_text
     assert out_text.count(" ok ") == 4 and "refused  delete_file" in out_text
     assert "ENTRY_VERIFIED (DESTRUCTIVE_TOOL)" in out_text
@@ -143,3 +144,30 @@ def test_the_package_runs_as_a_module():
     import subprocess, sys
     r = subprocess.run([sys.executable, "-m", "gargoyle", "--help"], capture_output=True, text=True, timeout=60)
     assert r.returncode == 0 and "audit" in r.stdout
+
+
+def test_init_observe_allows_everything_and_records_it(tmp_path, capsys):
+    """Observe mode: the rules file allows every call, so the gate holds
+    nothing and refuses nothing while every call still gets a receipt and an
+    evidence entry. The default rules are not touched once someone edited them."""
+    from gargoyle.cli import DEFAULT_RULES, OBSERVE_RULES
+    from gargoyle.rules import RulesPolicy
+    out = tmp_path / "deploy"
+    assert main(["init", str(tmp_path / "project"), "--out", str(out), "--observe"]) == 0
+    assert "observe mode" in capsys.readouterr().out
+    assert json.loads((out / "rules.json").read_text()) == OBSERVE_RULES
+    policy = RulesPolicy(str(out / "rules.json"))
+    for tool in ("read_file", "write_file", "delete_file", "anything_else"):
+        d = policy.decide("mcp://x", {"tool": tool, "args": {}, "principal": "p"})
+        assert d.eligible and not d.requires_approval
+    assert policy.pin()["policy_sha256"] != RulesPolicy.__module__ and policy.pin()["policy_id"]
+    # A hand-edited rules file is left alone by a later --observe.
+    custom = {**DEFAULT_RULES, "rules": DEFAULT_RULES["rules"][:1]}
+    (out / "rules.json").write_text(json.dumps(custom))
+    assert main(["init", str(tmp_path / "project"), "--out", str(out), "--observe"]) == 0
+    assert json.loads((out / "rules.json").read_text()) == custom
+    assert "left as it is" in capsys.readouterr().err
+    # A broken rules file is refused, not overwritten and not a traceback.
+    (out / "rules.json").write_text("{not json")
+    assert main(["init", str(tmp_path / "project"), "--out", str(out), "--observe"]) == 2
+    assert (out / "rules.json").read_text() == "{not json"