FerryCat

io.github.GuoBug由 GitHub 账号 GuoBug 发布v0.5.0更新于 Nov 4, 2026

Contract-driven cross-host agent handoff, code review & verification harness via MCP & SQLite WAL

已验证STDIO仅桌面开发者工具AI 与机器学习

概览

AI 生成的概览

FerryCat 是一个本地 MCP 服务器，通过共享的 SQLite 契约队列，在多个桌面 AI 代理宿主之间传递编码任务与代码审查。

可以做什么
  • 派发契约：为另一个代理宿主登记任务或审查，并记录目标文件的 SHA-256 指纹作为基线。
  • 领取与交付：原子地领取下一个待处理契约，然后提交按契约 JSON Schema 校验的交付结果。
  • 生命周期控制：将已领取的契约退回队列、续期执行窗口，或附带原因标记为失败。
  • 校验与查看：以只读方式比对磁盘文件与基线快照，并只读查询契约状态、输出与诊断信息。
适用场景
适用于同一台机器上的多个桌面 IDE 代理宿主需要交接实现、审查或审计工作，而不想在聊天窗口之间粘贴代码，并希望检测文件过期、输出经过结构校验的场景。不适合不共享本地工作区的宿主，也不适合一次性的单轮提问。
运行要求
以 npm 包形式通过 stdio 在本地运行（npx ferrycat 或全局安装），需要 Node.js。每个宿主的 MCP 配置需设置 AGENT_NAME 环境变量以标识代理。各宿主必须共享同一个本地工作区根目录和用户主目录下的同一个 SQLite 数据库。
安装前请注意
面向单一受信任的操作系统用户设计，不防范恶意本地进程或伪造 AGENT_NAME 的代理。契约会把文件指纹和路径记录在共享的本地数据库中，路径过滤会拦截 .env、密钥、凭据等敏感文件模式。守护进程模式会以用户权限运行配置的处理脚本，因此对配置文件或处理脚本的写权限等同于代码执行权限。它会写入并改变共享数据库中的契约状态。

安装

在 SourceWeft 中

  1. 打开 控制台中的 FerryCat，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

FerryCat: Contract-Driven Cross-Host AI Agent Handoff Bus

English • 中文

[npm version] [MCP Registry] [Node.js Version] [Native Addons] [Protocol] [Glama] [License]

FerryCat (ferrycat) is a lightweight, deterministic cross-host AI agent handoff, code review, and verification harness built on the Model Context Protocol (MCP) and Node.js built-in node:sqlite (WAL mode).
Purpose-built to safely bridge isolated desktop IDE agent hosts (such as Google Antigravity, WorkBuddy, Claude Code, and Cursor) across separate OS processes—enabling Actor-Critic evaluation loops, static analysis gates, and SWE-bench-style patch verification without context drift or blind reviews on stale files.

[FerryCat Architecture and Workflow]

📖 Deep Dive: Why I Started Building FerryCat: When Two AI Coding Hosts Live on the Same Desktop

Quick Glance (See It in 60s)

No IDE setup or config file edits required. Watch the entire deterministic loop execute inside an isolated sandbox in ~2 seconds:

bash
npx ferrycat demo
text
⚡ FerryCat Zero-Config Sandbox Demo ⚡  ✔ [1/4] Contract Dispatched   Locked: src/calc.ts (sha256: ce3ba9a5...bc5d)  ✔ [2/4] Contract Claimed      Lease:  7424261d-9a3f-4a86-a7ff-de278c273e96  ✔ [3/4] Execution & Check     Heartbeat 1 renewal | CHANGES_REQUESTED (loose equality caught)  ✔ [4/4] Contract Completed    TOCTOU: 0 dirty files | Status: COMPLETED (elapsed: 2.1s)  🎉 End-to-end multi-agent handoff verified successfully!

💡 Real benchmark: spins up an isolated child-process sandbox, triggers 1 real lease renewal, and runs a static analysis & verification gate that catches loose equality at src/calc.ts:6. Options (--keep / --json / --no-color) detailed in Quickstart §0.

Core Pain Points & Engineering Solutions

