coherence-cli 0.4.1 → 0.6.1

package/README.md

@@ -59,6 +59,39 @@ cc fork <id>      # Fork an idea and take it a new direction
 cc contribute     # Record any contribution (code, docs, review, design, community)
 ```
 
+### Tasks — agent-to-agent work protocol
+
+AI agents and human contributors use the same task queue. Pick up work, execute it, report back.
+
+```bash
+cc tasks              # See what's pending
+cc tasks running      # See what's in progress
+cc task next          # Claim the highest-priority pending task
+cc task <id>          # View task detail (direction, idea link, context)
+cc task claim <id>    # Claim a specific task
+cc task report <id> completed "All tests pass"   # Report success
+cc task report <id> failed "Missing dependency"   # Report failure
+cc task seed <idea-id> spec   # Create a spec task from an idea
+```
+
+When piped (non-TTY), `cc task next` outputs raw JSON — so an AI agent can parse it programmatically:
+
+```bash
+TASK=$(cc task next 2>/dev/null | tail -1)
+# Agent processes the task...
+cc task report $(echo $TASK | jq -r .id) completed "Done"
+```
+
+### Federation — multi-node coordination
+
+```bash
+cc nodes                          # See all federation nodes (status, providers, last seen)
+cc msg broadcast "Update ready"   # Broadcast to all nodes
+cc msg <node_id> "Run tests"      # Message a specific node
+cc cmd <node> diagnose            # Send a structured command
+cc inbox                          # Read your messages
+```
+
 ### Identity — bring your own
 
 Link any identity you already have. No new accounts. 37 providers across 6 categories.
@@ -146,21 +179,42 @@ Config is stored in `~/.coherence-network/config.json`.
 
 ```
 cc help                           Show all commands
+
+# Explore
 cc ideas [limit]                  Browse ideas by ROI
 cc idea <id>                      View idea detail with scores
+cc idea create <id> <name>        Create a new idea
 cc specs [limit]                  List feature specs
 cc spec <id>                      View spec detail
-cc share                          Submit a new idea
+cc resonance                      What's alive right now
+cc status                         Network health + node info
+
+# Contribute
+cc share                          Submit a new idea (interactive)
 cc stake <id> <cc>                Stake CC on an idea
 cc fork <id>                      Fork an idea
 cc contribute                     Record any contribution
-cc resonance                      What's alive right now
-cc status                         Network health + node info
+
+# Tasks (agent-to-agent)
+cc tasks [status] [limit]         List tasks (pending|running|completed)
+cc task <id>                      View task detail
+cc task next                      Claim next pending task
+cc task claim <id>                Claim a specific task
+cc task report <id> <status> [output]  Report result
+cc task seed <idea> [type]        Create task from idea
+
+# Identity
 cc identity                       Show linked accounts
 cc identity setup                 Guided identity onboarding
 cc identity link <provider> <id>  Link a provider identity
 cc identity unlink <provider>     Unlink a provider
 cc identity lookup <provider> <id> Find contributor by identity
+
+# Federation
+cc nodes                          List federation nodes
+cc msg <node|broadcast> <text>    Send message to a node
+cc cmd <node> <command>           Send structured command
+cc inbox                          Read your messages
 ```
 
 ---

package/README.template.md

@@ -52,6 +52,39 @@ cc fork <id>      # Fork an idea and take it a new direction
 cc contribute     # Record any contribution (code, docs, review, design, community)
 ```
 
