bounded-agent 0.1.2__tar.gz → 0.1.3__tar.gz

{bounded_agent-0.1.2 → bounded_agent-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bounded-agent
-Version: 0.1.2
+Version: 0.1.3
 Summary: Contract-bounded autonomy for LLM agents: five small primitives that make an agent safe to leave alone.
 Project-URL: Repository, https://github.com/scholih/bounded-agent
 Project-URL: Manifesto, https://medium.com/@scholih/the-edge-is-the-harness-not-the-model-a543abade391
@@ -55,6 +55,16 @@ contracts:
     scope: checkout-stack
     tier: act                     # observe | propose | act
     allows: [restart_worker]
+  - name: cache
+    status: active
+    scope: checkout-stack
+    tier: propose                 # may draft fixes; a human executes them
+    allows: [clear_cache]
+  - name: payments-db
+    status: proposed              # not signed off — grants NOTHING until active
+    scope: checkout-stack
+    tier: act
+    allows: [failover_replica]
 ```
 
 ```python
@@ -63,8 +73,15 @@ from pathlib import Path
 
 from bounded_agent import ActionSet, ContractBook, Envelope, EvidenceLedger, Gate
 
+print("1. the book — who may do what, declared by a human:")
 book = ContractBook.load("contracts.yaml")            # raises loudly if missing/malformed
-granted = book.granted(Gate(required_scope="checkout-stack", required_tier="act"))
+for c in book.contracts:
+    print(f"   {c.name}: status={c.status} scope={c.scope} tier={c.tier} allows={list(c.allows)}")
+
+gate = Gate(required_scope="checkout-stack", required_tier="act")
+granted = book.granted(gate)
+print(f"\n2. the gate — scope={gate.required_scope!r} at tier '{gate.required_tier}' grants:")
+print(f"   {granted or 'nothing — no active, in-scope contract at this tier'}")
 
 actions = ActionSet()                                 # the implemented closed set:
 actions.register("restart_worker", lambda: (True, "worker restarted"))
@@ -72,20 +89,42 @@ actions.register("restart_worker", lambda: (True, "worker restarted"))
 env = Envelope(armed=True,                            # ships disarmed; arming is explicit
                kill_switch_path=Path("STOP"),         # `touch STOP` halts everything
                max_actions_per_run=2,
-               notify=print)                          # act-then-report (stand in a pager here)
+               notify=lambda msg: print(f"   [report] {msg}"))
+ks = "PRESENT" if env.kill_switch_path.exists() else "absent"
+print(f"\n3. the envelope — armed={env.armed}, kill-switch {ks}, breaker {env.max_actions_per_run}/run")
 
+print("\n4. executing (double-closed: contracted AND registered; every outcome reported):")
 outcome = actions.execute(list(granted.items()), env,
                           ledger=EvidenceLedger(Path("ledger")),
                           period=dt.date.today())
-print(outcome.executed, "action(s) —", outcome.records[0].status)
+
+print(f"\n5. outcome — {outcome.summary()}")
+print(f"   ledger: ledger/{dt.date.today().isoformat()}.jsonl (append-only; every run adds lines)")
+```
+
+Run it and the output narrates the authorization chain — note the gate silently denying
+`cache` (propose tier) and `payments-db` (not signed off):
+
 ```
+1. the book — who may do what, declared by a human:
+   queue-worker: status=active scope=checkout-stack tier=act allows=['restart_worker']
+   cache: status=active scope=checkout-stack tier=propose allows=['clear_cache']
+   payments-db: status=proposed scope=checkout-stack tier=act allows=['failover_replica']
+
+2. the gate — scope='checkout-stack' at tier 'act' grants:
+   {'queue-worker': ('restart_worker',)}
 
