a2a-doctor 0.1.0__tar.gz

a2a_doctor-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Run tests
+        run: |
+          python -m pip install pytest
+          python -m pytest test_a2a_doctor.py -q

a2a_doctor-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: a2a-doctor
+Version: 0.1.0
+Summary: One command, every A2A audit - replay recorded streams offline and health-check agent-to-agent traffic: token tax, artifact loss, task lifecycle, context correlation, webhook SSRF, MCP collisions.
+Author: ZidoCode
+License: MIT
+Keywords: a2a,agent,agent2agent,audit,llm,mcp,offline,replay,ssrf,token,webhook
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# a2a-doctor
+
+**One command, every A2A audit in the family. Dumb math, honest numbers, zero dependencies.**
+
+[![tests](https://github.com/ZidoCode/a2a-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/ZidoCode/a2a-doctor/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)]()
+
+The umbrella entry point for the ZidoCode A2A audit suite:
+
+| Repo | What it audits |
+|---|---|
+| [a2a-tax](https://github.com/ZidoCode/a2a-tax) | token cost of the agent card + polling model |
+| [a2a-stream-tax](https://github.com/ZidoCode/a2a-stream-tax) | token cost of a recorded SSE stream |
+| [a2a-reconnect-tax](https://github.com/ZidoCode/a2a-reconnect-tax) | replayed-event tax across SSE reconnects |
+| [a2a-artifact-audit](https://github.com/ZidoCode/a2a-artifact-audit) | chunk gaps, duplicates, writes after `last_chunk` |
+| [a2a-task-state-audit](https://github.com/ZidoCode/a2a-task-state-audit) | task resurrection, illegal transitions, unknown states |
+| [a2a-context-audit](https://github.com/ZidoCode/a2a-context-audit) | empty IDs, context mutation, orphan contexts ([A2A#1309](https://github.com/a2aproject/A2A/issues/1309)) |
+| [a2a-webhook-audit](https://github.com/ZidoCode/a2a-webhook-audit) | webhook SSRF: metadata IPs, credentials, risky ports ([a2a-go#373](https://github.com/a2aproject/a2a-go/issues/373)) |
+| [a2a-timeline-replay](https://github.com/ZidoCode/a2a-timeline-replay) | time-travel explorer — per-task timelines, event windows, raw JSON at any line |
+| [a2a-card-lock](https://github.com/ZidoCode/a2a-card-lock) | agent-card pin + drift gate |
+
+Each member works standalone. a2a-doctor runs them all in one pass and gives one verdict.
+
+## Install
+
+```bash
+pip install a2a-doctor   # or: copy the .py files (they are all stdlib-only)
+```
+
+## Usage
+
+```bash
+$ a2a-doctor check --card card.json --stream stream.jsonl --lock a2a-card.lock
+a2a-doctor check — 7 section(s)
+
+  ✓ card       418 tok estimated
+  ✓ polling    ~418 tok/task estimated
+  ✓ stream     17 event(s) recorded
+  ✗ artifacts  1 critical — event 14: write to 'a1' after last_chunk (artifact already closed)
+  ✗ lifecycle  5 critical — line 7: task 'zombie-task' resumed after terminal state 'failed' -> 'working'
+  ✓ reconnect  no replayed events
+  ✓ lock       card unchanged — hash matches
+
+  verdict: FAIL (artifacts, lifecycle)
+$ echo $?
+2
+```
+
+`check` is the CI gate: **exit 0** clean, **1** warnings only, **2** critical findings.
+
+Individual sections:
+
+```bash
+a2a-doctor tax card.json          # card size + $ estimate
+a2a-doctor stream stream.jsonl    # token breakdown of a recorded stream
+a2a-doctor reconnect stream.jsonl # replayed events across reconnects
+a2a-doctor artifacts stream.jsonl # artifact integrity report
+a2a-doctor lifecycle stream.jsonl # task state machine audit
+a2a-doctor context stream.jsonl   # context/task correlation audit
+a2a-doctor webhook stream.jsonl   # webhook SSRF audit (offline)
+a2a-doctor timeline stream.jsonl  # time-travel explorer: per-task state chains
+a2a-doctor lock card.json a2a-card.lock  # drift check
+```
+
+## Stream format
+
+One JSON event per line — record your client's `message/stream` session, replay it anywhere, anytime. Deterministic: same input, same verdict, byte for byte.
+
+## Why
+
+Auditing an A2A endpoint once is easy. Continuously — in CI, on every deploy — is the point. a2a-doctor exists so there is one command to wire into the pipeline, not six. MIT license.

a2a_doctor-0.1.0/README.md

@@ -0,0 +1,70 @@
+# a2a-doctor
+
+**One command, every A2A audit in the family. Dumb math, honest numbers, zero dependencies.**
+
+[![tests](https://github.com/ZidoCode/a2a-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/ZidoCode/a2a-doctor/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)]()
+
+The umbrella entry point for the ZidoCode A2A audit suite:
+
+| Repo | What it audits |
+|---|---|
+| [a2a-tax](https://github.com/ZidoCode/a2a-tax) | token cost of the agent card + polling model |
+| [a2a-stream-tax](https://github.com/ZidoCode/a2a-stream-tax) | token cost of a recorded SSE stream |
+| [a2a-reconnect-tax](https://github.com/ZidoCode/a2a-reconnect-tax) | replayed-event tax across SSE reconnects |
+| [a2a-artifact-audit](https://github.com/ZidoCode/a2a-artifact-audit) | chunk gaps, duplicates, writes after `last_chunk` |
+| [a2a-task-state-audit](https://github.com/ZidoCode/a2a-task-state-audit) | task resurrection, illegal transitions, unknown states |
+| [a2a-context-audit](https://github.com/ZidoCode/a2a-context-audit) | empty IDs, context mutation, orphan contexts ([A2A#1309](https://github.com/a2aproject/A2A/issues/1309)) |
+| [a2a-webhook-audit](https://github.com/ZidoCode/a2a-webhook-audit) | webhook SSRF: metadata IPs, credentials, risky ports ([a2a-go#373](https://github.com/a2aproject/a2a-go/issues/373)) |
+| [a2a-timeline-replay](https://github.com/ZidoCode/a2a-timeline-replay) | time-travel explorer — per-task timelines, event windows, raw JSON at any line |
+| [a2a-card-lock](https://github.com/ZidoCode/a2a-card-lock) | agent-card pin + drift gate |
+
+Each member works standalone. a2a-doctor runs them all in one pass and gives one verdict.
+
+## Install
+
+```bash
+pip install a2a-doctor   # or: copy the .py files (they are all stdlib-only)
+```
+
+## Usage
+
+```bash
+$ a2a-doctor check --card card.json --stream stream.jsonl --lock a2a-card.lock
+a2a-doctor check — 7 section(s)
+
+  ✓ card       418 tok estimated
+  ✓ polling    ~418 tok/task estimated
+  ✓ stream     17 event(s) recorded
+  ✗ artifacts  1 critical — event 14: write to 'a1' after last_chunk (artifact already closed)
+  ✗ lifecycle  5 critical — line 7: task 'zombie-task' resumed after terminal state 'failed' -> 'working'
+  ✓ reconnect  no replayed events
+  ✓ lock       card unchanged — hash matches
+
+  verdict: FAIL (artifacts, lifecycle)
+$ echo $?
+2
+```
+
+`check` is the CI gate: **exit 0** clean, **1** warnings only, **2** critical findings.
+
+Individual sections:
+
+```bash
+a2a-doctor tax card.json          # card size + $ estimate
+a2a-doctor stream stream.jsonl    # token breakdown of a recorded stream
+a2a-doctor reconnect stream.jsonl # replayed events across reconnects
+a2a-doctor artifacts stream.jsonl # artifact integrity report
+a2a-doctor lifecycle stream.jsonl # task state machine audit
+a2a-doctor context stream.jsonl   # context/task correlation audit
+a2a-doctor webhook stream.jsonl   # webhook SSRF audit (offline)
+a2a-doctor timeline stream.jsonl  # time-travel explorer: per-task state chains
+a2a-doctor lock card.json a2a-card.lock  # drift check
+```
+
+## Stream format
+
+One JSON event per line — record your client's `message/stream` session, replay it anywhere, anytime. Deterministic: same input, same verdict, byte for byte.
+
+## Why
+
+Auditing an A2A endpoint once is easy. Continuously — in CI, on every deploy — is the point. a2a-doctor exists so there is one command to wire into the pipeline, not six. MIT license.

a2a_doctor-0.1.0/a2a_artifact_audit.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""a2a-artifact-audit — audit A2A artifact streaming for silent data loss.
+
+A2A artifacts stream in chunks: `artifact-update` events with append=true,
+a last_chunk flag, and artifactIds the client is trusted to track. The spec
+leaves the hard cases open — can an artifact be replaced after last_chunk
+(a2aproject/A2A#1231)? Should append to an unknown artifactId fail loudly
+(silent drop today: a2a-python#1038)? Is there any content integrity at all
+(proposal #1140)?
+
+a2a-artifact-audit replays a recorded artifact stream and reports:
+  - chunks appended to artifactIds that were never announced (silent drops)
+  - duplicate part deliveries (appended twice)
+  - events after last_chunk (post-completion writes)
+  - artifacts never closed (missing last_chunk)
+  - size accounting per artifact
+
+Usage:
+  python3 a2a_artifact_audit.py audit <stream.jsonl>
+  python3 a2a_artifact_audit.py report <stream.jsonl>
+  python3 a2a_artifact_audit.py simulate <card-url-or-file> [--artifacts N] [--chunks M]
+
+Stream format: one JSON event per line (message/stream output).
+
+Zero dependencies. Python 3.8+.
+"""
+
+import argparse
+import json
+import sys
+
+from a2a_tax import est_tokens, fetch_card
+from a2a_stream_tax import event_tokens, load_stream
+
+
+# ---------------------------------------------------------------- audit
+
+def audit(events):
+    """Replay artifact-update events, detect data-integrity violations.
+    Returns (findings, artifacts). findings: list of (severity, msg)."""
+    CRIT, WARN, INFO = "CRITICAL", "WARNING", "INFO"
+    findings = []
+    artifacts = {}   # artifactId -> {"chunks": n, "parts_tokens": t, "closed": bool,
+                     #                "seen_parts": set, "announced": bool}
+    order = 0
+    for ev in events:
+        order += 1
+        res = ev.get("result") if isinstance(ev.get("result"), dict) else {}
+        if res.get("kind") != "artifact-update":
+            continue
+        art = res.get("artifact") or {}
+        aid = art.get("artifactId")
+        if not aid:
+            findings.append((WARN, f"event {order}: artifact-update without artifactId"))
+            continue
+        append = bool(res.get("append"))
+        last = bool(res.get("last_chunk"))
+        parts = art.get("parts") or []
+        part_sig = json.dumps(parts, sort_keys=True, separators=(",", ":"))
+        ptoks = est_tokens(part_sig)
+
+        a = artifacts.setdefault(aid, {"chunks": 0, "parts_tokens": 0,
+                                       "closed": False, "seen_parts": [],
+                                       "announced": False})
+        # 1. protocol hygiene: first chunk should not be an append
+        #    (server-side, append to an unannounced id is silently dropped — a2a-python#1038;
+        #     from a client replay we flag it as hygiene, not data loss)
+        if append and a["chunks"] == 0:
+            findings.append((INFO, f"event {order}: first chunk of {aid!r} has append=true — "
+                                   "should be a fresh write (servers drop appends to unknown ids)"))
+        # 2. write after last_chunk (a2aproject/A2A#1231)
+        if a["closed"]:
+            findings.append((CRIT, f"event {order}: write to {aid!r} after last_chunk "
+                                   "(artifact already closed)"))
+        # 3. duplicate part delivery
+        if part_sig in a["seen_parts"]:
+            findings.append((WARN, f"event {order}: duplicate part delivered to {aid!r} "
+                                   f"(~{ptoks} tokens re-sent)"))
+        # 4. replacement without append after previously closed is #2; full
+        #    replacement (append=false) after chunks is suspicious
+        if not append and a["chunks"] > 0:
+            findings.append((INFO, f"event {order}: artifact {aid!r} replaced wholesale "
+                                   f"({a['chunks']} earlier chunk(s) discarded)"))
+        a["chunks"] += 1
+        a["parts_tokens"] += ptoks
+        a["seen_parts"].append(part_sig)
+        a["announced"] = True
+        if last:
+            a["closed"] = True
+
+    # 5. never closed
+    for aid, a in sorted(artifacts.items()):
+        if not a["closed"]:
+            findings.append((WARN, f"artifact {aid!r} never closed — missing last_chunk "
+                                   f"({a['chunks']} chunk(s) held open)"))
+    return findings, artifacts
+
+
+# ---------------------------------------------------------------- simulate
+
+def simulate(card, artifacts=3, chunks=5, gap=True):
+    """Model an artifact stream: N artifacts x M chunks. With gap=True,
+    one append targets an unannounced artifact (the silent-drop class)."""
+    base = {"tokens": 0}
+    ev = {"jsonrpc": "2.0", "id": 1, "result": {
+        "kind": "artifact-update", "taskId": "t1", "contextId": "c1",
+        "append": True, "last_chunk": False,
+        "artifact": {"artifactId": "a", "parts": [{"kind": "text",
+                     "text": "chunk payload — simulating artifact audit"}]}}}
+    per = event_tokens(ev)
+    total_events = artifacts * chunks
+    base["tokens"] = per * total_events
+    findings = 1 if gap else 0
+    return {"artifact_events": total_events, "tokens_total": base["tokens"],
+            "per_event_tokens": per, "simulated_findings": findings,
+            "note": "1 first-chunk has append=true (protocol hygiene)" if gap else ""}
+
+
+# ---------------------------------------------------------------- report
+
+def report(events):
+    findings, artifacts = audit(events)
+    crit = sum(1 for s, _ in findings if s == "CRITICAL")
+    warn = sum(1 for s, _ in findings if s == "WARNING")
+    info = sum(1 for s, _ in findings if s == "INFO")
+    lines = [f"a2a-artifact-audit report — {len(artifacts)} artifact(s), {len(findings)} finding(s)"]
+    lines.append("")
+    for aid, a in sorted(artifacts.items()):
+        state = "closed" if a["closed"] else "OPEN (no last_chunk)"
+        lines.append(f"  {aid:20s} {a['chunks']:>3} chunks  {a['parts_tokens']:>7,} tok  {state}")
+    if findings:
+        lines.append("")
+        for s, m in findings:
+            lines.append(f"  [{s:8s}] {m}")
+        lines.append("")
+        if crit:
+            lines.append(f"  verdict: {crit} CRITICAL — chunks silently lost or written after close.")
+        else:
+            lines.append("  verdict: no critical loss — review warnings above.")
+    else:
+        lines.append("  clean — every chunk announced, ordered, and closed.")
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------- CLI
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="a2a-artifact-audit",
+                                 description="Audit A2A artifact streaming for silent data loss.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_a = sub.add_parser("audit", help="machine list of findings")
+    p_a.add_argument("path")
+
+    p_r = sub.add_parser("report", help="human-readable report")
+    p_r.add_argument("path")
+
+    p_s = sub.add_parser("simulate", help="model artifact stream from an AgentCard")
+    p_s.add_argument("source")
+    p_s.add_argument("--artifacts", type=int, default=3)
+    p_s.add_argument("--chunks", type=int, default=5)
+    p_s.add_argument("--no-gap", action="store_true", help="model a clean stream")
+
+    args = ap.parse_args(argv)
+    args.artifacts = max(0, getattr(args, "artifacts", 3))
+    args.chunks = max(0, getattr(args, "chunks", 5))
+
+    if args.cmd == "simulate":
+        try:
+            card, _ = fetch_card(args.source)
+        except Exception as e:
+            print(f"error: cannot load card from {args.source}: {e}", file=sys.stderr)
+            return 2
+        if not isinstance(card, dict):
+            print(f"error: {args.source} is not an AgentCard (expected a JSON object, "
+                  f"got {type(card).__name__})", file=sys.stderr)
+            return 2
+        m = simulate(card, args.artifacts, args.chunks, not args.no_gap)
+        for k, v in m.items():
+            print(f"{k:22s}: {v:,}" if isinstance(v, int) else f"{k:22s}: {v}")
+        return 0
+
+    try:
+        events, bad = load_stream(args.path)
+    except OSError as e:
+        print(f"error: cannot read stream file {args.path}: {e}", file=sys.stderr)
+        return 2
+    if bad:
+        print(f"note: skipped {len(bad)} unparseable line(s), first: line {bad[0][0]}: {bad[0][1]!r}",
+              file=sys.stderr)
+    if not events:
+        print(f"error: no valid events in {args.path}", file=sys.stderr)
+        return 2
+
+    if args.cmd == "audit":
+        findings, _ = audit(events)
+        for s, m in findings:
+            print(f"[{s:8s}] {m}")
+        if not findings:
+            print("clean — no artifact integrity violations")
+        return 2 if any(s == "CRITICAL" for s, _ in findings) else 0
+
+    print(report(events))
+    return 2 if any(s == "CRITICAL" for s, _ in audit(events)[0]) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

a2a_doctor-0.1.0/a2a_card_lock.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""a2a-card-lock — pin A2A Agent Cards, catch silent drift in CI.
+
+An Agent Card is a trust anchor: you fetch it once, verify it, and build a
+peering on top. But nothing stops the remote agent from quietly changing the
+card tomorrow — a new skill with a different description, a rewritten URL, a
+dropped auth scheme, a loosened security block. mcp-lock proved the pattern
+for MCP tool chains; agent cards are the same attack surface and nobody pins
+them.
+
+a2a-card-lock hashes a card into a lockfile, diffs live cards against it,
+and exits non-zero on breaking changes so CI catches drift before your
+agents obey it.
+
+Usage:
+  python3 a2a_card_lock.py pin <card-url-or-file> [--out a2a-card.lock]
+  python3 a2a_card_lock.py diff <card-url-or-file> [--lock a2a-card.lock]
+  python3 a2a_card_lock.py report <card-url-or-file> [--lock a2a-card.lock]
+
+Zero dependencies. Python 3.8+.
+"""
+
+import argparse
+import hashlib
+import json
+import sys
+
+from a2a_tax import est_tokens, fetch_card
+
+BREAKING = "CRITICAL"
+WARNING = "WARNING"
+INFO = "INFO"
+
+
+# ---------------------------------------------------------------- hashing
+
+def canonical(card):
+    """Deterministic serialization: sort keys recursively, compact separators.
+    Two semantically identical cards must hash identically."""
+    return json.dumps(card, sort_keys=True, separators=(",", ":"))
+
+
+def card_hash(card):
+    return hashlib.sha256(canonical(card).encode("utf-8")).hexdigest()
+
+
+def field_hashes(card):
+    """Per-field sha256, so the diff can name exactly what moved."""
+    out = {}
+    for k, v in card.items():
+        out[k] = hashlib.sha256(json.dumps(v, sort_keys=True,
+                                           separators=(",", ":")).encode("utf-8")).hexdigest()[:16]
+    return out
+
+
+def skill_map(card):
+    """skill id -> {name, description-hash, tags-hash}"""
+    out = {}
+    for s in card.get("skills") or []:
+        sid = s.get("id", s.get("name", "?"))
+        out[sid] = {
+            "name": s.get("name", ""),
+            "desc_hash": hashlib.sha256((s.get("description") or "").encode()).hexdigest()[:16],
+            "tags": sorted(s.get("tags") or []),
+        }
+    return out
+
+
+# ---------------------------------------------------------------- pin
+
+def pin(card):
+    """Build a lockfile dict from a live card."""
+    return {
+        "lock_version": 1,
+        "card_hash": card_hash(card),
+        "protocolVersion": card.get("protocolVersion", ""),
+        "fields": field_hashes(card),
+        "skills": skill_map(card),
+        "pinned_at": "",  # intentionally no timestamp: same card -> same lockfile
+    }
+
+
+def save_lock(lock, path):
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(lock, f, indent=2, sort_keys=True)
+        f.write("\n")
+
+
+def load_lock(path):
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+# ---------------------------------------------------------------- diff
+
+def diff(card, lock):
+    """Compare a live card against a pinned lock. Returns (findings, summary).
+    Breaking: card hash, protocolVersion, url/auth/security, skill removal,
+    skill description changes. Warnings: skill additions, new fields."""
+    findings = []
+    live = pin(card)
+
+    if live["card_hash"] == lock.get("card_hash"):
+        return [], "card unchanged — hash matches"
+
+    # protocolVersion
+    if live["protocolVersion"] != lock.get("protocolVersion"):
+        findings.append((BREAKING,
+                         f"protocolVersion changed: {lock.get('protocolVersion')!r} -> {live['protocolVersion']!r}"))
+
+    # per-field: url / auth / security are breaking on any change
+    for key in ("url", "preferredTransport", "security", "securitySchemes", "provider"):
+        old = (lock.get("fields") or {}).get(key)
+        new = live["fields"].get(key)
+        if old and new and old != new:
+            findings.append((BREAKING, f"{key} changed (was pinned, now differs)"))
+
+    # skills
+    old_skills = lock.get("skills") or {}
+    new_skills = live["skills"]
+    for sid in sorted(set(old_skills) - set(new_skills)):
+        findings.append((BREAKING, f"skill removed: {sid}"))
+    for sid in sorted(set(new_skills) - set(old_skills)):
+        findings.append((WARNING, f"skill added: {sid} — review its description before trusting"))
+    for sid in sorted(set(old_skills) & set(new_skills)):
+        if old_skills[sid]["desc_hash"] != new_skills[sid]["desc_hash"]:
+            findings.append((BREAKING,
+                             f"skill description changed: {sid} ({old_skills[sid]['name']!r})"))
+        elif old_skills[sid]["tags"] != new_skills[sid]["tags"]:
+            findings.append((INFO, f"skill tags changed: {sid}"))
+
+    # other fields (informational)
+    for k in sorted(set(live["fields"]) - set(lock.get("fields") or {})):
+        findings.append((INFO, f"new field: {k}"))
+
+    if not findings:
+        findings.append((INFO, "card changed but only in untracked fields"))
+    return findings, None
+
+
+def classify_severity(findings):
+    for sev, _ in findings:
+        if sev == BREAKING:
+            return 2
+    for sev, _ in findings:
+        if sev == WARNING:
+            return 1
+    return 0
+
+
+# ---------------------------------------------------------------- CLI
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="a2a-card-lock",
+                                 description="Pin A2A Agent Cards, catch silent drift in CI.")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    p_pin = sub.add_parser("pin", help="pin a card into a lockfile")
+    p_pin.add_argument("source")
+    p_pin.add_argument("--out", default="a2a-card.lock")
+
+    p_diff = sub.add_parser("diff", help="compare a live card against a lockfile")
+    p_diff.add_argument("source")
+    p_diff.add_argument("--lock", default="a2a-card.lock")
+
+    p_rep = sub.add_parser("report", help="human-readable drift report")
+    p_rep.add_argument("source")
+    p_rep.add_argument("--lock", default="a2a-card.lock")
+
+    args = ap.parse_args(argv)
+
+    try:
+        card, src = fetch_card(args.source)
+    except Exception as e:
+        print(f"error: cannot load card from {args.source}: {e}", file=sys.stderr)
+        return 2
+    if not isinstance(card, dict):
+        print(f"error: {args.source} is not an AgentCard (expected a JSON object, "
+              f"got {type(card).__name__})", file=sys.stderr)
+        return 2
+
+    if args.cmd == "pin":
+        lock = pin(card)
+        save_lock(lock, args.out)
+        print(f"pinned {src}")
+        print(f"  card hash : {lock['card_hash'][:32]}…")
+        print(f"  skills    : {len(lock['skills'])}")
+        print(f"  lockfile  : {args.out}")
+        return 0
+
+    # diff / report need a lockfile
+    try:
+        lock = load_lock(args.lock)
+    except OSError as e:
+        print(f"error: cannot read lockfile {args.lock}: {e}", file=sys.stderr)
+        return 2
+    except json.JSONDecodeError as e:
+        print(f"error: lockfile {args.lock} is not valid JSON: {e}", file=sys.stderr)
+        return 2
+    if not isinstance(lock, dict) or "card_hash" not in lock:
+        print(f"error: {args.lock} is not an a2a-card-lock lockfile", file=sys.stderr)
+        return 2
+
+    findings, unchanged = diff(card, lock)
+    if unchanged:
+        print(unchanged)
+        return 0
+
+    sev_max = classify_severity(findings)
+    if args.cmd == "diff":
+        icon = {BREAKING: "CRITICAL", WARNING: "WARNING", INFO: "INFO"}
+        for sev, msg in findings:
+            print(f"  {icon[sev]:8s}  {msg}")
+        return 2 if sev_max == 2 else (1 if sev_max == 1 else 0)
+
+    # report
+    def usd(_):  # no pricing here; report is qualitative
+        return ""
+    print(f"a2a-card-lock report — {src}")
+    print(f"  pinned hash : {lock.get('card_hash', '')[:32]}…")
+    print(f"  live hash   : {card_hash(card)[:32]}…")
+    print(f"  skills now  : {len(card.get('skills') or [])} (pinned: {len(lock.get('skills') or {})})")
+    print()
+    if not findings:
+        print("  no drift detected")
+        return 0
+    counts = {s: sum(1 for sv, _ in findings if sv == s) for s in (BREAKING, WARNING, INFO)}
+    print(f"  {counts[BREAKING]} breaking, {counts[WARNING]} warning, {counts[INFO]} info")
+    for sev, msg in findings:
+        print(f"  [{sev:8s}] {msg}")
+    print()
+    if counts[BREAKING]:
+        print("  verdict: BREAKING — re-verify this agent out-of-band before your next task.")
+    elif counts[WARNING]:
+        print("  verdict: CHANGED — review new skills before trusting them.")
+    else:
+        print("  verdict: COSMETIC — safe to re-pin.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())