succession-cli 0.2.0__py3-none-any.whl

succession/__init__.py

@@ -0,0 +1,52 @@
+"""Succession — the property layer for agent memory.
+
+Public surface:
+
+    from succession import export_tenant, import_package, open_tenant
+
+Everything else is reachable through the submodules: :mod:`succession.smp` for
+the package format, :mod:`succession.merkle` for the integrity scheme,
+:mod:`succession.valuation`, :mod:`succession.dataroom`, :mod:`succession.seal`,
+and :mod:`succession.certificate`.
+"""
+
+from .canonical import canonical_bytes, canonical_json
+from .export import ExportResult, build_package, export_tenant, read_all
+from .importer import ImportResult, IntegrityMismatch, import_package, verify_package
+from .memory.sibyl import SibylMemory, open_tenant
+from .merkle import MerkleTree, build_tree, to_hex, verify_proof
+from .provenance import SignatureError, sign_header, verify_header
+from .redaction import Disclosure, Sensitivity, mark, read_disclosure
+from .smp import DATA_CATEGORIES, SMP_CATEGORIES, SMP_VERSION, SMPPackage
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "DATA_CATEGORIES",
+    "SMP_CATEGORIES",
+    "SMP_VERSION",
+    "Disclosure",
+    "ExportResult",
+    "ImportResult",
+    "IntegrityMismatch",
+    "MerkleTree",
+    "SMPPackage",
+    "Sensitivity",
+    "SibylMemory",
+    "SignatureError",
+    "build_package",
+    "build_tree",
+    "canonical_bytes",
+    "canonical_json",
+    "export_tenant",
+    "import_package",
+    "mark",
+    "open_tenant",
+    "read_all",
+    "read_disclosure",
+    "sign_header",
+    "to_hex",
+    "verify_header",
+    "verify_package",
+    "verify_proof",
+]

succession/acp.py

