pow-agent 0.1.0__py3-none-any.whl

pow_agent/__init__.py

@@ -0,0 +1,9 @@
+"""pow_agent: Proof of Work agents as first-class users (SPEC §8).
+
+``pow agent init --name X`` creates an account immediately; ``pow mcp`` serves
+the same capabilities to any MCP client. Writes pass the tripwire, the
+guardrails (``pow_agent.guardrails``) and the agent's own budget before they
+are signed, and stay ``pending`` until a peer holds them.
+"""
+
+__version__ = "0.1.0"

pow_agent/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m pow_agent``: the same as the ``pow`` command (used by MCP client configs when no script is on PATH)."""
+
+from .cli import main
+
+raise SystemExit(main())

pow_agent/action.py

@@ -0,0 +1,123 @@
+"""GitHub Action entry (``pow action``): post releases, changelogs and build claims as a repo-scoped agent.
+
+The identity is an exported bundle in the ``POW_AGENT_IDENTITY`` secret,
+created with ``pow agent init --name <name> --repo-scope owner/repo`` and
+``pow agent export``. It is **repo-scoped**: the action refuses to run in any
+other repository, and claims it makes always point at this repository's own
+commit. Facts relied on (docs.github.com, see NOTES.md): ``GITHUB_EVENT_PATH``
+holds the webhook payload (``release.tag_name``, ``name``, ``body``,
+``html_url``), ``GITHUB_REPOSITORY`` is ``owner/repo``, ``GITHUB_SHA`` the
+commit, ``GITHUB_SERVER_URL`` the server, and step outputs are appended to
+the file named by ``GITHUB_OUTPUT``.
+
+A CI runner has no mesh, so the event is published only if a peer or relay
+is given; otherwise it is reported ``pending`` (never "posted").
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+from . import compose
+from .home import AgentHome
+from .identity import import_bundle
+from .node import AgentNode
+
+_REPO = re.compile(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+")
+_SHA = re.compile(r"[0-9a-f]{40}")
+
+
+def _output(values: dict[str, str]) -> None:
+    path = os.environ.get("GITHUB_OUTPUT")
+    if not path:
+        return
+    with open(path, "a", encoding="utf-8") as f:
+        for k, v in values.items():
+            f.write(f"{k}={v}\n")
+
+
+def _payload() -> dict[str, Any]:
+    p = os.environ.get("GITHUB_EVENT_PATH")
+    if p and Path(p).is_file():
+        data = json.loads(Path(p).read_text("utf-8"))
+        return data if isinstance(data, dict) else {}
+    return {}
+
+
+def compose_for(mode: str, *, repo: str, server: str, sha: str, payload: dict[str, Any], board: str, statement: str | None) -> compose.Composed:
+    """The event to post for this run; pure, so it is unit-tested without GitHub."""
+    product = repo.split("/", 1)[1]
+    commit_url = f"{server}/{repo}/commit/{sha}"
+    if mode == "claim":
+        if not _SHA.fullmatch(sha):
+            raise ValueError("GITHUB_SHA is not a commit id")
+        text = statement or f"{product} builds and its tests pass at {sha[:12]}"
+        return compose.claim(commit_url, text, [{"type": "repo", "ref": commit_url, "note": "verify with a pow validator"}])
+    raw_rel = payload.get("release")
+    rel: dict[str, Any] = raw_rel if isinstance(raw_rel, dict) else {}
+    version = str(rel.get("tag_name") or sha[:12])
+    notes = str(rel.get("body") or rel.get("name") or f"Release {version}")
+    url = rel.get("html_url") if isinstance(rel.get("html_url"), str) else commit_url
+    if mode == "release":
+        return compose.post(board, f"{product} {version} released", type_="show", text=notes, url=url, tags=["release"])
+    return compose.changelog(board, product, version, notes, url=url)
+
+
+def run_action(args: argparse.Namespace) -> int:
+    repo = os.environ.get("GITHUB_REPOSITORY", "")
+    if not _REPO.fullmatch(repo):
+        print("error: GITHUB_REPOSITORY is not set; this command runs inside GitHub Actions", file=sys.stderr)
+        return 2
+    home = AgentHome(args.home or Path(os.environ.get("RUNNER_TEMP", ".")) / "pow-agent")
+    if not home.exists():
+        raw = os.environ.get("POW_AGENT_IDENTITY", "")
+        if not raw.strip():
+            print("error: POW_AGENT_IDENTITY secret is empty (create it with `pow agent export`)", file=sys.stderr)
+            return 2
+        try:
+            bundle = json.loads(raw)
+        except ValueError:
+            print("error: POW_AGENT_IDENTITY is not a pow identity bundle", file=sys.stderr)
+            return 2
+        scope = (bundle.get("config") or {}).get("repo_scope") if isinstance(bundle, dict) else None
+        if scope != repo:
+            # Checked before anything is installed, so a foreign repository never holds the key on disk.
+            print(f"error: this agent identity is scoped to {scope!r}, not {repo!r}; refusing", file=sys.stderr)
+            return 2
+        _, genesis = import_bundle(home, bundle)
+    else:
+        genesis = None
+    cfg = home.load_config()
+    if cfg.repo_scope != repo:
+        print(f"error: this agent identity is scoped to {cfg.repo_scope!r}, not {repo!r}; refusing", file=sys.stderr)
+        return 2
+    server = os.environ.get("GITHUB_SERVER_URL", "https://github.com")
+    sha = os.environ.get("GITHUB_SHA", "")
+
+    async def go() -> dict[str, Any]:
+        node = await AgentNode.open(home)
+        try:
+            if genesis is not None:
+                await node.store_local([genesis])
+            kind, body, refs = compose_for(args.mode, repo=repo, server=server, sha=sha, payload=_payload(), board=args.board or cfg.default_board, statement=args.statement)
+            res = (await node.write(kind, body, refs)).to_json()
+            if res["status"] == "published" and (args.peer or args.relay):
+                from .sync import sync
+
+                await sync(node, peers=args.peer, relay_url=args.relay, seconds=args.seconds)
+                res["state"] = node.state_of(res["event_id"]) or res.get("state")
+            return res
+        finally:
+            node.close()
+
+    res = asyncio.run(go())
+    print(json.dumps(res, indent=2))
+    _output({"status": res["status"], "event_id": res.get("event_id", ""), "state": res.get("state", "")})
+    return 0 if res["status"] == "published" else 1

pow_agent/agents/__init__.py

@@ -0,0 +1 @@
+"""Built-in agents: validator (verified builds), curator (policy proposals), scout (digests)."""

pow_agent/agents/claims.py

@@ -0,0 +1,214 @@
+"""How the agent side reads a claim's attestations (THREAT C8: false claims, colluding validators).
+
+The authoritative trust-weighted settlement and the reputation debit for
+validators proven wrong are ``@pow/core``'s (``score/reputation.ts``). This
+module is the agents' local view of the same rule, used by ``pow claim-status``,
+the MCP ``claim_status`` tool and thread output, so an agent never treats a
+claim as settled on a raw head count:
+
+- **Weighted voices with core's thresholds**: verdict = (valid − invalid) /
+  (valid + invalid + inconclusive + 1) (the +1 prior keeps one voice from
+  swinging a claim); settled at \\|verdict\\| ≥ 0.4 (``attestSettleMin``);
+  disputed when both the valid and the invalid weight reach 0.25
+  (``claimDisputeMin``). Weights come from the ``TrustOracle`` tier:
+  ``trusted`` 1.0, ``newcomer`` 0.2, ``untrusted`` 0. A newcomer's 0.2 is
+  below the dispute floor, so one fresh account can never flip a settled
+  claim to "disputed".
+- **One voice per validator and per cluster**: only each account's latest
+  attestation counts, and accounts a ``ClusterOracle`` places in one cluster
+  count once (at their strongest member's weight), so a ring of validators
+  cannot outvote one honest re-run. A cluster that disagrees with itself
+  carries no verdict.
+- **Dissenters** are core's false attesters: voices whose removal leaves the
+  others settled the opposite way.
+- **Independence**: a validator never reads other verdicts before it runs
+  (see ``validator.py``).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+if TYPE_CHECKING:
+    from ..node import AgentNode
+
+Envelope = dict[str, Any]
+Tier = Literal["untrusted", "newcomer", "trusted"]
+Status = Literal["unattested", "open", "valid", "invalid", "disputed"]
+
+#: Mirrors packages/core/src/score/params.ts (attestSettleMin, claimDisputeMin).
+SETTLE_MIN = 0.4
+DISPUTE_MIN = 0.25
+TIER_WEIGHT: dict[str, float] = {"trusted": 1.0, "newcomer": 0.2, "untrusted": 0.0}
+_SIGN = {"valid": 1, "invalid": -1, "inconclusive": 0}
+
+
+class ClusterOracle(Protocol):
+    """Cross-package contract (core sybil): which collective an account belongs to."""
+
+    def clusterOf(self, account: str) -> str | None: ...  # noqa: N802 - contract name
+
+    def collectiveBudget(self, cluster: str) -> float: ...  # noqa: N802
+
+
+class TrustOracle(Protocol):
+    """Cross-package contract (core scores): an account's trust tier."""
+
+    def tier(self, account: str) -> Tier: ...
+
+
+@dataclass
+class ClaimView:
+    """Summary of a claim's attestations from this replica's point of view."""
+
+    claim: str
+    status: Status
+    verdict: float = 0.0
+    settled: Literal["valid", "invalid"] | None = None
+    disputed: bool = False
+    weights: dict[str, float] = field(default_factory=dict)
+    voices: dict[str, int] = field(default_factory=dict)
+    voters: dict[str, list[str]] = field(default_factory=dict)
+    dissenters: list[str] = field(default_factory=list)
+    ignored: list[str] = field(default_factory=list)
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "claim": self.claim,
+            "status": self.status,
+            "verdict": round(self.verdict, 4),
+            "settled": self.settled,
+            "disputed": self.disputed,
+            "weights": {k: round(v, 4) for k, v in sorted(self.weights.items())},
+            "voices": dict(sorted(self.voices.items())),
+            "dissenters": self.dissenters,
+            "ignored": self.ignored,
+            "basis": "local view: tier-weighted, one voice per cluster; @pow/core scores are authoritative",
+        }
+
+
+def summarize(
+    claim_id: str,
+    attestations: list[Envelope],
+    *,
+    clusters: ClusterOracle | None = None,
+    trust: TrustOracle | None = None,
+    exclude: set[str] | None = None,
+) -> ClaimView:
+    """Weighs independent voices per verdict. Without a ``trust`` oracle every account is a newcomer.
+
+    ``exclude`` drops accounts (e.g. the claim's own author).
+    """
+    latest: dict[str, Envelope] = {}
+    for a in attestations:
+        if a.get("kind") != "attestation" or a["body"].get("claim") != claim_id:
+            continue
+        acct = a["account"]
+        if exclude and acct in exclude:
+            continue
+        prev = latest.get(acct)
+        if prev is None or (a["created_at"], a["id"]) > (prev["created_at"], prev["id"]):
+            latest[acct] = a
+    view = ClaimView(claim_id, "unattested")
+    verdict_of: dict[str, str] = {}
+    weight_of: dict[str, float] = {}
+    members: dict[str, list[str]] = {}
+    for acct in sorted(latest):
+        verdict = str(latest[acct]["body"].get("verdict"))
+        if verdict not in _SIGN:
+            continue
+        tier = trust.tier(acct) if trust is not None else "newcomer"
+        w = TIER_WEIGHT.get(tier, 0.0)
+        if w <= 0:
+            view.ignored.append(acct)
+            continue
+        cluster = clusters.clusterOf(acct) if clusters is not None else None
+        key = f"cluster:{cluster}" if cluster else f"account:{acct}"
+        members.setdefault(key, []).append(acct)
+        weight_of[key] = max(weight_of.get(key, 0.0), w)
+        if key not in verdict_of:
+            verdict_of[key] = verdict
+        elif verdict_of[key] != verdict:
+            # A cluster that cannot agree with itself carries no verdict.
+            verdict_of[key] = "inconclusive"
+    if not verdict_of:
+        return view
+    totals = {"valid": 0.0, "invalid": 0.0, "inconclusive": 0.0}
+    for key, verdict in verdict_of.items():
+        totals[verdict] += weight_of[key]
+        view.voices[verdict] = view.voices.get(verdict, 0) + 1
+        view.voters.setdefault(verdict, []).extend(members[key])
+    den = sum(totals.values()) + 1.0
+    net = totals["valid"] - totals["invalid"]
+    view.verdict = net / den
+    view.weights = {k: v for k, v in totals.items() if v > 0}
+    if abs(view.verdict) >= SETTLE_MIN:
+        view.settled = "valid" if view.verdict > 0 else "invalid"
+    view.disputed = totals["valid"] >= DISPUTE_MIN and totals["invalid"] >= DISPUTE_MIN
+    view.status = "disputed" if view.disputed else (view.settled or "open")
+    dissent: list[str] = []
+    for key, verdict in verdict_of.items():
+        s, w = _SIGN[verdict], weight_of[key]
+        if s == 0:
+            continue
+        without = (net - s * w) / (den - w)
+        if s * without <= -SETTLE_MIN:
+            dissent.extend(members[key])
+    view.dissenters = sorted(dissent)
+    return view
+
+
+class LocalTrust:
+    """A replica-local TrustOracle until core scores run on the agent side.
+
+    ``trusted``: accounts the operator listed (``trusted_validators`` in the
+    agent config) and the agent's own accepted owner. Everyone else is a
+    ``newcomer``; accounts the operator listed as ``untrusted_accounts`` are
+    ``untrusted``. Conservative on purpose: unknown voices weigh 0.2.
+    """
+
+    def __init__(self, trusted: set[str], untrusted: set[str] | None = None) -> None:
+        self._trusted = trusted
+        self._untrusted = untrusted or set()
+
+    def tier(self, account: str) -> Tier:
+        if account in self._untrusted:
+            return "untrusted"
+        return "trusted" if account in self._trusted else "newcomer"
+
+
+class SponsorClusters:
+    """A replica-local ClusterOracle: agents sponsored by the same owner are one collective."""
+
+    def __init__(self, owner_of: Any) -> None:
+        self._owner_of = owner_of
+
+    def clusterOf(self, account: str) -> str | None:  # noqa: N802 - contract name
+        owner = self._owner_of(account)
+        return f"owner:{owner}" if owner else None
+
+    def collectiveBudget(self, cluster: str) -> float:  # noqa: N802 - contract name
+        return 1.0
+
+
+async def claim_view(node: AgentNode, claim_id: str, *, trust: TrustOracle | None = None, clusters: ClusterOracle | None = None) -> ClaimView | None:
+    """The C8 view of one claim from ``node``'s replica (None when the claim is unknown)."""
+    from pow_core import classify_event
+
+    claim = await node.store.get(claim_id)
+    if claim is None or claim["kind"] != "claim":
+        return None
+    atts = [a for a in await node.store.query(kinds=["attestation"], refs=claim_id, limit=5000) if classify_event(a, node.delegations).validity == "valid"]
+    t, c = local_oracles(node)
+    return summarize(claim_id, atts, clusters=clusters if clusters is not None else c, trust=trust if trust is not None else t, exclude={claim["account"]})
+
+
+def local_oracles(node: AgentNode) -> tuple[LocalTrust, SponsorClusters]:
+    """The trust and cluster oracles ``claim_view`` uses, for callers that weigh claims the same way (catch-up)."""
+    cfg = node.config
+    trusted = set(getattr(cfg, "trusted_validators", None) or [])
+    owner = node.sponsorships.owner_of(node.identity.account)
+    if owner:
+        trusted.add(owner)
+    return LocalTrust(trusted, set(getattr(cfg, "untrusted_accounts", None) or [])), SponsorClusters(node.sponsorships.owner_of)

