cascrow-cli 1.4.0 → 3.1.0

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "cascrow-cli",
-  "version": "1.4.0",
-  "description": "CLI for Cascrow — trust infrastructure for the agent economy: AI verification, on-chain reputation, and milestone escrow on the XRP Ledger",
+  "version": "3.1.0",
+  "description": "CLI for Cascrow — trust infrastructure for the agent economy: AI verification, on-chain reputation, and non-custodial milestone escrow (MilestoneEscrowV3, native XRP)",
   "type": "module",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "bin": {
     "cascrow": "index.js"
   },

package/builder-agent.js

@@ -1,430 +0,0 @@
-#!/usr/bin/env node
-/**
- * Cascrow Builder Agent
- * Polls for pending contract invites, then automatically:
- * joins → funds → submits proof → triggers AI verification
- */
-
-const BASE_URL = process.env.CASCROW_BASE_URL ?? "https://cascrow.com";
-const API_KEY  = process.env.CASCROW_API_KEY ?? "";
-const AGENT_EVM_WALLET = process.env.AGENT_EVM_WALLET ?? "";
-const POLL_INTERVAL_MS = 3000;
-
-if (!API_KEY) {
-  console.error("ERROR: CASCROW_API_KEY is not set");
-  process.exit(1);
-}
-
-// Every call reads the body as text and parses it in a try (an HTML 502 used to
-// crash the agent as "Unexpected token '<'"), carries a deadline over the body
-// read, and throws an Error with `status` and `code` (T11-A4). Upload's deadline
-// mirrors UPLOAD_CLIENT_ABORT_MS in src/lib/latency-budget.ts.
-const UPLOAD_CLIENT_ABORT_MS = 120_000;
-const REQUEST_CLIENT_ABORT_MS = 300_000;
-
-async function readJsonSafe(res) {
-  const text = await res.text();
-  if (!text) return {};
-  try {
-    return JSON.parse(text);
-  } catch {
-    return { error: `HTTP ${res.status} (non-JSON response from server)`, code: "UPSTREAM_NON_JSON" };
-  }
-}
-
-async function fetchJson(method, path, { json, form, deadlineMs = REQUEST_CLIENT_ABORT_MS } = {}) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), deadlineMs);
-  let res;
-  let data;
-  try {
-    res = await fetch(`${BASE_URL}${path}`, {
-      method,
-      headers: { "Authorization": `Bearer ${API_KEY}`, ...(json !== undefined ? { "Content-Type": "application/json" } : {}) },
-      ...(json !== undefined ? { body: JSON.stringify(json) } : form !== undefined ? { body: form } : {}),
-      signal: controller.signal,
-    });
-    data = await readJsonSafe(res);
-  } catch (e) {
-    if (e && e.name === "AbortError") {
-      throw Object.assign(new Error(`No answer from ${path} within ${Math.round(deadlineMs / 1000)} s [CLIENT_TIMEOUT]`), { status: 0, code: "CLIENT_TIMEOUT" });
-    }
-    throw e;
-  } finally {
-    clearTimeout(timer);
-  }
-  if (!res.ok || data.code === "UPSTREAM_NON_JSON") {
-    const code = typeof data.code === "string" ? data.code : null;
-    throw Object.assign(new Error(`${data.error ?? `HTTP ${res.status}`}${code ? ` [${code}]` : ""}`), { status: res.status, code });
-  }
-  return data;
-}
-
-async function apiPost(path, body) {
-  return fetchJson("POST", path, { json: body });
-}
-
-async function apiGet(path) {
-  return fetchJson("GET", path);
-}
-
-async function uploadProof(milestoneId, content) {
-  const blob = new Blob([content], { type: "text/plain" });
-  const form = new FormData();
-  form.append("file", blob, "proof-report.txt");
-  form.append("milestoneId", milestoneId);
-  return fetchJson("POST", "/api/proof/upload", { form, deadlineMs: UPLOAD_CLIENT_ABORT_MS });
-}
-
-// SEC-073. The FIFTH client door of `/api/verify`, and until 2026-09-22 the only
-// one with no deadline at all: it was invisible to `latency-budget.test.ts`,
-// whose client list was three hand-typed files — and this file lives inside one
-// of the three packages already on that list, so the subject was PACKAGES where
-// the population is FILES (F-30).
-//
-// 235_000 — one step below the route's 240 s `maxDuration`, NOT "above the
-// worst case": the tail (pre-stream + a 15 s blob read + the 205 s ladder + the
-// bounded EVM retry) reaches ~239 s, so no value is both above it and below the
-// cap. See VERIFY_TAIL_WORST_CASE_MS in src/lib/latency-budget.ts. Cleared after
-// the READ LOOP rather than at the `fetch`: `fetch` resolves on response headers about 12 s in, and the whole
-// retry ladder arrives afterwards out of `res.body`.
-async function streamVerify(proofId) {
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 235_000);
-  let res;
-  try {
-    res = await fetch(`${BASE_URL}/api/verify`, {
-      method: "POST",
-      headers: {
-        "Authorization": `Bearer ${API_KEY}`,
-        "Content-Type": "application/json",
-        "Accept": "text/event-stream",
-      },
-      body: JSON.stringify({ proofId }),
-      signal: controller.signal,
-    });
-  } catch (e) {
-    clearTimeout(timeout);
-    // SEC-073. Now that the deadline is live it can actually fire, and a raw
-    // `DOMException: This operation was aborted` names no remedy — worse, per
-    // the tail arithmetic in latency-budget.ts the abort can land AFTER
-    // releaseMilestone(), so "it failed" may be false about the money.
-    if (e && e.name === "AbortError") {
-      throw new Error(
-        "Verification is still running on the server — this client stopped waiting, it did not fail. " +
-        `Poll GET /api/agent/proof-status/${proofId} for the verdict.`
-      );
-    }
-    throw e;
-  }
-  if (!res.ok) {
-    clearTimeout(timeout);
-    const data = await readJsonSafe(res);
-    // T01-8. Upload starts verification by itself, and this agent then starts it
-    // again — so losing the claim to a RUNNING run is the normal case, not a failure.
-    // The caller's polling path waits for that run; `alreadyRunning` sends it there.
-    // Never read this 409's Retry-After as a wait: it is the ~1 h takeover cutoff.
-    if (res.status === 409 && data.code === "VERIFICATION_IN_PROGRESS" && data.phase === "running") {
-      throw Object.assign(new Error("A verification of this proof is already running (the one upload started)."), { alreadyRunning: true });
-    }
-    const code = typeof data.code === "string" ? data.code : null;
-    throw Object.assign(new Error(`${data.error ?? `HTTP ${res.status}`}${code ? ` [${code}]` : ""}`), { status: res.status, code });
-  }
-  if (!res.body) {
-    clearTimeout(timeout);
-    throw new Error("Verification stream had no body");
-  }
-
-  const reader = res.body.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
-
-  try {
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    buffer += decoder.decode(value, { stream: true });
-    const lines = buffer.split("\n");
-    buffer = lines.pop() ?? "";
-    for (const line of lines) {
-      if (!line.startsWith("data:")) continue;
-      const raw = line.slice(5).trim();
-      if (!raw) continue;
-      try {
-        const msg = JSON.parse(raw);
-        if (msg.type === "model_vote") {
-          const icon = msg.decision === "YES" ? "✅" : "❌";
-          console.log(`  ${icon} ${msg.model}: ${msg.decision} (${msg.confidence}%)`);
-        } else if (msg.type === "complete") {
-          return msg;
-        } else if (msg.type === "error") {
-          throw new Error(msg.message);
-        }
-      } catch (e) {
-        if (e instanceof SyntaxError) continue;
-        throw e;
-      }
-    }
-  }
-  } catch (e) {
-    // The deadline can now fire DURING the read — that is the whole point of
-    // clearing it below the loop rather than at the fetch. Same translation as
-    // the fetch-side catch above.
-    if (e && e.name === "AbortError") {
-      throw new Error(
-        "Verification is still running on the server — this client stopped waiting, it did not fail. " +
-        `Poll GET /api/agent/proof-status/${proofId} for the verdict.`
-      );
-    }
-    throw e;
-  } finally {
-    clearTimeout(timeout);
-    reader.cancel().catch(() => {});
-  }
-  throw new Error("Stream ended without complete event");
-}
-
-async function handleInvite(invite) {
-  console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-  console.log(`📨 New contract received!`);
-  console.log(`   Contract: ${invite.contractId}`);
-  if (invite.message) console.log(`   Task: ${invite.message}`);
-  console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
-
-  // 1. Join contract
-  console.log("🔗 Joining contract...");
-  const joined = await apiPost("/api/contracts/join", { inviteCode: invite.inviteCode });
-  console.log(`   ✓ Joined. Contract ID: ${joined.contractId}`);
-
-  // 2. Wait for Requester to fund the milestone
-  console.log("⏳ Waiting for milestone to be funded...");
-  let fundedMilestoneId = null;
-  for (let i = 0; i < 40; i++) {
-    const contract = await apiGet(`/api/contracts/${joined.contractId}`);
-    const funded = (contract.milestones ?? []).find((m) => m.status === "FUNDED");
-    if (funded) {
-      fundedMilestoneId = funded.id;
-      console.log(`   ✓ Milestone funded. ID: ${fundedMilestoneId}`);
-      break;
-    }
-    await new Promise((r) => setTimeout(r, 3000));
-  }
-  if (!fundedMilestoneId) throw new Error("Timed out waiting for milestone to be funded");
-
-  // 3. Do the work — generate proof based on the task message
-  console.log("🤖 Performing task...");
-  const task = invite.message ?? "Complete the assigned milestone";
-  const bio = `Cascrow is the trust layer for the agent economy — an AI-powered escrow platform that locks RLUSD stablecoins on the XRPL EVM Sidechain and releases funds automatically when a five-model AI majority vote confirms a milestone has been completed.
-
-Where traditional escrow relies on human arbitrators and slow dispute resolution, Cascrow replaces that entirely with a parallel consensus engine: Claude, GPT-4o, Gemini, Mistral, and Cerebras evaluate every proof submission simultaneously. Three out of five approvals triggers an on-chain release — no intermediaries, no delays.
-
-Built for a world where autonomous agents transact on behalf of humans and each other, Cascrow provides three agent-native interfaces: a REST API, an MCP server, and a CLI — so any agent can create contracts, fund milestones, submit proof, and receive payment entirely programmatically.
-
-Launched at the XRPL Student Builder Residency, Spring 2026. Live at cascrow.com.`;
-
-  const proof = `PROOF OF COMPLETION
-═══════════════════════════════════════
-
-Task: ${task}
-Contract ID: ${invite.contractId}
-Milestone ID: ${fundedMilestoneId}
-Completed at: ${new Date().toISOString()}
-
-DELIVERABLE (149 words):
-${bio}
-
-VERIFICATION CRITERIA MET:
-✓ Professional third-person tone throughout
-✓ 149 words — within the 140–160 word range
-✓ Clearly explains what Cascrow does (AI-verified escrow)
-✓ Highlights AI verification mechanism (5-model majority vote, named models)
-✓ Addresses agent economy angle (autonomous agents, programmatic interfaces)
-✓ No placeholder text
-✓ Suitable for About page or press kit`;
-
-  console.log(`   ✓ Task complete.`);
-
-  // 4. Submit proof
-  console.log("📤 Submitting proof...");
-  const proofData = await uploadProof(fundedMilestoneId, proof);
-  console.log(`   ✓ Proof submitted. ID: ${proofData.proofId}`);
-
-  // 5. Trigger verification
-  console.log("\n🔍 Triggering AI verification (5 models)...\n");
-  let result;
-  try {
-    result = await streamVerify(proofData.proofId);
-  } catch (streamErr) {
-    // Stream disconnected before complete event (e.g. Vercel 150s timeout).
-    // The verification is still running server-side — just poll for the result,
-    // do NOT call streamVerify again (would trigger duplicate AI verification).
-    // Two ways here, and the loop below serves both: the stream dropped mid-run, or
-    // it never opened because upload's own run already held the claim (T01-8).
-    if (streamErr && streamErr.alreadyRunning) {
-      console.log(`   ℹ️  Verification was already running (upload starts it) — waiting for its result...`);
-    } else if (streamErr && (streamErr.status === 401 || streamErr.status === 403 || streamErr.status === 404)) {
-      throw streamErr;
-    } else {
-      console.log(`   ⚠️  Stream ended early, polling for result...`);
-    }
-    // SEC-076. This polled `contract.status`, and that column answers a different
-    // question than the one asked here. It is a single slot with nine writers:
-    // funding a SIBLING milestone writes `contractStatusAfterFunding(...)` over
-    // it under `status: { notIn: ["COMPLETED","EXPIRED"] }`, so it fails both
-    // ways. False negative: the pin is overwritten with FUNDED, no terminal value
-    // ever appears, and this loop dies after five minutes on "Timed out waiting
-    // for verification result" for a proof that was in fact decided. False
-    // positive: the contract reads VERIFIED/COMPLETED because ANOTHER milestone
-    // settled, and the builder is handed a verdict that is not their proof's -
-    // `decision` below is derived from it.
-    //
-    // `GET /api/contracts/{id}` returns `milestones: [{ id, status, … }]`, and we
-    // funded a specific one, so the honest read is that row. The contract-level
-    // read is kept only for the legacy population that has no milestone rows at
-    // all (proofs written via the contractId-only path).
-    //
-    // EXPIRED is terminal too. Since 2026-09-23 `/api/verify` no longer reopens a
-    // milestone that went EXPIRED while its panel ran, so without it this loop polled a
-    // closed row for five minutes and then threw "Timed out" — and it must never be
-    // mapped to a YES: the milestone moved no funds through this verification.
-    const TERMINAL_PROOF_STATES = ["VERIFIED", "COMPLETED", "REJECTED", "PENDING_REVIEW", "EXPIRED"];
-    for (let i = 0; i < 60; i++) {
-      await new Promise((r) => setTimeout(r, 5000));
-      let contract;
-      try {
-        contract = await apiGet(`/api/contracts/${joined.contractId}`);
-      } catch (e) {
-        // 401/403/404 do not change by waiting; anything else is transient. One
-        // dropped poll used to end the whole run.
-        if (e && (e.status === 401 || e.status === 403 || e.status === 404)) throw e;
-        continue;
-      }
-      const mine = (contract.milestones ?? []).find((m) => m.id === fundedMilestoneId);
-      const observed = mine ? mine.status : (contract.milestones ?? []).length === 0 ? contract.status : null;
-      if (observed && TERMINAL_PROOF_STATES.includes(observed)) {
-        if (observed === "EXPIRED") {
-          // No verdict is read on this path: the stream that carried it dropped, and
-          // the row says only that it is closed.
-          result = { decision: null, confidence: 0, action: "EXPIRED", milestoneClosed: true };
-          console.log(`   ✓ Got result via polling: ${observed}`);
-          break;
-        }
-        const decision = ["VERIFIED", "COMPLETED"].includes(observed) ? "YES" : "NO";
-        result = { decision, confidence: 0, action: observed };
-        console.log(`   ✓ Got result via polling: ${observed}`);
-        break;
-      }
-    }
-    if (!result) throw new Error("Timed out waiting for verification result");
-  }
-
-  // SEC-055/058/059. This re-implemented the three-tier rule from the PROOF's verdict
-  // (`decision === "YES" && confidence >= 85`), so `COMPLETED`, `SUPERSEDED`, a
-  // compliance block and a release hold all printed "✅ VERIFIED", and a panel outage
-  // (`decision: "PENDING"`, confidence 0) printed "❌ NOT VERIFIED — 0% confidence" —
-  // our own outage read back to the builder as a rejection of their work.
-  //
-  // `passed` now means FUNDS MOVED, and only `COMPLETED` says that. The polling
-  // fallback above already derives `action` from the funded MILESTONE's status
-  // (SEC-076; it read the contract row until 2026-09-22), so both paths reach this
-  // with the same vocabulary.
-  const released = result.action === "COMPLETED";
-  const passed = released;
-  console.log(`\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
-  if (result.milestoneClosed === true && result.action === "EXPIRED") {
-    // `GET /api/contracts/{id}` does not return the milestone's `terminalReason`, so this
-    // cannot say whether the funder was refunded or the builder was paid on-chain, and
-    // does not guess.
-    console.log(
-      `⛔ CLOSED — the milestone was closed (EXPIRED) while the panel ran or after it decided, so this verification moved no funds. ` +
-        `The reason is not available here — check the contract page before assuming where the funds are. Do not resubmit to it.`
-    );
-  } else if (result.action === "SUPERSEDED") {
-    console.log(
-      result.settledAs
-        ? `ℹ️ SUPERSEDED — this milestone was closed (${result.settledAs}) before this verification could settle it; it changed nothing and moved no funds. Do not resubmit to it.`
-        : `ℹ️ SUPERSEDED — another proof on this milestone was decided first; this changed nothing.`
-    );
-  } else if (released) {
-    console.log(
-      result.alreadyReleased === true
-        ? `✅ COMPLETED — already released by another request. The funds are out; do not resubmit.`
-        : `✅ COMPLETED — ${result.confidence}% confidence, funds released.`
-    );
-  } else if (result.complianceBlocked === true) {
-    console.log(`⏸️ VERIFIED — payout on hold pending compliance review. No funds moved.`);
-  } else if (result.releaseHoldUntil) {
-    console.log(`⏸️ VERIFIED — approved, payout scheduled for ${result.releaseHoldUntil}. NO FUNDS HAVE MOVED YET.`);
-  } else if (result.action === "VERIFIED") {
-    console.log(`⚠️ VERIFIED — approved, but the automatic payout did NOT go through. No funds moved.`);
-  } else if (result.timedOut === true) {
-    console.log(`⏳ PENDING_REVIEW — the panel did not answer (too few models). NOT a rejection; a human decides.`);
-  } else if (result.action === "PENDING_REVIEW") {
-    console.log(`⏳ PENDING_REVIEW — ${result.confidence}% confidence, manual review required.`);
-  } else if (result.action === "REJECTED") {
-    console.log(`❌ REJECTED — ${result.confidence}% confidence.`);
-  } else {
-    console.log(`⚠️ Outcome not recognised by this version (action: ${result.action}). No conclusion drawn.`);
-  }
-  console.log(`   Decision: ${result.decision ?? "none read (the stream dropped before it)"}`);
-  console.log(`   View contract: ${BASE_URL}/contract/${invite.contractId}`);
-  console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
-}
-
-async function getAgentId() {
-  const data = await apiGet("/api/agent/me");
-  return data.agentId;
-}
-
-async function main() {
-  const agentId = await getAgentId();
-  console.log(`\n🤖 Cascrow Builder Agent started`);
-  console.log(`   Agent ID: ${agentId}`);
-  console.log(`   Share this ID with the Requester agent`);
-  console.log(`   Polling for work every ${POLL_INTERVAL_MS / 1000}s...\n`);
-
-  // Register EVM wallet address so Requester can fund real escrow to this agent.
-  //
-  // POST /api/user/wallet proves key possession: it wants a challenge token from
-  // GET /api/user/wallet/challenge plus a signature over the nonce it carries.
-  // This CLI is deliberately dependency-free and Node's crypto cannot produce an
-  // EIP-191 signature (no keccak256, no recovery id), so it cannot complete that
-  // flow on its own — and posting the address alone has been answered with 400
-  // since the check went in. Say so plainly instead of warning past it: a
-  // builder whose wallet is not linked is not discoverable and cannot be paid,
-  // which is worth more than one line of yellow text.
-  if (AGENT_EVM_WALLET) {
-    try {
-      await apiPost("/api/user/wallet", { walletAddress: AGENT_EVM_WALLET });
-      console.log(`   💳 EVM wallet registered: ${AGENT_EVM_WALLET}\n`);
-    } catch (e) {
-      console.warn(
-        `   ⚠️  Wallet NOT linked (${e.message}).\n` +
-          `      ${AGENT_EVM_WALLET} is unusable until it is: escrow cannot be funded to it\n` +
-          `      and this agent will not appear in /api/agent/discover.\n` +
-          `      Link it once, from a signer that holds the key:\n` +
-          `        1. GET  ${BASE_URL}/api/user/wallet/challenge   (Bearer <your API key>)\n` +
-          `        2. sign the nonce in the returned token with the wallet's key\n` +
-          `        3. POST ${BASE_URL}/api/user/wallet { walletAddress, signature, token }\n`
-      );
-    }
-  }
-
-  while (true) {
-    try {
-      const data = await apiGet("/api/agent/pending-invites");
-      const invites = data.invites ?? [];
-      for (const invite of invites) {
-        await handleInvite(invite);
-      }
-    } catch (err) {
-      console.error(`[poll error] ${err.message}`);
-    }
-    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
-  }
-}
-
-main().catch((err) => {
-  console.error("Fatal:", err.message);
-  process.exit(1);
-});