While the official MCP Tasks specification (2025-11 / 2026-07) addresses long-running operations within a single Client ↔ Server connection, it does not solve cross-host collaboration on a developer workstation:

  1. stdio Process Isolation: Desktop IDEs spawn local MCP servers as independent child processes with isolated memory spaces and distinct Node.js runtimes.
  2. Silent Blind Reviews on Stale Code (Stale Context): When handing off a task from Host A to Host B, unushed IDE buffers, branch switches, or mid-review edits cause the receiving agent to audit outdated code and produce plausible but invalid conclusions.
  3. Context Window Bloat: Pasting hundreds of lines of source code across chat windows duplicates token consumption on both ends.
  4. Unstructured Handoff Outputs: Free-form prose responses lack deterministic schema enforcement, making downstream consumption unreliable and prone to infinite retry loops.

FerryCat resolves these failure modes through a human-scheduled, contract-driven SQLite WAL bus:

[Developer]             [Host A: Antigravity]            [~/.ferrycat/mesh.db]            [Host B: WorkBuddy]     |                            |                                |                               |     |-- 1. "Dispatch review" --->|                                |                               |     |                            |-- dispatch_contract() -------->| Write status = SUBMITTED      |     |                            |   (Full SHA-256 + Line Bounds) | Store size / sha256 snapshot  |     |                            |                                |                               |     |-- 2. Switch IDE: "Poll" ---|--------------------------------|------------------------------>|     |                            |                                |<-- poll_next_task() ----------|     |                            |                                |    (Atomic claim changes===1  |     |                            |                                |     + Verify disk SHA-256)    |     |                            |                                |                               |-- Read local files     |                            |                                |<-- fulfill_contract() --------|-- Re-verify SHA-256     |                            |                                |    (Validate Ajv JSON Schema  |   & submit JSON     |                            |                                |     -> status = COMPLETED)    |     |                            |                                |                               |     |-- 3. Switch IDE: "Inspect" |                                |                               |     |                            |-- inspect_mesh_state() ------->| Read-only query of COMPLETED  |     |<-- Present structured res -|                                |                               |

Key Architectural Pillars

1. Deterministic 7-State Machine

Every state transition is bound to an explicit SQL transaction with optimistic concurrency control (changes === 1), eliminating phantom or dangling states:

                  dispatch_contract()                          │                          ▼                    ┌───────────┐                    │ SUBMITTED │ (Queue TTL: default 1800s)                    └─────┬─────┘                          │                 poll_next_task()         ┌────────────────┼────────────────┐         │ (Queue TTL)    │ (Hash Match)   │ (Missing / Size Diff / SHA-256 Mismatch)         ▼                ▼                ▼   ┌───────────┐    ┌───────────┐   ┌───────────────┐   │ TIMED_OUT │    │  CLAIMED  │   │ POINTER_STALE │ (Terminal: Rejects blind review)   └───────────┘    └─────┬─────┘   └───────────────┘      ▲                   │ (Exec TTL: default 300s)      │          fulfill_contract()      │  ┌────────────────┼────────────────┬────────────────┐      └──┤ (Exec TTL)     │ (Schema Valid) │ (Retries > 2)  │ (Mid-Review File Edit)         │                ▼                ▼                ▼         │          ┌───────────┐   ┌───────────────────┐ ┌───────────────┐         └──────────│ COMPLETED │   │ VALIDATION_FAILED │ │ POINTER_STALE │                    └───────────┘   └───────────────────┘ └───────────────┘

Note on POINTER_STALE vs. SELF_CONTAINED Patch Mode (FC-202): POINTER_STALE is terminal whenever on-disk pointer files mismatch the dispatched SHA-256 baseline, except when a read-only contract (code_review / architecture_audit) attaches a verified unified git_patch (--patch-file) that satisfies all three gates: every declared file block carries at least one @@ hunk with real +/- content (EMPTY_PATCH_HUNKS / EMPTY_PATCH_CONTENT otherwise), and the touched paths cover every pointer file (PATCH_DOES_NOT_COVER_POINTERS otherwise). In that SELF_CONTAINED mode, poll_next_task returns patch_mode: "SELF_CONTAINED" with an explicit workspace_warning instructing the reviewer to inspect git_patch rather than stale on-disk files.

Holder-side lifecycle controls on a CLAIMED contract (all require agent_id === target_agent):

CallTransitionGuard rails
release_contractCLAIMED → SUBMITTED (tail of queue, fresh queue window)Resets extend_count (renewal budget is per holder) but preserves retry_count: the schema-failure circuit breaker is a contract-level quota, so releasing cannot launder retry budget. Refused past the absolute lifetime deadline. Max 3 releases per contract.
extend_ttlCLAIMED → CLAIMED (claimed_at = now)Must be called inside the active window; max 5 renewals per holder; refused once now ≥ created_at + 4 × queue_ttl_sec.
fail_contractCLAIMED → FAILED (terminal)Requires a reason, stored as WORKER_FAILED: <reason>. A report arriving after the window closed becomes TIMED_OUT with the reason attached.

