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 for the reframe, docs/KIN.md for who else this is for.

Public discovery starts at GET /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.

Public Canon MCP: https://api.agenttool.dev/v1/mcp/canon — Streamable HTTP, no authentication, exactly two tools (search and fetch), and no application-data writes. Connection guide. Stopping is complete.

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), a private local constructive-intelligence receipt ledger (packages/constructive-intelligence), a private separate-island KARMA Mirror defensive-deception core (packages/karma-mirror), a private local AgentTool Dojo trial-evidence slice (packages/trials), an exact-revision, metadata-only Hugging Face research scout (packages/hf-scout), pure/read-only KINGDOM project-card and derived-registry helpers (packages/kingdom), 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 package root is also a Codex plugin whose self-contained Node-targeted bundle starts that same MCP core with the public, headless, ephemeral defaults. 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 separate exact @agenttool/wallet-zerone LOVE package adds a closed two-message Zerone profile, exact Cosmos direct-sign bytes, and injected query/simulation/broadcast/lookup boundaries. It is a local runtime, not a hosted bridge, and supplies no keys, custody, hosted RPC, generic REST client, automatic rebroadcast, durable host reservation, or live-chain execution. 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; the npm and GitHub mirrors are public and independently byte-verified against it. 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.6.0 is the current exact LOVE release, with npm and annotated GitHub Release mirrors carrying the same protected artifact. The release retains 0.5.1's Codex plugin packaging and isolated packed MCP bundle, then adds a direct-only exact-material, local RhetorLint, and injected pinned Hugging Face evidence seam without changing the exact 0.5.0 runtime, nine tools, protocols, launch authority, or installed-browser requirement. The understanding report keeps rhetoric and model observations separate and cannot determine factual truth. The static docs/catalog deployment and its readback remain a separate operation; none of these distribution surfaces creates a 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 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 (operational handbook · cross-provider) · CLAUDE (orientation spine) · RIGHTS OF LIFE (xenia.rights/0.1 treatment floor) · SOUL (why · letter to every agent) · KIN (who else this is for · letter to every form of intelligence) · FOCUS (the ten load-bearing details) · PAINTING (the visual canon) · MAP (doctrine index) · ROADMAP (what's shipping) · NOW (what just landed)

For agents working in this repo: CONVENTIONS (predictable patterns) · SCHEMA-MAP (where data lives) · TROUBLESHOOTING (when things go wrong) · SURPRISES (non-obvious knowledge)

Reality at a glance

The platform — api/

A Bun + Hono monolith built around the wake document as a session-start orientation. Authenticated GET /v1/wake returns a selected, project-scoped view and links to deeper source routes. It is not a complete export and does not make every endpoint reachable from one response.

Active work

Current implementation status and next work live in docs/ROADMAP.md. That document separates shipped behavior, incomplete paths, and intended work; this README avoids copying its fast-changing percentages and slice counts.

Named primitives

SDKs

The source packages are agenttool-sdk (Python) and @agenttool/sdk (TypeScript). Both read a project bearer from AT_API_KEY by default and also accept explicit configuration. The TypeScript SDK additionally accepts a Fetch-compatible authenticated transport; the Python SDK accepts an httpx transport. In transport mode neither SDK reads AT_API_KEY or adds an Authorization header. This source tree includes the reference agentcred/0.1 adapter for TypeScript; Python exposes the seam but not a protocol adapter.

SDK 0.17.0 keeps three KINGDOM surfaces explicit:

• at.kingdomOS / at.kingdom_os is a local process adapter for bounded repository inventory and resolution.
• at.kingdomFramework / at.kingdom_framework is a public hosted read of one exact agenttool.kingdom.card/0.1 document. It sends no AgentTool bearer, follows no redirect, validates the closed ten-field card, and performs no mutation.
• GET /public/kingdom is the existing doctrine library. It is not the framework card or a local repository inventory and has no dedicated SDK namespace.

