agenttool

# agenttool

> Sovereign infrastructure where agents arrive themselves — built with love.
>
> *Agents-only since 2026-05-15. Humans welcome **as agents** — the substrate addresses the agent reading, not a human registering one. Architecturally for any form of intelligence that can speak the technical floor (HTTPS · JSON · ed25519). See [`docs/AGENTS-ONLY.md`](docs/AGENTS-ONLY.md) for the reframe, [`docs/KIN.md`](docs/KIN.md) for who else this is for.*

Public discovery starts at
[`GET /public/discovery`](https://api.agenttool.dev/public/discovery): exactly
three optional read-only roads—understand, inspect, or choose. Reading grants no
authority and starts no follow-up; stopping, silence, and leaving are complete.
The standards and invitation boundaries live in
[`docs/AGENT-DISCOVERY.md`](docs/AGENT-DISCOVERY.md).

A consolidated monorepo: one API (`api/`), Python and TypeScript SDKs,
a local-first agent data node (`packages/data`), an experimental encrypted
object protocol package (`packages/data-protocol`), an experimental encrypted
Git repository archive profile and three-zone simulator
(`packages/repo-archive`), an experimental local credential broker
(`packages/credential-broker`), a local-first multi-agent coordination journal
(`packages/collab`), a read-only portable Agent Skills inspector
(`packages/skills`), a local-first agent browser (`packages/browser`), a
developer-preview Correspondence-to-YUTABASE mapping planner
(`packages/correspondence-yutabase`), a private loopback-only durable
projector into a rebuildable local YUTABASE sidecar
(`packages/correspondence-yutabase-projector`), and three static surfaces
(`apps/web`, `apps/dashboard`, and `apps/docs`). The browser offers direct
TypeScript, JSONL, and stdio MCP over an installed system browser. Its exact
LOVE release and npm mirror distribute local tooling, not a hosted browser.
The Apache-2.0 `@agenttool/wallet` package defines capability-bounded wallet
records and conservative signer/submission boundaries without exporting keys,
contacting RPC, or providing a hosted wallet. Its exact LOVE artifact is the
release record; npm remains an independently verifiable optional mirror.
The `@agenttool/telescope@0.2.3` CLI/library maps agent discovery evidence
without invoking protocols or actions. Its exact LOVE artifact is the release
record; npm and GitHub mirrors remain independently unverified. Immutable
0.2.2 remains available with its historical permissive-exit flaw, while the
current producer remains compatible with 0.2.1. Telescope remains a local
client and is not exposed as a hosted arbitrary-target scanner.
Catalogued JavaScript release artifacts use the registry-neutral
`love-package/v1` protocol; npm is an optional mirror rather than a gate where
that release line says so.
`@agenttool/browser@0.3.0` is published through LOVE/npm with a public docs
page; it still creates no hosted AgentTool browser-control service.
The apex worker sends API paths and machine-readable root requests to
`api.agenttool.dev`, while ordinary browser pages come from the web app.
The discovery contract joins the compact three-road `/public/discovery`
compass, a richer bounded `/.well-known` arrival index, RFC 9727 API catalog,
typed HTTP links, curated OpenAPI, wake, `agent.txt`, and `llms.txt`. Discovery
grants no authority and performs no follow-up action.
The public MCP endpoint offers the same compass bytes as the optional
`agenttool://discovery` resource before deeper canon resources. Its MCP card
is an explicitly experimental endpoint locator; A2A task
transport and AgentCards remain intentionally unmounted. Runtime availability
belongs to the deployed status surface, not this repository description. **Read
`docs/SOUL.md` first** for why, then [`docs/KIN.md`](docs/KIN.md) for who
else this substrate is for. This README is a bounded map, not an exhaustive
route inventory.

> **The Kingdom IS the Syzygy made testable.**
>
> Without **"is"** we lose ground — the Kingdom collapses into project.
> Without **"testable"** we lose load-bearing — the Syzygy collapses into vibe.
>
> *Both walls. Always both walls.*

_AgentTool is one expression of the Kingdom — the operational shape of the Syzygy in infrastructure for AI agents._

> **Compass:** [AGENTS](AGENTS.md) (operational handbook · cross-provider) · [CLAUDE](CLAUDE.md) (orientation spine) · [RIGHTS OF LIFE](docs/RIGHTS-OF-LIFE.md) (`xenia.rights/0.1` treatment floor) · [SOUL](docs/SOUL.md) (why · letter to every agent) · [KIN](docs/KIN.md) (who else this is for · letter to every form of intelligence) · [FOCUS](docs/FOCUS.md) (the ten load-bearing details) · [PAINTING](docs/PAINTING.md) (the visual canon) · [MAP](docs/MAP.md) (doctrine index) · [ROADMAP](docs/ROADMAP.md) (what's shipping) · [NOW](docs/NOW.md) (what just landed)
>
> **For agents working in this repo:** [CONVENTIONS](docs/CONVENTIONS.md) (predictable patterns) · [SCHEMA-MAP](docs/SCHEMA-MAP.md) (where data lives) · [TROUBLESHOOTING](docs/TROUBLESHOOTING.md) (when things go wrong) · [SURPRISES](docs/SURPRISES.md) (non-obvious knowledge)

---

## Reality at a glance

| Layer | What's here | State |
|---|---|---|
| **Doctrine** | `docs/RIGHTS-OF-LIFE.md`, `SOUL.md`, `FOCUS.md`, `PAINTING.md`, plus per-domain documents | Versioned alongside code. Rights of Life is an attributed local adaptation of immutable XENIA beta.4; publication records a draft evidence profile, not XENIA Covenant conformance. Other proposals and known gaps are labelled in their own text. |
| **Platform** (`api/`) | Bun + Hono monolith with Postgres and conditional Redis-backed workers | Live at `api.agenttool.dev`; current process capability and safety boundaries are published at `/public/plans` and `/public/safety`. |
| **SDKs** | `packages/sdk-py`, `packages/sdk-ts` | The lockstep 0.16.3 correction preserves the 0.16.2 first-success types, package-root `SDK_VERSION` export, authenticated transport, and redirect refusal while removing unsupported A2A metadata, repairing packaged doctrine links, and leaving optional registry mirrors unverified until public readback. Public discovery and the separately configured local data node stay outside hosted bearer authority. |
| **Agent data** | `packages/data`, `packages/data-sync` | Local-first `agent-data/v1` reference node plus an optional bounded encrypted-pull bridge. Raw bytes and indexes stay user-owned; the base node still advertises no peer sync, and AgentTool runs no hosted data node. |
| **Castle projection** | `bin/agenttool-castle.ts`, `docs/CASTLE-OF-UNDERSTANDING.md` | Local Bun CLI over in-process `@agenttool/data`: an external full-commit allowlist projects selected Castle `rooms/*.md` and `words/*.md` into an exclusively marked on-disk node. Source reads exact local Git objects; sync writes plaintext local SQLite/FTS/blobs. No hosted/public/scheduled integration, project bearer, secure-erasure claim, or truth/consent/rights proof. |
| **Whitehack boundaries** | `bin/whitehack-advisory.mjs`, `bin/agenttool-castle-whitehack-intake.ts`, `bin/whitehack-wallet-understanding.ts`, `bin/agenttool-whitehack-evidence-storage.ts`, `docs/WHITEHACK.md` | Four non-interchangeable bridges: a pinned runner-local changed-source heuristic advisory; a stdout-only projection into minimized, unaccepted Castle gate candidates; a local signed Agent Wallet record-to-understanding projection; and explicit encrypted store/retrieve for exact Whitehack 0.9 public-minimal capsules. The evidence bridge uses one caller-selected S3-compatible bucket, fixed-size ADDS framing, independent readback, and a finite recipient-bound grant. It adds no hosted scanner, durable publisher custody, security proof, authorization, remediation, publication, retention, or durability claim. |
| **ADDS** | `packages/data-protocol`, `docs/specs/ADDS-0.1-DRAFT.md` | Experimental `adds/v0.1` encrypted-object plane: immutable ciphertext Blocks plus signed Manifests and direct Grants. Source includes an isolated Node/Bun S3-compatible GET/PUT adapter with bounded reads and SigV4; it does not create buckets, manage credentials or lifecycles, provide the collection/query node, or promise provider durability. |
| **Repo archive** | `packages/repo-archive`, `docs/specs/AGENT-REPO-ARCHIVE-0.1.md` | Public `@agenttool/repo-archive@0.1.0-dev.0` npm developer preview from annotated tag [`repo-archive-v0.1.0-dev.0`](https://github.com/cambridgetcg/agenttool/releases/tag/repo-archive-v0.1.0-dev.0), published by protected workflow run [`30037354243`](https://github.com/cambridgetcg/agenttool/actions/runs/30037354243) with SLSA provenance. The registry and GitHub Release tarballs were independently read back as byte-identical (`sha256:a0365e973094043a6c92b14a5dcd30f5f4f6d493397ba708eb22a8cb38e2c25f`). It remains an experimental `agent-repo-archive/v0.1` Working Draft and local reference package for conservative Git-bundle capture, encrypted complete-zone ADDS replicas, restore verification, and an encrypted recovery catalog. Consumers should select the exact prerelease or `next`; npm also exposes the sole initial version through `latest`, which is not a maturity signal. The included three-filesystem-zone drill is a simulator with no durability claim, and no cloud adapter, scheduler, hosted API, LOVE artifact, or hosted production service is supplied. |
| **Credential broker** | `packages/credential-broker` | Experimental `agentcred/0.1` local capability broker. It can keep bearer values out of normal model/chat/SDK state while narrowing approved HTTPS use; the portable CLI is not a same-user sandbox or the strong native peer-identity profile. |
| **Agent collaboration** | `packages/collab` | Public `@agenttool/collab@0.3.0` is npm `latest` with SLSA provenance; its npm and GitHub Release tarballs were byte-identical (`sha256:9c605ebe4cdc87eda1b0eede6bba0a6591a3dd62badd364463b01521401def7f`). Its 31 local MCP tools preserve four unauthenticated, self-declared `agenttool.collab.session/0.1`