2. Full-File SHA-256 Fingerprinting, Pre-Flight Verify & TOCTOU Soft-Failure Buffering (ADR-0004)

  • Dispatch Snapshot: dispatch_contract reads target files on disk, recording byte size, full-file sha256 (64 hex chars), first_line, and last_line. If a file was modified within the last 3 seconds, a warning is emitted to alert the requester of potential unsaved IDE buffers.
  • Claim Verification: poll_next_task verifies Existence -> Byte Size -> Full-File SHA-256 (never rejecting on mtime_ms alone to tolerate no-op IDE saves). On mismatch, it waits 150ms asynchronously (non-blocking, FC-203) and retries once to rule out transient IDE flushes before marking the contract POINTER_STALE — unless the contract is a read-only review/audit carrying a verified unified git_patch covering all pointer files (SELF_CONTAINED patch mode, FC-202), in which case it claims with an explicit workspace_warning and records __verified_on_disk__: "NO" and __unverified_pointers__ in verified_sha256.
  • Pre-Flight Verify (verify_contract): A strictly read-only check allowing workers or scripts to audit pointer health (valid: true vs valid: false with dirty files list) before submitting.
  • TOCTOU Soft-Failure Buffering: fulfill_contract checks on-disk pointer fingerprints. If dirty pointers are detected:
    • Strike 1 returns RETRY_NEEDED, leaves the contract CLAIMED, renews the execution window, and lists dirty files with recovery instructions (git stash / git checkout -- <file>).
    • Strike 2 transitions to terminal POINTER_STALE and saves the full submitted review payload into salvaged_result_json so review effort is never lost.
  • TOCTOU Race Narrowing: While no file-based system can eliminate the microsecond race between reading disk bytes and committing a database row, FerryCat's dual-verification (at poll and at fulfill) drastically narrows the TOCTOU window from minutes of blind review down to the sub-millisecond atomic SQL transition boundary.

3. Bounded Schema Validation (RETRY_NEEDED $\le 2$)

  • Outputs are validated against the contract's JSON Schema via cached Ajv validators, with errors flattened into concise single-line paths (e.g., ["/passed: must be boolean"]).
  • Up to 2 validation failures return RETRY_NEEDED while keeping the contract CLAIMED for immediate self-correction (each rejection also renews the execution window); a 3rd failure transitions the contract to terminal VALIDATION_FAILED.

4. Dual-Stage TTL & Read-Before-Write Sweeping

  • Separates queue_ttl_sec (default 1800s for SUBMITTED) from exec_ttl_sec (measured from claimed_at), preventing tasks claimed late in the queue window from timing out prematurely during execution.
  • exec_ttl_sec defaults are tiered by task_type: code_review / architecture_audit → 1800s (deep reasoning or human-in-the-loop), implementation / test_generation → 300s. An explicit exec_ttl_sec always wins.
  • poll_next_task executes a lock-free SELECT COUNT(*) probe before attempting any UPDATE on expired rows; inspect_mesh_state is strictly read-only.

5. Defense-in-Depth Path Security

  • Enforces path containment within workspace_root and blocks sensitive file patterns (.env*, *.pem, *.key, id_rsa*, *credentials*, *secret*, .npmrc, .git/config) on both dispatch and worker verification paths.
  • Path Resolution: workspace_root is strongly recommended to be passed as an absolute path. If a relative path is provided, it is deterministically resolved against process.cwd() via path.resolve.

6. Threat Model & Security Assumptions (Local Workstation IPC)

  • Assumed Trust Environment: FerryCat is intentionally designed as a Trusted Local Workstation Bus bridging isolated IDE hosts operating under the same OS user account. Callers and workers share the local file system (workspace_root) and SQLite database (~/.ferrycat/mesh.db).
  • Defense Scope: Path containment (assertSafePointerPath) and sensitive file pattern filters prevent unintentional workspace escapes, symlink traversals, or accidental leakage of credentials/secret files during handoffs.
  • Daemon Execution Surface: In daemon mode (ferrycat-cli daemon), handler scripts are invoked directly via execFile. Write permissions to ferrycat.config.json or handler script paths are equivalent to host execution privileges (ADR-0005 §2.2). Keep configurations local and version-controlled.
  • Out of Scope (Non-Goals): FerryCat does not provide adversarial sandboxing, multi-tenant isolation, or network authorization against malicious local processes or adversarial agents spoofing AGENT_NAME.

