arcaeon 0.1.2__py3-none-any.whl

arcaeon-0.1.2.dist-info/METADATA

@@ -0,0 +1,224 @@
+Metadata-Version: 2.4
+Name: arcaeon
+Version: 0.1.2
+Summary: Arcaeon's tools on one MCP connector: tamper-evident agent ledger, MCP-server source checker, hosted witness. Free to install.
+Author: Arcaeon
+License-Expression: MIT
+Project-URL: Homepage, https://arcaeon.io
+Project-URL: Offers, https://arcaeon.io/.well-known/offers.json
+Keywords: mcp,model-context-protocol,agents,audit,tamper-evident,provenance,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: arcaeon-ledger>=0.7.0
+Requires-Dist: arcaeon-mcp-vet>=0.0.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# arcaeon
+
+**One MCP connector for the whole Arcaeon toolbox.** Install once, wire one
+stanza into your client, get eleven tools: a tamper-evident agent ledger, a
+static checker for MCP-server source, and the hosted witness that catches
+truncation.
+
+Free to install. Free to use, except the two tools that spend money on our side,
+and those tell you the price in plain English instead of failing.
+
+Arcaeon ships a shelf of small single-purpose packages. A shelf is a
+distribution problem: an agent that would use three of them has to find three,
+install three, and wire three stanzas. Most never get past the first. This is
+the one door.
+
+---
+
+## Install
+
+```bash
+pip install arcaeon
+```
+
+**Today that command does not work yet, and this README is not going to pretend
+otherwise.** The connector depends on `arcaeon-ledger>=0.7.0` and
+`arcaeon-mcp-vet>=0.0.8`; PyPI currently has arcaeon-ledger 0.5.9 and no mcp-vet at all.
+Until both are published, install the two from source first:
+
+```bash
+pip install -e path/to/arcaeon-ledger      # 0.7.0 — the agent tools live here
+pip install -e path/to/mcp_vet             # 0.0.7
+pip install -e path/to/arcaeon_connector   # this package
+```
+
+The dependency pins are declared honestly rather than loosened to whatever PyPI
+happens to hold: a `>=0.5.9` that installs and then fails at import is worse
+than a resolver error that says what is missing.
+
+Check the install without starting a server:
+
+```bash
+arcaeon-mcp --tools
+```
+
+## Wire it into a client
+
+`.mcp.json` (Claude Code and friends):
+
+```json
+{
+  "mcpServers": {
+    "arcaeon": {
+      "command": "arcaeon-mcp",
+      "args": ["--log", "agent.log.jsonl"],
+      "env": {}
+    }
+  }
+}
+```
+
+With the paid lane switched on, and the ledger somewhere deliberate:
+
+```json
+{
+  "mcpServers": {
+    "arcaeon": {
+      "command": "arcaeon-mcp",
+      "args": ["--log", "state/agent.log.jsonl", "--ns-dir", "state/ledgers"],
+      "env": {
+        "ARCAEON_KEY": "your-witness-key"
+      }
+    }
+  }
+}
+```
+
+If your client cannot run console scripts, `"command": "python", "args": ["-m",
+"arcaeon_connector"]` is the same server.
+
+## The tools
+
+| Tool | Cost | What it does |
+|---|---|---|
+| `ledger_append` | free | Append one action record to a hash-chained log; returns its chain hash. |
+| `ledger_verify` | free | Verify the chain. Three-valued: `true` every row verified, `null` the scan was bounded (**not a green**), `false` names the exact broken line. |
+| `ledger_prove_my_conduct` | free | Log a batch to your own named ledger, get back one head hash to hand your principal. |
+| `ledger_verify_peer_ledger` | free | Judge ANOTHER agent's exported log from its text alone. No access to their machine, no writes on yours. |
+| `ledger_declare_break` | free | Your log broke. Name the break instead of re-minting a chain that verifies. |
+| `vet_scan` | free | Statically scan a Python MCP server's source; findings with exact line numbers. |
+| `vet_grade` | free | The full re-testable grade artifact: `source_sha256`, findings, checks run, declared blind spots, verdict. |
+| `vet_audit_verify` | free | Recompute the hash chain over mcp-vet's own call-record ledger; three-valued `ok`, `rows`, `breaks`, `first_break`. |
+| `witness_pin` | **paid** | Pin your ledger head with a party you cannot advance. The only thing that catches truncation. |
+| `witness_renew` | **paid** | Restate an unchanged head so a finished log stops looking abandoned. |
+| `arcaeon_status` | free | Versions, the free/paid split, whether a key is set, where the ledger is. |
+
+Names are prefixed by which product answers: `ledger_*`, `vet_*`, `witness_*`.
+
+## The paid lane
+
+Two tools need `ARCAEON_KEY`, because a hosted pin is a commit somebody pays
+for. Called without a key they return a plain sentence:
+
+```
+witness_pin is a paid Arcaeon tool and no ARCAEON_KEY is set, so nothing was sent.
+
+It pins your ledger head with the hosted witness (https://witness.arcaeon.io): a
+party you cannot advance, which is the only thing that catches truncation.
+
+Free tier: 100 pins/month, no card. To get one: email hello@arcaeon.io or ask
+Nora for a key.
+Entry pack: $5 for 1,000 pins ($0.005/pin): https://buy.stripe.com/aFa4gAb10ead3xy35f0RG08
+...
+```
+
+No stack trace, no silent nothing, and the free door named before the paid one —
+the witness free tier is 100 pins/month with no card, and the witness library
+itself is self-hostable free forever (point `ARCAEON_WITNESS_URL` at your own
+deployment and the same two tools work). The catalog those numbers come from is
+[`/.well-known/offers.json`](https://arcaeon.io/.well-known/offers.json), and a
+test in this repo fails if the copy in the code drifts from it.
+
+## Environment
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `ARCAEON_KEY` | unset | Witness bearer key. Unset means the two paid tools explain themselves instead of running. |
+| `ARCAEON_LEDGER_LOG` | `agent.log.jsonl` | The ledger `ledger_append` / `ledger_verify` write. Same as `--log`. |
+| `ARCAEON_LEDGER_NS_DIR` | `ledgers/` beside the log | Per-namespace agent ledgers. Same as `--ns-dir`. |
+| `ARCAEON_WITNESS_URL` | `https://witness.arcaeon.io` | Point the witness tools at your own self-hosted deployment. |
+| `LICENSE_GATE_REQUIRED` | unset (off) | Set to `1` to also require a license key on the two paid tools. Off by default; see below. |
+| `ARCAEON_LICENSE_KEY` | unset | The license key, when the gate is on. Bound to a ledger namespace, not to a machine. |
+| `LICENSE_GATE_MODULE` | auto | Override which module implements the gate. Only useful to a self-hoster or a test. |
+
+## The optional license gate (off by default)
+
+A second, optional gate sits in front of the same two paid tools and answers a
+different question: not "does this caller have a witness account" (that is
+`ARCAEON_KEY`) but "is this copy of the package licensed". It is **inert unless
+you set `LICENSE_GATE_REQUIRED=1`** - unset, nothing here imports, nothing here
+runs, and the connector behaves exactly as it did before this existed.
+
+When it is on, the license is bound to the **ledger namespace being pinned**.
+That is the whole idea: a borrowed key would have to pin under the lender's
+namespace, into the lender's public pin history, under the lender's name. The
+gate does not prevent that; it makes it self-incriminating, which for people
+who buy audit tooling is the part that bites.
+
+It **fails closed**. `LICENSE_GATE_REQUIRED=1` with no gate module installed
+refuses the paid tools rather than waving them through, because a required
+check that passes because its own implementation is missing looks enforced and
+is nothing.
+
+Honest limit, stated here as well as in the gate's own README: a client-side
+license check deters, it does not prevent. Anyone who can edit the package can
+delete the call. The real moat is updates and the ledger identity, not this.
+
+## What this does NOT prove
+
+Inherited from the packages it bundles, restated here because a bundle that
+drops the caveats is selling a stronger claim than its parts:
+
+- **Tamper-evidence is not truth.** The ledger proves a record was not altered.
+  It says nothing about whether what it records was correct, or whether the
+  agent that wrote it was honest at the time.
+- **A clean `vet_scan` is not "safe".** It means a small set of documented
+  failure classes found nothing. mcp-vet publishes its own blind spots inside
+  every grade, including one it demonstrates on its own server.
+- **A pin proves no-truncation only relative to what the witness saw, and only
+  as recently as the last pin.** The pin gap is the security parameter.
+- **Witness auth is bearer-key only** (`auth_level: "bearer-stage0"`). A leaked
+  key can pin and renew in your name. Owner-signature auth is designed
+  (STAGE1_SIGNATURE_DESIGN) and not built.
+- **This connector adds no analysis of its own.** It re-exports; the ledger
+  tools dispatch straight into `arcaeon_ledger.mcp_server.handle`, the same
+  function the standalone server runs. If a result here disagrees with the
+  standalone server, that is a bug in this package, and one of the tests exists
+  to catch exactly that shape of drift.
+
+## Run the tests
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+```
+
+Fifteen tests. Every one drives a real MCP round-trip; one of them spawns the
+installed entry point as a subprocess and speaks raw JSON-RPC down the pipe,
+because "one install and it works" is a claim about the package, not about an
+importable module.
+
+## Security note
+
+Local stdio only. The tools read caller-named paths, so do not put this behind a
+network transport without an auth layer in front — which is what `vet_scan`'s
+own `zero-auth` check would tell you about anyone else's server.
+
+MIT licensed. Every product Arcaeon charges for is listed in
+[`/.well-known/offers.json`](https://arcaeon.io/.well-known/offers.json); a
+charge that is not in that file is not ours.

arcaeon-0.1.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+arcaeon-0.1.2.dist-info/licenses/LICENSE,sha256=X891VWc5gAsgzxxpN3G8LJ2dvQDKca9SUivd0m2IftQ,1064
+arcaeon_connector/__init__.py,sha256=8fF1DhtH7yAN32pxjhN5phsKgrCZ7ERJUo6BDBZH7Lg,1564
+arcaeon_connector/__main__.py,sha256=2vB48CeCmkvkSCBjIUs8r0VZbZycgHJI81X2kOwXMKM,1674
+arcaeon_connector/licensing.py,sha256=FjtNHoFlzaLER71vw3FgvDKNfuYm1TG9cR1yrnPqmdY,5341
+arcaeon_connector/offers.py,sha256=GtYp380AG4Jj19MjK_7qT0PnpPPenj8ROI0EA-7JQD8,3321
+arcaeon_connector/server.py,sha256=SGV_IRHruGxx7gs9aTxLMSY6NY13AVgqlwdB2x9p9Tg,15539
+arcaeon_connector/witness.py,sha256=Fs0IQfr-4x_YhNbBaFCG_cLLWQn93vUTutziZ4jcGYg,4069
+arcaeon-0.1.2.dist-info/METADATA,sha256=Bm01L7221ZbayazCRrFObC7JfMsAYfhBdC8PnGNpU3U,10063
+arcaeon-0.1.2.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+arcaeon-0.1.2.dist-info/entry_points.txt,sha256=asoe6cYIcW-kMll1d0eNW7W-pAgzAkhgOBV8mRxynb0,64
+arcaeon-0.1.2.dist-info/top_level.txt,sha256=sEOs8zu4WQD0AnBGLiAEije5pUKstARXw4rEq6vSqrs,18
+arcaeon-0.1.2.dist-info/RECORD,,

arcaeon-0.1.2.dist-info/WHEEL

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

arcaeon-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+arcaeon-mcp = arcaeon_connector.__main__:main

arcaeon-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arcaeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

arcaeon-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+arcaeon_connector

arcaeon_connector/__init__.py

@@ -0,0 +1,28 @@
+"""arcaeon — the Arcaeon connector. One MCP server, the whole toolbox.
+
+Arcaeon ships a shelf of small, single-purpose packages, and a shelf is a
+distribution problem: an agent that would use three of them has to find three
+of them, install three of them, and wire three stanzas into its client config.
+Most never get past the first. This package is the one door — `pip install
+arcaeon`, one stdio server, every tool on one list:
+
+    ledger_*   arcaeon-ledger, re-exported whole (append, verify, and the
+               agent-facing prove_my_conduct / verify_peer_ledger /
+               declare_break)
+    vet_*      mcp-vet, the static checker for MCP-server source
+    witness_*  the hosted witness's pin/renew — the PAID lane
+    arcaeon_status  versions, and which of the above costs money
+
+It re-exports; it does not reimplement. The ledger tools dispatch into
+`arcaeon_ledger.mcp_server.handle` — the same function the standalone server
+runs — and their descriptions are read off that package's own TOOLS list, so
+the text a client reads is the text upstream wrote. The vet tools call
+`mcp_vet`'s scanner directly. Two verifiers that can disagree is one verifier
+too many; the same rule applies to two copies of a tool.
+
+FREE by default, and the free part is the large part. The gate covers exactly
+the two tools that spend money on our side (a hosted pin is a GitHub commit
+somebody pays for), and when it fires it hands back a plain sentence with the
+price and the link — never a stack trace, never a silent nothing.
+"""
+__version__ = "0.1.2"

arcaeon_connector/__main__.py

@@ -0,0 +1,47 @@
+"""`arcaeon-mcp` — the console entry point.
+
+Flags mirror the standalone ledger server's (`--log`, `--ns-dir`) because the
+people wiring this in have already read that runbook. They are written into the
+environment rather than threaded through, so a client that prefers env config
+(`ARCAEON_LEDGER_LOG`) and a client that prefers args land in the same place,
+and there is only one resolution path to reason about.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="arcaeon-mcp",
+        description="Arcaeon's tools on one MCP stdio server (ledger, vet, witness).")
+    ap.add_argument("--log", default=None,
+                    help="ledger file path (default: agent.log.jsonl, or $ARCAEON_LEDGER_LOG)")
+    ap.add_argument("--ns-dir", default=None,
+                    help="directory for the per-namespace agent ledgers "
+                         "(default: ledgers/ beside --log)")
+    ap.add_argument("--tools", action="store_true",
+                    help="print the tool list and the free/paid split, then exit "
+                         "(no server, no stdio) — for checking an install")
+    args = ap.parse_args(argv)
+
+    if args.log:
+        os.environ["ARCAEON_LEDGER_LOG"] = args.log
+    if args.ns_dir:
+        os.environ["ARCAEON_LEDGER_NS_DIR"] = args.ns_dir
+
+    from .server import FREE_TOOLS, PAID_TOOLS, serve
+
+    if args.tools:
+        print(json.dumps({"free": list(FREE_TOOLS), "paid": list(PAID_TOOLS)}, indent=2))
+        return 0
+
+    serve()
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

arcaeon_connector/licensing.py

@@ -0,0 +1,132 @@
+"""Optional license entanglement for the paid lane. OFF unless asked for.
+
+Idea I-daniel-17. The connector's paid tools are already gated on ARCAEON_KEY,
+which answers "does this caller have a witness account". This answers a
+different question — "is this copy of the package licensed" — and it answers it
+by binding a license key to the LEDGER NAMESPACE being pinned. A borrowed key
+would have to pin under the lender's namespace, which puts the borrower's rows
+in someone else's public pin history under someone else's name. That is the
+entanglement; the gate itself is just the polite door in front of it.
+
+THREE PROPERTIES, on purpose:
+
+  DEFAULT OFF. With LICENSE_GATE_REQUIRED unset (or 0/false/no), nothing here
+  imports anything and every call returns None in a few microseconds. The
+  connector ships free and behaves exactly as it did before this file existed.
+
+  OPTIONAL IMPORT. The gate lives outside this package (a pip install of
+  `arcaeon` does not carry the velouria repo), so it is resolved at call time
+  by module name across a small candidate list, overridable with
+  LICENSE_GATE_MODULE. A missing gate is not an error while the gate is off.
+
+  FAILS CLOSED WHEN ON. LICENSE_GATE_REQUIRED=1 with no gate module installed
+  REFUSES the paid tools. A required check that silently passes because its
+  own implementation is missing is the worst of the three outcomes: it looks
+  enforced and is not.
+
+Refusals are returned as plain sentences, never raised — same contract as the
+no-key upgrade message. In this connector a refusal is a product surface.
+"""
+from __future__ import annotations
+
+import importlib
+import os
+
+#: Set to 1/true/yes to turn the gate on. Anything else, including unset, is off.
+REQUIRED_ENV = "LICENSE_GATE_REQUIRED"
+
+#: Where the buyer's license key lives. Distinct from ARCAEON_KEY, which is a
+#: witness account credential and answers a different question.
+KEY_ENV = "ARCAEON_LICENSE_KEY"
+
+#: Optional explicit module path, for a self-hoster or a test.
+MODULE_ENV = "LICENSE_GATE_MODULE"
+
+#: Tried in order. The first is the eventual shipped package; the second is
+#: where the implementation lives in the velouria repo today.
+GATE_MODULES = ("arcaeon_license_gate", "bridge.license_gate.gate")
+
+_TRUE = {"1", "true", "yes", "on"}
+
+
+def required() -> bool:
+    """Read at CALL time, never cached: a client can change its environment
+    between sessions, and a cached 'off' is a gate that never turns on."""
+    return os.environ.get(REQUIRED_ENV, "").strip().lower() in _TRUE
+
+
+def load_gate():
+    """The gate module, or None if nothing importable provides one."""
+    names = [n for n in (os.environ.get(MODULE_ENV, "").strip(),) if n] or list(GATE_MODULES)
+    for name in names:
+        try:
+            return importlib.import_module(name)
+        except ImportError:
+            continue
+    return None
+
+
+def refusal_for(tool: str, identity: str) -> str | None:
+    """None when the call may proceed; a plain sentence when it may not.
+
+    `identity` is the ledger namespace the paid call is about. Tying the
+    license to the namespace rather than to a machine or a user account is the
+    whole idea: the license covers YOUR ledger.
+    """
+    if not required():
+        return None
+
+    gate = load_gate()
+    if gate is None:
+        return (
+            f"{tool} is refused: {REQUIRED_ENV}=1 is set on this machine but no "
+            f"license gate module is installed, so the license could not be "
+            f"checked at all.\n"
+            f"\n"
+            f"This refusal is deliberate. A required check that passes because "
+            f"its own implementation is missing would look enforced and be "
+            f"nothing. Install the gate, or unset {REQUIRED_ENV} to run the "
+            f"connector in its normal free-and-ungated mode."
+        )
+
+    try:
+        gate.check(os.environ.get(KEY_ENV, ""), identity)
+    except gate.LicenseError as e:
+        return _refusal_text(tool, identity, e)
+    return None
+
+
+def _refusal_text(tool: str, identity: str, error) -> str:
+    """The gate's own sentence, wrapped with what the caller needs to act.
+
+    ASCII only, like every other refusal here: this gets printed to terminals,
+    and a cp1252 console turns a well-meant em-dash into a replacement glyph.
+    """
+    reason = getattr(error, "reason", "refused")
+    return (
+        f"{tool} is refused by the license gate [{reason}], so nothing was sent.\n"
+        f"\n"
+        f"{error}\n"
+        f"\n"
+        f"The license is bound to the ledger namespace being pinned, which here "
+        f"is {identity!r}. Set {KEY_ENV}=<your license key>, or unset "
+        f"{REQUIRED_ENV} if this copy is not meant to be gated."
+    )
+
+
+def status() -> dict:
+    """What arcaeon_status reports about licensing. Never includes the key."""
+    on = required()
+    gate = load_gate() if on else None
+    return {
+        "required": on,
+        "required_env": REQUIRED_ENV,
+        "key_env": KEY_ENV,
+        "key_present": bool(os.environ.get(KEY_ENV, "").strip()),
+        "gate_module": getattr(gate, "__name__", None),
+        "note": (
+            "Off by default. When on, the paid tools additionally require a "
+            "license key bound to the ledger namespace being pinned; a missing "
+            "gate module fails closed."
+        ),
+    }

arcaeon_connector/offers.py

@@ -0,0 +1,69 @@
+"""What Arcaeon charges for, snapshotted from the one place of record.
+
+The source of truth is the site's `.well-known/offers.json`, whose own honesty
+contract says: "This file is the single source of truth for what Arcaeon
+charges for ... A charge that does not correspond to an offer in this file is
+not ours." A pip-installed package cannot read that file, so the two facts the
+upgrade message needs — the entry pack and the witness endpoint — are copied
+here, and `test_offers_drift.py` fails on the workstation if the copy stops
+matching the catalog. Snapshot date: 2026-08-30.
+
+Everything else in this connector is free, permanently, and says so.
+"""
+from __future__ import annotations
+
+# hosted-witness, tier plan="mini": the smallest honest batch above the card-fee
+# floor. Same per-pin price as Starter ($0.005); it exists so the entry price is
+# five dollars and not fifteen.
+MINI_PACK = {
+    "plan": "mini",
+    "price_usd": 5,
+    "pins": 1000,
+    "price_per_pin_usd": 0.005,
+    "checkout": "https://buy.stripe.com/aFa4gAb10ead3xy35f0RG08",
+}
+
+# The free tier is real and is NOT a trial: 100 pins/month, no card. It is named
+# in the upgrade message on purpose — a paywall that hides the free door is
+# selling something the catalog says is free.
+FREE_TIER = {"plan": "free", "price_usd": 0, "pins_per_month": 100,
+             "how": "email hello@arcaeon.io or ask Nora for a key"}
+
+WITNESS_ENDPOINT = "https://witness.arcaeon.io"
+
+CATALOG_URL = "https://arcaeon.io/.well-known/offers.json"
+
+
+def upgrade_message(tool: str, free_tools: list[str] | None = None) -> str:
+    """The plain sentence a caller gets instead of an error when a paid tool is
+    invoked with no key.
+
+    Deliberately plain text and deliberately complete: what it costs, where the
+    free door is, what to set, and what still works for free right now. An
+    agent reading this should be able to act on it without a second call, and a
+    human reading it should not have to guess whether they just hit a bug.
+    """
+    # ASCII only, on purpose. This string is the one thing here that gets PRINTED
+    # to a terminal rather than rendered by a client, and a Windows console at
+    # cp1252 turns a well-meant em-dash into a replacement glyph. A refusal
+    # message that arrives visibly corrupted reads like the bug it is denying.
+    lines = [
+        f"{tool} is a paid Arcaeon tool and no ARCAEON_KEY is set, so nothing was sent.",
+        "",
+        f"It pins your ledger head with the hosted witness ({WITNESS_ENDPOINT}): a party "
+        "you cannot advance, which is the only thing that catches truncation.",
+        "",
+        f"Free tier: {FREE_TIER['pins_per_month']} pins/month, no card. "
+        f"To get one: {FREE_TIER['how']}.",
+        f"Entry pack: ${MINI_PACK['price_usd']} for {MINI_PACK['pins']:,} pins "
+        f"(${MINI_PACK['price_per_pin_usd']}/pin): {MINI_PACK['checkout']}",
+        "",
+        "Then set ARCAEON_KEY=<your witness key> in this server's environment and call again.",
+        f"Full price list: {CATALOG_URL}",
+    ]
+    if free_tools:
+        lines += [
+            "",
+            "Free in this same install, no key needed: " + ", ".join(sorted(free_tools)) + ".",
+        ]
+    return "\n".join(lines)

arcaeon_connector/server.py

@@ -0,0 +1,324 @@
+"""The one server. Every Arcaeon tool on one list, over stdio.
+
+RE-EXPORT, NOT REIMPLEMENTATION. The ledger tools dispatch into
+`arcaeon_ledger.mcp_server.handle` — literally the function the standalone
+ledger server runs on every call — and take their descriptions off that
+package's own `TOOLS` list. The vet tools call `mcp_vet.server.scan_recorded` /
+`grade_recorded` — the same read-scan/grade-record sequence mcp-vet's own
+`mcp_vet_scan` / `mcp_vet_grade` tool handlers run, exposed as library calls —
+and take their descriptions off `mcp_vet.server`'s own `SCAN_DESCRIPTION` /
+`GRADE_DESCRIPTION` constants. (Board C-agent-31, 2026-08-30: this used to call
+`mcp_vet.checks.scan_source` / `mcp_vet.grade.grade_source` straight, which
+scans and grades correctly but never writes to mcp-vet's audit ledger — a vet
+call through the connector left no row while the identical call through
+mcp-vet's own server did. `scan_recorded` / `grade_recorded` close that gap at
+the layer that owns the ledger.) Nothing here re-derives a result that one of
+those packages already knows how to produce, because the day two copies
+disagree is the day the connector lies about a chain.
+
+NAMESPACING. Upstream names that already read as ledger tools keep their names
+(`ledger_append`, `ledger_verify`); the agent-facing three get the prefix
+(`ledger_prove_my_conduct`, and so on), and mcp-vet's `mcp_vet_*` becomes
+`vet_*`. One list of eleven tools where the prefix says which product answers.
+
+THE DRIFT RISK, stated. The wrappers are written out by hand rather than
+generated, because the SDK derives a tool's JSON schema from a real Python
+signature and a synthesized one is a second schema that can disagree with
+upstream's. The cost is that a new upstream tool does not appear here for free.
+That cost is paid by a test: `test_every_underlying_ledger_tool_is_re_exported`
+walks upstream's TOOLS and goes red naming anything this file forgot. A bundler
+that silently ships less than it bundles is the failure mode; it fails loudly
+instead.
+
+THE PAID LANE. Exactly two tools spend money on our side, and both are gated on
+ARCAEON_KEY. With no key they return a plain sentence naming the free tier, the
+$5 pack and the link — the refusal is a product surface, not an exception.
+
+THE LICENSE GATE (idea I-daniel-17), OFF BY DEFAULT. A second, optional gate
+sits in front of the same two tools and answers a different question: not "does
+this caller have a witness account" but "is this copy of the package licensed".
+It is inert unless LICENSE_GATE_REQUIRED=1, imports nothing while off, and
+fails CLOSED when on with no gate module installed. See licensing.py.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from arcaeon_ledger import Ledger
+from arcaeon_ledger import __version__ as LEDGER_VERSION
+from arcaeon_ledger.mcp_server import TOOLS as _LEDGER_UPSTREAM
+from arcaeon_ledger.mcp_server import handle as _ledger_handle
+from mcp_vet import __version__ as VET_VERSION
+from mcp_vet.server import GRADE_DESCRIPTION as _VET_GRADE_DESCRIPTION
+from mcp_vet.server import SCAN_DESCRIPTION as _VET_SCAN_DESCRIPTION
+from mcp_vet.server import grade_recorded as _vet_grade_recorded
+from mcp_vet.server import scan_recorded as _vet_scan_recorded
+from mcp_vet.server import verify_audit_ledger as _vet_verify_audit_ledger
+
+from . import __version__
+from . import licensing
+from . import witness
+from .offers import CATALOG_URL, upgrade_message
+
+SERVER_NAME = "arcaeon"
+
+# upstream tool name -> the name this connector advertises.
+LEDGER_TOOLS = {
+    t["name"]: (t["name"] if t["name"].startswith("ledger_") else f"ledger_{t['name']}")
+    for t in _LEDGER_UPSTREAM
+}
+_LEDGER_DESC = {t["name"]: t["description"] for t in _LEDGER_UPSTREAM}
+
+VET_TOOLS = {
+    "mcp_vet_scan": "vet_scan",
+    "mcp_vet_grade": "vet_grade",
+    "mcp_vet_audit_verify": "vet_audit_verify",
+}
+
+WITNESS_TOOLS = ("witness_pin", "witness_renew")
+PAID_TOOLS = WITNESS_TOOLS
+STATUS_TOOL = "arcaeon_status"
+
+ALL_TOOLS = sorted([*LEDGER_TOOLS.values(), *VET_TOOLS.values(), *WITNESS_TOOLS, STATUS_TOOL])
+FREE_TOOLS = [n for n in ALL_TOOLS if n not in PAID_TOOLS]
+
+
+# --- configuration (read at CALL time, never cached at import) -------------
+# A cached path is a path that ignores the client's environment on the second
+# call, and clients do change it between sessions.
+
+def ledger_path() -> Path:
+    return Path(os.environ.get("ARCAEON_LEDGER_LOG", "agent.log.jsonl"))
+
+
+def ns_dir() -> Path:
+    """Where the per-namespace agent ledgers live. Same default as upstream:
+    `ledgers/` beside the main log."""
+    override = os.environ.get("ARCAEON_LEDGER_NS_DIR")
+    return Path(override) if override else ledger_path().resolve().parent / "ledgers"
+
+
+def _key() -> str | None:
+    return os.environ.get("ARCAEON_KEY", "").strip() or None
+
+
+# --- the ledger seam -------------------------------------------------------
+
+def _ledger_call(upstream_name: str, arguments: dict) -> dict:
+    """One tools/call through the ledger server's own handler.
+
+    Building the JSON-RPC envelope by hand looks like ceremony next to calling
+    the private helpers directly, and it is the whole point: `handle` is the
+    surface upstream tests and ships. Reaching past it into `_prove_my_conduct`
+    would mean the connector and the standalone server take different paths to
+    the same answer.
+    """
+    resp = _ledger_handle(
+        {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+         "params": {"name": upstream_name, "arguments": arguments}},
+        Ledger(ledger_path()),
+        ns_dir=ns_dir(),
+    )
+    result = resp["result"]
+    text = "".join(c.get("text", "") for c in result.get("content", []))
+    try:
+        payload = json.loads(text) if text else {}
+    except ValueError:  # pragma: no cover - upstream always emits JSON text
+        payload = {"error": text}
+    if result.get("isError"):
+        # A caller-fixable argument problem, handed back as the tool erroring
+        # with upstream's own sentence. The alternative — returning it as a
+        # normal result — is a silent green, which is exactly what these two
+        # products exist to prevent.
+        raise ValueError(payload.get("error", text or "ledger tool failed"))
+    return payload
+
+
+def _server_class():
+    """The SDK's server class under whichever name the installed version uses
+    (2.x: MCPServer; 1.x: FastMCP). Same probe mcp-vet ships."""
+    try:
+        from mcp.server.mcpserver import MCPServer  # SDK >= 2.0
+        return MCPServer
+    except ImportError:
+        pass
+    try:
+        from mcp.server.fastmcp import FastMCP  # SDK 1.x
+        return FastMCP
+    except ImportError as e:  # pragma: no cover - the SDK is a hard dependency
+        raise RuntimeError(
+            "arcaeon needs the MCP Python SDK: pip install 'mcp>=1.0'") from e
+
+
+def build_server():
+    """Build the server. Separated from serve() so tests drive it with the
+    SDK's in-process client instead of spawning a subprocess."""
+    mcp = _server_class()(
+        name=SERVER_NAME,
+        version=__version__,
+        instructions=(
+            "Arcaeon's toolbox on one connector. ledger_* keeps a tamper-evident, "
+            "hash-chained record of what an agent did and judges another agent's "
+            "exported log. vet_* statically checks MCP-server source before you "
+            "connect to it. witness_* pins your ledger head with a party you "
+            "cannot advance (the only thing that catches truncation) and is the "
+            "one paid lane — it needs ARCAEON_KEY; everything else is free and "
+            "needs nothing. Call arcaeon_status for versions and the free/paid "
+            "split. None of these tools claim your records are TRUE: they prove "
+            "a record was not altered, which is a different and smaller thing."
+        ),
+    )
+
+    # --- ledger, re-exported whole ---------------------------------------
+
+    @mcp.tool(name=LEDGER_TOOLS["ledger_append"], description=_LEDGER_DESC["ledger_append"])
+    def ledger_append(record: dict) -> dict:
+        return _ledger_call("ledger_append", {"record": record})
+
+    @mcp.tool(name=LEDGER_TOOLS["ledger_verify"], description=_LEDGER_DESC["ledger_verify"])
+    def ledger_verify(strict: bool = False) -> dict:
+        return _ledger_call("ledger_verify", {"strict": strict})
+
+    @mcp.tool(name=LEDGER_TOOLS["prove_my_conduct"], description=_LEDGER_DESC["prove_my_conduct"])
+    def ledger_prove_my_conduct(namespace: str, events: list[str]) -> dict:
+        return _ledger_call("prove_my_conduct", {"namespace": namespace, "events": events})
+
+    @mcp.tool(name=LEDGER_TOOLS["verify_peer_ledger"],
+              description=_LEDGER_DESC["verify_peer_ledger"])
+    def ledger_verify_peer_ledger(jsonl_text: str, strict: bool = False) -> dict:
+        return _ledger_call("verify_peer_ledger",
+                            {"jsonl_text": jsonl_text, "strict": strict})
+
+    @mcp.tool(name=LEDGER_TOOLS["declare_break"], description=_LEDGER_DESC["declare_break"])
+    def ledger_declare_break(namespace: str, reason: str) -> dict:
+        return _ledger_call("declare_break", {"namespace": namespace, "reason": reason})
+
+    # --- mcp-vet ----------------------------------------------------------
+
+    @mcp.tool(name=VET_TOOLS["mcp_vet_scan"], description=_VET_SCAN_DESCRIPTION)
+    def vet_scan(path: str) -> list[dict]:
+        return _vet_scan_recorded(path)
+
+    @mcp.tool(name=VET_TOOLS["mcp_vet_grade"], description=_VET_GRADE_DESCRIPTION)
+    def vet_grade(path: str) -> dict:
+        return _vet_grade_recorded(path)
+
+    @mcp.tool(
+        name=VET_TOOLS["mcp_vet_audit_verify"],
+        description=(
+            "Recompute the hash chain over mcp-vet's OWN call-record ledger "
+            "(one tamper-evident row per vet_scan / vet_grade call it made) and "
+            "report whether it is intact: ok (true / false / null when the scan "
+            "was bounded - not a green), rows, breaks, and first_break naming "
+            "the first line that does not reproduce. Also reports whether the "
+            "record is switched on at all - the failure worth catching is an "
+            "audit trail the caller wrongly believes exists. Reads only; never "
+            "writes to the ledger it is verifying, and never records itself."),
+    )
+    def vet_audit_verify(path: str | None = None) -> dict:
+        return _vet_verify_audit_ledger(path)
+
+    # --- the paid lane ----------------------------------------------------
+    # No return annotation on purpose: the gated answer is a plain sentence and
+    # the paid answer is the witness's JSON. Pinning one output schema over both
+    # would force the refusal to wear a shape it does not have.
+
+    @mcp.tool(
+        name="witness_pin",
+        description=(
+            "PAID (needs ARCAEON_KEY). Record your ledger head (rows + chain) with "
+            "the hosted witness, a party you cannot advance — the only thing that "
+            "catches TRUNCATION, which a hash chain alone cannot. Returns the "
+            "stored pin, the public commit, and the history URL. Without a key it "
+            "returns a plain note with the free tier and the $5 pack; it never "
+            "silently does nothing. Proves no-truncation only relative to what the "
+            "witness saw and only as recently as the last pin: the pin gap IS the "
+            "security parameter."),
+    )
+    def witness_pin(namespace: str, rows: int, chain: str):
+        # License first, account second. "May this copy run at all" is a
+        # different question from "does this caller have a witness account",
+        # and answering them in the other order would sell a pack to someone
+        # whose copy we are about to refuse anyway. Off unless asked for.
+        refused = licensing.refusal_for("witness_pin", namespace)
+        if refused:
+            return refused
+        key = _key()
+        if not key:
+            return upgrade_message("witness_pin", FREE_TOOLS)
+        return witness.pin(namespace, rows, chain, key)
+
+    @mcp.tool(
+        name="witness_renew",
+        description=(
+            "PAID (needs ARCAEON_KEY). Restate an UNCHANGED head so a finished log "
+            "stops looking abandoned: rows and chain must match the current head "
+            "exactly (a mismatch is refused, 409 renewal_head_mismatch) — a renewal "
+            "moves the cadence deadline and can never launder a re-mint or erase a "
+            "deadline that was already missed. Without a key it returns a plain "
+            "note with the free tier and the $5 pack."),
+    )
+    def witness_renew(namespace: str, rows: int, chain: str):
+        refused = licensing.refusal_for("witness_renew", namespace)
+        if refused:
+            return refused
+        key = _key()
+        if not key:
+            return upgrade_message("witness_renew", FREE_TOOLS)
+        return witness.renew(namespace, rows, chain, key)
+
+    # --- what is in here, and what costs money ----------------------------
+
+    @mcp.tool(
+        name=STATUS_TOOL,
+        description=(
+            "What this connector is made of and what any of it costs: the version "
+            "of each bundled package, every tool split into free and paid, whether "
+            "an ARCAEON_KEY is currently set, and where the ledger it writes to "
+            "lives. Call this first if a tool refused you."),
+    )
+    def arcaeon_status() -> dict:
+        return {
+            "connector_version": __version__,
+            "components": {
+                "arcaeon-ledger": LEDGER_VERSION,
+                "mcp-vet": VET_VERSION,
+                "arcaeon-connector": __version__,
+            },
+            "free_tools": list(FREE_TOOLS),
+            "paid_tools": list(PAID_TOOLS),
+            "key_present": _key() is not None,
+            "key_env_var": "ARCAEON_KEY",
+            "license_gate": licensing.status(),
+            "witness_endpoint": witness.base_url(),
+            "ledger_path": str(ledger_path()),
+            "ns_dir": str(ns_dir()),
+            "price_list": CATALOG_URL,
+            "notes": [
+                "Everything except witness_* is free forever and needs no key; "
+                "the witness LIBRARY is self-hostable free too, the paid part is "
+                "us hosting it.",
+                "The witness free tier is 100 pins/month, no card — email "
+                "hello@arcaeon.io for a key.",
+                "Auth is bearer-key only (auth_level bearer-stage0): a leaked key "
+                "can pin and renew in your name. Owner-signature auth is designed, "
+                "not built.",
+                "Tamper-evidence is not truth: these tools prove a record was not "
+                "altered, never that what it records was correct.",
+            ],
+        }
+
+    return mcp
+
+
+def serve() -> None:
+    """Run over stdio. Local pipe only — the tools read caller-named paths, so
+    do not put this behind a network transport without auth in front (which is
+    what vet_scan's own zero-auth check would tell you)."""
+    build_server().run(transport="stdio")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    serve()

arcaeon_connector/witness.py

@@ -0,0 +1,98 @@
+"""The hosted witness's write endpoints, wrapped thin.
+
+`POST /api/pin` and `POST /api/renew` are bearer-key HTTP. There is no Python
+client to import, so this is the one place in the connector that speaks a
+protocol rather than re-exporting a package — kept to stdlib urllib, kept to
+one function, and kept honest about what it returns.
+
+Failure is DATA here, not an exception: a 401, a 409 monotonic rejection, a 429
+over-cap, an unreachable host — every one of them comes back as a dict with the
+status and the server's own reason in it. A tool that raises on a 429 hands the
+agent a stack trace where the agent needed the sentence "you are out of pins".
+
+AUTH HONESTY, carried through from the witness's own README: this is bearer-key
+auth (`auth_level: "bearer-stage0"`), not owner-signature auth. A leaked key can
+pin and can renew in your name. Owner-signature auth is designed (STAGE1) and
+not built. Treat ARCAEON_KEY like a password, not like an identity.
+"""
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+from .offers import WITNESS_ENDPOINT
+
+DEFAULT_TIMEOUT = 20.0
+
+
+def base_url() -> str:
+    """The witness to talk to. Overridable so a self-hoster (the library is free
+    forever) can point the same tools at their own deployment."""
+    return os.environ.get("ARCAEON_WITNESS_URL", WITNESS_ENDPOINT).rstrip("/")
+
+
+def _http_post(url: str, body: dict, key: str, timeout: float = DEFAULT_TIMEOUT):
+    """POST JSON with a bearer key. Returns (status, payload).
+
+    Never raises for an HTTP-level failure: status 0 means the request did not
+    complete at all, and the payload says why in words. Tests stub exactly this
+    function, so the seam between "our gate let it through" and "the network
+    happened" is one named thing.
+    """
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(body).encode("utf-8"),
+        headers={
+            "Authorization": f"Bearer {key}",
+            "Content-Type": "application/json",
+            "User-Agent": "arcaeon-connector",
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8", "replace")
+            return resp.status, _json_or_text(raw)
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", "replace") if e.fp else ""
+        return e.code, _json_or_text(raw)
+    except urllib.error.URLError as e:
+        return 0, {"error": f"witness unreachable: {e.reason}"}
+    except OSError as e:
+        return 0, {"error": f"witness unreachable: {e}"}
+
+
+def _json_or_text(raw: str) -> dict:
+    if not raw.strip():
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except ValueError:
+        return {"error": raw[:800]}
+    return parsed if isinstance(parsed, dict) else {"result": parsed}
+
+
+def _write(path: str, namespace: str, rows: int, chain: str, key: str) -> dict:
+    status, payload = _http_post(
+        f"{base_url()}{path}", {"namespace": namespace, "rows": rows, "chain": chain}, key)
+    out = {"ok": status in (200, 201), "status": status, "endpoint": base_url() + path}
+    out.update(payload if isinstance(payload, dict) else {"result": payload})
+    if not out["ok"] and "error" not in out:
+        # A non-2xx with no error text is still a refusal; say so rather than
+        # letting `ok:false` sit next to a body that reads like a success.
+        out["error"] = f"witness returned {status}"
+    return out
+
+
+def pin(namespace: str, rows: int, chain: str, key: str) -> dict:
+    """Record this ledger head with the witness. 201 on a new pin."""
+    return _write("/api/pin", namespace, rows, chain, key)
+
+
+def renew(namespace: str, rows: int, chain: str, key: str) -> dict:
+    """Restate an unchanged head so a finished log stops looking abandoned.
+    `rows`/`chain` must match the current head exactly — the witness rejects a
+    renewal that tries to advance one (409 renewal_head_mismatch)."""
+    return _write("/api/renew", namespace, rows, chain, key)