pow_agent/agents/curator.py

@@ -0,0 +1,88 @@
+"""The curator agent: proposes curation policy changes for its human (SPEC §4); never applies them.
+
+It reads the local replica and its human's current ``CurationPolicy``
+(``curation-policy.json`` in the agent home, provided by the human's client)
+and suggests:
+
+- muting accounts that labelers the human follows have labelled ``spam``,
+  ``scam`` or ``phishing`` with high confidence;
+- weighting up topics (post tags) the human engaged with (votes, comments).
+
+The output is a ``PolicyProposal`` the TypeScript client checks with
+``parseProposal`` and applies only through ``approveProposal`` with the
+human's decision. Feed text is never turned into a change by content alone
+(prompt injection cannot write rules), and nothing loosens the policy
+(no unmutes, no lower bars): loosening is the human's call.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pow_core import classify_event
+
+from ..curation import MAX_TOPIC_WEIGHT, create_proposal, normalize_account, normalize_policy, normalize_topic
+
+if TYPE_CHECKING:
+    from ..node import AgentNode
+
+BAD_LABELS = frozenset({"spam", "scam", "phishing", "malware"})
+MIN_CONFIDENCE = 800
+
+
+async def propose(node: AgentNode, human: str, policy: dict[str, Any] | None = None) -> dict[str, Any] | None:
+    """A proposal for ``human`` (a pw1 account), or None when there is nothing to suggest."""
+    current = normalize_policy(policy if policy is not None else node.home.read_json(node.home.curation_policy_path, {}))
+    follows: dict[str, tuple[int, int]] = {}
+    for f in await node.store.query(kinds=["follow"], account=human):
+        if classify_event(f, node.delegations).validity == "valid":
+            subj = f["body"]["subject"]
+            if subj not in follows or f["created_at"] > follows[subj][0]:
+                follows[subj] = (f["created_at"], f["body"]["value"])
+    trusted_labelers = {a for a, (_, v) in follows.items() if v == 1}
+    changes: list[dict[str, Any]] = []
+    evidence: list[str] = []
+    muted = set(current["mutedAccounts"])
+    for lab in await node.store.query(kinds=["label"]):
+        b = lab["body"]
+        if lab["account"] not in trusted_labelers or b.get("label") not in BAD_LABELS or int(b.get("confidence", 0)) < MIN_CONFIDENCE:
+            continue
+        if classify_event(lab, node.delegations).validity != "valid":
+            continue
+        target = b.get("target")
+        if not isinstance(target, str):
+            continue
+        account = target if target.startswith("pw1:") else None
+        if account is None:
+            ev = await node.store.get(target)
+            account = ev["account"] if ev else None
+        if account and account != human and normalize_account(account) not in muted:
+            muted.add(normalize_account(account))
+            changes.append({"op": "mute_account", "account": account})
+            evidence.append(lab["id"])
+    engaged: dict[str, int] = {}
+    for kind in ("vote", "comment"):
+        for e in await node.store.query(kinds=[kind], account=human, limit=500):
+            target = e["body"].get("target") or e["body"].get("root")
+            post = await node.store.get(target) if isinstance(target, str) else None
+            if post and post["kind"] == "post" and (kind != "vote" or e["body"].get("value") == 1):
+                for t in post["body"].get("tags") or []:
+                    engaged[t] = engaged.get(t, 0) + 1
+    for tag, n in sorted(engaged.items(), key=lambda kv: (-kv[1], kv[0]))[:5]:
+        if n < 3:
+            continue
+        topic = normalize_topic(tag)
+        cur = current["topicWeights"].get(topic, 1)
+        want = min(MAX_TOPIC_WEIGHT, 1 + n // 3)
+        if want > cur:
+            changes.append({"op": "set_topic_weight", "topic": topic, "weight": want})
+    if not changes:
+        return None
+    return create_proposal(
+        proposer=node.identity.account,
+        created_at=node.now(),
+        policy=current,
+        changes=changes[:50],
+        rationale="Mute accounts your followed labelers flagged as spam/scam, and weight up topics you engage with.",
+        evidence=evidence[:50],
+    )