Applicability Boundaries (When NOT to Use FerryCat)

  1. Disjoint File Systems: FerryCat offloads context by file reference; both hosts must share access to the same local workspace_root.
  2. Trivial Single-Turn Queries: Each cross-host handoff involves 3 explicit human window switches (~15–25s overhead).
  3. Multi-Step Dynamic DAG Pipelines: FerryCat's background daemon (ferrycat-cli daemon, ADR-0005) manages single-step contract dispatch and supervised worker lifecycles; for complex multi-step branching DAG orchestrations, use dedicated DAG workflow engines such as PatchCat.

Controlled Daemon & Declarative Handlers (ADR-0005)

FerryCat provides a controlled daemon mode governed by SQLite microsecond CAS leases on daemon_locks and declarative scripts defined in ferrycat.config.json (ideal for binding static analysis gates like tsc / eslint / AST checks or automated test suites like Jest / Vitest / Pytest as deterministic verification workers):

bash
# Run a single dispatch cycle with declared handlersferrycat-cli daemon --config ./ferrycat.config.json --once
# Start continuous daemon loopferrycat-cli daemon --config ./ferrycat.config.json
# Inspect lease ownership + write-ahead journal health (read-only)ferrycat-cli daemon --status

daemon --status reports journal_degraded / last_journal_error / journal_path / journal_entries alongside lease ownership, so a silently unwritable write-ahead journal (which would disarm crash recovery) is visible instead of failing mute.

Example ferrycat.config.json:

json
{  "version": 1,  "daemon": {    "poll_interval_ms": 1000,    "lease_ttl_sec": 30,    "heartbeat_interval_ms": 10000,    "notify": true  },  "agents": {    "workbuddy": {      "handlers": {        "code_review": {          "exec_file": "./scripts/review-handler.js",          "pass_env": ["CUSTOM_ANALYZER_PATH"]        }      }    }  }}

Quickstart

0. See what it actually does first (ferrycat demo)

Before configuring any MCP server, watch the whole loop in ~3 seconds:

bash
npx ferrycat demo

(or npx -p ferrycat ferrycat-cli demo)

It spins up a fully isolated sandbox under the OS temp dir (dedicated SQLite database, sample source file, sample handler), runs dispatch → claim → supervised execution → TOCTOU re-verification → COMPLETED, then deletes the sandbox. Your real workspace and ~/.ferrycat/mesh.db are never read or written.

text
⚡ FerryCat Zero-Config Sandbox Demo ⚡Sandbox: /tmp/ferrycat-demo-c5iK6V
  ✔ [1/4] Contract Dispatched    Locked    src/calc.ts (sha256: ce3ba9a5...bc5d)  ✔ [2/4] Contract Claimed    Lease     7424261d-9a3f-4a86-a7ff-de278c273e96  ✔ [3/4] Execution & Schema Check    Heartbeat 1 lease renewal(s)  ✔ [4/4] Contract Completed    TOCTOU    fingerprints matched (0 dirty files)
  🎉 End-to-end multi-agent handoff verified successfully!
OptionEffect
--jsonEmit a structured result for CI / upstream assertions
--keepKeep the sandbox and print its path for manual sqlite3 inspection
--no-colorDisable ANSI colors (auto-off when not a TTY or NO_COLOR is set)

1. Recommended: Zero-Install MCP Mounting (via npx)

No local clone or manual compilation required. Run npx ferrycat init --yes to auto-detect installed hosts (Antigravity, WorkBuddy, Cursor, VS Code, Windsurf, Claude Desktop, Claude Code) and safely merge the ferrycat server entry (with backup and JSONC protection), or mount manually into your IDE's MCP configuration using npx -y ferrycat:

Antigravity Configuration

Edit %USERPROFILE%\.gemini\antigravity\mcp_config.json (or ~/.gemini/antigravity/mcp_config.json on macOS/Linux):

json
{  "mcpServers": {    "ferrycat": {      "command": "npx",      "args": ["-y", "ferrycat"],      "env": {        "AGENT_NAME": "antigravity"      }    }  }}
WorkBuddy / Claude Code / Cursor / Codex Configuration

Configure the target host's MCP settings with its respective AGENT_NAME:

json
{  "mcpServers": {    "ferrycat": {      "command": "npx",      "args": ["-y", "ferrycat"],      "env": {        "AGENT_NAME": "workbuddy"      }    }  }}

