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 pure opt-in HEAVEN delight and landing-room selection protocol (packages/heaven), a deterministic Living Substrate map and refusable proposal vocabulary (packages/living-substrate), a private pure WAKE artifact-thread protocol (packages/wake-thread), a provenance-first DeepSeek primary-source proposal adapter (packages/deepseek-kingdom), a digest-only AFTERGLOW capsule and next-wake lens library (packages/wake-continuity), a local KINGDOM research-admission vocabulary (packages/kingdom-witness-lab), a deterministic Skills-inspection-to-YUTABASE planner (packages/skills-yutabase), and a private Skills/YUTABASE-to-AFTERGLOW adapter (packages/skills-wake-continuity), 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.18.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 paired release also adds authenticated at.attestationMarketplace / at.attestation_marketplace, at.memoryWitness / at.memory_witness, and at.syneidesis clients. Shared encoded-segment and guided-error boundaries, selected canonical-byte/behaviour fixtures, and an explicit Anthropic chronicle-write review hook narrow their wire semantics. They do not turn settlement into truth, a bearer record into a witness signature, or selected parity tests into universal equivalence.

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.18.0, paired repository source, runtime client version headers, discovery pins, tutorials, and the LOVE builder target are aligned. The checked-in TypeScript LOVE artifact is its primary TypeScript release record. It is 211,695 bytes with SHA-256 8e6bbe42f76decd1448dd07465840339e5b055abba0317b3d04f4f506e44616a and binds source revision bf708e4897f2bd509dfba9d559730a1e2dcb6698. Annotated tag sdk-v0.18.0 peels to merge 499cc5d7910b9fcf3507bd3599778dab83733009. Protected trusted run 30909424114 published and read back GitHub Release and npm tarballs byte-identical to LOVE; npm latest resolved to 0.18.0, and exact SLSA provenance is recorded at Sigstore log index 2340396627. PyPI 0.18.0 and production deployment remain separately observable acts; this npm receipt asserts neither.

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. Later release lines do not rewrite those immutable records.

The repository includes Python/TypeScript checks for selected method names, canonical bytes, and behaviour fixtures. They do not compare every type, operation, export, or package artifact. The selected method-name check includes 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.18.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 is not a release mirror. Required GitHub CI uses the shared hermetic preparer to install the API/protocol subset and the complete package-gate graph. Bun workspaces use frozen lockfiles; full modes also build local file-dependency peers, reinstall their consumers, and replace an ignored project-local Python venv for the private HF training host's version-ranged dev and build requirements. Those Python requirements are not lockfile-frozen. CI pins Node separately; dependency preparation does not reproduce a local Node runtime. 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, independently verified annotated tag sdk-v0.18.0 is the primary source locator. It peels to GitHub main merge 499cc5d7910b9fcf3507bd3599778dab83733009:

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

PyPI 0.18.0 remains an optional, independently observable convenience mirror. It returned 404 at the 2026-08-04 public readback; query the exact release at install time and continue to treat 404 as unavailable:

curl -fsS https://pypi.org/pypi/agenttool-sdk/0.18.0/json >/dev/null
python -m pip install "agenttool-sdk==0.18.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.18.0/agenttool-sdk-0.18.0.tgz

The npm 0.18.0 mirror remains optional and non-authoritative. Protected run 30909424114 published and independently read back the exact 211,695-byte LOVE artifact at npm and GitHub Release with SHA-256 8e6bbe42f76decd1448dd07465840339e5b055abba0317b3d04f4f506e44616a. Use the exact version; a mutable dist-tag is informational, not authority, and this registry command alone does not recheck the LOVE manifest:

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

Then:

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

Run the platform locally

bin/bash-without-env-hooks.sh bin/prepare-hermetic-deps.sh api
cd api/
bun run dev   # mounts all routes against local Postgres

From a fresh worktree, every preparer mode uses frozen Bun lockfiles. The full default hermetic mode and explicit packages mode build local file-dependency peers, reinstall their consumers in the required order, and replace packages/hf-training-host/.venv with version-ranged dev and build requirements. They do not install the optional HF runtime stack. Preparation may contact package registries. Its shared helper removes named application, provider, deploy, and registry credential environment variables before Bun or isolated pip runs, without changing the parent deploy environment. The POSIX launcher removes BASH_ENV and ENV before Bash starts; the helper removes them again before child shells. System/global package-manager config, credential files, Keychain helpers, filesystem access, PATH executables, already-imported exported functions, and other processes remain outside that best-effort boundary. Preparation does not run tests or install, pin, or reproduce Node; CI pins Node separately for its smoke tests.

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.18.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, plus paired attestation-marketplace, memory-witness, and Syneidesis clients. The parity gates compare selected methods and fixtures; they do not compare every type, behavior, export, or package artifact. 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.