treeship-commerce 0.28.0__py3-none-any.whl

treeship_commerce/__init__.py

@@ -0,0 +1,26 @@
+"""Treeship receipts for anthropics/commerce-agents.
+
+One shared executor runs every tool call on all three commerce-agents
+runtimes (Messages API, Agent SDK, Managed Agents). Wrapping it once gives
+every call a signed intent receipt before it runs and a signed result
+receipt after, chained from the session's root. See ``receipts.py``.
+"""
+
+from .receipts import (
+    TreeshipExecutorMixin,
+    TreeshipReceipts,
+    args_digest,
+    attach,
+    receipted,
+    text_digest,
+)
+
+__all__ = [
+    "TreeshipExecutorMixin",
+    "TreeshipReceipts",
+    "args_digest",
+    "attach",
+    "receipted",
+    "text_digest",
+]
+__version__ = "0.28.0"

treeship_commerce/demo.py

@@ -0,0 +1,127 @@
+"""A receipted shopping session over the retail mock, no model and no API key.
+
+    python -m treeship_commerce.demo            # from a clone of commerce-agents, venv active
+    python -m treeship_commerce.demo --report   # also publish, if a hub is attached
+
+Drives the reference's ``ShoppingToolExecutor`` over ``examples/retail``'s
+mock backend exactly the way the reference's own tests do, with receipts on:
+a search, a product read, an add to the cart, an add the provenance gate
+holds, and a checkout hand-off. Then it seals the Treeship session and prints
+where the package is and how to verify it. Every receipt id printed is real.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import os
+import sys
+import uuid
+
+from treeship_sdk import Treeship
+
+from . import TreeshipReceipts, attach, receipted
+from .lifecycle import close_session, session_status, start_session
+
+ACTOR = "agent://shopping"
+
+
+def _build_executor(session_id: str):
+    try:
+        from commerce_common.memory import InMemoryMemoryStore
+        from commerce_common.skills import SkillRegistry
+        from shopping_agent import ShoppingAgentConfig, ShoppingSessionContext, ShoppingSessionState
+        from shopping_agent.executor import ShoppingToolExecutor, build_memory
+        from shopping_agent_sdk import load_mock_backend
+    except ImportError as err:  # pragma: no cover - environment, not logic
+        sys.exit(
+            f"commerce-agents packages are not installed ({err}). From a clone of "
+            "anthropics/commerce-agents: pip install -r requirements.txt"
+        )
+    config = ShoppingAgentConfig(brand_name="ACME", assistant_name="Scout")
+    cls = receipted(ShoppingToolExecutor)
+    return cls(
+        backend=load_mock_backend(),
+        config=config,
+        skills=SkillRegistry([]),
+        session=ShoppingSessionContext(session_id=session_id, user_id="demo-user"),
+        state=ShoppingSessionState(),
+        memory=build_memory(config, InMemoryMemoryStore()),
+        inline_context=True,
+    )
+
+
+async def run(report: bool) -> int:
+    ts = Treeship()
+    commerce_session = f"demo-{uuid.uuid4().hex}"  # the reference treats this as a credential
+    root = start_session(ts, name="commerce:retail-demo", actor=ACTOR)
+    executor = attach(
+        _build_executor(commerce_session),
+        TreeshipReceipts(ts, actor=ACTOR, session_id=commerce_session, parent_id=root),
+    )
+    receipts: TreeshipReceipts = executor.treeship_receipts
+
+    async def call(name: str, tool_input: dict) -> None:
+        before = len(receipts.recorded)
+        outcome = await executor.execute(name, tool_input)
+        status = (
+            "blocked:" + outcome.blocked
+            if outcome.blocked
+            else ("error" if outcome.is_error else "ok")
+        )
+        new = receipts.recorded[before:]
+        ids = " ".join(new) if new else "(no receipt written)"
+        print(f"  {name:<22} {status:<20} {ids}")
+
+    tag = hashlib.sha256(commerce_session.encode()).hexdigest()[:12]
+    print(f"session root      {root}")
+    print(f"commerce session  sha256:{tag}  (tag; the id itself is never written)")
+    print("tool calls        intent-id result-id")
+    await call("search_products", {"query": "tent"})
+    seen = list(executor._state.seen_products)
+    if not seen:
+        print("the retail mock returned nothing for 'tent'; stopping")
+        return 1
+    await call("get_product_details", {"product_id": seen[0]})
+    await call("add_to_cart", {"product_id": seen[0], "quantity": 1})
+    await call("add_to_cart", {"product_id": "p-not-from-this-session", "quantity": 1})
+    await call("checkout", {"note": "Ready when you are."})
+
+    status = session_status(ts)
+    print(
+        f"\nsession           receipts={status['receipts']} events={status['events']} "
+        f"root_verified={status['root_verified']}"
+    )
+    if receipts.dropped:
+        print(f"WARNING           {receipts.dropped} receipt(s) not written; the chain has gaps")
+    sealed = close_session(
+        ts,
+        summary=(
+            f"Retail demo: {len(receipts.recorded) // 2} tool calls signed, one add held by the "
+            "provenance gate, checkout handed off. No order placed, no card charged."
+        ),
+        headline="Receipted shopping session over the ACME retail mock",
+    )
+    print(f"package           {sealed.get('package')}")
+    print(f"verify            treeship verify {receipts.head}")
+    print(f"                  treeship package verify {sealed.get('package')}")
+    if report:
+        result = ts.session_report()
+        print(f"report            {result.receipt_url}")
+    return 0 if receipts.dropped == 0 else 2
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--report", action="store_true", help="publish the session report to the attached hub"
+    )
+    args = parser.parse_args()
+    if os.environ.get("TREESHIP_DISABLE") == "1":
+        sys.exit("TREESHIP_DISABLE=1 is set; this demo exists to write receipts")
+    sys.exit(asyncio.run(run(report=args.report)))
+
+
+if __name__ == "__main__":
+    main()

treeship_commerce/lifecycle.py

@@ -0,0 +1,102 @@
+"""Treeship session lifecycle around a commerce session.
+
+The per-call receipts live in ``receipts.py``. These helpers open and seal the
+Treeship session that contains them, so a host can do::
+
+    ts = Treeship(env=env)
+    root = start_session(ts, name="storefront:retail", actor="agent://shopping")
+    receipts = TreeshipReceipts(ts, actor="agent://shopping", session_id=sid, parent_id=root)
+    ...
+    package = close_session(ts, summary="12 tool calls, 1 held by the provenance gate")
+
+They shell out to the CLI the same way the SDK does and parse the last JSON
+document on stdout, because ``attest`` may print a warning object first.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from typing import Any, Mapping, Sequence
+
+from treeship_sdk import Treeship, TreeshipError
+
+
+def _run_json(
+    client: Treeship,
+    args: Sequence[str],
+    *,
+    env: Mapping[str, str] | None = None,
+    cwd: str | os.PathLike[str] | None = None,
+) -> dict[str, Any]:
+    """Run one CLI command. ``cwd`` matters: ``session start`` and ``session
+    event`` find the workspace by walking up from the working directory, so a
+    host that runs elsewhere would start a session in the wrong tree."""
+    merged = {**os.environ, **(env or {})}
+    proc = subprocess.run(
+        [client.binary, *args, "--format", "json"],
+        capture_output=True,
+        text=True,
+        env=merged,
+        cwd=cwd,
+        timeout=60,
+    )
+    if proc.returncode != 0:
+        raise TreeshipError(
+            f"treeship {' '.join(args[:2])} failed (exit={proc.returncode}): "
+            f"{proc.stderr.strip() or proc.stdout.strip() or '<no output>'}",
+            list(args),
+        )
+    docs = [
+        json.loads(chunk)
+        for chunk in proc.stdout.replace("}\n{", "}\n\x00{").split("\x00")
+        if chunk.strip()
+    ]
+    if not docs:
+        raise TreeshipError(f"treeship {' '.join(args[:2])} printed no JSON", list(args))
+    return docs[-1]
+
+
+def start_session(
+    client: Treeship,
+    *,
+    name: str,
+    actor: str,
+    env: Mapping[str, str] | None = None,
+    cwd: str | os.PathLike[str] | None = None,
+) -> str:
+    """Start a Treeship session in the workspace at ``cwd`` (the working
+    directory by default) and return its ``root_artifact_id`` -- the parent
+    every tool receipt chains from."""
+    _run_json(client, ["session", "start", "--name", name, "--actor", actor], env=env, cwd=cwd)
+    status = _run_json(client, ["session", "status"], env=env, cwd=cwd)
+    root = status.get("root_artifact_id")
+    if not isinstance(root, str) or not root:
+        raise TreeshipError("session start left no root_artifact_id", ["session", "status"])
+    return root
+
+
+def session_status(
+    client: Treeship,
+    *,
+    env: Mapping[str, str] | None = None,
+    cwd: str | os.PathLike[str] | None = None,
+) -> dict[str, Any]:
+    return _run_json(client, ["session", "status"], env=env, cwd=cwd)
+
+
+def close_session(
+    client: Treeship,
+    *,
+    summary: str,
+    headline: str | None = None,
+    env: Mapping[str, str] | None = None,
+    cwd: str | os.PathLike[str] | None = None,
+) -> dict[str, Any]:
+    """Seal the session into a ``.treeship`` package. Returns the CLI's document
+    (``session_id``, ``receipts``, ``events``, ``package``)."""
+    args = ["session", "close", "--summary", summary]
+    if headline:
+        args += ["--headline", headline]
+    return _run_json(client, args, env=env, cwd=cwd)

