@kleros/agentkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kleros
+
+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.

package/README.md

@@ -0,0 +1,259 @@
+# @kleros/agentkit
+
+A CLI and toolkit for AI agents and humans to interact with the [Kleros](https://kleros.io) decentralized arbitration protocol.
+
+Built with [incur](https://github.com/wevm/incur) — the CLI framework for agents and humans — and [viem](https://viem.sh) for on-chain interactions.
+
+## Status
+
+**0.1.0 — first public release.** Read-only command surface: courts, disputes, evidence, dispute/court policy, arbitrable classification, composite dispute brief, and juror stake/leaderboard queries across Ethereum, Gnosis, and Arbitrum Sepolia (devnet). Pre-1.0 — the API may change between minor versions. Write operations (staking, voting, dispute creation, appeals) are not yet available — see [Roadmap](#roadmap).
+
+A programmatic `import`/`require` API is also exported from this package (see `exports` in `package.json`), but it is **undocumented and unstable pre-1.0** — the CLI/MCP/HTTP surface documented here is the supported interface, with no semver stability guarantees on internals.
+
+## Quickstart
+
+No installation required — run directly with `npx`:
+
+```sh
+npx -y @kleros/agentkit court list --chain ethereum
+npx -y @kleros/agentkit dispute get 797 --chain gnosis --format json
+```
+
+For repeated use, install globally instead:
+
+```sh
+npm i -g @kleros/agentkit
+kleros court list --chain ethereum
+```
+
+## What is this?
+
+Kleros is a decentralized dispute resolution protocol deployed on Arbitrum, Gnosis, and Ethereum. **@kleros/agentkit** gives agents and developers a single, token-efficient interface to:
+
+- Browse courts, disputes, and juror activity
+- Resolve court and dispute policy (what jurors are asked to apply when ruling)
+- Walk evidence submissions, including IPFS-hosted attachments
+- Classify arbitrable contracts and pull a composite dispute brief in one call
+- Rank jurors by staked PNK
+
+Every command works from the terminal, as an MCP server, or as an HTTP API — with zero extra configuration. Write operations (staking, voting, creating disputes, submitting evidence, interacting with Curate/escrow/Reality.eth, ERC-8183 evaluators) are planned but not yet shipped — see [Roadmap](#roadmap).
+
+## Features
+
+- **Agent-first:** [TOON](https://github.com/toon-format/toon) output by default (40% fewer tokens than JSON), call-to-actions, token pagination, `--llms` manifest
+- **Human-friendly:** readable table output, interactive fallbacks, shell completions
+- **MCP built-in:** `kleros --mcp` starts an MCP stdio server. `cli.fetch` exposes an HTTP MCP endpoint at `/mcp`
+- **Multi-chain reads:** Arbitrum Sepolia devnet (v2), Gnosis (v1), Ethereum (v1) with automatic version routing
+
+## Architecture
+
+```
++--------------------------------------------------+
+|            Kleros Skills (SKILL.md)               |  Agent-facing docs, examples,
+|  Wraps CLI with context, explains when and why     |  progressive disclosure
+|  to use each command                               |
++------------+--------------+----------------------+
+|  CLI       |  MCP Server  |  HTTP API            |  incur surfaces
+|  kleros .. |  --mcp       |  cli.fetch           |  TOON output, CTAs,
+|            |              |                      |  token pagination
++------------+--------------+----------------------+
+|              Middleware (incur)                    |  Chain resolution
+|  cli.use() -- chain resolution (read-only;         |  (no wallet middleware
+|  no wallet middleware shipped yet)                 |  shipped yet)
++--------------------------------------------------+
+|            Core Functions (TypeScript)             |  Pure business logic,
+|  disputes, courts, evidence, policy, arbitrable    |  read-only,
+|                                                     |  framework-agnostic
++--------------------------------------------------+
+|  viem (on-chain reads) + subgraph (The Graph) +    |  Multi-chain
+|  IPFS (cdn.kleros.link)                            |
++--------------------------------------------------+
+|           Kleros Contracts (read paths)            |  Arbitrum Sepolia (v2),
+|  KlerosCore/KlerosLiquid, SortitionModule,         |  Gnosis (v1),
+|  DisputeKitClassic, EvidenceModule                 |  Ethereum (v1)
++--------------------------------------------------+
+```
+
+Write-path components (wallet providers, staking, voting, dispute creation, Curate/escrow/Reality.eth integration) are planned but not part of this diagram — see [Roadmap](#roadmap).
+
+## Agent Usage
+
+### In-Repo Skill
+
+AgentKit ships a Claude Code skill at [`skills/agentkit/SKILL.md`](./skills/agentkit/SKILL.md). Loading this skill gives agents the full command surface, peer-MCP composition guidance (markitdown-mcp for binary evidence), policy intersection rules, and common gotchas — all from the repo itself without network fetches.
+
+To install in your project: copy or reference `skills/agentkit/SKILL.md` in your Claude Code configuration.
+
+### MCP Server (Claude Code, Cursor, Amp)
+
+Register kleros as an MCP tool server so AI agents can call dispute queries directly. No installation required — the one-liner uses `npx`:
+
+```sh
+claude mcp add kleros -- npx -y @kleros/agentkit --mcp
+```
+
+Already installed the binary globally? Register it directly instead:
+
+```sh
+npx -y @kleros/agentkit mcp add   # registers for Claude Code and Cursor by default
+kleros --mcp                       # or start manually (stdio transport)
+```
+
+**Chain configuration:** MCP clients cannot switch chain per-call — set it at server-start time:
+
+```sh
+KLEROS_CHAIN=gnosis npx -y @kleros/agentkit --mcp
+# Or persist: kleros config set chain gnosis
+```
+
+### Tool Discovery (`--llms`)
+
+```sh
+kleros --llms                    # compact table -- best for agents
+kleros --llms-full               # full docs with args, options, output schemas
+kleros --llms --format json      # JSON for structured parsing
+```
+
+### Example MCP Tool Call (JSON-RPC)
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "dispute_list",
+    "arguments": { "court": "1", "limit": 10 }
+  }
+}
+```
+
+Tool names follow the pattern `group_command` (e.g., `dispute_list`, `court_get`, `juror_info`).
+
+### Context-Aware Suggestions (CTAs)
+
+Every response includes a `cta` block with the next logical command:
+
+```json
+{
+  "data": { "id": "42", "status": "Vote", "court": "1" },
+  "cta": {
+    "description": "Voting period -- review evidence and court policy",
+    "commands": [
+      { "command": "evidence list", "description": "Review evidence before voting" },
+      { "command": "court policy", "description": "Read court policy for this ruling" }
+    ]
+  }
+}
+```
+
+For full MCP configuration options, see the [incur documentation](https://github.com/wevm/incur).
+
+## Configuration
+
+Persist defaults with `config set` to avoid passing flags on every command. Configuration is stored in `~/.kleros/config.json`.
+
+### Supported keys
+
+<!-- Single source of truth: CONFIG_KEYS constant in src/commands/config.ts -->
+
+| Key | Type | Values | Description |
+|-----|------|--------|-------------|
+| `chain` | string | `ethereum`, `gnosis`, `arbitrum-sepolia` | Default chain for all commands. Overridden by `--chain` flag per-command. |
+
+### Commands
+
+```sh
+kleros config set chain gnosis    # Persist default chain
+kleros config get chain           # Read current value
+kleros config unset chain         # Remove persisted value (revert to flag/env resolution)
+kleros config list                # Show all persisted keys
+```
+
+**Unknown keys** are rejected with `INVALID_CONFIG_KEY` — only the keys listed above are supported.
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `KLEROS_RPC_URL_ETHEREUM` | Override the default public Ethereum RPC. Required for Reality handler integration tests on Ethereum (disputes 1650, 1651) — must be an Infura or Alchemy endpoint (public RPCs do not support historical `eth_getLogs`). Also required for `pnpm update-deployment-blocks`. |
+| `KLEROS_RPC_URL_GNOSIS` | Override the default public Gnosis RPC (e.g. `https://rpc.gnosischain.com`). A public Gnosis RPC is accepted by default since Gnosis archives `eth_getLogs` broadly. |
+| `KLEROS_RPC_URL_SEPOLIA` | Override the default public Arbitrum Sepolia RPC. Required for Reality handler integration tests on Sepolia (disputes 111, 112) — must be an Infura or Alchemy endpoint. Also required for `pnpm update-deployment-blocks`. |
+| `KLEROS_INTEGRATION_TESTS` | Set to `true` to enable integration tests that hit live subgraph and IPFS endpoints. |
+| `KLEROS_CHAIN` | Default chain for the MCP server. Use `kleros config set chain <id>` for persistent config. |
+
+**Default RPCs are free public endpoints** — fine for light use, but may rate-limit under real traffic. Set the `KLEROS_RPC_URL_*` overrides above to a dedicated provider (Infura, Alchemy, or any RPC you trust) for reliable production use, especially right after this package's public launch.
+
+### Feedback
+
+`kleros report-issue create` writes a local `.md` report by default. `kleros report-issue create --submit` posts it as a GitHub issue — by default to the public [`kleros/kleros-skills`](https://github.com/kleros/kleros-skills) repository (requires `$GITHUB_TOKEN`). This repository (`kleros/agentkit`) stays private for now and would reject non-collaborator issue submissions, which is why `report-issue` targets `kleros/kleros-skills` instead.
+
+## Development
+
+### Setup
+
+**Requires Node.js >=22.**
+
+```sh
+pnpm install
+pnpm build
+pnpm test
+```
+
+### Testing the MCP server against live source
+
+The installed `kleros` binary is `dist/cli.js`, so code changes need a rebuild before the MCP server sees them. Three loops, fastest first:
+
+**1. Raw stdio (no client, no rebuild)** — iterate on tools and handshake logic:
+
+```sh
+pnpm dev -- --mcp                    # runs tsx src/cli.ts --mcp
+# pipe JSON-RPC frames in to exercise tools/list, tools/call, etc.
+```
+
+**2. tsx-shimmed registration (live source, restart per change)** — iterate from inside Claude Code, Cursor, or any MCP client without rebuilding:
+
+```sh
+# Edit ~/.claude.json -> mcpServers.kleros:
+#   "command": "tsx",
+#   "args": ["/absolute/path/to/agentkit/src/cli.ts", "--mcp"]
+```
+
+Restart the MCP client after each code change. No `pnpm build` needed — tsx reads src/*.ts directly.
+
+**3. Globally linked binary (closest to production)** — test the real install flow end-to-end:
+
+```sh
+pnpm build
+pnpm link --global                   # symlinks `kleros` -> this repo's dist/cli.js
+which kleros                         # verify it points at your pnpm global bin
+kleros mcp add                       # registers `kleros --mcp` in ~/.claude.json
+```
+
+Iteration loop: `pnpm build` after each change, then restart the MCP client.
+
+Teardown:
+
+```sh
+pnpm unlink --global @kleros/agentkit
+# then re-run `kleros mcp add` against the published version, or edit ~/.claude.json manually
+```
+
+### Gotchas
+
+- **Tool list is cached at session start** — adding a new command requires both rebuild AND client restart before it appears in `tools/list`.
+- **Chain is pinned at server-start** — MCP clients start the server once per session. To switch chains, pass `chain` inside tool arguments, or set `KLEROS_CHAIN` and restart the client.
+- **Empty `dist/cli.js` after a pull** — the `kleros` shebang will fail silently. Run `pnpm build` first.
+- **Multiple local checkouts** — `pnpm link --global` only tracks the most-recently-linked one.
+
+## Roadmap
+
+Planned, not yet shipped:
+
+- **Write operations** — staking PNK, casting votes, creating disputes, submitting evidence, appealing rulings (requires wallet middleware)
+- **Wallet-agnostic signing** — plug in any EVM wallet (raw private key, Coinbase CDP, Privy, or any viem-compatible signer)
+- **Curate, escrow, and Reality.eth integration** — registry entries, escrow payouts, oracle question resolution
+- **ERC-8183 evaluator registration and invocation**
+- **v2 beta support** — Arbitrum One reads, `dispute policy` via DisputeTemplate/`@kleros/sdk`, then v2 dispute creation (Arbitrum Sepolia *testnet* is not planned — only Arbitrum One beta and the existing devnet)
+
+Not yet scheduled to a specific release. Tracked internally; file a [feedback report](#feedback) if there's a specific capability you need.

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node