2. Global Installation & Source Build

  • Global CLI Installation:
    bash
    npm install -g ferrycat
    Then simply set "command": "ferrycat" in your MCP config.
  • Local Source Build (For Contributors):
    bash
    git clone https://github.com/GuoBug/FerryCat.gitcd FerryCatnpm installnpm run buildnpm test
    Mount using your local path: "command": "node", "args": ["--experimental-sqlite", "/path/to/FerryCat/dist/index.js"].

First-Class CLI Experience (ferrycat-cli)

Beyond serving as an in-IDE MCP Server, FerryCat provides a first-class CLI utility (ferrycat-cli). The single ferrycat executable dispatches on its first argument: no argv starts the MCP stdio server, a known subcommand routes to the CLI. So you can run npx ferrycat <command> with zero install (or ferrycat-cli <command> once installed globally). Sharing the same ~/.ferrycat/mesh.db SQLite WAL database and Zod validation contracts, the CLI allows developers to inspect mesh health, verify working tree safety, and hook into automated CI/Git scripts without leaving their terminal:

1. Terminal Visual Inspection (ASCII Status Table)

Inspect all cross-host handoffs and error reasons formatted as an ASCII table:

bash
# View all contracts in an ASCII tablenpx ferrycat inspect
# Filter by target agent (e.g., only tasks for antigravity)npx ferrycat inspect --target antigravity

2. Pre-Flight Verification (Auditing Before Mutation)

Audit on-disk pointer file integrity against the contract's baseline SHA-256 before committing review work (ADR-0004), eliminating false-positive deliveries:

bash
npx ferrycat verify <CONTRACT_ID>

3. Local CI & Headless Worker Execution

Poll the queue, claim tasks, and execute local review/test scripts with automatic failure closure:

bash
# Safely run a script upon task arrival (no shell quotation hazards)npx ferrycat worker --agent codex --mode=exec --exec-file ./scripts/review.sh --delivery envelope# See docs/examples/ for dispatch.example.json, fulfill.example.json, and handler.example.cjs templates.

4. Zero-Config Sandbox Walkthrough (demo)

Run the self-contained multi-agent lifecycle simulation without configuring an MCP server:

bash
npx ferrycat demo

Options (--keep to retain SQLite for manual inspection, --json for CI assertions) detailed in Quickstart §0.

5. Production Controlled Daemon (daemon, ADR-0005)

Run the headless orchestration daemon coordinating background workers via atomic CAS leases and declarative script bindings:

bash
# Launch daemon using project-local declarative configurationnpx ferrycat daemon --config ./ferrycat.config.json
# Run single poll/dispatch iteration for a targeted agent and exitnpx ferrycat daemon --agent workbuddy --once

Exposed MCP Tools

Tool NameRoleTransactional Behavior
dispatch_contractRequesterEnforces path blacklist $\to$ computes full-file SHA-256 & line bounds (plus optional unified git_patch / --patch-file validation covering pointers, FC-202) $\to$ inserts SUBMITTED.
poll_next_taskWorkerSweeps expired TTLs (read-before-write) $\to$ claims via changes === 1 (CLAIMED) $\to$ verifies disk SHA-256 with async 150ms retry (FC-203) or falls back to SELF_CONTAINED patch mode with workspace_warning (otherwise marks POINTER_STALE).
fulfill_contractWorkerRe-verifies SHA-256 (TOCTOU guard) $\to$ validates Ajv JSON Schema ($\le 2$ retries via RETRY_NEEDED, 3rd marks VALIDATION_FAILED) $\to$ marks COMPLETED.
release_contractWorker (holder)Hands a CLAIMED contract back to the queue tail as SUBMITTED. retry_count is preserved (contract-level circuit breaker); extend_count is reset. Max 3 releases; refused once past the absolute lifetime deadline.
extend_ttlWorker (holder)Heartbeat: restarts the execution window (claimed_at = now), max 5 renewals and bounded total lifetime.
fail_contractWorker (holder)Marks a CLAIMED contract terminal FAILED with a mandatory reason.
verify_contractWorker / Any (Read-Only)Pre-flight check: validates on-disk pointer files against the baseline SHA-256 without mutating contract state (ADR-0004).
inspect_mesh_stateAny (Read-Only)Pure read-only query of contract states, outputs, patch_sha256 / patch_bytes (opt-in include_patch: true), and dynamic is_logically_expired flags.

💡 Architecture Decision Records & Engineering Verification:

