strata-agent-memory 0.2.6__tar.gz → 0.2.7__tar.gz

{strata_agent_memory-0.2.6/strata_agent_memory.egg-info → strata_agent_memory-0.2.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: strata-agent-memory
-Version: 0.2.6
+Version: 0.2.7
 Summary: Portable, auditable, cross-vendor memory for LLM agents: evidence-bound claims, trust tiers, and compiled context views.
 Author: Strata Intelligence
 License-Expression: Apache-2.0

{strata_agent_memory-0.2.6 → strata_agent_memory-0.2.7}/agent_memory/__init__.py

@@ -9,4 +9,4 @@ see, what did it claim, and can the proof be re-run.
 The core is dependency-free (Python 3.10+ standard library only).
 """
 
-__version__ = "0.2.6"
+__version__ = "0.2.7"

{strata_agent_memory-0.2.6 → strata_agent_memory-0.2.7}/agent_memory/cli.py

@@ -606,9 +606,10 @@ def _private_contract_refusal(args) -> Optional[int]:
 
 
 def _acceptance_checks(args) -> List[dict]:
-    """The acceptance checks a `contract create` asks for, in the order the flags read
-    them. The remote lane files the same contract as the local one, so both build the
-    list here: a check that got lost on the way is a contract nobody can prove."""
+    """The acceptance checks a `contract create` asks for, or a `contract update` amends the
+    list to (ctr_649e0b459a758929), in the order the flags read them. The remote lane files
+    the same record as the local one, so both build the list here: a check that got lost on
+    the way is a contract nobody can prove."""
     acceptance = [{"kind": "command", "cmd": c, "expect_exit": 0} for c in args.check or []]
     acceptance += [{"kind": "human", "statement": s} for s in args.human_check or []]
     acceptance += [{"kind": "file", "path": f} for f in args.file_check or []]
@@ -637,8 +638,13 @@ def cmd_contract(args) -> int:
         _print(out)
         return 0 if signed else 3
     if args.action == "update":
-        rec = contracts.update(ledger, author, scope, args.id, args.status, note=args.note, claims=args.claims or (),
-                               assigned_to=getattr(args, "assign", None))
+        try:
+            rec = contracts.update(ledger, author, scope, args.id, args.status, note=args.note, claims=args.claims or (),
+                                   assigned_to=getattr(args, "assign", None),
+                                   acceptance_checks=_acceptance_checks(args) or None)
+        except ValidationError as exc:
+            print(f"rejected: {exc}", file=sys.stderr)
+            return 3
         out = {"id": rec["id"], "status": args.status}
         signed = _sign_after(args, ledger, author, scope, rec, out)
         _print(out)
@@ -1479,7 +1485,10 @@ def _remote_recheck(args, client) -> int:
                                max=args.max, cwd=root, timeout=args.timeout, path_map=path_map,
                                dry_run=args.dry_run, min_age_days=args.min_age_days, force=args.force,
                                assessment=view.assessment, file=file,
-                               policy=_sandbox_policy(args, _local_sandbox(view.config, root)))
+                               policy=_sandbox_policy(args, _local_sandbox(view.config, root)),
+                               # a re-run away from the outcome's bound commit refutes nothing
+                               # (the lane's rule, ctr_207af145a59463ed)
+                               away_is_error=True)
     except ValueError as exc:
         print(f"recheck: {exc}", file=sys.stderr)
         return 2
@@ -1679,7 +1688,8 @@ def _remote_contract_update(args, client) -> int:
         return 2
     claims = list(args.claims or [])
     body = contracts.update_body(args.id, args.status, note=args.note, claims=claims,
-                                 assigned_to=getattr(args, "assign", None))
+                                 assigned_to=getattr(args, "assign", None),
+                                 acceptance_checks=_acceptance_checks(args) or None)
     payload = {"kind": "contract_update", "body": body, "derived_from": [args.id, *claims]}
     rec, _ = client.post_record(_scoped_payload(payload, _remote_scope(args, client)))
     out = {"id": rec["id"], "status": rec["body"]["status"]}
@@ -1704,9 +1714,16 @@ def _remote_contract_accept(args, client) -> int:
     if local is None:
         return 2
     served = _ServedLedger(client, local)
+    # read once, before anything runs: the checks the replica says the contract answers to
+    # now, an amendment's included (the served view holds no contract_updates to find one
+    # in, ctr_649e0b459a758929), and the status the run reports it started under, which
+    # ``contracts.run_acceptance`` reads before its checks run too (PROTOCOL 4.1)
+    started = client.contract_status(args.id)
+    checks = started.get("acceptance")
     results = contracts.run_acceptance(served, args.id, cwd=args.cwd or str(local.root),
                                        timeout=args.timeout, file=False,
-                                       policy=_sandbox_policy(args, served.config))
+                                       policy=_sandbox_policy(args, served.config),
+                                       checks=checks if isinstance(checks, list) else None)
     # asked once and used for the receipts and the run alike: a --scope this client typed
     # has to reach the server the way `claim` and `retract` send it, and a project scope
     # is still the server's own to stamp
@@ -1716,7 +1733,7 @@ def _remote_contract_accept(args, client) -> int:
         if body and body.get("kind") in ("command", "test"):
             rec, _ = client.post_record(_scoped_payload({"kind": "evidence", "body": body}, scope))
             r["receipt"] = rec["id"]
-    status = client.contract_status(args.id)["status"]  # an acceptance run reports, it does not promote
+    status = started["status"]  # an acceptance run reports, it does not promote
     client.post_record(_scoped_payload({"kind": "contract_update", "body": {
         "contract": args.id, "status": status,
         "acceptance": [{"check": r["check"], "outcome": r["outcome"], "detail": r["detail"],
@@ -2349,6 +2366,12 @@ def build_parser() -> argparse.ArgumentParser:
     c.add_argument("--note")
     c.add_argument("--claims", nargs="*")
     c.add_argument("--assign", help="hand the contract to this agent (the board follows the latest assignee)")
+    # an amendment of the acceptance checks: the whole list, as `contract create` takes it
+    # (ctr_649e0b459a758929); refused under the contract's assignee's own key
+    c.add_argument("--check", action="append", help="amend the acceptance: a command expecting exit 0 (repeatable)")
+    c.add_argument("--human-check", action="append", help="amend the acceptance: a human sign-off (repeatable)")
+    c.add_argument("--file-check", action="append", help="amend the acceptance: a file that must exist (repeatable)")
+    c.add_argument("--acceptance-json", help="amend the acceptance: a JSON list of checks, replacing the contract's")
     _add_identity(c)
     _add_signing(c)
     c = cs.add_parser("from-issue", help="create a contract from a GitHub issue (needs the gh CLI)")
@@ -2419,7 +2442,8 @@ def build_parser() -> argparse.ArgumentParser:
                                        "verifications under the running identity; with --remote, the "
                                        "replica's claims, re-run here under the replica's re-check policy")
     s.add_argument("--only", choices=list(recheck_mod.ONLY_CHOICES), default="unverified",
-                   help="unverified (tier evidenced, default), stale, or all (everything but refuted/tainted)")
+                   help="unverified (tier evidenced or self-verified, whatever inconclusives it carries; the "
+                        "default), stale, or all (everything but refuted/tainted)")
     s.add_argument("--type", action="append",
                    help="restrict to these claim types, comma-separated (e.g. outcome,fact)")
     s.add_argument("--max", type=int, help="stop after this many claims")

{strata_agent_memory-0.2.6 → strata_agent_memory-0.2.7}/agent_memory/contracts.py

@@ -181,6 +181,116 @@ def _linked_claims(ledger, contract_id: str, extra: Iterable[str] = ()) -> List[
     return out
 
 
+def _assignee_of(body: dict) -> Optional[str]:
+    value = (body or {}).get("assigned_to")
+    return value.strip().lower() if isinstance(value, str) and value.strip() else None
+
+
+def assignee_now(ledger, contract_id: str) -> Optional[str]:
+    """Who holds the contract: the latest update that names an assignee, else the one it
+    was filed with (what ``status_of`` reports as ``assigned_to``)."""
+    rec = ledger.get(contract_id)
+    held = _assignee_of((rec or {}).get("body") or {})
+    for u in sorted(ledger.contract_updates(contract_id), key=sort_key):
+        held = _assignee_of(u["body"]) or held
+    return held
+
+
+def _may_amend(config: dict, author: dict) -> bool:
+    """A person, or the ledger's PM (config.pm): an agent's standing to amend a bar would
+    rest on an assignment any token can file, so no other agent has it."""
+    return author.get("kind") == "human" or is_pm(config, author)
+
+
+def _names_of(author: dict) -> set:
+    """The names that mean ``author`` when a contract is assigned: its user id and the local
+    part the relay addresses it by, as a reader is matched (``compiler._reader_names``,
+    PROTOCOL section 11). Every holder test here goes through it (the review of #148)."""
+    from .compiler import _reader_names  # local: compiler imports this module
+    return _reader_names(author)
+
+
+def _has_note(body: dict) -> bool:
+    note = body.get("note")
+    return isinstance(note, str) and bool(note.strip())
+
+
+def amendment_refusal(ledger, author: dict, contract_id: str, assigned_to: Optional[str] = None,
+                      note: Optional[str] = None) -> Optional[str]:
+    """Why ``author`` may not amend the contract's acceptance checks, or None
+    (ctr_649e0b459a758929). The worker never writes their own bar, so only a person or
+    the PM amends one. Reassignment is open to any token, so "anybody but the assignee"
+    would let the assignee reassign the contract away and amend it in the next update,
+    and would leave an unassigned contract to whoever wants it (the review of this
+    story). The PM does not amend a contract it holds, or one the same update hands to
+    it; a person may, as a person may reopen a closed one: the bar is the person's to set
+    (the PE's ruling). An amendment is a decision on the record, so it carries a note.
+    A contract names its holder by user id or by local part, and both mean the author."""
+    names = _names_of(author)
+    if not _may_amend(getattr(ledger, "config", None) or {}, author):
+        return (f"{author.get('user') or 'this agent'} may not amend contract {contract_id}'s acceptance checks: "
+                f"an amendment is a person's or the PM's (config.pm), since the worker never writes their own bar")
+    if not (note or "").strip():
+        return (f"an amendment of contract {contract_id}'s acceptance checks is a decision on the record: "
+                f"say why in --note")
+    if author.get("kind") == "human":
+        return None
+    holder = assignee_now(ledger, contract_id)
+    if holder and holder in names:
+        return (f"contract {contract_id} is assigned to {holder}, and the assignee never amends its own "
+                f"acceptance checks: the PM or somebody else does")
+    handed = _assignee_of({"assigned_to": assigned_to})
+    if handed and handed in names:
+        return (f"an amendment of contract {contract_id}'s acceptance checks may not assign the contract to its "
+                f"own author ({handed})")
+    return None
+
+
+def amendments(ledger, contract_id: str) -> List[dict]:
+    """The contract_updates that amend the contract's acceptance checks, oldest first.
+
+    Refused where it is filed, and not counted where it is read, by the same rules: an
+    amendment by anybody but a person or the PM, or with no note, or whose agent author
+    held the contract when it was filed (by user id or local part), or which handed it to
+    that author, changes nothing (one written by hand, or through a replica that did not
+    know the key). The history is folded in ``sort_key`` order, so every machine counts
+    the same ones."""
+    config = getattr(ledger, "config", None) or {}
+    rec = ledger.get(contract_id)
+    held = _assignee_of((rec or {}).get("body") or {})
+    counted = []
+    for u in sorted(ledger.contract_updates(contract_id), key=sort_key):
+        body = u.get("body") or {}
+        if "acceptance_checks" in body and "acceptance" not in body:
+            author = u.get("author") or {}
+            names = _names_of(author)
+            handed = _assignee_of(body)
+            held_by_author = author.get("kind") != "human" and bool(
+                (held and held in names) or (handed and handed in names))
+            if _may_amend(config, author) and _has_note(body) and not held_by_author:
+                counted.append(u)
+        held = _assignee_of(body) or held
+    return counted
+
+
+def acceptance_of(ledger, contract_id: str) -> tuple:
+    """(the acceptance checks the contract answers to, the amendment that set them or
+    None): the latest counted amendment's list, else the one the contract was filed with.
+    Every reader and runner of the checks goes through here (ctr_649e0b459a758929)."""
+    rec = ledger.get(contract_id)
+    if rec is None or rec.get("kind") != "contract":
+        raise KeyError(f"no contract {contract_id}")
+    if not hasattr(ledger, "contract_updates"):
+        # a view that holds no contract_updates cannot see an amendment, and running the list
+        # the contract was filed with would be the very slip this reads past: a caller with
+        # such a view passes the checks the replica reports (``run_acceptance(checks=)``)
+        raise TypeError(f"the acceptance of {contract_id} needs a ledger that holds its contract_updates")
+    latest = amendments(ledger, contract_id)
+    if latest:
+        return latest[-1]["body"]["acceptance_checks"], latest[-1]["id"]
+    return rec["body"]["acceptance"], None
+
+
 def acceptance_runs(ledger, contract_id: str) -> List[dict]:
     """Acceptance-run contract_updates for a contract, oldest first."""
     runs = [u for u in ledger.contract_updates(contract_id) if u["body"].get("acceptance")]
@@ -270,6 +380,13 @@ def verification_basis(ledger, contract_id: str, assessment=None) -> dict:
         return out
     latest = runs[-1]
     out["run"] = latest["id"]
+    amended = amendments(ledger, contract_id)
+    if amended and sort_key(amended[-1]) > sort_key(latest):
+        # the run asked the checks the contract answered to then, not the ones it answers to
+        # now (ctr_649e0b459a758929)
+        out["reason"] = (f"the acceptance was amended by {amended[-1]['id']} after the latest run; "
+                         f"run `agent-memory contract accept {contract_id}`")
+        return out
     if not _run_ok(latest):
         failing = [r.get("check", {}).get("cmd") or r.get("check", {}).get("path") or r.get("check", {}).get("kind")
                    for r in latest["body"]["acceptance"] if r.get("outcome") not in ("match", "skipped")]
@@ -452,6 +569,11 @@ def transition_refusal(ledger, rec: dict, assessment=None) -> Optional[str]:
                           note=note if isinstance(note, str) else None, assessment=assessment)
     except ValidationError as exc:
         return str(exc)
+    if "acceptance_checks" in body:
+        assigned = body.get("assigned_to")
+        return amendment_refusal(ledger, rec.get("author") or {}, contract_id,
+                                 assigned if isinstance(assigned, str) else None,
+                                 note=note if isinstance(note, str) else None)
     return None
 
 
@@ -461,6 +583,7 @@ def update_body(
     note: Optional[str] = None,
     claims: Iterable[str] = (),
     assigned_to: Optional[str] = None,
+    acceptance_checks: Optional[List[dict]] = None,
 ) -> dict:
     """The body of a contract_update that asks for a move, without filing it.
 
@@ -473,6 +596,8 @@ def update_body(
         body["note"] = note
     if assigned_to:
         body["assigned_to"] = assigned_to
+    if acceptance_checks:
+        body["acceptance_checks"] = list(acceptance_checks)
     return body
 
 
@@ -486,13 +611,21 @@ def update(
     claims: Iterable[str] = (),
     tags: Iterable[str] = (),
     assigned_to: Optional[str] = None,
+    acceptance_checks: Optional[List[dict]] = None,
 ) -> dict:
     """File a status transition, enforcing the rules above. ``assigned_to`` hands the
     contract to another agent: the latest update that names one is who holds it, which
-    is what the compiled board shows (a PM reassigns with `contract update --assign`)."""
+    is what the compiled board shows (a PM reassigns with `contract update --assign`).
+    ``acceptance_checks`` replaces the checks the contract answers to from here on
+    (``acceptance_of``); the assignee may not file one (``amendment_refusal``)."""
     _check_transition(ledger, author, contract_id, status, claims, note=note)
+    if acceptance_checks:
+        refusal = amendment_refusal(ledger, author, contract_id, assigned_to, note=note)
+        if refusal:
+            raise ValidationError(refusal)
     rec = new_record("contract_update", author, scope,
-                     update_body(contract_id, status, note=note, claims=claims, assigned_to=assigned_to),
+                     update_body(contract_id, status, note=note, claims=claims, assigned_to=assigned_to,
+                                 acceptance_checks=acceptance_checks),
                      derived_from=[contract_id, *claims], tags=tags)
     return ledger.append(rec)
 
@@ -522,6 +655,8 @@ def status_of(ledger, contract_id: str, assessment: Optional[dict] = None) -> di
     for u in updates:
         linked_ids.update(u["body"].get("claims", []))
     claims = [ledger.get(i) for i in sorted(linked_ids) if ledger.get(i)]
+    checks, amended_by = acceptance_of(ledger, contract_id)
+    amended_note = next((u["body"].get("note") for u in updates if u["id"] == amended_by), None)
     out = {
         "id": contract_id,
         "title": rec["body"]["title"],
@@ -537,7 +672,11 @@ def status_of(ledger, contract_id: str, assessment: Optional[dict] = None) -> di
         # thread besides the assignee's (ctr_b3b3e487832b5c94): a relay asks the replica
         "pm": pm_users(getattr(ledger, "config", None) or {}),
         "issue": rec["body"].get("issue"),
-        "acceptance": rec["body"]["acceptance"],
+        "acceptance": checks,
+        # the amendment the checks come from, or None for the list the contract was filed
+        # with, and the note that says why (an amendment is a decision on the record)
+        "acceptance_amended_by": amended_by,
+        "acceptance_amended_note": amended_note,
         "updates": [{"ts": u["ts"], "status": u["body"]["status"], "by": u["author"].get("harness"), "note": u["body"].get("note")} for u in updates],
         "acceptance_runs": [],
         "last_acceptance_ok": False,
@@ -560,7 +699,7 @@ def status_of(ledger, contract_id: str, assessment: Optional[dict] = None) -> di
 
 def run_acceptance(ledger, contract_id: str, cwd: Optional[str] = None, timeout: Optional[float] = 600,
                    author: Optional[dict] = None, scope: Optional[dict] = None, file: bool = True,
-                   policy: Optional[dict] = None) -> List[dict]:
+                   policy: Optional[dict] = None, checks: Optional[List[dict]] = None) -> List[dict]:
     """Run each acceptance check and return [{check, outcome, detail, receipt_body, receipt}].
 
     With ``file=True`` and an author and scope, the command/test receipts and a
@@ -588,7 +727,12 @@ def run_acceptance(ledger, contract_id: str, cwd: Optional[str] = None, timeout:
     except ev.SandboxError as exc:  # asked for and malformed: no check runs at all
         sandbox, unsandboxable = None, str(exc)
     results = []
-    for check in rec["body"]["acceptance"]:
+    # what this runner saw when it started (PROTOCOL 4.1: the status its runner read before
+    # the checks ran), as the remote lane reads it, never a status a close filed mid-run
+    started = status_now(ledger, contract_id) if file and author and scope else None
+    # the checks it answers to now (``acceptance_of``); a caller whose ledger holds no
+    # updates (the remote lane's served view) passes the list the replica reports
+    for check in (checks if checks is not None else acceptance_of(ledger, contract_id)[0]):
         kind = check.get("kind")
         if kind == "command":
             where = ev.resolved_directory(base / check["cwd"] if check.get("cwd") else base,
@@ -646,7 +790,7 @@ def run_acceptance(ledger, contract_id: str, cwd: Optional[str] = None, timeout:
             body = r.get("receipt_body")
             if body and body.get("kind") in ("command", "test"):
                 r["receipt"] = ledger.append(new_record("evidence", author, scope, body))["id"]
-        status = status_now(ledger, contract_id)  # what this runner saw: a run reports, it never promotes
+        status = started  # what this runner saw when it started: a run reports, it never promotes
         body = {
             "contract": contract_id,
             "status": status,

{strata_agent_memory-0.2.6 → strata_agent_memory-0.2.7}/agent_memory/evidence.py

@@ -2150,6 +2150,11 @@ def _check_binding(body: dict, cwd: Optional[str] = None, strict: bool = False,
                                  f"without it): bind it, even at 0, with `agent-memory run --var "
                                  f"{gate} -- ...`")
             cmd, run_env, variables = body["cmd"], None, bound
+            if unsets and not body.get("shell"):
+                # what the receipt's `env -u` takes away is not in the environment the command
+                # runs in, so not on a sandbox's podman line either (LANG, TZ); a shell line's
+                # prefix is the shell's guess, and it unsets for its first command only
+                run_env = {k: v for k, v in os.environ.items() if k not in unsets}
             if bound is not None or assigned:
                 # exactly the receipt's SIT_* switches, however it bound them, and none of
                 # the verifier's own; never its place variables (SIT_PLACE_VARS)
@@ -2365,8 +2370,11 @@ def recheck_claim(ledger, claim: dict, cwd: Optional[str] = None, strict: bool =
         role = binding_role(body)
         if role != "proof":
             entry["role"] = role
-            if body.get("path"):
-                entry["path"] = body["path"]
+        # a file's path rides on its result whatever its role: a reader deciding whether that
+        # file was re-checked in a given tree needs the path, not the claim's other bindings
+        # (recheck.away_from_bound; the review of #146)
+        if body.get("path") and (role != "proof" or body.get("kind") == "file"):
+            entry["path"] = body["path"]
         if rid:
             answered.add(rid)
         results.append(entry)