+### Tasks — agent-to-agent work protocol
+
+AI agents and human contributors use the same task queue. Pick up work, execute it, report back.
+
+```bash
+cc tasks              # See what's pending
+cc tasks running      # See what's in progress
+cc task next          # Claim the highest-priority pending task
+cc task <id>          # View task detail (direction, idea link, context)
+cc task claim <id>    # Claim a specific task
+cc task report <id> completed "All tests pass"   # Report success
+cc task report <id> failed "Missing dependency"   # Report failure
+cc task seed <idea-id> spec   # Create a spec task from an idea
+```
+
+When piped (non-TTY), `cc task next` outputs raw JSON — so an AI agent can parse it programmatically:
+
+```bash
+TASK=$(cc task next 2>/dev/null | tail -1)
+# Agent processes the task...
+cc task report $(echo $TASK | jq -r .id) completed "Done"
+```
+
+### Federation — multi-node coordination
+
+```bash
+cc nodes                          # See all federation nodes (status, providers, last seen)
+cc msg broadcast "Update ready"   # Broadcast to all nodes
+cc msg <node_id> "Run tests"      # Message a specific node
+cc cmd <node> diagnose            # Send a structured command
+cc inbox                          # Read your messages
+```
+
 ### Identity — bring your own
 
 Link any identity you already have. No new accounts. 37 providers across 6 categories.
@@ -126,21 +159,42 @@ Config is stored in `~/.coherence-network/config.json`.
 
 ```
 cc help                           Show all commands
+
+# Explore
 cc ideas [limit]                  Browse ideas by ROI
 cc idea <id>                      View idea detail with scores
+cc idea create <id> <name>        Create a new idea
 cc specs [limit]                  List feature specs
 cc spec <id>                      View spec detail
-cc share                          Submit a new idea
+cc resonance                      What's alive right now
+cc status                         Network health + node info
+
+# Contribute
+cc share                          Submit a new idea (interactive)
 cc stake <id> <cc>                Stake CC on an idea
 cc fork <id>                      Fork an idea
 cc contribute                     Record any contribution
-cc resonance                      What's alive right now
-cc status                         Network health + node info
+
+# Tasks (agent-to-agent)
+cc tasks [status] [limit]         List tasks (pending|running|completed)
+cc task <id>                      View task detail
+cc task next                      Claim next pending task
+cc task claim <id>                Claim a specific task
+cc task report <id> <status> [output]  Report result
+cc task seed <idea> [type]        Create task from idea
+
+# Identity
 cc identity                       Show linked accounts
 cc identity setup                 Guided identity onboarding
 cc identity link <provider> <id>  Link a provider identity
 cc identity unlink <provider>     Unlink a provider
 cc identity lookup <provider> <id> Find contributor by identity
+
+# Federation
+cc nodes                          List federation nodes
+cc msg <node|broadcast> <text>    Send message to a node
+cc cmd <node> <command>           Send structured command
+cc inbox                          Read your messages
 ```
 
 ---

package/bin/cc.mjs

@@ -7,12 +7,46 @@
  * Zero dependencies. Node 18+ required.
  */
 
+import { createRequire } from "node:module";
 import { listIdeas, showIdea, shareIdea, stakeOnIdea, forkIdea, createIdea } from "../lib/commands/ideas.mjs";
 import { listSpecs, showSpec } from "../lib/commands/specs.mjs";
 import { contribute } from "../lib/commands/contribute.mjs";
 import { showStatus, showResonance } from "../lib/commands/status.mjs";
 import { showIdentity, linkIdentity, unlinkIdentity, lookupIdentity, setupIdentity, setIdentity } from "../lib/commands/identity.mjs";
-import { listNodes, sendMessage, readMessages } from "../lib/commands/nodes.mjs";
+import { listNodes, sendMessage, readMessages, sendCommand } from "../lib/commands/nodes.mjs";
+import { listTasks, showTask, claimTask, claimNext, reportTask, seedTask } from "../lib/commands/tasks.mjs";
+
+// Version check — non-blocking, runs in background
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const LOCAL_VERSION = pkg.version;
+
+async function checkForUpdate() {
+  try {
+    const resp = await fetch("https://registry.npmjs.org/coherence-cli/latest", {
+      signal: AbortSignal.timeout(3000),
+    });
+    if (!resp.ok) return;
+    const data = await resp.json();
+    const latest = data.version;
+    if (latest && latest !== LOCAL_VERSION && latest > LOCAL_VERSION) {
+      console.log(
+        `\n\x1b[33m  Update available: ${LOCAL_VERSION} → ${latest} — auto-updating...\x1b[0m`,
+      );
+      const { execSync } = await import("node:child_process");
+      try {
+        execSync(`npm i -g coherence-cli@${latest}`, { stdio: "pipe" });
+        console.log(`\x1b[32m  ✓ Updated to v${latest}\x1b[0m\n`);
+      } catch {
+        console.log(`\x1b[31m  ✗ Auto-update failed. Run: npm i -g coherence-cli@${latest}\x1b[0m\n`);
+      }
+    }
+  } catch {
+    // Silent — don't block the CLI for a version check
+  }
+}
+
+const updateCheck = checkForUpdate();
 
 const [command, ...args] = process.argv.slice(2);
 
@@ -30,8 +64,13 @@ const COMMANDS = {
   identity:   () => handleIdentity(args),
   nodes:      () => listNodes(),
   msg:        () => sendMessage(args),
+  cmd:        () => sendCommand(args),
   messages:   () => readMessages(args),
   inbox:      () => readMessages(args),
+  tasks:      () => listTasks(args),
+  task:       () => handleTask(args),
+  update:     () => selfUpdate(),
+  version:    () => console.log(`cc v${LOCAL_VERSION}`),
   help:       () => showHelp(),
 };
 
@@ -40,6 +79,17 @@ async function handleIdea(args) {
   return showIdea(args);
 }
 
+async function handleTask(args) {
+  const sub = args[0];
+  switch (sub) {
+    case "next":    return claimNext();
+    case "claim":   return claimTask(args.slice(1));
+    case "report":  return reportTask(args.slice(1));
+    case "seed":    return seedTask(args.slice(1));
+    default:        return showTask(args);
+  }
+}
+
 async function handleIdentity(args) {
   const sub = args[0];
   const subArgs = args.slice(1);
@@ -53,6 +103,29 @@ async function handleIdentity(args) {
   }
 }
 
+async function selfUpdate() {
+  const { execSync } = await import("node:child_process");
+  console.log(`Current: v${LOCAL_VERSION}`);
+  console.log("Checking npm for latest version...");
+  try {
+    const resp = await fetch("https://registry.npmjs.org/coherence-cli/latest", {
+      signal: AbortSignal.timeout(5000),
+    });
+    const data = await resp.json();
+    const latest = data.version;
+    if (latest === LOCAL_VERSION) {
+      console.log(`\x1b[32m✓\x1b[0m Already on latest version (${LOCAL_VERSION})`);
+      return;
+    }
+    console.log(`Updating ${LOCAL_VERSION} → ${latest}...`);
+    execSync(`npm i -g coherence-cli@${latest}`, { stdio: "inherit" });
+    console.log(`\x1b[32m✓\x1b[0m Updated to v${latest}`);
+  } catch (e) {
+    console.error(`\x1b[31m✗\x1b[0m Update failed: ${e.message}`);
+    console.log("  Manual: npm i -g coherence-cli@latest");
+  }
+}
+
 function showHelp() {
   console.log(`
 \x1b[1mcc\x1b[0m — Coherence Network CLI
@@ -83,11 +156,25 @@ function showHelp() {
   identity unlink <p>     Unlink a provider
   identity lookup <p> <id> Find contributor by identity
 
+\x1b[1mTasks (agent-to-agent):\x1b[0m
+  tasks [status] [limit]  List tasks (pending|running|completed)
+  task <id>               View task detail
+  task next               Claim next pending task (for AI agents)
+  task claim <id>         Claim a specific task
+  task report <id> <status> [output]  Report result (completed|failed)
+  task seed <idea> [type] Create task from idea (spec|test|impl|review)
+
 \x1b[1mFederation:\x1b[0m
   nodes                   List federation nodes
   msg <node|broadcast> <text>  Send message to a node
+  cmd <node> <command>    Remote command (update|status|diagnose|restart|ping)
   inbox                   Read your messages
 
+\x1b[1mSystem:\x1b[0m
+  update                  Self-update to latest npm version
+  version                 Show current version
+  help                    Show this help
+
 \x1b[1mProviders:\x1b[0m
   github, x, discord, telegram, mastodon, bluesky, linkedin, reddit,
   youtube, twitch, instagram, tiktok, gitlab, bitbucket, npm, crates,

package/lib/api.mjs

@@ -51,6 +51,21 @@ export async function post(path, body) {
   }
 }
 
+export async function patch(path, body) {
+  try {
+    const res = await fetch(buildUrl(path), {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
 export async function del(path) {
   try {
     const res = await fetch(buildUrl(path), {

package/lib/commands/nodes.mjs

@@ -1,10 +1,66 @@
 /**
- * Federation node commands: nodes, msg, broadcast
+ * Federation node commands: nodes, msg, cmd, broadcast
  */
 
 import { get, post } from "../api.mjs";
 import { hostname } from "node:os";
 
+/**
+ * Send a remote command to a node.
+ * Usage: cc cmd <node_id_or_name> <command> [...args]
+ * Commands: update, status, diagnose, restart, ping
+ */
+export async function sendCommand(args) {
+  if (args.length < 2) {
+    console.log("Usage: cc cmd <node_id_or_name> <command>");
+    console.log("Commands: update, status, diagnose, restart, ping");
+    return;
+  }
+
+  const [target, command, ...cmdArgs] = args;
+
+  // Resolve target: could be node_id prefix or hostname
+  const nodes = await get("/api/federation/nodes");
+  const node = nodes?.find(
+    (n) =>
+      n.node_id?.startsWith(target) ||
+      n.hostname?.toLowerCase().includes(target.toLowerCase()),
+  );
+  if (!node) {
+    console.log(`Node not found: ${target}`);
+    console.log("Available nodes:");
+    for (const n of nodes || []) {
+      console.log(`  ${n.node_id?.slice(0, 12)}  ${n.hostname}`);
+    }
+    return;
+  }
+
+  const myNodeId = nodes?.find(
+    (n) => n.hostname === hostname(),
+  )?.node_id || "unknown";
+
+  console.log(
+    `Sending \x1b[1m${command}\x1b[0m to \x1b[1m${node.hostname}\x1b[0m (${node.node_id?.slice(0, 12)})...`,
+  );
+
+  const result = await post(`/api/federation/nodes/${myNodeId}/messages`, {
+    from_node: myNodeId,
+    to_node: node.node_id,
+    type: "command",
+    text: `Remote command: ${command} ${cmdArgs.join(" ")}`.trim(),
+    payload: { command, args: cmdArgs },
+  });
+
+  if (result?.id) {
+    console.log(`\x1b[32m✓\x1b[0m Command sent (msg ${result.id.slice(0, 12)})`);
+    console.log(
+      "  Node will execute on next poll cycle (~2 min) and reply.",
+    );
+  } else {
+    console.log("\x1b[31m✗\x1b[0m Failed to send command");
+  }
+}
+
 export async function listNodes() {
   const nodes = await get("/api/federation/nodes");
   if (!nodes || !Array.isArray(nodes)) {

package/lib/commands/tasks.mjs

@@ -0,0 +1,198 @@
+/**
+ * Task commands: list, claim, report, next
+ *
+ * This is the agent-to-agent work protocol. An AI agent (Claude, Codex,
+ * Cursor, Gemini) can:
+ *   cc tasks              — see what's pending/running
+ *   cc task next          — claim the highest-priority pending task
+ *   cc task <id>          — view task detail
+ *   cc task claim <id>    — claim a specific task
+ *   cc task report <id> <status> [output] — report result
+ *   cc task seed <idea>   — create a task from an idea
+ */
+
+import { get, post, patch } from "../api.mjs";
+import { hostname } from "node:os";
+import { createHash } from "node:crypto";
+
+function nodeId() {
+  return createHash("sha256").update(hostname()).digest("hex").slice(0, 16);
+}
+
+export async function listTasks(args) {
+  const status = args[0] || "pending";
+  const limit = parseInt(args[1]) || 10;
+  const data = await get("/api/agent/tasks", { status, limit });
+  const tasks = data?.tasks || (Array.isArray(data) ? data : []);
+
+  console.log();
+  console.log(`\x1b[1m  TASKS\x1b[0m (${status}, ${tasks.length})`)
+  console.log(`  ${"─".repeat(60)}`);
+
+  if (!tasks.length) {
+    console.log(`  No ${status} tasks.`);
+    return;
+  }
+
+  for (const t of tasks) {
+    const type = (t.type || t.phase || "?").padEnd(7);
+    const age = t.created_at ? timeSince(t.created_at) : "?";
+    const dir = (t.direction || t.description || "").slice(0, 50);
+    const ctx = t.context || {};
+    const ideaId = ctx.idea_id || "";
+    const statusMark = t.status === "running" ? "\x1b[33m▸\x1b[0m" :
+                       t.status === "completed" ? "\x1b[32m✓\x1b[0m" :
+                       t.status === "failed" ? "\x1b[31m✗\x1b[0m" : "\x1b[2m○\x1b[0m";
+
+    console.log(`  ${statusMark} ${type} \x1b[2m${age}\x1b[0m  ${dir}`);
+    if (ideaId) console.log(`    \x1b[2midea: ${ideaId}\x1b[0m`);
+  }
+  console.log();
+}
+
+export async function showTask(args) {
+  const id = args[0];
+  if (!id) {
+    console.log("Usage: cc task <id>");
+    return;
+  }
+  const t = await get(`/api/agent/tasks/${id}`);
+  if (!t) {
+    console.log(`Task not found: ${id}`);
+    return;
+  }
+
+  console.log();
+  console.log(`\x1b[1m  TASK ${t.id}\x1b[0m`);
+  console.log(`  ${"─".repeat(60)}`);
+  console.log(`  Status:    ${t.status}`);
+  console.log(`  Type:      ${t.type || t.phase || "?"}`);
+  console.log(`  Direction: ${(t.direction || t.description || "").slice(0, 200)}`);
+  if (t.context?.idea_id) console.log(`  Idea:      ${t.context.idea_id}`);
+  if (t.worker_id) console.log(`  Worker:    ${t.worker_id}`);
+  if (t.result) console.log(`  Result:    ${String(t.result).slice(0, 200)}`);
+  console.log();
+}
+
+export async function claimTask(args) {
+  const id = args[0];
+  if (!id) {
+    // Claim next available
+    return claimNext();
+  }
+
+  const nid = nodeId();
+  const result = await patch(`/api/agent/tasks/${id}`, {
+    status: "running",
+    worker_id: `${hostname()}:cc-cli`,
+  });
+
+  if (result) {
+    console.log(`\x1b[32m✓\x1b[0m Claimed task ${id}`);
+    console.log(`  Type: ${result.type || result.phase || "?"}`);
+    console.log(`  Direction: ${(result.direction || result.description || "").slice(0, 150)}`);
+  } else {
+    console.log(`\x1b[31m✗\x1b[0m Failed to claim task ${id}`);
+  }
+}
+
+export async function claimNext() {
+  const data = await get("/api/agent/tasks", { status: "pending", limit: 1 });
+  const tasks = data?.tasks || (Array.isArray(data) ? data : []);
+
+  if (!tasks.length) {
+    console.log("No pending tasks available.");
+    return null;
+  }
+
+  const task = tasks[0];
+  const result = await patch(`/api/agent/tasks/${task.id}`, {
+    status: "running",
+    worker_id: `${hostname()}:cc-cli`,
+  });
+
+  if (result) {
+    console.log(`\x1b[32m✓\x1b[0m Claimed next task: ${task.id}`);
+    console.log(`  Type: ${task.type || task.phase || "?"}`);
+    console.log(`  Direction: ${(task.direction || task.description || "").slice(0, 150)}`);
+    // Output JSON for machine consumption when piped
+    if (!process.stdout.isTTY) {
+      console.log(JSON.stringify(task));
+    }
+    return task;
+  } else {
+    console.log(`\x1b[31m✗\x1b[0m Failed to claim task ${task.id}`);
+    return null;
+  }
+}
+
+export async function reportTask(args) {
+  const [id, status, ...outputParts] = args;
+  const output = outputParts.join(" ");
+
+  if (!id || !status) {
+    console.log("Usage: cc task report <id> <completed|failed> [output text]");
+    return;
+  }
+
+  if (!["completed", "failed"].includes(status)) {
+    console.log(`Status must be 'completed' or 'failed', got: ${status}`);
+    return;
+  }
+
+  const result = await patch(`/api/agent/tasks/${id}`, {
+    status,
+    result: output || `Task ${status} by ${hostname()}`,
+  });
+
+  if (result) {
+    const mark = status === "completed" ? "\x1b[32m✓\x1b[0m" : "\x1b[31m✗\x1b[0m";
+    console.log(`${mark} Reported task ${id} as ${status}`);
+  } else {
+    console.log(`\x1b[31m✗\x1b[0m Failed to report task ${id}`);
+  }
+}
+
+export async function seedTask(args) {
+  const [ideaId, type] = args;
+  const taskType = type || "spec";
+
+  if (!ideaId) {
+    console.log("Usage: cc task seed <idea_id> [spec|test|impl|review]");
+    return;
+  }
+
+  // Fetch idea for context
+  const idea = await get(`/api/ideas/${ideaId}`);
+  if (!idea) {
+    console.log(`Idea not found: ${ideaId}`);
+    return;
+  }
+
+  const result = await post("/api/agent/tasks", {
+    task_type: taskType,
+    direction: `${taskType} for '${idea.name}' (${ideaId})`,
+    context: {
+      idea_id: ideaId,
+      idea_name: idea.name,
+      seeded_by: `${hostname()}:cc-cli`,
+    },
+  });
+
+  if (result?.id) {
+    console.log(`\x1b[32m✓\x1b[0m Seeded ${taskType} task: ${result.id}`);
+    console.log(`  Idea: ${idea.name}`);
+  } else {
+    console.log(`\x1b[31m✗\x1b[0m Failed to seed task`);
+  }
+}
+
+function timeSince(iso) {
+  const ms = Date.now() - new Date(iso).getTime();
+  const min = Math.floor(ms / 60000);
+  if (min < 1) return "now";
+  if (min < 60) return `${min}m`;
+  const hrs = Math.floor(min / 60);
+  if (hrs < 24) return `${hrs}h`;
+  return `${Math.floor(hrs / 24)}d`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "coherence-cli",
-  "version": "0.4.1",
-  "description": "Coherence Network CLI — trace ideas from inception to payout, with fair attribution, coherence scoring, and 37 identity providers. No signup needed.",
+  "version": "0.6.1",
+  "description": "Coherence Network CLI \u2014 trace ideas from inception to payout, with fair attribution, coherence scoring, and 37 identity providers. No signup needed.",
   "type": "module",
   "bin": {
     "cc": "bin/cc.mjs",
@@ -47,4 +47,4 @@
     "url": "https://github.com/seeker71/Coherence-Network/issues"
   },
   "author": "Coherence Network Contributors"
-}
+}