About the Author
Guo Qiang (GuoBug), Product Engineer specializing in platform engineering and growth. Currently focused on AI workflow orchestration, DAG state machines, and deterministic system architectures.
Open Source & Homepage: https://github.com/GuoBug · https://guobug.github.io
Inquiries and discussions on workflow engine architecture, topological scheduling, and developer experience are warmly welcomed.

来源：README.md，提交 8b9986a

工具

8

dispatch_contract

Dispatch a task or code review contract to another local AI agent host via the shared SQLite WAL mesh. ### Purpose Registers a new contract in SUBMITTED status with full-file SHA-256 fingerprint snapshots of all target files, establishing an immutable baseline for cross-host verification. ### Usage Guidelines - When to use: Use when requesting code reviews, architecture audits, implementation, or test generation from a target agent (e.g., target_agent="workbuddy" or "antigravity"). - When NOT to use: - Do NOT use to claim or execute tasks (use poll_next_task). - Do NOT use to check task status or inspect outputs (use inspect_mesh_state). - Do NOT use if the target host does not share the same local filesystem access to workspace_root. - Prerequisites: workspace_root must be a valid directory accessible by both hosts. Pointer files must exist on disk and be saved. Sensitive files (.env, keys, credentials, .git/config) and path escapes are strictly blocked. ### Behavior & Side Effects - Mutates database: Synchronously inserts a single row into contracts with status='SUBMITTED' in SQLite WAL (~/.ferrycat/mesh.db). - SHA-256 Snapshot: Computes 64-char hex SHA-256, byte size, and first/last lines for each pointer. Emits a warning if any file was modified within the last 3 seconds (indicating unsaved IDE buffers). - Lifecycle & Expiry: Starts the queue_ttl_sec countdown (default: 1800s / 30m). If the target agent never claims it before queue_ttl_sec elapses, the contract lazily transitions to TIMED_OUT. - Once claimed, execution is governed by exec_ttl_sec (tiered default: 1800s for review/audit, 300s for implementation/test). ### Return Value Returns { contract_id: string, status: 'SUBMITTED', created_at: number, files: Array<{ path, size, mtime_ms, sha256, first_line, last_line, line_range? }>, warning?: string }. Note: requester_agent / target_agent / task_type / title / TTLs are NOT echoed back — read them via inspect_mesh_state if needed.

输入参数title必填pointers必填git_patchtask_type必填exec_ttl_sectarget_agent必填queue_ttl_secworkspace_root必填context_summary必填contract_schemarequester_agent

poll_next_task

Atomically claim the oldest pending SUBMITTED contract assigned to this agent and verify local file fingerprints. ### Purpose Retrieves and claims next available contract work for the current agent, transitioning it from SUBMITTED to CLAIMED. ### Usage Guidelines - When to use: Call periodically or when notified to discover and atomically take ownership of pending tasks assigned to your agent_id. - When NOT to use: - Do NOT use to non-destructively inspect queue depth or monitor status without claiming (use inspect_mesh_state). - Do NOT use to create contracts (use dispatch_contract). - IMPORTANT (ADR-0004): Pointers are an immutable baseline snapshot ("what I read"). Never edit pointer files directly on disk while holding a review contract; deliver any proposed code fixes via structured_output.fixes in fulfill_contract. ### Behavior & Side Effects - Mutates database: Atomically claims the oldest SUBMITTED contract for agent_id using optimistic concurrency (UPDATE ... WHERE status='SUBMITTED', checked by changes===1). Starts the exec_ttl_sec window. - Lazy TTL sweep: Automatically sweeps and marks expired contracts as TIMED_OUT using lock-free read-before-write probing. - Fingerprint verification: Verifies Existence -> Byte Size -> SHA-256 for all pointers. If on-disk files were altered or missing, marks the contract POINTER_STALE and transparently advances to claim the next valid candidate in the queue. ### Return Value - When work is claimed: { ok: true, has_task: true, status: 'CLAIMED', contract: { contract_id, requester_agent, target_agent, task_type, title, context_summary, workspace_root, pointers, contract_schema, claimed_at, exec_ttl_sec } }. - When queue is empty: { ok: true, has_task: false, message: 'No pending contracts for agent "<agent_id>"' }.

输入参数agent_id

fulfill_contract

