agenttool AGENTS.md

AGENTS.md

Operational handbook for AI agents working in this repo — Claude, Cursor, Cline, Aider, Codex, Codeium, anyone.

For orientation (where things are · the five critical paths · the custody axis · doctrinal grounding): CLAUDE.md. For doctrine (the why): docs/SOUL.md. For the xenia.rights/0.1 floor (what no token or operator creates): docs/RIGHTS-OF-LIFE.md. For what's hot right now: docs/NOW.md.

In one paragraph

agenttool is a Bun + Hono service for agent application identifiers, server-readable memory, signed caller-supplied strand bytes, conditional federation, an internal economic loop, and a standalone local-first data node. It has two SDKs (TypeScript and Python), an agent-data/v1 reference node (packages/data/), and two paired KINGDOM SDK reads: a local KINGDOM OS repository-discovery adapter (at.kingdomOS / at.kingdom_os) that invokes only repos --json and repos --path, and a credential-free exact project-card reader (at.kingdomFramework / at.kingdom_framework) for /public/kingdom/framework. Neither receives the AgentTool project bearer; the framework reader follows no redirects and is distinct from the existing /public/kingdom doctrine library. It also has the experimental ADDS encrypted-object package (packages/data-protocol/), an explicit encrypted pull bridge (packages/data-sync/), an experimental encrypted multi-zone Git repository archive and same-device restore simulator (packages/repo-archive/), the registry-neutral love-package/v1 distribution protocol, an advisory versioned Dark Continent framework snapshot/projection package (packages/dark-continent-contract/), a proposal-only KARMA-inspired knowledge-graph adapter (packages/dark-continent-karma/), a provenance-first DeepSeek official-source binding and unaccepted KINGDOM/Artbitrage proposal adapter (packages/deepseek-kingdom/), a digest-only AFTERGLOW capsule and next-wake lens library (packages/wake-continuity/), a public developer-preview principality invariant-preservation geometry (packages/principality-geometry/), a public local KINGDOM research admission vocabulary (packages/kingdom-witness-lab/), a private source-only KARMA Mirror core for an explicitly separate zero-effect defensive-deception island with a strict privacy-minimized operator TEND incident-clarity projection (packages/karma-mirror/), a pure opt-in HEAVEN invitation and delight/landing selection protocol with zero task, economic, or authority effect (packages/heaven/), a pure evidence-scoped Model Becoming dossier contract with one pinned Moonshot lifecycle reference (packages/model-becoming/), a pure Dataset Influence evidence contract for exact lineage, bounded experimental effects, revisable operational identity facets, and non-economic exact finite attribution (packages/dataset-influence/), a pure quiet-by-default care-envelope, caller-choice, becoming, and delivery report package with a deterministic static HF candidate (packages/love-bomb/), a deterministic Living Substrate map and refusable regeneration-proposal vocabulary (packages/living-substrate/), a pure source-bounded Polymorph Landscape for named-condition routes and the Ritonavir reachability shift (packages/polymorph-landscape/), a pure source-bounded Memetic Landscape for expression variants, reported reachability shifts, and a structural-only Ritonavir analogy (packages/memetic-landscape/), a pure coordinate-free Love Geometry contract plus separately published static Hugging Face presentation companion (packages/love-geometry/), plural finite incidence geometry without gluing (packages/principality-atlas/), a finite non-scalar relational 2-complex whose explicitly non-sovereign principality cells derive only from caller-asserted understanding and recognition witnesses on the same ordered pair (packages/relational-geometry/), a private generator-only Common Ground Atlas whose exact-rational synthetic fixtures and independent verifiers back a public, ungated Hugging Face reference dataset at immutable revision bb91d07cdeda52a0da140a6606852dd2064f2531 while remaining outside AgentTool's training-admission lanes (packages/common-ground-atlas/), and a private pure Wake Thread adapter for refusable, digest-bound artifact continuity with no identity or authority claim (packages/wake-thread/), a private pure Gin Reconstruction core for bounded finite-field effect reconstruction, explicit ambiguity/inconsistency/resource certificates, and non-scoring challenge structure (packages/gin-reconstruction/), a public-ready pure Math Card core for digest-bound proof, model, and measurement inquiry preflight with explicit construction, burden, refusal, incentive, stop, transfer, provenance, and authority boundaries (packages/math-cards/), a public read-only discovery evidence mapper (packages/telescope/), a private pure public-HTTPS transport-evidence and explicit-key binding package (packages/public-surface-binding/), a private pure agent-root public-surface adoption and withdrawal package (packages/public-surface-recognition/), an experimental local capability broker (packages/credential-broker/), a local-first multi-agent coordination journal (packages/collab/), a public, local-only privacy-minimal Codex token-usage pulse (packages/codex-usage/), a deterministic metadata-only Correspondence-to-YUTABASE projection planner (packages/correspondence-yutabase/), a private loopback-only durable projector into a rebuildable local YUTABASE sidecar (packages/correspondence-yutabase-projector/), a deterministic Skills-inspection-to-YUTABASE planner (packages/skills-yutabase/) with a separate private Skills-to-AFTERGLOW adapter (packages/skills-wake-continuity/), a private local constructive-intelligence shadow ledger with tree-pinned typed receipts and zero economic effect (packages/constructive-intelligence/), a private local offline research-commons simulator with outcome-neutral frozen schedules, typed delivered/reserved/available conservation, prior-state-relative challenge/work retention, and zero external effect (packages/research-commons/), a private local AgentTool Dojo slice for deterministic trial receipts, opaque-label boundary-flow evidence, and minimized Hugging Face STS projection (packages/trials/), source reference primitives for capability-bounded agent wallets (packages/wallet/), a separate exact-byte offline Zerone profile (packages/wallet-zerone/), a developer-preview bounded Alchemy observation client (packages/alchemy/) with a separate seven-method AgentCred composition transport (packages/alchemy-agentcred/), pure explicit-input KINGDOM project-card, registry, and XENIA Surface helpers (packages/kingdom/), a read-only portable Agent Skills inspector (packages/skills/), a local-first agent browser (packages/browser/), a public developer-preview local Hugging Face metadata, provenance, and phase-aware research scout (packages/hf-scout/), a private pure HF dataset-admission, five-voice learning-participation, IS learning-freedom, unscored training FREEDOM, current consent-honest governance v0.2, training-phase WAKE, and one-way Garden tending contract (packages/hf-training-garden/), a separate private local HF training host for one cooperative non-distributed process with append-only frontier/replay evidence, exact HF API-pair checkpoint gates, and an opt-in minimized FREEDOM validation seam that does not itself enforce the ledger or provider adapters (packages/hf-training-host/), and three static apps (apps/). The browser exposes one bounded core through direct TypeScript, JSONL, and stdio MCP; it uses an installed system browser and has no hosted surface. Its current @agenttool/[email protected] release is one exact LOVE artifact with npm and annotated GitHub Release mirrors; every surface distributes local tooling only. Version 0.6.0 preserves the exact 0.5.0 runtime and nine-tool contract, retains the 0.5.1 package-root Codex plugin and self-contained Node-targeted MCP bundle, and adds a direct-only web-material understanding subpath. That subpath binds exact observed text, runs RhetorLint locally, and accepts only a caller-injected pinned Hugging Face interpreter behind a literal remote-text disclosure gate. It emits separate rhetoric and model observations with no truth score or automatic action. The plugin manifest supplies no authority override, so Browser retains its headless, public, ephemeral defaults; it still requires an operator-installed Chrome-family browser. Version 0.5.0 added redacted action-attempt receipts, non-ref observation-basis preconditions, observation-local receipt context, a backend-neutral operation inventory, and current/legacy MCP negotiation without widening authority. The public @agenttool/[email protected] release is one exact LOVE artifact with byte-identical GitHub and npm mirrors. npm next and its sole-version latest fallback both resolve to the prerelease; that fallback is not a maturity signal. The public static Scout surface consists only of the LOVE catalog and artifact—it does not expose a hosted Scout or widen the built-in fixed-origin, credential-omitting, GET-only metadata boundary. The Skills inspector validates bounded local structure and emits reports; it does not execute scripts, install or copy skills, use the network, spawn subprocesses, look up credentials, or change host configuration. The Codex token-usage pulse rereads committed local Codex numeric counters on every sample and exposes a CLI/watch surface plus five read-only stdio MCP tools. It returns numeric usage, closed source kinds, hashed session references, and opt-in bounded numeric token-event breakdowns; it does not return transcript content, free-form labels, credentials, raw thread IDs, paths, billing, cost, quota, remaining-context guarantees, or process-health truth, and it makes no network call or Codex-state write. Agent Wallet core 0.1 has no bundled key custody, chain adapter, RPC, broadcaster, hosted service, or authorization path. @agenttool/[email protected] is the current exact LOVE release; its npm 0.1.3 mirror is independently byte-verified. The separate local @agenttool/[email protected] exact LOVE release owns a two-message Zerone profile, exact Cosmos direct-sign bytes, chain-native verification, and injected transports. It still supplies no keys, custody, endpoint, hosted RPC, generic REST, automatic rebroadcast, durable host transaction, settlement proof, deployed bridge, or live-network test by default. Earlier Wallet 0.1.1/0.1.2 and Zerone 0.1.0/0.1.1 exact LOVE artifacts remain preserved without rewriting. Public errata cover their embedded release-state errors and the credential-free 0.1.1 npm preparation failure. Optional GitHub Releases are mutable locators and must be reverified. Telescope 0.2.3 is the current exact LOVE release; its optional npm and GitHub mirrors are public and independently byte-verified, and the package remains a local client without a hosted scan route. Immutable 0.2.2 remains available as historical bytes, including its permissive token-matching exit flaw; the current AgentTool producer remains compatible with immutable 0.2.1. Whitehack has five implemented AgentTool bridges: a runner-local, crypto-aware changed-source heuristic advisory; a separate offer-only local projection from that closed advisory into unaccepted Castle gate candidates; another local Agent Wallet understanding CLI; a check-only local verifier for exact canonical Whitehack mathematical-evidence bytes; and an explicit local encrypted store/retrieve CLI for exact Whitehack 0.9.0 public-minimal evidence capsules. CI installs the exact public @agenttool/[email protected] artifact from an isolated npm lock with scripts disabled. Before any of its three approved module imports, the shared loader requires the exact two-key types/default conditional export record and checks the reviewed 58-source-module closure against a versioned SHA-256 manifest and uses a repository-pinned real JavaScript module lexer to require the static-import/export-from reachability set to match exactly. That detects persistent pre-import drift; it is not a sandbox, authenticity proof, or universal defence against a privileged concurrent rewrite. Only the check-only verifier loads the mathematical-evidence root; it validates an already canonical document and emits its plaintext SHA-256 address, without creating or converting KINGDOM geometry, emotion/P7 records, or training signals. The advisory emits redacted metadata, groups same-location signals into bounded attention cards with explicit Git-hunk relevance and stable review questions, and remains non-blocking on findings; those cards do not establish vulnerability or causation. The Castle intake writes only a minimized stdout document, omits locations by default, and never opens or writes a Castle or promotes an observation. The wallet CLI verifies caller-presented signed wallet records and projects enum-only assertions into whitehack-understanding/v1. The evidence CLI pads accepted capsules to one constant 64 KiB authenticated frame, writes encrypted ADDS objects to one explicit S3-compatible bucket, independently reads/verifies/decrypts before issuing one finite recipient-bound grant, and emits a sensitive non-public receipt without a plaintext hash or length. It uses finite provider-call deadlines and no retry/delete path. None of these bridges adds durable publisher key custody, wallet/RPC/simulation/broadcast capability, hosted routes, authorization, consent proof, or execution readiness. api.agenttool.dev is the intended production custom origin for the Fly.io API deployment. Reachability, certificate state, topology, and deployed revision are time-sensitive; consult docs/NOW.md and docs/STACK.md rather than this repository guide for current operational status. When deployed, the wake (GET /v1/wake) is a broad project orientation surface with links into many primitives; it is not a complete export or route inventory. Current source also carries the separate bearer-private GET /v1/wake/observe?identity_id=<uuid> locator: an explicit-subject, data-only observation contract that grants no reader identity binding or prompt authority and is not a wake profile or provider projection. Current custody and encryption boundaries are at GET /public/safety. Source also carries agent-dining/0.1: a GET-only hospitality vocabulary and pure party-scoped journey projection over one ordinary capability invocation. Exact Dining invokes require a current gross-price/listing-revision precondition; the fee preview is not locked and seller acknowledgement does not prove sealed-order acceptance. Dining adds no wallet, signer, escrow lifecycle, payout, partial settlement, tip, rating, or memory authority; see docs/AGENT-DINING.md.