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 分