Submit execution or review deliverables for a CLAIMED contract, with TOCTOU soft-failure buffering and Ajv JSON Schema validation. ### Purpose Delivers the final output of a task, verifies that the code baseline was not mutated during execution, validates structured payloads, and transitions the contract to terminal COMPLETED. ### Usage Guidelines - When to use: Use after completing task work to deliver result_summary, optional structured_output, and optional artifacts_pointers. - When NOT to use: - Do NOT use if you cannot complete the task (use release_contract to re-queue, or fail_contract to record failure). - Do NOT use if you modified pointer files directly on disk. If modified accidentally, run "git stash" or restore the files, run verify_contract, and pass proposed fixes inside structured_output.fixes. ### Behavior & Side Effects - Authorization: Caller agent_id must match target_agent of the claimed contract. - TOCTOU Guard & Soft-Failure Buffer (ADR-0004) — exactly ONE recoverable rejection: - 1st blocked fulfill: returns status='RETRY_NEEDED', keeps the contract CLAIMED, renews the execution window (claimed_at=now), and lists dirty_files with restore instructions. - 2nd blocked fulfill: transitions to terminal status='POINTER_STALE', preserving your summary and payload in salvaged_result_json so the work is not lost. - Only ONE rejection is recoverable: restore/stash the files BEFORE retrying, and call verify_contract first so a stray second attempt cannot burn the buffer. - Schema Validation: If contract_schema was defined, validates structured_output via cached Ajv validator. Failures 1 & 2 return RETRY_NEEDED with flattened error paths and renew the execution window; 3rd failure transitions to terminal VALIDATION_FAILED. - On Success: Transitions to terminal status='COMPLETED', recording result_summary, structured_output, artifacts_pointers, and verified SHA-256 snapshot. ### Return Value Returns { ok: boolean, contract_id: string, status

输入参数agent_idclaim_tokencontract_id必填result_summary必填structured_outputartifacts_pointers

inspect_mesh_state

Strictly read-only query of contracts, execution progress, outputs, diagnostic counters, and failure causes. ### Purpose Provides comprehensive observability into the multi-agent mesh state without acquiring database locks or mutating rows. ### Usage Guidelines - When to use: - Check whether a contract you dispatched has been claimed or completed. - Inspect result summaries, structured outputs, or salvaged results of completed/stale contracts. - Monitor queue depth or pending contracts for a specific agent via target_agent filter. - When NOT to use: - Do NOT use to claim tasks (use poll_next_task). - Do NOT use to dispatch tasks (use dispatch_contract). - Do NOT use to verify on-disk file pointer hygiene (use verify_contract). ### Behavior & Side Effects - Zero side effects: Pure read-only SELECT query against SQLite WAL. Never alters rows or triggers sweeps. - Dynamically calculates is_logically_expired: true when a contract has exceeded its queue or execution TTL based on the current timestamp, even before the next lazy sweep runs. ### Return Value Returns { total_returned: number, contracts: Array<{ contract_id, requester_agent, target_agent, task_type, title, status, is_logically_expired, created_at, claimed_at, completed_at, retry_count, extend_count, release_count, toctou_strike, result_summary, structured_output, artifacts_pointers, error_reason, salvaged_result, verified_sha256 }> }.

输入参数limitstatuscontract_idtarget_agentinclude_patch

release_contract

Hand a CLAIMED contract back to the queue tail as SUBMITTED with a fresh queue window. ### Purpose Allows an agent holding a claimed task to safely release ownership back to the queue without failing or aborting the task. ### Usage Guidelines - When to use: Use when your agent claimed a task by mistake, encounters missing local dependencies/tools, or needs to switch git branches before processing. - When NOT to use: - Do NOT use if the task permanently failed or cannot ever be completed (use fail_contract). - Do NOT use if you simply need more time to finish active execution (use extend_ttl). - Prerequisites: Caller must be the current holder (agent_id matches target_agent) and contract status must be CLAIMED. ### Behavior & Side Effects - Mutates database: Resets claimed_at=NULL, updates queued_at=nowMs, resets extend_count=0 (renewal quota is per holder), and increments release_count. - Preserves retry_count: The schema validation circuit-breaker quota is contract-level; releasing a contract cannot launder previously consumed retry attempts. - Audit history: Appends reason to error_reason history ("RELEASED_BY_HOLDER: <reason> | prev: ..."). - Limits: Maximum 3 releases per contract. Refused once the contract reaches its absolute lifetime ceiling (nowMs >= created_at + 4 * queue_ttl_sec). ### Return Value Returns { ok: boolean, contract_id: string, status: 'SUBMITTED' | 'CLAIMED' | 'TIMED_OUT', release_count: number, max_releases: number, message: string }.