-Both files as-is, `python` it, and you'll see the act-then-report line fire and one
-`executed-ok` record land in `ledger/` — the whole authorization chain in 20 lines.
+3. the envelope — armed=True, kill-switch absent, breaker 2/run
+
+4. executing (double-closed: contracted AND registered; every outcome reported):
+   [report] executed-ok: restart_worker on queue-worker (worker restarted)
+
+5. outcome — 1 executed | queue-worker:restart_worker=executed-ok
+   ledger: ledger/2026-08-01.jsonl (append-only; every run adds lines)
+```
 
-An action fires only if it appears in **both** the contract's `allows` list **and** the
-registered set — and only inside an armed envelope with no kill-switch present and breaker
-budget remaining. Everything that happens (and everything refused) is one JSONL line.
+Then `touch STOP` and run again to watch the kill-switch refuse everything — and land in
+the ledger anyway (the halt is on the record too; silence is impossible).
 
 For the LLM side, see `examples/sentinel/` — a complete service-health watchdog: deterministic
 probes → an escalate-only LLM verdict → a typed diagnosis → contract-bounded remediation.

{bounded_agent-0.1.2 → bounded_agent-0.1.3}/README.md

@@ -41,6 +41,16 @@ contracts:
     scope: checkout-stack
     tier: act                     # observe | propose | act
     allows: [restart_worker]
+  - name: cache
+    status: active
+    scope: checkout-stack
+    tier: propose                 # may draft fixes; a human executes them
+    allows: [clear_cache]
+  - name: payments-db
+    status: proposed              # not signed off — grants NOTHING until active
+    scope: checkout-stack
+    tier: act
+    allows: [failover_replica]
 ```
 
 ```python
@@ -49,8 +59,15 @@ from pathlib import Path
 
 from bounded_agent import ActionSet, ContractBook, Envelope, EvidenceLedger, Gate
 
+print("1. the book — who may do what, declared by a human:")
 book = ContractBook.load("contracts.yaml")            # raises loudly if missing/malformed
-granted = book.granted(Gate(required_scope="checkout-stack", required_tier="act"))
+for c in book.contracts:
+    print(f"   {c.name}: status={c.status} scope={c.scope} tier={c.tier} allows={list(c.allows)}")
+
+gate = Gate(required_scope="checkout-stack", required_tier="act")
+granted = book.granted(gate)
+print(f"\n2. the gate — scope={gate.required_scope!r} at tier '{gate.required_tier}' grants:")
+print(f"   {granted or 'nothing — no active, in-scope contract at this tier'}")
 
 actions = ActionSet()                                 # the implemented closed set:
 actions.register("restart_worker", lambda: (True, "worker restarted"))
@@ -58,20 +75,42 @@ actions.register("restart_worker", lambda: (True, "worker restarted"))
 env = Envelope(armed=True,                            # ships disarmed; arming is explicit
                kill_switch_path=Path("STOP"),         # `touch STOP` halts everything
                max_actions_per_run=2,
-               notify=print)                          # act-then-report (stand in a pager here)
+               notify=lambda msg: print(f"   [report] {msg}"))
+ks = "PRESENT" if env.kill_switch_path.exists() else "absent"
+print(f"\n3. the envelope — armed={env.armed}, kill-switch {ks}, breaker {env.max_actions_per_run}/run")
 
+print("\n4. executing (double-closed: contracted AND registered; every outcome reported):")
 outcome = actions.execute(list(granted.items()), env,
                           ledger=EvidenceLedger(Path("ledger")),
                           period=dt.date.today())
-print(outcome.executed, "action(s) —", outcome.records[0].status)
+
+print(f"\n5. outcome — {outcome.summary()}")
+print(f"   ledger: ledger/{dt.date.today().isoformat()}.jsonl (append-only; every run adds lines)")
+```
+
+Run it and the output narrates the authorization chain — note the gate silently denying
+`cache` (propose tier) and `payments-db` (not signed off):
+
 ```
+1. the book — who may do what, declared by a human:
+   queue-worker: status=active scope=checkout-stack tier=act allows=['restart_worker']
+   cache: status=active scope=checkout-stack tier=propose allows=['clear_cache']
+   payments-db: status=proposed scope=checkout-stack tier=act allows=['failover_replica']
+
+2. the gate — scope='checkout-stack' at tier 'act' grants:
+   {'queue-worker': ('restart_worker',)}
 
-Both files as-is, `python` it, and you'll see the act-then-report line fire and one
-`executed-ok` record land in `ledger/` — the whole authorization chain in 20 lines.
+3. the envelope — armed=True, kill-switch absent, breaker 2/run
+
+4. executing (double-closed: contracted AND registered; every outcome reported):
+   [report] executed-ok: restart_worker on queue-worker (worker restarted)
+
+5. outcome — 1 executed | queue-worker:restart_worker=executed-ok
+   ledger: ledger/2026-08-01.jsonl (append-only; every run adds lines)
+```
 
