ferrycat 0.0.0-stage → 0.3.2

package/dist/types.d.ts

@@ -0,0 +1,203 @@
+export type ContractStatus = 'SUBMITTED' | 'CLAIMED' | 'COMPLETED' | 'POINTER_STALE' | 'VALIDATION_FAILED' | 'TIMED_OUT' | 'FAILED';
+export type TaskType = 'code_review' | 'architecture_audit' | 'implementation' | 'test_generation';
+export interface FilePointerInput {
+    path: string;
+    line_range?: [number, number];
+}
+export interface FileFingerprint {
+    path: string;
+    size: number;
+    mtime_ms: number;
+    sha256: string;
+    first_line: string;
+    last_line: string;
+    line_range?: [number, number];
+}
+export interface ArtifactPointer {
+    path: string;
+    description: string;
+}
+export interface ContractRow {
+    id: string;
+    requester_agent: string;
+    target_agent: string;
+    task_type: TaskType;
+    title: string;
+    context_summary: string;
+    workspace_root: string;
+    pointers_json: string;
+    contract_schema_json: string | null;
+    status: ContractStatus;
+    retry_count: number;
+    max_retries: number;
+    queue_ttl_sec: number;
+    exec_ttl_sec: number;
+    result_summary: string | null;
+    structured_output_json: string | null;
+    artifacts_pointers_json: string | null;
+    verified_sha256_json?: string | null;
+    error_reason: string | null;
+    created_at: number;
+    /** Start of the current queue window; reset on release. NULL for rows written by pre-0.2 hosts. */
+    queued_at: number | null;
+    claimed_at: number | null;
+    completed_at: number | null;
+    /** Number of extend_ttl calls by the current holder (reset on release). */
+    extend_count: number;
+    /** Number of times the contract was released back to the queue. */
+    release_count: number;
+    /** Number of fulfill-time TOCTOU mismatch strikes (contract-level, max 1 soft warning before POINTER_STALE). */
+    toctou_strike: number;
+    /** Preserved submission payload if fulfill transitions to terminal POINTER_STALE. */
+    salvaged_result_json?: string | null;
+    /** Exclusive lease token issued at claim time (FC-301). NULL for unassigned or released rows. */
+    claim_token?: string | null;
+}
+export interface DispatchContractInput {
+    requester_agent?: string;
+    target_agent: string;
+    task_type: TaskType;
+    title: string;
+    context_summary: string;
+    workspace_root: string;
+    pointers: FilePointerInput[];
+    contract_schema?: Record<string, unknown>;
+    queue_ttl_sec?: number;
+    exec_ttl_sec?: number;
+}
+export interface DispatchContractResult {
+    contract_id: string;
+    status: 'SUBMITTED';
+    created_at: number;
+    files: Array<{
+        path: string;
+        size: number;
+        mtime_ms: number;
+        sha256: string;
+        first_line: string;
+        last_line: string;
+        line_range?: [number, number];
+    }>;
+    warning?: string;
+}
+export interface PollNextTaskInput {
+    agent_id?: string;
+}
+export interface PollNextTaskResult {
+    has_task: boolean;
+    status?: 'CLAIMED' | 'POINTER_STALE';
+    contract?: {
+        contract_id: string;
+        requester_agent: string;
+        target_agent: string;
+        task_type: TaskType;
+        title: string;
+        context_summary: string;
+        workspace_root: string;
+        pointers: FileFingerprint[];
+        contract_schema: Record<string, unknown> | null;
+        claimed_at: number;
+        exec_ttl_sec: number;
+        /** Exclusive lease token issued for this claim session (FC-301). Pass to mutating operations. */
+        claim_token?: string;
+    };
+    stale_error?: {
+        contract_id: string;
+        reason: string;
+        message: string;
+    };
+    message?: string;
+}
+export interface FulfillContractInput {
+    contract_id: string;
+    agent_id?: string;
+    claim_token?: string;
+    result_summary: string;
+    structured_output?: Record<string, unknown>;
+    artifacts_pointers?: ArtifactPointer[];
+}
+export interface FulfillContractResult {
+    ok: boolean;
+    contract_id: string;
+    status: 'COMPLETED' | 'RETRY_NEEDED' | 'VALIDATION_FAILED' | 'TIMED_OUT' | 'POINTER_STALE';
+    retry_count: number;
+    max_retries: number;
+    toctou_strike?: number;
+    max_toctou_strikes?: number;
+    dirty_files?: Array<{
+        path: string;
+        reason: string;
+        detail: string;
+    }>;
+    validation_errors?: string[];
+    message: string;
+}
+export interface VerifyContractInput {
+    contract_id: string;
+    agent_id?: string;
+    claim_token?: string;
+}
+export interface VerifyContractResult {
+    ok: boolean;
+    valid: boolean;
+    contract_id: string;
+    status: ContractStatus;
+    /** True only when status === 'CLAIMED'; file validity alone does not imply fulfillability. */
+    fulfillable?: boolean;
+    target_agent: string;
+    toctou_strike: number;
+    max_toctou_strikes: number;
+    dirty_files: Array<{
+        path: string;
+        reason: string;
+        detail: string;
+    }>;
+    message: string;
+}
+export interface ReleaseContractInput {
+    contract_id: string;
+    agent_id?: string;
+    claim_token?: string;
+    reason?: string;
+}
+export interface ReleaseContractResult {
+    ok: boolean;
+    contract_id: string;
+    status: 'SUBMITTED' | 'CLAIMED' | 'TIMED_OUT';
+    release_count: number;
+    max_releases: number;
+    message: string;
+}
+export interface ExtendTtlInput {
+    contract_id: string;
+    agent_id?: string;
+    claim_token?: string;
+}
+export interface ExtendTtlResult {
+    ok: boolean;
+    contract_id: string;
+    status: 'CLAIMED' | 'TIMED_OUT';
+    claimed_at?: number;
+    expires_at?: number;
+    extend_count: number;
+    max_extends: number;
+    message: string;
+}
+export interface FailContractInput {
+    contract_id: string;
+    agent_id?: string;
+    claim_token?: string;
+    reason: string;
+}
+export interface FailContractResult {
+    ok: boolean;
+    contract_id: string;
+    status: 'FAILED' | 'TIMED_OUT';
+    message: string;
+}
+export interface InspectMeshStateInput {
+    contract_id?: string;
+    target_agent?: string;
+    status?: ContractStatus | 'ACTIVE' | 'ALL';
+    limit?: number;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/glama.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "GuoBug"
+  ]
+}

package/package.json

@@ -1,6 +1,60 @@
 {
   "name": "ferrycat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "mcpName": "io.github.GuoBug/ferrycat",
+  "description": "FerryCat: Contract-driven cross-host AI agent handoff & review bus over MCP and SQLite WAL",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ferrycat": "bin/ferrycat.js",
+    "ferrycat-cli": "bin/ferrycat-cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "README_zh.md",
+    "LICENSE",
+    "server.json",
+    "glama.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "start": "node --experimental-sqlite dist/index.js",
+    "test": "node --experimental-sqlite --import tsx test/run-all.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuoBug/FerryCat.git"
+  },
+  "homepage": "https://github.com/GuoBug/FerryCat#readme",
+  "bugs": {
+    "url": "https://github.com/GuoBug/FerryCat/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "multi-agent",
+    "agent-handoff",
+    "sqlite-wal",
+    "antigravity",
+    "workbuddy",
+    "contract-driven"
+  ],
+  "author": "Guo Qiang (GuoBug) <https://github.com/GuoBug>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.5.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "ajv": "^8.17.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  }
+}

package/server.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.GuoBug/ferrycat",
+  "title": "FerryCat",
+  "description": "Contract-driven cross-host AI agent handoff & review bus over MCP and SQLite WAL",
+  "version": "0.3.2",
+  "repository": {
+    "url": "https://github.com/GuoBug/FerryCat",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "ferrycat",
+      "version": "0.3.2",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}