Agent Receipts

Логи говорят вам, что что-то произошло. Квитанции доказывают это.

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Пример из реальной жизни

Я создал ModQuote — SaaS-платформу с поддержкой нескольких арендаторов для автосервисов. В процессе разработки я активно использовал Claude Code для аудита и исправления кодовой базы.

Проблема: когда что-то шло не так, у меня не было способа доказать, какие входные данные получил Claude, что он изменил и соответствовал ли результат ожиданиям.

С Agent Receipts каждый сеанс Claude Code теперь генерирует подписанные квитанции:

• Хэш входных данных доказывает, какой именно код видел Claude

• Хэш выходных данных доказывает, что именно он создал

• Ограничения фиксируют скачки задержки или превышение бюджета

• Цепочки показывают полную последовательность многоэтапного сеанса аудита

Когда исправление не работало должным образом, я мог получить квитанцию, проверить подпись и увидеть точные хэши входных/выходных данных — никаких догадок и никаких «Claude, должно быть, неправильно понял».

В этом разница между логами и квитанциями. Логи говорят вам, что что-то произошло. Квитанции доказывают это.

Быстрый старт: MCP-сервер

Добавьте MCP-сервер Agent Receipts в конфигурацию вашего ИИ-инструмента, и каждое действие будет автоматически получать криптографическую квитанцию.

Поддержка платформ: macOS, Windows и Linux — требуется Node.js 18+

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Claude Code

Добавьте в .mcp.json в корне вашего проекта:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Cursor

Добавьте в .cursor/mcp.json в корне вашего проекта:

{
  "mcpServers": {
    "agent-receipts": {
      "command": "npx",
      "args": ["@agent-receipts/mcp-server"]
    }
  }
}

Быстрый старт: SDK

npm install @agent-receipts/sdk

import { AgentReceipts } from '@agent-receipts/sdk'

const ar = new AgentReceipts()

const receipt = await ar.track({
  action: 'generate_report',
  input: { query: 'Q4 revenue' },
  output: { total: 142000 },
})

console.log(receipt.receipt_id)  // rcpt_8f3k2j4n...
console.log(receipt.signature)   // ed25519 signature

Быстрый старт: CLI

npx @agent-receipts/cli init          # Generate signing keys
npx @agent-receipts/cli keys          # Show public key
npx @agent-receipts/cli list          # List all receipts
npx @agent-receipts/cli verify <id>   # Verify a receipt signature

Как это работает

1. Агент выполняет действие — вызов API, генерация кода, поиск данных

2. Входные/выходные данные хэшируются с помощью SHA-256 — необработанные данные никогда не покидают вашу машину

3. Создается квитанция — действие, хэши, метка времени, ID агента, метаданные

4. Квитанция подписывается Ed25519 — с помощью локально сгенерированного закрытого ключа

5. Любой может проверить — поделитесь своим открытым ключом; получатели проверяют независимо

Справочник инструментов MCP

MCP-сервер предоставляет 14 инструментов, которые ИИ-агенты могут вызывать напрямую:

Справочник API SDK

new AgentReceipts(config?)

const ar = new AgentReceipts({
  dataDir: '~/.agent-receipts',  // optional, defaults to ~/.agent-receipts
})

ar.track(params) — Отслеживание завершенного действия

const receipt = await ar.track({
  action: 'analyze_data',
  input: { dataset: 'sales_2024' },
  output: { summary: 'Revenue up 12%' },
  agent_id: 'analyst-v2',
  chain_id: 'chain_abc',              // optional, auto-generated if omitted
  parent_receipt_id: 'rcpt_prev',     // optional, links to parent receipt
})

ar.start(params) — Запуск ожидающей квитанции

const receipt = await ar.start({
  action: 'long_running_task',
  input: { job_id: '12345' },
})

ar.complete(receiptId, params) — Завершение ожидающей квитанции

const completed = await ar.complete(receipt.receipt_id, {
  output: { result: 'done' },
  status: 'completed',
})

ar.verify(receiptId) — Проверка подписи квитанции

const { verified, receipt } = await ar.verify('rcpt_8f3k2j4n')
// verified: true | false

ar.get(receiptId) — Получение квитанции по ID

const receipt = await ar.get('rcpt_8f3k2j4n')

ar.list(filter?) — Список квитанций

const result = await ar.list({ agent_id: 'my-agent', status: 'completed' })
// result.data: ActionReceipt[]
// result.pagination: { page, limit, total, total_pages, has_next, has_prev }

ar.getPublicKey() — Получение открытого ключа для подписи

const publicKey = await ar.getPublicKey()
// 64-char hex string (Ed25519 public key)

ar.track() с ограничениями

const receipt = await ar.track({
  action: 'generate_summary',
  input: { document_id: 'doc-q4-2024' },
  output: { summary: 'Revenue grew 12% YoY...' },
  latency_ms: 1200,
  cost_usd: 0.005,
  constraints: [
    { type: 'max_latency_ms', value: 5000 },
    { type: 'max_cost_usd', value: 0.01 },
    { type: 'min_confidence', value: 0.8 },
  ],
})
// receipt.constraint_result.passed → true/false

ar.getJudgments(receiptId) — Получение оценок

const judgments = await ar.getJudgments('rcpt_8f3k2j4n')

ar.cleanup() — Удаление просроченных квитанций

const { deleted, remaining } = await ar.cleanup()

ar.generateInvoice(params) — Генерация счета из квитанций

const invoice = await ar.generateInvoice({
  from: '2026-01-01',
  to: '2026-01-31',
  agent_id: 'my-agent',       // optional filter
  group_by: 'agent',          // optional: agent | action | day
})

Справочник CLI

Формат квитанции

{
  "receipt_id": "rcpt_8f3k2j4n",
  "chain_id": "chain_x9f2k",
  "parent_receipt_id": null,
  "receipt_type": "action",
  "agent_id": "my-agent",
  "org_id": "my-org",
  "action": "generate_report",
  "status": "completed",
  "input_hash": "sha256:abc123...",
  "output_hash": "sha256:def456...",
  "output_summary": "Generated Q4 report",
  "model": "claude-sonnet-4-20250514",
  "timestamp": "2026-02-07T14:32:01.442Z",
  "completed_at": "2026-02-07T14:32:02.100Z",
  "latency_ms": 658,
  "cost_usd": 0.003,
  "signature": "ed25519:<hex>"
}

Входные и выходные данные хэшируются на стороне клиента с помощью SHA-256. Необработанные данные никогда не покидают вашу среду. В квитанции хранятся только хэши.

Проверка

Поделитесь своим открытым ключом с любым, кому нужно проверить ваши квитанции:

# Export your public key
npx @agent-receipts/cli keys --export

# Verify a receipt with an external public key
npx @agent-receipts/cli verify receipt.json --key <public-key-hex>

Проверка пересчитывает подпись Ed25519 по детерминированным полям квитанции и подтверждает, что она совпадает с сохраненной подписью. Никаких сетевых запросов — полностью офлайн.

Конфигурация

Хранилище

Все данные хранятся локально в директории данных:

~/.agent-receipts/
├── keys/
│   ├── private.key          # Ed25519 private key (mode 0600)
│   └── public.key           # Ed25519 public key
├── receipts/
│   └── *.json               # Legacy JSON files (auto-migrated)
├── receipts.db              # SQLite database (primary storage)
└── config.json              # Agent and org configuration

Начиная с версии v0.2.7, квитанции хранятся в SQLite с индексированными запросами для быстрой фильтрации и пагинации. Существующие JSON-файлы квитанций автоматически мигрируют при первом запуске.

Архитектура

┌─────────────────────────────────────────────┐
│                  CLI                         │
│           @agent-receipts/cli                 │
├─────────────────────────────────────────────┤
│           SDK            │   MCP Server      │
│   @agent-receipts/sdk     │ @agent-receipts/   │
│                          │   mcp-server      │
├──────────────────────────┴──────────────────┤
│              Crypto + Schema                 │
│   @agent-receipts/crypto  @agent-receipts/     │
│                            schema            │
└─────────────────────────────────────────────┘

• schema — Zod-схемы, типы TypeScript, JSON Schema для протокола Action Receipt Protocol

• crypto — генерация ключей Ed25519, подпись, проверка, каноническая сериализация

• mcp-server — сервер протокола MCP с движком квитанций, хранилищем и управлением ключами

• sdk — высокоуровневый Node.js SDK, обертывающий движок

• cli — инструмент командной строки для проверки и управления квитанциями

• dashboard — веб-интерфейс Mission Control для визуализации и управления квитанциями

Панель управления (Mission Control)

Визуализируйте каждую квитанцию, цепочку, агента, ограничение и оценку в вашей системе.

npx @agent-receipts/dashboard

Открывает Mission Control по адресу http://localhost:3274 — визуализируйте, проверяйте и управляйте всеми квитанциями.

Функции: лента квитанций в реальном времени, визуализация цепочек, мониторинг состояния ограничений, оценки, проверка подписей, генерация счетов, темная тема, глобальный поиск.

13 страниц: Обзор, Квитанции, Детали квитанции, Цепочки, Детали цепочки, Агенты, Детали агента, Ограничения, Оценки, Счета, Проверка, Настройки, Как это работает.

Примеры

Пакеты

Дорожная карта

• [x] Локальное хранилище квитанций (SQLite с индексированными запросами)

• [x] Подпись и проверка Ed25519

• [x] MCP-сервер с 14 инструментами

• [x] Node.js SDK

• [x] CLI с полным набором команд

• [x] Проверка ограничений (6 встроенных типов)

• [x] ИИ-судья с оценкой на основе рубрик

• [x] Валидация схемы вывода (JSON Schema)

• [x] TTL квитанций и очистка

• [x] Генерация счетов (JSON, CSV, Markdown, HTML)

• [x] Панель управления Mission Control (13 страниц, темная тема, поиск)

• [x] NPM-пакет панели управления — npx @agent-receipts/dashboard

• [x] Живая демо-версия на agent-receipts-web.vercel.app

• [ ] Привязка квитанций к блокчейну/сервисам временных меток

• [ ] Протокол обмена квитанциями между агентами

• [ ] Сжатие и архивация квитанций

• [ ] Хостинг-уровень с облачной базой данных

Разработка

pnpm install
pnpm build
pnpm test
pnpm dev

Лицензия

MIT — см. LICENSE