-An action fires only if it appears in **both** the contract's `allows` list **and** the
-registered set — and only inside an armed envelope with no kill-switch present and breaker
-budget remaining. Everything that happens (and everything refused) is one JSONL line.
+Then `touch STOP` and run again to watch the kill-switch refuse everything — and land in
+the ledger anyway (the halt is on the record too; silence is impossible).
 
 For the LLM side, see `examples/sentinel/` — a complete service-health watchdog: deterministic
 probes → an escalate-only LLM verdict → a typed diagnosis → contract-bounded remediation.

{bounded_agent-0.1.2 → bounded_agent-0.1.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "bounded-agent"
-version = "0.1.2"
+version = "0.1.3"
 description = "Contract-bounded autonomy for LLM agents: five small primitives that make an agent safe to leave alone."
 readme = "README.md"
 requires-python = ">=3.12"

{bounded_agent-0.1.2 → bounded_agent-0.1.3}/src/bounded_agent/actions.py

@@ -57,6 +57,15 @@ class ExecOutcome(BaseModel):
     records: tuple[ActionRecord, ...] = ()
     executed: int = 0                   # attempts, successful or not
 
+    def summary(self) -> str:
+        """One human line for logs/pagers: what ran, what was refused, what halted."""
+        if self.blocked_reason is not None:
+            return f"blocked: {self.blocked_reason}"
+        if not self.records:
+            return "0 executed (nothing actionable)"
+        parts = [f"{r.contract}:{r.action}={r.status}" for r in self.records]
+        return f"{self.executed} executed | " + "; ".join(parts)
+
 
 class ActionSet:
     """The registered half of the double-closed check, plus the execution loop."""

{bounded_agent-0.1.2 → bounded_agent-0.1.3}/tests/test_actions.py

@@ -107,3 +107,18 @@ def test_every_record_is_notified_and_ledgered(tmp_path):
                             ledger=ledger, period=DAY)
     lines = (tmp_path / "ev" / f"{DAY.isoformat()}.jsonl").read_text().splitlines()
     assert len(lines) == 2 and len(seen) == 2       # the refusal is recorded too
+
+
+def test_outcome_summary_reads_like_a_report():
+    calls: list[str] = []
+    out = _actions(calls).execute([("svc", ("restart_worker", "drop_database"))],
+                                  Envelope(armed=True, max_actions_per_run=5))
+    s = out.summary()
+    assert "1 executed" in s
+    assert "svc:restart_worker=executed-ok" in s
+    assert "svc:drop_database=refused" in s
+
+
+def test_outcome_summary_when_blocked():
+    out = _actions([]).execute([("svc", ("restart_worker",))], Envelope())
+    assert out.summary() == "blocked: disarmed"

{bounded_agent-0.1.2 → bounded_agent-0.1.3}/uv.lock

@@ -45,7 +45,7 @@ wheels = [
 
 [[package]]
 name = "bounded-agent"
-version = "0.1.0"
+version = "0.1.3"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },