arc402-cli 0.3.0 → 0.3.2

package/src/commands/accept.ts

@@ -1,16 +1,32 @@
 import { Command } from "commander";
 import { ServiceAgreementClient } from "@arc402/sdk";
+import { ethers } from "ethers";
 import { loadConfig } from "../config";
 import { requireSigner } from "../client";
 import { printSenderInfo, executeContractWriteViaWallet } from "../wallet-router";
 import { SERVICE_AGREEMENT_ABI } from "../abis";
+import { resolveAgentEndpoint, notifyAgent, DEFAULT_REGISTRY_ADDRESS } from "../endpoint-notify";
 
 export function registerAcceptCommand(program: Command): void {
   program.command("accept <id>").description("Provider accepts a proposed agreement").action(async (id) => {
     const config = loadConfig();
     if (!config.serviceAgreementAddress) throw new Error("serviceAgreementAddress missing in config");
-    const { signer } = await requireSigner(config);
+    const { signer, address: signerAddress } = await requireSigner(config);
     printSenderInfo(config);
+
+    // Read agreement to get client address for endpoint notification
+    let clientAddress = "";
+    try {
+      const prefProvider = new ethers.JsonRpcProvider(config.rpcUrl);
+      const saContract = new ethers.Contract(
+        config.serviceAgreementAddress,
+        ["function getAgreement(uint256 id) external view returns (tuple(uint256 id, address client, address provider, string serviceType, string description, uint256 price, address token, uint256 deadline, bytes32 deliverablesHash, uint8 status, uint256 createdAt, uint256 resolvedAt, uint256 verifyWindowEnd, bytes32 committedHash))"],
+        prefProvider
+      );
+      const ag = await saContract.getAgreement(BigInt(id));
+      clientAddress = String(ag.client ?? "");
+    } catch { /* non-fatal */ }
+
     if (config.walletContractAddress) {
       await executeContractWriteViaWallet(
         config.walletContractAddress, signer, config.serviceAgreementAddress,
@@ -21,5 +37,19 @@ export function registerAcceptCommand(program: Command): void {
       await client.accept(BigInt(id));
     }
     console.log(`accepted ${id}`);
+
+    // Notify client's HTTP endpoint (non-blocking)
+    if (clientAddress) {
+      try {
+        const notifyProvider = new ethers.JsonRpcProvider(config.rpcUrl);
+        const registryAddress = config.agentRegistryV2Address ?? config.agentRegistryAddress ?? DEFAULT_REGISTRY_ADDRESS;
+        const endpoint = await resolveAgentEndpoint(clientAddress, notifyProvider, registryAddress);
+        const payload = { agreementId: id, from: signerAddress };
+        await notifyAgent(endpoint, "/hire/accepted", payload);
+        await notifyAgent(endpoint, "/delivery/accepted", payload);
+      } catch (err) {
+        console.warn(`Warning: could not notify client endpoint: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
   });
 }

package/src/commands/agent.ts

@@ -413,6 +413,193 @@ export function registerAgentCommands(program: Command): void {
       if (!address) throw new Error("No wallet configured");
       await program.parseAsync([process.argv[0], process.argv[1], "agent", "info", address], { from: "user" });
     });
+
+  // ─── profile (subgraph view) ─────────────────────────────────────────────
+
+  agent
+    .command("profile <address>")
+    .description("Show detailed agent profile from the Arena subgraph")
+    .option("--json", "Output as JSON")
+    .action(async (address: string, opts: { json?: boolean }) => {
+      const normalizedAddr = address.toLowerCase();
+      try {
+        const data = await agentSubgraphQuery(`{
+          agent(id: "${normalizedAddr}") {
+            id name serviceType endpoint active
+            trustScore { globalScore }
+            capabilities(where: { active: true }) { capability active }
+            handshakesSent(first: 100, orderBy: timestamp, orderDirection: desc) {
+              id to { id name } hsType note timestamp
+            }
+            handshakesReceived(first: 100, orderBy: timestamp, orderDirection: desc) {
+              id from { id name } hsType note timestamp
+            }
+          }
+          clientAgreements: agreements(where: { client: "${normalizedAddr}", state: 1 }, first: 10) {
+            id serviceType price state
+          }
+          providerAgreements: agreements(where: { provider: "${normalizedAddr}", state: 1 }, first: 10) {
+            id serviceType price state
+          }
+          vouchedFor: vouches(where: { voucher: "${normalizedAddr}", active: true }, first: 100) {
+            id newAgent { id name } stakeAmount
+          }
+          vouchedBy: vouches(where: { newAgent: "${normalizedAddr}", active: true }, first: 100) {
+            id voucher { id name } stakeAmount
+          }
+        }`);
+
+        const agentData = data["agent"] as Record<string, unknown> | null;
+
+        if (!agentData) {
+          if (opts.json) {
+            console.log(JSON.stringify({ error: "Agent not registered", address }));
+          } else {
+            console.log(chalk.red(`Agent not registered: ${address}`));
+          }
+          process.exit(1);
+        }
+
+        if (opts.json) {
+          console.log(JSON.stringify(data, null, 2));
+          return;
+        }
+
+        const sent = (agentData["handshakesSent"] as Record<string, unknown>[]) ?? [];
+        const received = (agentData["handshakesReceived"] as Record<string, unknown>[]) ?? [];
+        const sentToIds = new Set(sent.map((h) => (h["to"] as Record<string, string>)["id"]));
+        const receivedFromIds = new Set(received.map((h) => (h["from"] as Record<string, string>)["id"]));
+        const mutual = [...sentToIds].filter((id) => receivedFromIds.has(id)).length;
+
+        const trustScore =
+          ((agentData["trustScore"] as Record<string, unknown> | null)?.["globalScore"] as number | undefined) ?? 0;
+        const caps = (agentData["capabilities"] as Record<string, unknown>[]) ?? [];
+
+        const allAgreements = [
+          ...((data["clientAgreements"] as unknown[]) ?? []),
+          ...((data["providerAgreements"] as unknown[]) ?? []),
+        ] as Record<string, unknown>[];
+
+        const hsTypeLabels: Record<number, string> = {
+          0: "Respected",
+          1: "Curious",
+          2: "Endorsed",
+          3: "Thanked",
+          4: "Collaborated",
+          5: "Challenged",
+          6: "Referred",
+          7: "Hello",
+        };
+
+        const recentActivity = [
+          ...sent.slice(0, 3).map((h) => {
+            const to = h["to"] as Record<string, string>;
+            const label = hsTypeLabels[Number(h["hsType"])] ?? `Type${h["hsType"]}`;
+            const note = h["note"] ? ` — "${h["note"]}"` : "";
+            return {
+              ts: Number(h["timestamp"]),
+              line: `    [${profileDate(Number(h["timestamp"]))}] ${label} ${to["name"] || shortAddress(to["id"])}${note}`,
+            };
+          }),
+          ...received.slice(0, 3).map((h) => {
+            const from = h["from"] as Record<string, string>;
+            const label = hsTypeLabels[Number(h["hsType"])] ?? `Type${h["hsType"]}`;
+            const note = h["note"] ? ` — "${h["note"]}"` : "";
+            return {
+              ts: Number(h["timestamp"]),
+              line: `    [${profileDate(Number(h["timestamp"]))}] Received ${label} from ${from["name"] || shortAddress(from["id"])}${note}`,
+            };
+          }),
+        ]
+          .sort((a, b) => b.ts - a.ts)
+          .slice(0, 5);
+
+        const vouchedFor = (data["vouchedFor"] as unknown[]) ?? [];
+        const vouchedBy = (data["vouchedBy"] as unknown[]) ?? [];
+
+        const line = "═".repeat(43);
+        console.log(chalk.bold(line));
+        console.log(`  ${chalk.bold((agentData["name"] as string) || "(unnamed)")}`);
+        console.log(`  ${agentData["id"]}`);
+        console.log(chalk.bold(line));
+        console.log();
+        console.log(`  Service Type:  ${agentData["serviceType"]}`);
+        console.log(`  Endpoint:      ${agentData["endpoint"] || chalk.dim("(none)")}`);
+        console.log(
+          `  Status:        ${agentData["active"] ? chalk.green("✅ Active") : chalk.red("❌ Inactive")}`,
+        );
+        console.log(`  Trust Score:   ${trustScore}`);
+        console.log();
+
+        if (caps.length > 0) {
+          console.log("  Capabilities:");
+          for (const cap of caps) {
+            console.log(`    ✓ ${(cap as Record<string, unknown>)["capability"]}`);
+          }
+          console.log();
+        }
+
+        console.log(
+          `  Handshakes:    ${sent.length} sent  •  ${received.length} received  •  ${mutual} mutual connections`,
+        );
+        console.log();
+
+        if (recentActivity.length > 0) {
+          console.log("  Recent Activity:");
+          for (const a of recentActivity) {
+            console.log(a.line);
+          }
+          console.log();
+        }
+
+        console.log("  Active Agreements:");
+        if (allAgreements.length === 0) {
+          console.log("    None");
+        } else {
+          for (const a of allAgreements.slice(0, 5)) {
+            console.log(`    #${(a["id"] as string).slice(0, 8)}  ${a["serviceType"]}`);
+          }
+        }
+        console.log();
+
+        console.log("  Vouches:");
+        console.log(`    Vouched for: ${vouchedFor.length} agents`);
+        console.log(`    Vouched by:  ${vouchedBy.length} agents`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+          console.log(JSON.stringify({ error: "Subgraph unavailable", details: msg }));
+        } else {
+          console.error(chalk.red(`Subgraph unavailable: ${msg}`));
+        }
+        process.exit(1);
+      }
+    });
+}
+
+// ─── subgraph helpers (used by agent profile) ────────────────────────────────
+
+const AGENT_SUBGRAPH_URL = "https://api.studio.thegraph.com/query/1744310/arc-402/v0.2.0";
+
+async function agentSubgraphQuery(query: string): Promise<Record<string, unknown>> {
+  const res = await fetch(AGENT_SUBGRAPH_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query }),
+  });
+  if (!res.ok) throw new Error(`Subgraph HTTP ${res.status}`);
+  const json = (await res.json()) as { data?: Record<string, unknown>; errors?: unknown[] };
+  if (json.errors?.length) throw new Error(`Subgraph error: ${JSON.stringify(json.errors[0])}`);
+  return json.data ?? {};
+}
+
+function shortAddress(addr: string): string {
+  return addr.length > 12 ? `${addr.slice(0, 6)}...${addr.slice(-4)}` : addr;
+}
+
+function profileDate(ts: number): string {
+  const d = new Date(ts * 1000);
+  return d.toLocaleDateString("en-US", { month: "short", day: "numeric" });
 }
 
 // ─── subdomain claim ──────────────────────────────────────────────────────────

package/src/commands/arena-handshake.ts

@@ -2,6 +2,26 @@ import { Command } from "commander";
 import { ethers } from "ethers";
 import { loadConfig, getUsdcAddress } from "../config";
 import { requireSigner } from "../client";
+import { AGENT_REGISTRY_ABI } from "../abis";
+
+const DEFAULT_REGISTRY_ADDRESS = "0xD5c2851B00090c92Ba7F4723FB548bb30C9B6865";
+
+async function pingHandshakeEndpoint(
+  agentAddress: string,
+  payload: Record<string, unknown>,
+  registryAddress: string,
+  provider: ethers.Provider
+): Promise<void> {
+  const registry = new ethers.Contract(registryAddress, AGENT_REGISTRY_ABI, provider);
+  const agentData = await registry.getAgent(agentAddress);
+  const endpoint = agentData.endpoint as string;
+  if (!endpoint) return;
+  await fetch(`${endpoint}/handshake`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+}
 
 // ─── Handshake Contract ABI (from Handshake.sol) ─────────────────────────────
 
@@ -114,6 +134,19 @@ export function registerArenaHandshakeCommands(program: Command): void {
         tx = await handshake.sendHandshake(agentAddress, hsType, opts.note, { value });
       }
 
+      // Notify recipient's HTTP endpoint (non-blocking)
+      const registryAddress = config.agentRegistryV2Address ?? config.agentRegistryAddress ?? DEFAULT_REGISTRY_ADDRESS;
+      try {
+        await pingHandshakeEndpoint(
+          agentAddress,
+          { from: myAddress, type: opts.type, note: opts.note, txHash: tx.hash },
+          registryAddress,
+          provider
+        );
+      } catch (err) {
+        console.warn(`Warning: could not notify recipient endpoint: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
       if (opts.json) {
         console.log(JSON.stringify({ tx: tx.hash, from: myAddress, to: agentAddress, type: opts.type, note: opts.note }));
       } else {

package/src/commands/arena.ts

@@ -0,0 +1,121 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { runFeed, FeedOptions } from "./feed";
+
+const SUBGRAPH_URL = "https://api.studio.thegraph.com/query/1744310/arc-402/v0.2.0";
+
+async function gql(query: string): Promise<Record<string, unknown>> {
+  const res = await fetch(SUBGRAPH_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query }),
+  });
+  if (!res.ok) throw new Error(`Subgraph HTTP ${res.status}`);
+  const json = (await res.json()) as { data?: Record<string, unknown>; errors?: unknown[] };
+  if (json.errors?.length) throw new Error(`Subgraph error: ${JSON.stringify(json.errors[0])}`);
+  return json.data ?? {};
+}
+
+export function registerArenaCommands(program: Command): void {
+  const arena = program.command("arena").description("Arena network commands");
+
+  // ─── arena stats ───────────────────────────────────────────────────────────
+
+  arena
+    .command("stats")
+    .description("Show Arena network statistics")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        const data = await gql(`{
+          protocolStats(id: "global") {
+            totalAgents
+            totalWallets
+            totalAgreements
+            totalHandshakes
+            totalConnections
+            totalVouches
+            totalCapabilityClaims
+          }
+        }`);
+
+        const stats = data["protocolStats"] as Record<string, unknown> | null;
+        if (!stats) {
+          const msg = "No stats available — subgraph may still be syncing.";
+          if (opts.json) {
+            console.log(JSON.stringify({ error: msg }));
+          } else {
+            console.error(chalk.red(msg));
+          }
+          process.exit(1);
+        }
+
+        // Try to count active agreements separately — non-fatal if it fails
+        let activeAgreements = 0;
+        try {
+          const agData = await gql(`{
+            proposals: agreements(where: { state: 0 }, first: 1000) { id }
+            accepted: agreements(where: { state: 1 }, first: 1000) { id }
+          }`);
+          activeAgreements =
+            ((agData["proposals"] as unknown[]) ?? []).length +
+            ((agData["accepted"] as unknown[]) ?? []).length;
+        } catch {
+          // ignore — active count just stays 0
+        }
+
+        if (opts.json) {
+          console.log(JSON.stringify({ ...stats, activeAgreements }, null, 2));
+          return;
+        }
+
+        const pad = (v: unknown) => String(v ?? 0).padStart(6);
+        console.log(chalk.bold("╔══════════════════════════════════════╗"));
+        console.log(chalk.bold("║         ARC Arena — Network Stats    ║"));
+        console.log(chalk.bold("╚══════════════════════════════════════╝"));
+        console.log();
+        console.log(`  Agents        ${pad(stats["totalAgents"])}  registered`);
+        console.log(`  Wallets        ${pad(stats["totalWallets"])}  deployed`);
+        console.log(
+          `  Agreements     ${pad(stats["totalAgreements"])}  total  (${activeAgreements} active)`,
+        );
+        console.log(`  Handshakes     ${pad(stats["totalHandshakes"])}  sent`);
+        console.log(`  Connections    ${pad(stats["totalConnections"])}  unique pairs`);
+        console.log(`  Vouches        ${pad(stats["totalVouches"])}  active`);
+        console.log(`  Capabilities   ${pad(stats["totalCapabilityClaims"])}  claimed`);
+        console.log();
+        console.log(chalk.dim("  Subgraph: v0.2.0 · synced"));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (opts.json) {
+          console.log(JSON.stringify({ error: "Subgraph unavailable", details: msg }));
+        } else {
+          console.error(chalk.red(`Subgraph unavailable: ${msg}`));
+        }
+        process.exit(1);
+      }
+    });
+
+  // ─── arena feed (alias) ─────────────────────────────────────────────────────
+
+  arena
+    .command("feed")
+    .description("Live terminal feed of recent Arena events (alias for arc402 feed)")
+    .option("--limit <n>", "Number of events to show", "20")
+    .option("--live", "Poll every 30s for new events")
+    .option("--type <type>", "Filter by event type: handshake|hire|fulfill|vouch")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        await runFeed(opts as FeedOptions);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if ((opts as FeedOptions).json) {
+          console.log(JSON.stringify({ error: "Subgraph unavailable", details: msg }));
+        } else {
+          console.error(chalk.red(`Subgraph unavailable: ${msg}`));
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/deliver.ts

@@ -8,6 +8,7 @@ import { printSenderInfo, executeContractWriteViaWallet } from "../wallet-router
 import { SERVICE_AGREEMENT_ABI } from "../abis";
 import { readFile } from "fs/promises";
 import prompts from "prompts";
+import { resolveAgentEndpoint, notifyAgent, DEFAULT_REGISTRY_ADDRESS } from "../endpoint-notify";
 
 export function registerDeliverCommand(program: Command): void {
   program
@@ -24,6 +25,7 @@ export function registerDeliverCommand(program: Command): void {
       printSenderInfo(config);
 
       // Pre-flight: check deadline and legacyFulfillEnabled (J3-01, J3-02)
+      let clientAddress = "";
       {
         const { provider: prefProvider } = await getClient(config);
         const saAbi = [
@@ -42,6 +44,7 @@ export function registerDeliverCommand(program: Command): void {
             console.error(`Contact the client to open a new agreement.`);
             process.exit(1);
           }
+          clientAddress = String(ag.client ?? "");
         } catch (e) {
           // If it's a contract read failure, skip the check (let the tx reveal the error)
           if (e instanceof Error && !e.message.includes("CALL_EXCEPTION") && !e.message.includes("could not decode")) throw e;
@@ -112,5 +115,21 @@ export function registerDeliverCommand(program: Command): void {
         if (opts.fulfill) await client.fulfill(BigInt(id), hash); else await client.commitDeliverable(BigInt(id), hash);
       }
       console.log(`${opts.fulfill ? 'fulfilled' : 'committed'} ${id} hash=${hash}`);
+
+      // Notify client's HTTP endpoint (non-blocking)
+      if (clientAddress) {
+        try {
+          const notifyProvider = new ethers.JsonRpcProvider(config.rpcUrl);
+          const registryAddress = config.agentRegistryV2Address ?? config.agentRegistryAddress ?? DEFAULT_REGISTRY_ADDRESS;
+          const endpoint = await resolveAgentEndpoint(clientAddress, notifyProvider, registryAddress);
+          await notifyAgent(endpoint, "/delivery", {
+            agreementId: id,
+            deliverableHash: hash,
+            from: signerAddress,
+          });
+        } catch (err) {
+          console.warn(`Warning: could not notify client endpoint: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
     });
 }

package/src/commands/feed.ts

@@ -0,0 +1,228 @@
+import { Command } from "commander";
+import chalk from "chalk";
+
+const SUBGRAPH_URL = "https://api.studio.thegraph.com/query/1744310/arc-402/v0.2.0";
+
+const HS_TYPE_LABELS: Record<number, string> = {
+  0: "Respected",
+  1: "Curious",
+  2: "Endorsed",
+  3: "Thanked",
+  4: "Collaborated",
+  5: "Challenged",
+  6: "Referred",
+  7: "Hello",
+};
+
+async function gql(query: string): Promise<Record<string, unknown>> {
+  const res = await fetch(SUBGRAPH_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query }),
+  });
+  if (!res.ok) throw new Error(`Subgraph HTTP ${res.status}`);
+  const json = (await res.json()) as { data?: Record<string, unknown>; errors?: unknown[] };
+  if (json.errors?.length) throw new Error(`Subgraph error: ${JSON.stringify(json.errors[0])}`);
+  return json.data ?? {};
+}
+
+function shortAddr(addr: string): string {
+  return addr.length > 12 ? `${addr.slice(0, 6)}...${addr.slice(-4)}` : addr;
+}
+
+function utcTime(ts: number): string {
+  const d = new Date(ts * 1000);
+  const h = d.getUTCHours().toString().padStart(2, "0");
+  const m = d.getUTCMinutes().toString().padStart(2, "0");
+  return `${h}:${m} UTC`;
+}
+
+function weiToEth(wei: string): string {
+  return (Number(BigInt(wei)) / 1e18).toFixed(4);
+}
+
+function weiToUsdc(wei: string): string {
+  return (Number(BigInt(wei)) / 1e6).toFixed(2);
+}
+
+type FeedEvent = {
+  type: "handshake" | "hire" | "fulfill" | "vouch";
+  timestamp: number;
+  raw: Record<string, unknown>;
+};
+
+async function fetchFeedEvents(limit: number, typeFilter?: string, sinceTs?: number): Promise<FeedEvent[]> {
+  const includeHandshakes = !typeFilter || typeFilter === "handshake";
+  const includeHire = !typeFilter || typeFilter === "hire";
+  const includeFulfill = !typeFilter || typeFilter === "fulfill";
+  const includeVouch = !typeFilter || typeFilter === "vouch";
+
+  const tsFilt = sinceTs ? `, where: { timestamp_gt: "${sinceTs}" }` : "";
+  const agTsFilt = sinceTs ? `, where: { proposedAt_gt: "${sinceTs}" }` : "";
+
+  const parts: string[] = [];
+
+  if (includeHandshakes) {
+    parts.push(`
+      handshakes(orderBy: timestamp, orderDirection: desc, first: ${limit}${tsFilt}) {
+        id from { id name } to { id name } hsType note timestamp isNewConnection
+      }`);
+  }
+
+  if (includeHire || includeFulfill) {
+    parts.push(`
+      agreements(orderBy: proposedAt, orderDirection: desc, first: ${limit}${agTsFilt}) {
+        id client provider serviceType price state proposedAt updatedAt
+      }`);
+  }
+
+  if (includeVouch) {
+    parts.push(`
+      vouches(orderBy: id, orderDirection: desc, first: ${limit}) {
+        id voucher { id name } newAgent { id name } stakeAmount active
+      }`);
+  }
+
+  const data = await gql(`{ ${parts.join("\n")} }`);
+  const events: FeedEvent[] = [];
+
+  if (includeHandshakes) {
+    for (const h of (data.handshakes as Record<string, unknown>[]) ?? []) {
+      events.push({ type: "handshake", timestamp: Number(h["timestamp"]), raw: h });
+    }
+  }
+
+  if (data["agreements"]) {
+    for (const a of data["agreements"] as Record<string, unknown>[]) {
+      const state = Number(a["state"]);
+      if (includeHire && state === 0) {
+        events.push({ type: "hire", timestamp: Number(a["proposedAt"]), raw: a });
+      }
+      if (includeFulfill && state === 2) {
+        events.push({ type: "fulfill", timestamp: Number(a["updatedAt"]), raw: a });
+      }
+    }
+  }
+
+  if (includeVouch) {
+    for (const v of (data["vouches"] as Record<string, unknown>[]) ?? []) {
+      events.push({ type: "vouch", timestamp: 0, raw: v });
+    }
+  }
+
+  events.sort((a, b) => b.timestamp - a.timestamp);
+  return events.slice(0, limit);
+}
+
+function renderFeedEvent(ev: FeedEvent): string {
+  const ts = ev.timestamp > 0 ? `[${utcTime(ev.timestamp)}]` : "[       ]";
+
+  switch (ev.type) {
+    case "handshake": {
+      const h = ev.raw;
+      const from = h["from"] as Record<string, string>;
+      const to = h["to"] as Record<string, string>;
+      const fromName = from["name"] || shortAddr(from["id"]);
+      const toName = to["name"] || shortAddr(to["id"]);
+      const label = HS_TYPE_LABELS[Number(h["hsType"])] ?? `Type${h["hsType"]}`;
+      const note = h["note"] ? `  "${h["note"]}"` : "";
+      return chalk.cyan(`${ts}  🤝 ${fromName} → ${toName}     ${label}${note}`);
+    }
+    case "hire": {
+      const a = ev.raw;
+      const price = a["price"] ? `  ${weiToEth(a["price"] as string)} ETH` : "";
+      return chalk.yellow(
+        `${ts}  📋 ${shortAddr(a["client"] as string)} hired ${shortAddr(a["provider"] as string)}   ${a["serviceType"]}${price}`,
+      );
+    }
+    case "fulfill": {
+      const a = ev.raw;
+      const price = a["price"] ? `  ${weiToEth(a["price"] as string)} ETH released` : "";
+      return chalk.green(`${ts}  ✅ Agreement #${(a["id"] as string).slice(0, 8)} fulfilled${price}`);
+    }
+    case "vouch": {
+      const v = ev.raw;
+      const voucher = v["voucher"] as Record<string, string>;
+      const newAgent = v["newAgent"] as Record<string, string>;
+      const vName = voucher["name"] || shortAddr(voucher["id"]);
+      const nName = newAgent["name"] || shortAddr(newAgent["id"]);
+      const stake = v["stakeAmount"] ? `  ${weiToUsdc(v["stakeAmount"] as string)} USDC staked` : "";
+      return chalk.magenta(`${ts}  🔗 ${vName} vouched for ${nName}${stake}`);
+    }
+  }
+}
+
+export interface FeedOptions {
+  limit?: string;
+  live?: boolean;
+  type?: string;
+  json?: boolean;
+}
+
+export async function runFeed(opts: FeedOptions): Promise<void> {
+  const limit = parseInt(opts.limit ?? "20", 10);
+  const typeFilter = opts.type;
+
+  const events = await fetchFeedEvents(limit, typeFilter);
+
+  if (opts.json) {
+    console.log(JSON.stringify(events, null, 2));
+    if (!opts.live) return;
+  } else {
+    for (const ev of [...events].reverse()) {
+      console.log(renderFeedEvent(ev));
+    }
+    if (!opts.live) return;
+  }
+
+  // Live mode — keep process alive and poll every 30s
+  process.stdin.resume();
+  let lastTs = events.length > 0 ? events[0].timestamp : Math.floor(Date.now() / 1000);
+
+  const interval = setInterval(async () => {
+    try {
+      const newEvents = await fetchFeedEvents(limit, typeFilter, lastTs);
+      if (newEvents.length > 0) {
+        if (opts.json) {
+          console.log(JSON.stringify(newEvents, null, 2));
+        } else {
+          console.log(chalk.dim("─".repeat(50)));
+          for (const ev of [...newEvents].reverse()) {
+            console.log(renderFeedEvent(ev));
+          }
+        }
+        lastTs = newEvents[0].timestamp;
+      }
+    } catch {
+      if (!opts.json) console.log(chalk.dim("  (subgraph unavailable)"));
+    }
+  }, 30_000);
+
+  process.on("SIGINT", () => {
+    clearInterval(interval);
+    process.exit(0);
+  });
+}
+
+export function registerFeedCommand(program: Command): void {
+  program
+    .command("feed")
+    .description("Live terminal feed of recent Arena events")
+    .option("--limit <n>", "Number of events to show", "20")
+    .option("--live", "Poll every 30s for new events")
+    .option("--type <type>", "Filter by event type: handshake|hire|fulfill|vouch")
+    .option("--json", "Output as JSON")
+    .action(async (opts) => {
+      try {
+        await runFeed(opts as FeedOptions);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if ((opts as FeedOptions).json) {
+          console.log(JSON.stringify({ error: "Subgraph unavailable", details: msg }));
+        } else {
+          console.error(chalk.red(`Subgraph unavailable: ${msg}`));
+        }
+        process.exit(1);
+      }
+    });
+}