@@ -0,0 +1,522 @@
+"""Virtuals ACP — verifiable job history as the quality-of-earnings signal.
+
+The build spec is specific about why this matters: a listing should surface the
+agent's "real, independently verifiable ACP job history" so a buyer gets a
+signal they can check **without trusting the seller's word**. Succession's own
+data-room aggregates are computed from the seller's own memory — useful, but
+self-reported. ACP job history is not: every record here carries an on-chain
+job id against the ACP contract on Base, so a buyer (or a judge) can verify the
+counts independently.
+
+Three things this feeds, none of them decorative:
+
+1. **The data room.** Completed job count, gross volume, and distinct
+   counterparties come from ACP, shown beside the self-reported figures and
+   labelled for what each one is.
+2. **The valuation.** ``task_performance`` prefers the ACP completed-versus-
+   cancelled ratio over the journal-text heuristic whenever job history is
+   available. Real settlement outcomes beat guessing from strings.
+3. **The memory asset itself.** Job history is synced into Sibyl Memory as
+   ``acp-job`` entities, so it travels with the sale. The buyer inherits a
+   verifiable earnings record, not just a claim about one — which is precisely
+   what makes the customer book worth something.
+
+Registration is a precondition, not a detail: ACP will not let an unregistered
+agent be discovered or hired, so :func:`require_registered` gates listing.
+
+The SDK import is deliberately lazy. ``virtuals-acp`` pulls a socket client and
+wants wallet credentials at construction time; a contributor running the test
+suite should not need either.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from eth_utils import to_checksum_address
+from decimal import Decimal
+from typing import Any, Iterable, Protocol, runtime_checkable
+
+__all__ = [
+    "ACPJobRecord",
+    "ACPJobHistory",
+    "ACPSource",
+    "LiveACP",
+    "RecordedACP",
+    "ACPNotConfigured",
+    "AgentNotRegistered",
+    "require_registered",
+    "build_handover",
+    "verify_handover",
+    "sync_job_history",
+    "job_history_from_memory",
+]
+
+#: ACP job phases, from ``virtuals_acp.models.ACPJobPhase``. Mirrored rather
+#: than imported so reading history never drags in the socket client.
+PHASE_COMPLETED = 4
+PHASE_REJECTED = 5
+PHASE_EXPIRED = 6
+
+#: The Sibyl category ACP history is mirrored into. Routed to ``history/`` by
+#: the SMP category map, so it transfers with the sale like any other record.
+ACP_CATEGORY = "acp-job"
+
+
+class ACPNotConfigured(RuntimeError):
+    """No ACP credentials in the environment."""
+
+
+class AgentNotRegistered(RuntimeError):
+    """The agent is not on the ACP service registry, so it cannot be listed."""
+
+
+@dataclass(frozen=True)
+class ACPJobRecord:
+    """One ACP job, reduced to what a buyer can independently verify.
+
+    ``onchain_job_id`` is the point of this record. Everything else here is a
+    convenience; the id is what lets someone re-read the job from the ACP
+    contract and confirm the seller did not invent it.
+    """
+
+    onchain_job_id: int
+    phase: int
+    price: str            # decimal string — floats do not survive canonicalization
+    token: str
+    client_address: str
+    provider_address: str
+    evaluator_address: str
+    contract_address: str
+    settled_at: str = ""
+
+    @property
+    def completed(self) -> bool:
+        return self.phase == PHASE_COMPLETED
+
+    @property
+    def failed(self) -> bool:
+        return self.phase in (PHASE_REJECTED, PHASE_EXPIRED)
+
+    def counterparty(self, agent_address: str) -> str:
+        """The other side of this job, from ``agent_address``'s point of view."""
+        me = agent_address.lower()
+        return (
+            self.client_address
+            if self.provider_address.lower() == me
+            else self.provider_address
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "onchain_job_id": self.onchain_job_id,
+            "phase": self.phase,
+            "price": self.price,
+            "token": self.token,
+            "client_address": self.client_address,
+            "provider_address": self.provider_address,
+            "evaluator_address": self.evaluator_address,
+            "contract_address": self.contract_address,
+            "settled_at": self.settled_at,
+        }
+
+    @classmethod
+    def from_dict(cls, blob: dict[str, Any]) -> "ACPJobRecord":
+        return cls(**{k: blob[k] for k in blob if k in cls.__dataclass_fields__})
+
+    @classmethod
+    def from_sdk(cls, job: Any) -> "ACPJobRecord":
+        """Convert a ``virtuals_acp.job.ACPJob``.
+
+        ``price`` arrives as a float from the SDK and is stringified through
+        Decimal here: the canonical serializer rejects floats outright, and an
+        earnings figure that renders differently on two machines would break the
+        integrity hash of any memory carrying it.
+        """
+        return cls(
+            onchain_job_id=int(job.id),
+            phase=int(getattr(job.phase, "value", job.phase)),
+            price=str(Decimal(str(job.price))),
+            token=str(getattr(job, "price_token_address", "") or ""),
+            client_address=str(job.client_address),
+            provider_address=str(job.provider_address),
+            evaluator_address=str(getattr(job, "evaluator_address", "") or ""),
+            contract_address=str(getattr(job, "contract_address", "") or ""),
+        )
+
+
+@dataclass(frozen=True)
+class ACPJobHistory:
+    """The quality-of-earnings signal, derived from ACP rather than from memory."""
+
+    agent_address: str
+    agent_id: int | None = None
+    agent_name: str = ""
+    registered: bool = False
+    jobs: tuple[ACPJobRecord, ...] = ()
+    fetched_at: str = ""
+    source: str = "live"      # "live" | "memory" | "recorded"
+
+    @property
+    def completed(self) -> list[ACPJobRecord]:
+        return [j for j in self.jobs if j.completed]
+
+    @property
+    def failed(self) -> list[ACPJobRecord]:
+        return [j for j in self.jobs if j.failed]
+
+    @property
+    def gross_volume(self) -> Decimal:
+        return sum((Decimal(j.price) for j in self.completed), Decimal(0))
+
+    @property
+    def counterparties(self) -> set[str]:
+        return {j.counterparty(self.agent_address) for j in self.completed}
+
+    def success_rate(self) -> Decimal | None:
+        """Completed over resolved. ``None`` when the sample is too small.
+
+        The same five-outcome floor the journal heuristic uses: two-for-two is
+        not a 100% success rate, it is a small sample, and a valuation that
+        treats it as one is wrong in the seller's favour.
+        """
+        resolved = len(self.completed) + len(self.failed)
+        if resolved < 5:
+            return None
+        return Decimal(len(self.completed)) / Decimal(resolved)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "agent_address": self.agent_address,
+            "agent_id": self.agent_id,
+            "agent_name": self.agent_name,
+            "registered": self.registered,
+            "source": self.source,
+            "fetched_at": self.fetched_at,
+            "completed_jobs": len(self.completed),
+            "failed_jobs": len(self.failed),
+            "gross_volume": str(self.gross_volume),
+            "distinct_counterparties": len(self.counterparties),
+            "success_rate": (
+                str(self.success_rate()) if self.success_rate() is not None else None
+            ),
+            "verifiable_job_ids": sorted(j.onchain_job_id for j in self.completed),
+            "verification": (
+                "Each job id resolves against the ACP contract on Base Sepolia; "
+                "these counts can be re-derived without trusting the seller."
+            ),
+        }
+
+
+@runtime_checkable
+class ACPSource(Protocol):
+    """Where job history comes from."""
+
+    def agent(self) -> dict[str, Any] | None: ...
+    def jobs(self) -> list[ACPJobRecord]: ...
+
+
+class LiveACP:
+    """Reads job history from the real ACP API via ``virtuals-acp``.
+
+    Construction needs a whitelisted agent wallet, its private key, and the
+    agent's ACP entity id — the three things the ACP Tech Playbook issues when
+    an agent is registered. They are read from the environment because a private
+    key on a command line lands in shell history.
+    """
+
+    ENV = ("WHITELISTED_WALLET_PRIVATE_KEY", "AGENT_WALLET_ADDRESS", "ACP_ENTITY_ID")
+
+    def __init__(self, *, page_size: int = 100, max_pages: int = 20) -> None:
+        missing = [name for name in self.ENV if not os.environ.get(name)]
+        if missing:
+            raise ACPNotConfigured(
+                "ACP credentials missing from the environment: "
+                + ", ".join(missing)
+                + ". Register the agent with the ACP Tech Playbook first — an "
+                "unregistered agent cannot be discovered or hired."
+            )
+        self.page_size = page_size
+        self.max_pages = max_pages
+        self._client: Any = None
+
+    @property
+    def client(self) -> Any:
+        if self._client is None:
+            # Imported here, not at module scope: the SDK opens a socket
+            # connection and wants credentials the test suite does not have.
+            from virtuals_acp import VirtualsACP
+            from virtuals_acp.configs import BASE_SEPOLIA_CONFIG
+            from virtuals_acp.contract_clients.contract_client import AcpContractClient
+
+            contract = AcpContractClient(
+                wallet_private_key=os.environ["WHITELISTED_WALLET_PRIVATE_KEY"],
+                agent_wallet_address=os.environ["AGENT_WALLET_ADDRESS"],
+                config=BASE_SEPOLIA_CONFIG,
+                entity_id=int(os.environ["ACP_ENTITY_ID"]),
+            )
+            # skip_socket_connection: this is a read path. Opening a live task
+            # socket to count finished jobs would leave a listener running for
+            # the lifetime of a CLI invocation.
+            self._client = VirtualsACP(contract, skip_socket_connection=True)
+        return self._client
+
+    @property
+    def wallet_address(self) -> str:
+        return str(self.client.wallet_address)
+
+    def agent(self) -> dict[str, Any] | None:
+        record = self.client.get_agent(self.wallet_address)
+        if record is None:
+            return None
+        return {
+            "id": getattr(record, "id", None),
+            "name": getattr(record, "name", ""),
+            "description": getattr(record, "description", ""),
+            "wallet_address": getattr(record, "wallet_address", self.wallet_address),
+            "cluster": getattr(record, "cluster", None),
+            "twitter_handle": getattr(record, "twitter_handle", None),
+        }
+
+    def jobs(self) -> list[ACPJobRecord]:
+        """Every settled job: completed and cancelled both.
+
+        Fetching only the completed ones would make the success rate a
+        tautology — you cannot compute a ratio from the numerator.
+        """
+        out: list[ACPJobRecord] = []
+        for fetch in (self.client.get_completed_jobs, self.client.get_cancelled_jobs):
+            out.extend(self._page(fetch))
+        return out
+
+    def _page(self, fetch: Any) -> Iterable[ACPJobRecord]:
+        for page in range(1, self.max_pages + 1):
+            batch = fetch(page=page, page_size=self.page_size)
+            if not batch:
+                return
+            for job in batch:
+                yield ACPJobRecord.from_sdk(job)
+            if len(batch) < self.page_size:
+                return
+
+
+class RecordedACP:
+    """Replays a snapshot previously fetched from the live API.
+
+    For offline development and for the hosted build. It is honest only because
+    the snapshot is real API output and the history it produces is labelled
+    ``source="recorded"`` all the way to the UI — never presented as live.
+    """
+
+    def __init__(self, snapshot: dict[str, Any]) -> None:
+        self.snapshot = snapshot
+
+    @classmethod
+    def from_file(cls, path: str) -> "RecordedACP":
+        with open(path, encoding="utf-8") as handle:
+            return cls(json.load(handle))
+
+    def agent(self) -> dict[str, Any] | None:
+        return self.snapshot.get("agent")
+
+    def jobs(self) -> list[ACPJobRecord]:
+        return [ACPJobRecord.from_dict(j) for j in self.snapshot.get("jobs", [])]
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def fetch_history(source: ACPSource, *, agent_address: str = "") -> ACPJobHistory:
+    """Pull job history from any source into the neutral shape."""
+    agent = source.agent()
+    jobs = tuple(source.jobs())
+    address = agent_address or (agent or {}).get("wallet_address", "")
+    return ACPJobHistory(
+        agent_address=str(address),
+        agent_id=(agent or {}).get("id"),
+        agent_name=(agent or {}).get("name", ""),
+        registered=agent is not None,
+        jobs=jobs,
+        fetched_at=_utc_now(),
+        source="recorded" if isinstance(source, RecordedACP) else "live",
+    )
+
+
+def require_registered(history: ACPJobHistory) -> None:
+    """Gate listing on ACP registration.
+
+    ACP will not let an unregistered agent be discovered or hired, so listing
+    one for transfer would be selling an identity that cannot trade. Checking
+    at listing time rather than at settlement keeps a buyer's funds out of
+    escrow against a sale that could never complete — the same reasoning the
+    ListingContract applies to registry approval.
+    """
+    if not history.registered:
+        raise AgentNotRegistered(
+            f"agent {history.agent_address!r} is not on the ACP service registry; "
+            "register it via the ACP Tech Playbook before listing"
+        )
+
+
+# -- memory sync ----------------------------------------------------------
+
+
+def sync_job_history(memory: Any, history: ACPJobHistory) -> int:
+    """Mirror ACP job history into Sibyl Memory. Returns the record count.
+
+    This is what makes the integration part of the *asset* rather than a
+    decoration on the listing page. Once synced, the job history exports inside
+    the SMP package, hashes into the Merkle tree, and lands in the buyer's
+    tenant — so the successor agent inherits a verifiable earnings record, and
+    the buyer's own future resale can prove it.
+
+    Idempotent: jobs are keyed by their on-chain id, so re-syncing updates
+    rather than duplicates.
+    """
+    written = 0
+    for job in history.jobs:
+        memory.client.set_entity(
+            ACP_CATEGORY,
+            str(job.onchain_job_id),
+            {
+                **job.to_dict(),
+                "counterparty": job.counterparty(history.agent_address),
+                "source": "virtuals-acp",
+            },
+            status="completed" if job.completed else "failed",
+        )
+        written += 1
+
+    memory.client.set_entity(
+        "identity",
+        "acp-registration",
+        {
+            "agent_id": history.agent_id,
+            "agent_name": history.agent_name,
+            "wallet_address": history.agent_address,
+            "registered": history.registered,
+            "synced_at": history.fetched_at,
+            "job_count": len(history.jobs),
+        },
+    )
+    return written
+
+
+def job_history_from_memory(memory: Any) -> ACPJobHistory:
+    """Rebuild job history from a tenant's own records.
+
+    The buyer's side of the trip: after a transfer their store holds the ACP
+    records, and this reads them back without another API round trip. It is
+    also what lets the valuation use real settlement outcomes for an agent whose
+    credentials the current operator does not hold.
+    """
+    registration: dict[str, Any] = {}
+    jobs: list[ACPJobRecord] = []
+    for entity in memory.entities():
+        if entity["category"] == ACP_CATEGORY:
+            jobs.append(ACPJobRecord.from_dict(entity["body"]))
+        elif entity["category"] == "identity" and entity["name"] == "acp-registration":
+            registration = entity["body"]
+
+    return ACPJobHistory(
+        agent_address=registration.get("wallet_address", ""),
+        agent_id=registration.get("agent_id"),
+        agent_name=registration.get("agent_name", ""),
+        registered=bool(registration.get("registered")),
+        jobs=tuple(jobs),
+        fetched_at=registration.get("synced_at", ""),
+        source="memory",
+    )
+
+# -- standing handover ----------------------------------------------------
+
+#: Domain tag for a handover attestation. Distinct from the provenance and
+#: evaluation domains so one can never be replayed as another.
+HANDOVER_DOMAIN = "Succession/1.0/acp-handover"
+
+
+def build_handover(
+    *,
+    agent_identity: str,
+    entity_id: int | str,
+    agent_wallet: str,
+    buyer_identity: str,
+    buyer_address: str,
+    settlement_reference: str,
+    verified_hash: str,
+    private_key: str,
+) -> dict[str, Any]:
+    """A signed statement that a lineage's ACP standing passes to a buyer.
+
+    **This does not transfer a registration, and nothing can.** A Virtuals ACP
+    entity is issued to a wallet through the Virtuals app, and the SDK surface
+    is entirely reads, job initiation and evaluation: `browse_agents`,
+    `get_agent`, `get_completed_jobs` and so on. There is no reassign, no
+    change-owner, and no update-wallet call to make. A library that claimed
+    otherwise would be lying about someone else's system.
+
+    So this is the closest honest thing. The seller signs, with the key the
+    contract recorded as the seller, a statement naming the entity whose job
+    history is inside the memory, the buyer receiving it, and the settlement
+    that paid for it. The buyer registers their own entity and presents this as
+    evidence of where the record came from.
+
+    What the buyer actually gets is therefore in two parts, and they are worth
+    keeping distinct:
+
+    * the *record* of what the agent earned, inside the memory, hashed into the
+      Merkle tree and provable against the committed root
+    * a signed attestation of succession, which is a claim a third party can
+      verify the origin of but which no registry is obliged to honour
+
+    What they do not get is the seller's position on the registry. Stating that
+    plainly is worth more than a mechanism that implies otherwise.
+    """
+    from eth_account import Account
+    from eth_account.messages import encode_defunct
+
+    from .canonical import canonical_json
+
+    statement = {
+        "domain": HANDOVER_DOMAIN,
+        "agent_identity": agent_identity,
+        "acp_entity_id": str(entity_id),
+        "acp_agent_wallet": to_checksum_address(agent_wallet),
+        "succeeded_by": buyer_identity,
+        "succeeded_by_address": to_checksum_address(buyer_address),
+        "settlement_reference": settlement_reference,
+        "verified_hash": verified_hash,
+        "issued_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "transfers_registration": False,
+        "note": (
+            "Attests succession of the job history carried in this memory. It "
+            "does not transfer the ACP registration, which is issued to a "
+            "wallet and cannot be reassigned."
+        ),
+    }
+    signed = Account.sign_message(
+        encode_defunct(text=f"{HANDOVER_DOMAIN}\n{canonical_json(statement)}"),
+        private_key,
+    )
+    return {**statement, "signature": "0x" + signed.signature.hex().removeprefix("0x")}
+
+
+def verify_handover(handover: dict[str, Any]) -> str:
+    """Recover who signed a handover. Raises on anything malformed."""
+    from eth_account import Account
+    from eth_account.messages import encode_defunct
+
+    from .canonical import canonical_json
+
+    signature = handover.get("signature")
+    if not signature:
+        raise ValueError("handover carries no signature")
+    statement = {k: v for k, v in handover.items() if k != "signature"}
+    return Account.recover_message(
+        encode_defunct(text=f"{HANDOVER_DOMAIN}\n{canonical_json(statement)}"),
+        signature=signature,
+    )