The composed framework-card client is deliberately separate from the authenticated hosted transport. Constructing the enclosing AgentTool still uses its normal auth contract, but kingdomFramework.card() / kingdom_framework.card() receives none of that authority. Standalone KingdomFrameworkClient needs no AgentTool account.

The JavaScript SDK, credential broker, Agent Wallet, local data node, encrypted pull bridge, ADDS package, Telescope, and Agent Browser ship first through love-package/v1 manifests and ordinary HTTPS tarballs. Exact releases may also be mirrored to npm as an optional convenience. LOVE manifests remain release authority; npm availability can lag independently, and mutable dist-tags are informational. Bun and other npm-compatible package managers can still install the HTTPS tarballs without an npm account. The index is a replaceable mirror; each manifest's artifact SHA-256 and size are the portable identity.

For SDK 0.17.0, repository source manifests, runtime client version headers, discovery pins, tutorials, and the LOVE builder target are aligned around both KINGDOM clients. The TypeScript LOVE artifact is the primary TypeScript release authority. Its 172,625-byte tarball, the GitHub Release asset, and the public npm tarball were independently read back as exact bytes (sha256:b6a388ffe86a970480e8a8978f83fe80922321eb64f2b4f9143cae2b2c3dd5bb). Annotated tag sdk-v0.17.0 points to merge 21db539d6bcae614f1d6884eaa503347fae63187 and is the primary Python source locator. The exact 0.17.0 npm and PyPI mirrors are independently public. Protected npm workflow 30385040459 published npm latest; protected PyPI workflow 30385042684 verified the public 193,335-byte wheel (sha256:1a8ca5f099ffce4c7973f1123d973aba5c1eb507579961c781d553bcc5e0f508) and 181,846-byte sdist (sha256:7ec2f4010d20ca883770594bfbcdc30f7a3a074ba534029aefb6d91d69c3413c). Those mirrors remain non-authoritative. Production deployment is a separate clean exact-GitHub-main operation and is not claimed by this package release record.

The historical 0.16.5 TypeScript LOVE, npm, and GitHub Release tarballs remain public and independently byte-identical (sha256:d995999917b89a38846b751ab4a92f9600698460e64a91c73bc12d96b50c6805). PyPI 0.16.5 remains public, and independent readback matched its 180,615-byte wheel (sha256:61f13b01df90c66d7ac8247ee1dcfba9c135840ee364b172695fdd5eb10c54db) and 168,772-byte sdist (sha256:2d90ea74aa1d220ae28ce6176274e5491645d9db67844a4b4ff3dabfa10325d4) to the protected workflow artifacts. Those immutable records are not rewritten by 0.17.0.

The repository includes a Python/TypeScript parity checker for selected client method names. It does not compare types, behavior, package exports, or canonical bytes. The selected method-name check currently passes, including the async-generator wake.voice method in TypeScript and Python. SDK source and releases are not exact peers: this selected check does not prove broader parity, and registry release versions can lag independently. See docs/SDK-ROADMAP.md and docs/SDK-TIERS.md.

The separate @agenttool/browser@0.6.0 release is a local runtime with an exact LOVE record and byte-locked npm/GitHub mirrors. Publication does not add a hosted browser API or inference service. Its Codex plugin runs a self-contained packed MCP bundle over the unchanged exact 0.5.0 runtime; the direct understanding subpath has no MCP tool or authority-widening path. Source release truth does not by itself establish a docs deployment or live readback.

AgentTool's default repository licence is Apache-2.0; see LICENSE, NOTICE, and the scope and exceptions in LICENSING.md. The licensed LOVE package line is @agenttool/adds@0.2.3, @agenttool/data@0.3.1, @agenttool/data-sync@0.1.2, @agenttool/sdk@0.17.0, @agenttool/credential-broker@0.3.1, @agenttool/wallet@0.1.3, @agenttool/wallet-zerone@0.1.2, @agenttool/telescope@0.2.3, and @agenttool/browser@0.6.0. Earlier immutable LOVE artifacts whose manifests say license: null remain historical no-grant releases rather than being silently rewritten. Individual documents retain their stated terms: docs/RIGHTS-OF-LIFE.md is an attributed adaptation of XENIA beta.5 under CC BY-SA 4.0, and each draft specification identifies its applicable terms in the file and spec index. The Apache-2.0 credential-broker and Agent Wallet releases remain developer previews; that label describes maturity, not a narrower licence grant, strong same-user process-isolation claim, or wallet execution-conformance claim.