treeship_commerce/receipts.py

@@ -0,0 +1,330 @@
+"""Signed receipts for every commerce-agents tool call.
+
+Where this plugs in
+-------------------
+``commerce_common.execution.BaseToolExecutor.execute`` is the one method every
+tool call passes through on all three runtimes; the reference's own gates rely
+on that. :class:`TreeshipExecutorMixin` overrides it: a signed **intent**
+receipt before dispatch, the tool, then a signed **result** receipt. Each
+receipt names its parent, so the session's chain reads intent → result →
+intent → result … from the session-start root, and ``treeship verify`` walks
+it as one chain.
+
+What a receipt carries, and what it never carries
+-------------------------------------------------
+The reference fences third-party content and logs only a *digest* of the
+session id, because the id is also the request credential. A receipt keeps
+that discipline: the tool name, a SHA-256 of the canonical arguments, a
+SHA-256 of the result text, the outcome (``ok`` / ``blocked`` with the gate's
+name / ``error``), event types, timing, and the same twelve-hex session tag
+the reference's own log lines use. Never the arguments, never the result text,
+never the session id.
+
+Recording never breaks the agent path
+-------------------------------------
+This module records; it does not gate. A tool runs whether or not its receipt
+could be written, and a failure to record warns once and moves on -- the same
+rule the reference applies to its own attestation-shaped concerns and the rule
+``@treeship/mcp`` follows. The one thing it will not do is invent: a missing
+intent is recorded as ``intent_recorded: false`` on the result, never as a
+fabricated id. ``TREESHIP_DISABLE=1`` turns recording off entirely.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import logging
+import os
+import time
+from typing import Any, Callable, Mapping, Sequence
+
+from treeship_sdk import Treeship
+
+try:  # The reference's own helper, so tags line up with its log lines.
+    from commerce_common.turn import session_tag as _session_tag
+except ImportError:  # pragma: no cover - only when commerce-agents is absent
+
+    def _session_tag(session_id: str | None) -> str:
+        return hashlib.sha256(session_id.encode()).hexdigest()[:12] if session_id else "-"
+
+
+logger = logging.getLogger("treeship_commerce")
+
+INTENT_ACTION = "commerce.tool.{name}.intent"
+RESULT_ACTION = "commerce.tool.{name}.result"
+
+# Exit codes the timeline event carries. Blocked is distinct from error on
+# purpose: a held call is the gate working, not the tool failing.
+_EXIT_CODES = {"ok": 0, "error": 1, "blocked": 2}
+
+
+def _canonical(tool_input: Mapping[str, Any] | None) -> bytes:
+    return json.dumps(
+        dict(tool_input or {}), sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+
+
+def args_digest(tool_input: Mapping[str, Any] | None) -> str:
+    """``sha256:<hex>`` over the canonical JSON of the tool's arguments.
+
+    Canonical means sorted keys, no whitespace, UTF-8: the same arguments
+    always produce the same digest, so a holder of the arguments can check
+    the receipt, and a holder of the receipt learns nothing about them.
+    """
+    return "sha256:" + hashlib.sha256(_canonical(tool_input)).hexdigest()
+
+
+def text_digest(text: str) -> str:
+    """``sha256:<hex>`` of a result text. The text itself is fenced third-party
+    content on the reference and stays out of the receipt."""
+    return "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def outcome_status(outcome: Any) -> str:
+    """``blocked`` when a gate held the call, else ``error`` or ``ok``."""
+    if getattr(outcome, "blocked", None):
+        return "blocked"
+    if getattr(outcome, "is_error", False):
+        return "error"
+    return "ok"
+
+
+class TreeshipReceipts:
+    """The recorder one executor instance carries.
+
+    ``client`` is a configured :class:`treeship_sdk.Treeship`. ``actor`` is the
+    URI the receipts name (``agent://shopping`` or ``agent://merchant`` by
+    convention). ``session_id`` is the *commerce* session id; only its tag is
+    ever written. ``parent_id`` seeds the chain -- pass the Treeship session's
+    ``root_artifact_id`` so the tool receipts count into that session.
+    """
+
+    def __init__(
+        self,
+        client: Treeship,
+        *,
+        actor: str,
+        session_id: str | None = None,
+        role: str = "shopping",
+        parent_id: str | None = None,
+        timeline: bool = True,
+    ) -> None:
+        self.client = client
+        self.actor = actor
+        self.role = role
+        self.session_tag = _session_tag(session_id)
+        self.timeline = timeline
+        self._head: str | None = parent_id
+        self._lock = asyncio.Lock()
+        self._warned = False
+        self._timeline_unavailable_warned = False
+        self.recorded: list[str] = []
+        """Artifact ids written by this recorder, in chain order."""
+        self.dropped = 0
+        """Receipts that could not be written. Non-zero means the chain has
+        gaps that ``intent_recorded: false`` on later results points at."""
+
+    @property
+    def disabled(self) -> bool:
+        return os.environ.get("TREESHIP_DISABLE") == "1"
+
+    @property
+    def head(self) -> str | None:
+        """The most recent artifact in the chain, or the seed parent."""
+        return self._head
+
+    def _warn(self, context: str, err: BaseException) -> None:
+        self.dropped += 1
+        if not self._warned:
+            self._warned = True
+            logger.warning(
+                "treeship receipt not written (%s): %s. Tool calls continue; later "
+                "results record intent_recorded=false where the intent is missing. "
+                "Set TREESHIP_DISABLE=1 to silence recording entirely.",
+                context,
+                err,
+            )
+        elif os.environ.get("TREESHIP_DEBUG") == "1":
+            logger.warning("treeship receipt not written (%s): %s", context, err)
+
+    async def _attest(self, action: str, meta: dict[str, Any], parent: str | None) -> str | None:
+        if self.disabled:
+            return None
+        try:
+            result = await asyncio.to_thread(
+                self.client.attest_action, self.actor, action, parent, None, meta
+            )
+        except Exception as err:  # noqa: BLE001 -- a recorder must never break the tool
+            self._warn(action, err)
+            return None
+        async with self._lock:
+            self._head = result.artifact_id
+            self.recorded.append(result.artifact_id)
+        return result.artifact_id
+
+    async def intent(self, name: str, tool_input: Mapping[str, Any] | None) -> str | None:
+        """Sign that ``name`` is about to run with these (digested) arguments."""
+        async with self._lock:
+            parent = self._head
+        return await self._attest(
+            INTENT_ACTION.format(name=name),
+            {
+                "tool": name,
+                "role": self.role,
+                "args_digest": args_digest(tool_input),
+                "session_tag": self.session_tag,
+            },
+            parent,
+        )
+
+    async def result(
+        self,
+        name: str,
+        outcome: Any,
+        *,
+        intent_id: str | None,
+        elapsed_ms: int,
+    ) -> str | None:
+        """Sign what ``name`` produced: status, gate, digests, events, timing."""
+        status = outcome_status(outcome)
+        meta: dict[str, Any] = {
+            "tool": name,
+            "role": self.role,
+            "status": status,
+            "result_digest": text_digest(getattr(outcome, "result_text", "") or ""),
+            "events": [getattr(e, "type", str(e)) for e in getattr(outcome, "events", ())],
+            "elapsed_ms": int(elapsed_ms),
+            "session_tag": self.session_tag,
+            # False is a statement, not a default: this result's parent is then
+            # the previous chain head, and a reader can see the intent is missing.
+            "intent_recorded": intent_id is not None,
+        }
+        if status == "blocked":
+            meta["gate"] = outcome.blocked
+        async with self._lock:
+            parent = self._head
+        artifact_id = await self._attest(RESULT_ACTION.format(name=name), meta, parent)
+        if self.timeline:
+            await self._event(name, status, elapsed_ms)
+        return artifact_id
+
+    async def _event(self, name: str, status: str, elapsed_ms: int) -> None:
+        """Append the call to the Treeship session timeline (unsigned; it is what
+        the receipt page renders). The signed receipts are the evidence."""
+        if self.disabled:
+            return
+        session_event = getattr(self.client, "session_event", None)
+        if session_event is None:
+            # treeship-sdk < 0.28 has no session_event. The signed receipts are
+            # the evidence; the timeline is a rendering convenience. Say so
+            # once rather than raise into the tool call.
+            if not self._timeline_unavailable_warned:
+                self._timeline_unavailable_warned = True
+                logger.warning(
+                    "treeship-sdk %s has no session_event(); timeline events are skipped "
+                    "(signed receipts are still written). Upgrade treeship-sdk to restore them.",
+                    getattr(self.client, "__module__", "?"),
+                )
+            return
+        try:
+            await asyncio.to_thread(
+                session_event,
+                "agent.called_tool",
+                tool=name,
+                actor=self.actor,
+                exit_code=_EXIT_CODES[status],
+                duration_ms=int(elapsed_ms),
+            )
+        except Exception as err:  # noqa: BLE001 -- a recorder must never break the tool
+            self._warn(f"session event {name}", err)
+
+
+class TreeshipExecutorMixin:
+    """Put this first in the bases of a commerce-agents executor class::
+
+        class ReceiptedShoppingToolExecutor(TreeshipExecutorMixin, ShoppingToolExecutor):
+            pass
+
+    or let :func:`receipted` build that class. Give the instance its recorder
+    with :func:`attach`, or give the class a ``recorder`` factory through
+    :func:`receipted` so every runtime that constructs executors itself (all
+    three of the reference's do, through ``executor_class``) gets one per
+    executor on first use. Without either, the executor behaves exactly as
+    the reference does.
+    """
+
+    treeship_receipts: TreeshipReceipts | None = None
+    treeship_recorder_factory: Callable[[Any], TreeshipReceipts] | None = None
+
+    def _treeship_recorder(self) -> TreeshipReceipts | None:
+        if self.treeship_receipts is None and self.treeship_recorder_factory is not None:
+            # One recorder per executor. The reference builds one executor per
+            # session (Messages API), per toolset (Agent SDK), or per MCP
+            # connection (Managed Agents), so this is one chain per session.
+            self.treeship_receipts = self.treeship_recorder_factory(self)
+        return self.treeship_receipts
+
+    async def execute(self, name: str, tool_input: dict[str, Any] | None) -> Any:
+        receipts = self._treeship_recorder()
+        if receipts is None:
+            return await super().execute(name, tool_input)  # type: ignore[misc]
+        intent_id = await receipts.intent(name, tool_input)
+        started = time.monotonic()
+        outcome = await super().execute(name, tool_input)  # type: ignore[misc]
+        elapsed_ms = int((time.monotonic() - started) * 1000)
+        await receipts.result(name, outcome, intent_id=intent_id, elapsed_ms=elapsed_ms)
+        return outcome
+
+
+def receipted(
+    executor_cls: type,
+    *,
+    recorder: Callable[[Any], TreeshipReceipts] | None = None,
+) -> type:
+    """``ShoppingToolExecutor`` in, ``ReceiptedShoppingToolExecutor`` out.
+
+    All three of the reference's runtimes take an ``executor_class``
+    (``ShoppingAgent(executor_class=)``, ``ShoppingToolset(executor_class=)``,
+    ``build_server(executor_class=)``) and construct executors themselves, so
+    there is no instance to :func:`attach` to. Pass ``recorder``, a callable
+    from the executor to its :class:`TreeshipReceipts`, and each executor gets
+    one on its first tool call. The executor's ``_session`` carries the
+    commerce session id the recorder should tag::
+
+        receipted(ShoppingToolExecutor, recorder=lambda ex: TreeshipReceipts(
+            ts, actor="agent://shopping", session_id=ex._session.session_id, parent_id=root))
+    """
+    if issubclass(executor_cls, TreeshipExecutorMixin) and recorder is None:
+        return executor_cls
+    body: dict[str, Any] = {}
+    if recorder is not None:
+        body["treeship_recorder_factory"] = staticmethod(recorder)
+    bases = (
+        (executor_cls,)
+        if issubclass(executor_cls, TreeshipExecutorMixin)
+        else (
+            TreeshipExecutorMixin,
+            executor_cls,
+        )
+    )
+    return type(f"Receipted{executor_cls.__name__.removeprefix('Receipted')}", bases, body)
+
+
+def attach(executor: Any, receipts: TreeshipReceipts) -> Any:
+    """Give an executor instance its recorder. The executor's class must carry
+    :class:`TreeshipExecutorMixin`; attaching to a plain reference executor
+    would record nothing and say nothing, which is the failure this refuses."""
+    if not isinstance(executor, TreeshipExecutorMixin):
+        raise TypeError(
+            f"{type(executor).__name__} does not carry TreeshipExecutorMixin; build it from "
+            f"receipted({type(executor).__name__}) so execute() actually records."
+        )
+    executor.treeship_receipts = receipts
+    return executor
+
+
+def event_types(outcome: Any) -> Sequence[str]:
+    """The event types a tool outcome emitted, as recorded on its receipt."""
+    return [getattr(e, "type", str(e)) for e in getattr(outcome, "events", ())]

treeship_commerce-0.28.0.dist-info/METADATA

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: treeship-commerce
+Version: 0.28.0
+Summary: Signed, offline-verifiable receipts for every tool call in anthropics/commerce-agents, on all three of its runtimes.
+License: Apache-2.0
+Project-URL: Homepage, https://treeship.dev
+Project-URL: Documentation, https://docs.treeship.dev/integrations/commerce-agents
+Project-URL: Source, https://github.com/zerkerlabs/treeship/tree/main/integrations/commerce-agents
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: treeship-sdk>=0.27.0
+
+# Treeship for Claude Commerce Agents
+
+Signed, offline-verifiable receipts for every tool call in
+[anthropics/commerce-agents](https://github.com/anthropics/commerce-agents), on all three of
+its runtimes.
+
+The reference draws its own boundary in `docs/safety.md`: the approval surface, payment,
+and log hygiene are "what a deployment owns". This package is what a deployment adds for
+the record of what happened. It records; it does not gate. The reference's provenance
+gates, caps, and host approval still decide what runs.
+
+## What it does
+
+`commerce_common.execution.BaseToolExecutor.execute` is the one method every tool call
+passes through on the Messages API, the Agent SDK, and Managed Agents. `TreeshipExecutorMixin`
+overrides it:
+
+1. a signed **intent** receipt before dispatch: tool, SHA-256 of the canonical arguments,
+   session tag;
+2. the tool, exactly as the reference runs it;
+3. a signed **result** receipt: status (`ok`, `blocked` with the gate's name, `error`),
+   SHA-256 of the result text, event types, timing.
+
+Each receipt names its parent, so a session reads `intent → result → intent → result …` from
+the Treeship session's root, and `treeship verify` walks it as one chain. A held call is a
+signed refusal, not a missing receipt.
+
+Never written: the arguments, the result text (fenced third-party content on the
+reference), or the commerce session id (the request credential). The receipt carries the
+same twelve-hex session tag the reference's own log lines use, so an operator holding the id
+can correlate and a reader cannot.
+
+## Install
+
+```bash
+# from a clone of anthropics/commerce-agents, with its venv active
+pip install -r requirements.txt            # their seven packages (unregistered on PyPI)
+pip install treeship-sdk
+pip install "treeship-commerce @ git+https://github.com/zerkerlabs/treeship.git#subdirectory=integrations/commerce-agents"   # PyPI publication follows the next release
+curl -fsSL https://treeship.dev/install | sh && treeship init
+```
+
+## Use
+
+```python
+from treeship_sdk import Treeship
+from treeship_commerce import TreeshipReceipts, attach, receipted
+from treeship_commerce.lifecycle import close_session, start_session
+from shopping_agent.executor import ShoppingToolExecutor
+
+ts = Treeship()
+root = start_session(ts, name="storefront:acme", actor="agent://shopping")
+
+executor = receipted(ShoppingToolExecutor)(backend=..., config=..., skills=..., session=..., state=..., memory=...)
+attach(executor, TreeshipReceipts(ts, actor="agent://shopping", session_id=session.session_id, parent_id=root))
+
+# ... the runtime calls executor.execute(...) as it always did ...
+
+close_session(ts, summary="...")          # seals a .treeship package; `treeship session report` publishes it
+```
+
+All three runtimes construct executors themselves through `executor_class`
+(`ShoppingAgent`, `ShoppingToolset`, the MCP server's `build_server`). Give
+`receipted()` a `recorder` factory and each executor gets its own recorder on
+its first tool call:
+
+```python
+ReceiptedShopping = receipted(ShoppingToolExecutor, recorder=lambda ex: TreeshipReceipts(
+    ts, actor="agent://shopping", session_id=ex._session.session_id, parent_id=root))
+```
+
+Same for `MerchantToolExecutor`.
+
+Recording never breaks the agent path: a receipt that cannot be written warns once, is
+counted in `TreeshipReceipts.dropped`, and later results say `intent_recorded: false` where
+the intent is missing. Nothing is invented. `TREESHIP_DISABLE=1` turns recording off.
+
+## Demo
+
+```bash
+TREESHIP_BIN=... python -m treeship_commerce.demo
+```
+
+Runs the reference's shopping executor over the retail mock with no model and no API key:
+a search, a product read, an add, an add the provenance gate holds, a checkout hand-off.
+Prints every receipt id, seals the session, and shows the `treeship verify` command.
+
+## What this does not do (yet)
+
+- **Approvals.** The merchant `apply_change` gate checks a mark the host sets. Turning that
+  mark into a signed, single-use Treeship approval (nonce echoed by the apply receipt,
+  enforced by the Approval Use Journal) is the next piece.
+- **Checkout hand-off receipt.** Signing the cart digest and hosted-checkout URL digest at
+  `checkout_handoff`, chained to the host's order placement.
+- **Prove the work is correct.** A receipt is evidence of what ran and what the gates
+  decided. It does not make a wrong answer right.
+
+## Tests
+
+```bash
+TREESHIP_BIN=/path/to/treeship python -m pytest
+```
+
+Six cases on a real isolated ship and the real retail mock: chain order and linkage, a held
+call signed as blocked with its gate, digests-only content, recording failure leaving the
+tool untouched, `TREESHIP_DISABLE`, and `attach` refusing an executor that would record
+nothing.

treeship_commerce-0.28.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+treeship_commerce/__init__.py,sha256=2DV_k19AcDxFcWLm_LySLP4YiwCtz3QcYRUTtBwGdWA,639
+treeship_commerce/demo.py,sha256=QOQPOTkgYKGaBwQmE2Qdj1x5M4tMaheXOHctu2ctAdI,5173
+treeship_commerce/lifecycle.py,sha256=ynyAmjMutxLY9E1oU0bZ5LVdFrCQ2xsgchM11H6JA5g,3463
+treeship_commerce/receipts.py,sha256=4-BBD7A8MiRNNRDRmPuoaVQZ8QIxQ5jmvlkxV8pEzXw,13861
+treeship_commerce-0.28.0.dist-info/METADATA,sha256=ZqiR4DR5iVnHZ0ObLNZAtUs1sMr2hvHjWu73dHp6dcs,5274
+treeship_commerce-0.28.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+treeship_commerce-0.28.0.dist-info/top_level.txt,sha256=vnKaxb6_PjDR1XOHrth9aj9gmR74YeQAGRVOhp-n7g8,18
+treeship_commerce-0.28.0.dist-info/RECORD,,

treeship_commerce-0.28.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

treeship_commerce-0.28.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+treeship_commerce