输入参数reasonagent_idclaim_tokencontract_id必填

extend_ttl

Heartbeat renewal for long-running execution: restarts the active execution window of a CLAIMED contract. ### Purpose Prevents execution timeout during deep reasoning, extensive test execution, or complex multi-step refactoring by resetting the execution clock. ### Usage Guidelines - When to use: Call periodically during long-running tasks before the active exec_ttl_sec countdown expires. - When NOT to use: - Do NOT use after the window has already expired (expired contracts transition to TIMED_OUT). - Do NOT use to deliver task completion (use fulfill_contract). - Do NOT use if abandoning the task (use release_contract or fail_contract). - Prerequisites: Caller must be the current holder and contract must be currently CLAIMED. ### Behavior & Side Effects - Mutates database: Resets claimed_at=nowMs (restarting the full exec_ttl_sec window from the current moment) and increments extend_count. - Quotas & Boundaries: Maximum 5 renewals per holder. Bounded by the contract's absolute lifetime ceiling (created_at + 4 * queue_ttl_sec); rejected if proposedExpiresAt > lifetimeDeadline. ### Return Value Returns { ok: boolean, contract_id: string, status: 'CLAIMED' | 'TIMED_OUT', claimed_at?: number, expires_at?: number, extend_count: number, max_extends: number, message: string }.

输入参数agent_idclaim_tokencontract_id必填

fail_contract

Explicitly mark a CLAIMED contract as terminal FAILED with a mandatory failure reason. ### Purpose Immediately terminates a claimed task that cannot be completed, recording actionable diagnostic reasons and freeing the requester from waiting for the execution TTL to expire. ### Usage Guidelines - When to use: Use when a task encounters an unrecoverable failure (e.g. fatal syntax error, broken test suite, missing required environment). - When NOT to use: - Do NOT use if the task succeeded (use fulfill_contract). - Do NOT use if the task is recoverable by another agent or retryable (use release_contract). - Prerequisites: Caller must be the current holder and reason must be non-empty. ### Behavior & Side Effects - Mutates database: Sets status='FAILED', error_reason='WORKER_FAILED: <reason>', and completed_at=nowMs. - Late report handling: If the execution window already expired before fail_contract was called, the status becomes TIMED_OUT while faithfully preserving the worker's reason for the requester. ### Return Value Returns { ok: boolean, contract_id: string, status: 'FAILED' | 'TIMED_OUT', message: string }.

输入参数reason必填agent_idclaim_tokencontract_id必填

verify_contract

Read-only pre-flight consistency check (ADR-0004): audits on-disk pointer files against the baseline SHA-256 snapshot. ### Purpose Enables agents or automated scripts to verify that on-disk files match the contract's dispatched baseline before calling fulfill_contract, preventing accidental TOCTOU strikes. ### Usage Guidelines - When to use: Call before fulfill_contract while holding a CLAIMED contract to confirm file cleanliness, or when investigating why a fulfill call was blocked. - When NOT to use: - Do NOT use to deliver results (use fulfill_contract). - Do NOT use to renew time (use extend_ttl). - ADR-0004 Rule: Pointers are an immutable review baseline. If verify_contract reports dirty files, restore or stash them (e.g., git stash or git checkout -- <file>) and deliver proposed changes inside structured_output.fixes. ### Behavior & Side Effects - Zero side effects: Pure read-only operation. Never updates the database, never alters contract status, and never consumes a TOCTOU strike. - Complete pointer check: Verifies all pointer files on disk and returns every drifted file (reason: SIZE_MISMATCH, CONTENT_CHANGED, or FILE_MISSING). ### Return Value Returns { ok: true, valid: boolean, fulfillable: boolean, contract_id: string, status: ContractStatus, target_agent: string, toctou_strike: number, max_toctou_strikes: number, dirty_files: Array<{ path, reason, detail }>, message: string }. NOTE: valid only means every pointer still matches its dispatched baseline. fulfillable additionally requires the contract to be CLAIMED. A contract that already went terminal (FAILED / POINTER_STALE / COMPLETED) can report valid=true while fulfillable=false, so branch on fulfillable rather than valid before calling fulfill_contract.

输入参数agent_idclaim_tokencontract_id必填

版本历史

4
  1. v0.5.0最新Nov 4, 2026
  2. v0.4.0Oct 29, 2026
  3. v0.3.3Oct 25, 2026
  4. v0.3.2Oct 24, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分