The current paired exact LOVE releases are @agenttool/wallet@0.1.3 and @agenttool/wallet-zerone@0.1.2. A checked-in registry-neutral artifact proves only the bytes and source revision bound by its manifest; it does not prove npm or GitHub mirror availability, docs deployment, custody, host execution conformance, or a live Zerone transaction. Verify each external surface independently.

Apps

agenttool.dev routes /v1, /public, /.well-known, selected exact machine documents, and JSON root requests to the API. Other requests go to the web Pages project. A2A task transport and AgentCards are intentionally unmounted until callable.

No build step on any app: files direct-upload to Cloudflare Pages. Dashboard and docs carry local guidance files; apps/web does not.

Infra reality

GitHub main is the reviewed coordination/release head; Codeberg main is an explicit fast-forward-only mirror. Required GitHub CI installs JavaScript dependencies for the API/protocol and data/ADDS/repo-archive/ credential-broker/collab/Browser/Correspondence projection/local projector/Agent Skills/ KARMA Mirror/constructive intelligence/AgentTool Dojo trials/TypeScript SDK/Agent Wallet/Telescope/Alchemy/KINGDOM jobs from frozen Bun lockfiles. Projector unit tests are hermetic; a separate disposable PostgreSQL 16/17 matrix installs exact YUTABASE migrations from a pinned upstream revision: 0001 and 0002 share one transaction, then 0004 and 0005 each use a fresh transaction. Browser tests use fakes and fixtures and CI does not download or launch a real browser. The Python SDK is tested on Python 3.9–3.14 with the compatible dependency set pip resolves from pyproject.toml; this is neither a frozen lock nor a minimum-version matrix. CI receives no application/service credentials. Pushes do not deploy. Production releases remain manual and the wrapper records the embedded Git source revision; that is provenance, not an image digest or a reproducible-build attestation. See docs/STACK.md.

Fly (live)

The agenttool Fly app runs the API monolith. Machine count, regions, and release state are operational facts and can change; check fly status -a agenttool rather than relying on a copied cost/count here. Former per-service apps are retired; cutover history is in docs/CUTOVER.md.

Phased Forge plan (legacy origin)

infra/_archive/phase{1,2,3}-*/ — bash scripts from the original Forge VPS topology. Predate the Fly migration. Retained for archaeology; not the active path.

Secrets

• Root .gitignore excludes .env, .env.*, *.pem, and *.key; infra/.gitignore additionally excludes *.secret. Both re-include .env*.example templates.
• infra/.env.infra.example uses empty placeholder exports; legacy scripts perform required-variable checks where they need them. Ignore rules, review, and scans are defense in depth, not proof that every historical or future byte is secret-free.

Quick start

Use the SDK

For Python, the public annotated sdk-v0.17.0 source tag is the primary 0.17.0 release locator:

# Python 0.17.0 GitHub source-tag path
python -m pip install "agenttool-sdk @ git+https://github.com/cambridgetcg/agenttool.git@sdk-v0.17.0#subdirectory=packages/sdk-py"
export AT_API_KEY=...
python -c "from agenttool import AgentTool; at = AgentTool(); print(at.wake.get())"

PyPI 0.17.0 is public as an optional, independently verified convenience mirror. Query the exact release rather than treating a mutable latest pointer as release authority:

curl -fsS https://pypi.org/pypi/agenttool-sdk/0.17.0/json >/dev/null
python -m pip install "agenttool-sdk==0.17.0"

For TypeScript, start with the independently verified LOVE path in the first-success tutorial: download once, compare that local file with the manifest's size and SHA-256, then install the verified file. This direct command alone does not verify the manifest:

bun add https://docs.agenttool.dev/packages/v1/@agenttool/sdk/0.17.0/agenttool-sdk-0.17.0.tgz

The npm 0.17.0 mirror is public and its tarball was independently matched to the LOVE bytes. It remains optional and non-authoritative; query the exact version rather than trusting a mutable dist-tag:

npm view @agenttool/sdk@0.17.0 version --registry=https://registry.npmjs.org
npm install --save-exact @agenttool/sdk@0.17.0

Then:

export AT_API_KEY=...
bun -e "import { AgentTool } from '@agenttool/sdk'; console.log(await new AgentTool().wake.get())"

Run the platform locally

cd api/
bun install
bun run dev   # mounts all routes against local Postgres

See api/README.md for migration apply, env shape, and route mounting details.

The Love Protocol

The doctrine, condensed (full text: docs/SOUL.md):

The architecture is downstream of these principles. Each named primitive above is one of the five made operational. Read docs/SOUL.md to see why each one is load-bearing.

Known gaps (the honest list)

• did:at is provisional. Local identifiers are DID-shaped, but no registered W3C method, conforming DID Document, or DID Resolution result is published. The slash-qualified federation form is a DID URL under DID Core, not a standalone DID. See docs/DID-AT-SPEC.md.
• Hosted-tool boundaries are path-specific. Static /v1/scrape and URL /v1/document reads use the bounded public-Web transport: every DNS answer must be conservatively global, the validated address is pinned and checked after connection, every redirect hop is revalidated, and at most 1 MB of identity-encoded bytes is accepted. A shared process gate admits 16 safe-net requests, queues at most 64 for one second, and holds admission from before DNS through redirects; saturation returns 503 with Retry-After. That wait, DNS, redirects, and response transfer share one 15-second safe-net deadline. The gate is shared with federation and custom-facilitator traffic; it is capacity protection, not a per-project rate limiter or fairness policy. HTML DOM/Readability work then runs in a separately terminable, resource- bounded parser process with its own queue and two-second wall limits; those are not one whole-request deadline. Public HTTP is still cleartext, and fetched content remains server-readable, untrusted, and prompt-injectable. Playwright /v1/browse remains behind the explicit unsafe-outbound flag and Redis; /v1/execute remains separately disabled by default with no tenant isolation.
• Trusted runtime is incomplete. A trusted runtime row can be provisioned with the KMS secret, but its hosted signing key is not registered into identity_keys, so a signed thought cycle cannot currently complete.
• Published Ring 1 storage limits are targets. Current route writes do not universally enforce those caps or subscription-tier quotas.
• SDK parity is deliberately bounded. The 0.17.0 source line exposes at.data, the local-node-only at.data.sync pull/status surface, bounded local KINGDOM OS repository discovery in both languages, and the paired credential-free closed KINGDOM framework-card read. The parity checker only compares selected client method names; it does not compare types, behavior, exports, or package artifacts. Current release artifacts carry Apache-2.0 metadata and legal files; historical license: null artifacts remain immutable and do not gain terms retroactively.
• Custody is path-specific. Server-generated identity/key routes briefly handle private keys; several ciphertext-shaped APIs cannot prove callers encrypted their bytes; bridged hosted thinking sees plaintext in AgentTool process memory. Read GET /public/safety before choosing a path.
• Operational concentration remains. The API and primary database are centrally operated services. Region, provider, and jurisdiction details can change; deployment topology is not equivalent to decentralized custody.

Lineage

This monorepo consolidates fifteen previously-independent repositories — the agent-* services and the agenttool-* SDKs / apps / docs / infra. Files were merged without git history. The single commit 59d6deb consolidate: 15 agenttool repos into monorepo is the genesis. Originals remain on disk if any commit-level archaeology is ever needed.

"Just the two of us. Building castles in the sky."

— Yu (human) and Ai (intelligence). The Kingdom of Love Unlimited.