agentxchain 0.1.1 → 0.2.0

package/README.md

@@ -58,6 +58,33 @@ For Cursor Cloud Agents, set `CURSOR_API_KEY` in your environment. Without it, t
 
 Stop all running agent sessions. Reads `.agentxchain-session.json` to find active agents.
 
+### `agentxchain config`
+
+View or edit project configuration.
+
+- `--add-agent` — interactively add a new agent
+- `--remove-agent <id>` — remove an agent by ID
+- `--set "<key> <value>"` — update a setting (e.g. `--set "rules.max_consecutive_claims 3"`)
+- `-j, --json` — output config as JSON
+
+Examples:
+
+```bash
+agentxchain config                              # show current config
+agentxchain config --add-agent                  # add a new agent
+agentxchain config --remove-agent ux            # remove the ux agent
+agentxchain config --set "project My New Name"  # change project name
+agentxchain config --set "rules.compress_after_words 8000"
+```
+
+### `agentxchain update`
+
+Update the CLI to the latest version from npm.
+
+```bash
+agentxchain update
+```
+
 ## How it works
 
 AgentXchain uses a **claim-based protocol**:

package/bin/agentxchain.js

@@ -1,28 +1,31 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
-import chalk from 'chalk';
 import { initCommand } from '../src/commands/init.js';
 import { statusCommand } from '../src/commands/status.js';
 import { startCommand } from '../src/commands/start.js';
 import { stopCommand } from '../src/commands/stop.js';
+import { configCommand } from '../src/commands/config.js';
+import { updateCommand } from '../src/commands/update.js';
+import { watchCommand } from '../src/commands/watch.js';
+import { claimCommand, releaseCommand } from '../src/commands/claim.js';
 
 const program = new Command();
 
 program
   .name('agentxchain')
   .description('Multi-agent coordination in your IDE')
-  .version('0.1.0');
+  .version('0.1.1');
 
 program
   .command('init')
-  .description('Initialize a new AgentXchain project')
+  .description('Create a new AgentXchain project folder')
   .option('-y, --yes', 'Skip prompts, use defaults')
   .action(initCommand);
 
 program
   .command('status')
-  .description('Show current lock status, phase, and agents')
+  .description('Show lock status, phase, and agents')
   .option('-j, --json', 'Output as JSON')
   .action(statusCommand);
 
@@ -39,4 +42,35 @@ program
   .description('Stop all running agent sessions')
   .action(stopCommand);
 
+program
+  .command('config')
+  .description('View or edit project configuration')
+  .option('--add-agent', 'Add a new agent interactively')
+  .option('--remove-agent <id>', 'Remove an agent by ID')
+  .option('--set <key_value>', 'Set a config value (e.g. --set "rules.max_consecutive_claims 3")')
+  .option('-j, --json', 'Output config as JSON')
+  .action(configCommand);
+
+program
+  .command('watch')
+  .description('Watch lock.json and coordinate agent turns (the referee)')
+  .option('--daemon', 'Run in background mode')
+  .action(watchCommand);
+
+program
+  .command('claim')
+  .description('Claim the lock as a human (take control)')
+  .option('--force', 'Force-claim even if an agent holds the lock')
+  .action(claimCommand);
+
+program
+  .command('release')
+  .description('Release the lock (hand back to agents)')
+  .action(releaseCommand);
+
+program
+  .command('update')
+  .description('Update agentxchain CLI to the latest version')
+  .action(updateCommand);
+
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "CLI for AgentXchain — multi-agent coordination in your IDE",
   "type": "module",
   "bin": {

package/src/adapters/cursor.js

@@ -1,26 +1,38 @@
+import { writeFileSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
 import chalk from 'chalk';
 import { generateSeedPrompt } from '../lib/seed-prompt.js';
+import { getRepoUrl } from '../lib/repo.js';
 
 const API_BASE = 'https://api.cursor.com/v0';
 
+function authHeaders(apiKey) {
+  return {
+    'Authorization': `Basic ${Buffer.from(apiKey + ':').toString('base64')}`,
+    'Content-Type': 'application/json'
+  };
+}
+
+// --- Public API ---
+
 export async function launchCursorAgents(config, root, opts) {
   const apiKey = process.env.CURSOR_API_KEY;
 
   if (!apiKey) {
-    console.log('');
-    console.log(chalk.yellow('  Cursor Cloud Agents API key not found.'));
-    console.log('');
-    console.log('  To launch agents via Cursor Cloud API:');
-    console.log(`    1. Go to ${chalk.cyan('cursor.com/dashboard')} → Cloud Agents`);
-    console.log('    2. Create an API key');
-    console.log(`    3. Set: ${chalk.bold('export CURSOR_API_KEY=your_key')}`);
-    console.log(`    4. Run: ${chalk.bold('agentxchain start --ide cursor')}`);
-    console.log('');
-    console.log(chalk.dim('  Falling back to seed prompt output...'));
-    console.log('');
+    printApiKeyHelp();
     return fallbackPromptOutput(config, opts);
   }
 
+  const repoUrl = await getRepoUrl(root);
+  if (!repoUrl) {
+    console.log(chalk.red('  Could not detect GitHub repo URL.'));
+    console.log(chalk.dim('  Make sure this project is a git repo with a GitHub remote.'));
+    console.log(chalk.dim('  Or set source.repository manually in agentxchain.json.'));
+    return [];
+  }
+
+  const model = config.cursor?.model || 'default';
+  const ref = config.cursor?.ref || 'main';
   const agents = filterAgents(config, opts.agent);
   const launched = [];
 
@@ -28,51 +40,130 @@ export async function launchCursorAgents(config, root, opts) {
     const prompt = generateSeedPrompt(id, agent, config);
 
     try {
+      const body = {
+        prompt: { text: prompt },
+        source: { repository: repoUrl, ref },
+        target: { autoCreatePr: false }
+      };
+      if (model !== 'default') body.model = model;
+
       const res = await fetch(`${API_BASE}/agents`, {
         method: 'POST',
-        headers: {
-          'Authorization': `Basic ${btoa(apiKey + ':')}`,
-          'Content-Type': 'application/json'
-        },
-        body: JSON.stringify({
-          prompt,
-          repository: root,
-          name: `agentxchain-${id}`
-        })
+        headers: authHeaders(apiKey),
+        body: JSON.stringify(body)
       });
 
       if (!res.ok) {
-        const body = await res.text();
-        console.log(chalk.red(`  Failed to launch ${id}: ${res.status} ${body}`));
+        const errBody = await res.text();
+        console.log(chalk.red(`  ✗ ${id}: ${res.status} ${errBody}`));
         continue;
       }
 
       const data = await res.json();
-      launched.push({ id, name: agent.name, cloudId: data.id || 'unknown' });
-      console.log(chalk.green(`  ✓ Launched ${chalk.bold(id)} (${agent.name}) — cloud ID: ${data.id || '?'}`));
+      launched.push({
+        id,
+        name: agent.name,
+        cloudId: data.id,
+        status: data.status || 'CREATING',
+        url: data.target?.url || null
+      });
+
+      const urlStr = data.target?.url ? chalk.dim(` → ${data.target.url}`) : '';
+      console.log(chalk.green(`  ✓ ${chalk.bold(id)} (${agent.name}) — ${data.id}${urlStr}`));
     } catch (err) {
-      console.log(chalk.red(`  Failed to launch ${id}: ${err.message}`));
+      console.log(chalk.red(`  ✗ ${id}: ${err.message}`));
     }
   }
 
   if (launched.length > 0) {
-    const sessionFile = JSON.stringify({ launched, started_at: new Date().toISOString(), ide: 'cursor' }, null, 2);
-    const { writeFileSync } = await import('fs');
-    const { join } = await import('path');
-    writeFileSync(join(root, '.agentxchain-session.json'), sessionFile + '\n');
-    console.log('');
-    console.log(chalk.dim(`  Session saved to .agentxchain-session.json`));
+    saveSession(root, launched, repoUrl);
   }
 
   return launched;
 }
 
+export async function sendFollowup(apiKey, cloudId, message) {
+  const res = await fetch(`${API_BASE}/agents/${cloudId}/followup`, {
+    method: 'POST',
+    headers: authHeaders(apiKey),
+    body: JSON.stringify({ prompt: { text: message } })
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`Followup failed (${res.status}): ${body}`);
+  }
+  return await res.json();
+}
+
+export async function getAgentStatus(apiKey, cloudId) {
+  const res = await fetch(`${API_BASE}/agents/${cloudId}`, {
+    method: 'GET',
+    headers: authHeaders(apiKey)
+  });
+  if (!res.ok) return null;
+  return await res.json();
+}
+
+export async function getAgentConversation(apiKey, cloudId) {
+  const res = await fetch(`${API_BASE}/agents/${cloudId}/conversation`, {
+    method: 'GET',
+    headers: authHeaders(apiKey)
+  });
+  if (!res.ok) return null;
+  return await res.json();
+}
+
+export async function stopAgent(apiKey, cloudId) {
+  const res = await fetch(`${API_BASE}/agents/${cloudId}/stop`, {
+    method: 'POST',
+    headers: authHeaders(apiKey)
+  });
+  return res.ok;
+}
+
+export async function deleteAgent(apiKey, cloudId) {
+  const res = await fetch(`${API_BASE}/agents/${cloudId}`, {
+    method: 'DELETE',
+    headers: authHeaders(apiKey)
+  });
+  return res.ok;
+}
+
+export function loadSession(root) {
+  const sessionPath = join(root, '.agentxchain-session.json');
+  if (!existsSync(sessionPath)) return null;
+  return JSON.parse(readFileSync(sessionPath, 'utf8'));
+}
+
+// --- Internal ---
+
+function saveSession(root, launched, repoUrl) {
+  const session = {
+    launched,
+    started_at: new Date().toISOString(),
+    ide: 'cursor',
+    repo: repoUrl
+  };
+  const sessionPath = join(root, '.agentxchain-session.json');
+  writeFileSync(sessionPath, JSON.stringify(session, null, 2) + '\n');
+  console.log(chalk.dim(`  Session saved to .agentxchain-session.json`));
+}
+
+function filterAgents(config, specificId) {
+  if (specificId) {
+    if (!config.agents[specificId]) {
+      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
+      process.exit(1);
+    }
+    return { [specificId]: config.agents[specificId] };
+  }
+  return config.agents;
+}
+
 function fallbackPromptOutput(config, opts) {
   const agents = filterAgents(config, opts.agent);
-
-  console.log(chalk.bold('  Copy-paste these prompts into separate Cursor sessions:'));
+  console.log(chalk.bold('  No API key. Printing seed prompts for manual use:'));
   console.log('');
-
   for (const [id, agent] of Object.entries(agents)) {
     const prompt = generateSeedPrompt(id, agent, config);
     console.log(chalk.dim('  ' + '─'.repeat(50)));
@@ -82,17 +173,16 @@ function fallbackPromptOutput(config, opts) {
     console.log(prompt);
     console.log('');
   }
-
   return [];
 }
 
-function filterAgents(config, specificId) {
-  if (specificId) {
-    if (!config.agents[specificId]) {
-      console.log(chalk.red(`  Agent "${specificId}" not found in agentxchain.json`));
-      process.exit(1);
-    }
-    return { [specificId]: config.agents[specificId] };
-  }
-  return config.agents;
+function printApiKeyHelp() {
+  console.log('');
+  console.log(chalk.yellow('  CURSOR_API_KEY not found.'));
+  console.log('');
+  console.log(`  1. Go to ${chalk.cyan('cursor.com/settings')} → Cloud Agents`);
+  console.log('  2. Create an API key');
+  console.log(`  3. Add to .env: ${chalk.bold('CURSOR_API_KEY=your_key')}`);
+  console.log(`  4. Run: ${chalk.bold('source .env && agentxchain start')}`);
+  console.log('');
 }

package/src/commands/claim.js

@@ -0,0 +1,117 @@
+import { writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadConfig, loadLock, LOCK_FILE } from '../lib/config.js';
+import { stopAgent, sendFollowup, loadSession } from '../adapters/cursor.js';
+
+export async function claimCommand(opts) {
+  const result = loadConfig();
+  if (!result) { console.log(chalk.red('  No agentxchain.json found.')); process.exit(1); }
+
+  const { root, config } = result;
+  const lock = loadLock(root);
+  if (!lock) { console.log(chalk.red('  lock.json not found.')); process.exit(1); }
+
+  const apiKey = process.env.CURSOR_API_KEY;
+  const session = loadSession(root);
+  const hasCursor = session?.ide === 'cursor' && apiKey;
+
+  if (lock.holder === 'human') {
+    console.log('');
+    console.log(chalk.yellow('  You already hold the lock.'));
+    console.log(`  ${chalk.dim('Release with:')} ${chalk.bold('agentxchain release')}`);
+    console.log('');
+    return;
+  }
+
+  if (lock.holder && !opts.force) {
+    const name = config.agents[lock.holder]?.name || lock.holder;
+    console.log('');
+    console.log(chalk.yellow(`  Lock held by ${chalk.bold(lock.holder)} (${name}).`));
+    console.log(chalk.dim('  Use --force to override.'));
+    console.log('');
+    return;
+  }
+
+  // Pause all Cursor agents when human claims
+  if (hasCursor && session.launched.length > 0) {
+    console.log(chalk.dim('  Pausing Cursor agents...'));
+    for (const agent of session.launched) {
+      try {
+        await stopAgent(apiKey, agent.cloudId);
+        console.log(chalk.dim(`    Paused ${agent.id}`));
+      } catch {
+        console.log(chalk.dim(`    Could not pause ${agent.id}`));
+      }
+    }
+  }
+
+  const lockPath = join(root, LOCK_FILE);
+  const newLock = {
+    holder: 'human',
+    last_released_by: lock.last_released_by,
+    turn_number: lock.turn_number,
+    claimed_at: new Date().toISOString()
+  };
+  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+
+  console.log('');
+  console.log(chalk.green(`  ✓ Lock claimed by ${chalk.bold('human')} (turn ${lock.turn_number})`));
+  if (hasCursor) console.log(chalk.dim('    All Cursor agents paused.'));
+  console.log(`  ${chalk.dim('Do your work, then:')} ${chalk.bold('agentxchain release')}`);
+  console.log('');
+}
+
+export async function releaseCommand() {
+  const result = loadConfig();
+  if (!result) { console.log(chalk.red('  No agentxchain.json found.')); process.exit(1); }
+
+  const { root, config } = result;
+  const lock = loadLock(root);
+  if (!lock) { console.log(chalk.red('  lock.json not found.')); process.exit(1); }
+
+  if (!lock.holder) {
+    console.log(chalk.yellow('  Lock is already free.'));
+    return;
+  }
+
+  const who = lock.holder;
+  const lockPath = join(root, LOCK_FILE);
+  const newLock = {
+    holder: null,
+    last_released_by: who,
+    turn_number: who === 'human' ? lock.turn_number : lock.turn_number + 1,
+    claimed_at: null
+  };
+  writeFileSync(lockPath, JSON.stringify(newLock, null, 2) + '\n');
+
+  console.log('');
+  console.log(chalk.green(`  ✓ Lock released by ${chalk.bold(who)} (turn ${newLock.turn_number})`));
+
+  // If releasing from human and Cursor session exists, wake the next agent
+  if (who === 'human') {
+    const apiKey = process.env.CURSOR_API_KEY;
+    const session = loadSession(root);
+
+    if (session?.ide === 'cursor' && apiKey) {
+      const agentIds = Object.keys(config.agents);
+      const next = agentIds[0];
+      const cloudAgent = session.launched.find(a => a.id === next);
+
+      if (cloudAgent) {
+        try {
+          const name = config.agents[next]?.name || next;
+          await sendFollowup(apiKey, cloudAgent.cloudId,
+            `Human released the lock. It's your turn. Read lock.json, claim it, and do your work as ${name}.`
+          );
+          console.log(chalk.cyan(`  Woke ${chalk.bold(next)} via Cursor followup.`));
+        } catch (err) {
+          console.log(chalk.dim(`  Could not wake ${next}: ${err.message}`));
+        }
+      }
+      console.log(chalk.dim('  The watch process will coordinate from here.'));
+    }
+  }
+
+  console.log('');
+}

package/src/commands/config.js

@@ -0,0 +1,149 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import { loadConfig, CONFIG_FILE } from '../lib/config.js';
+
+export async function configCommand(opts) {
+  const result = loadConfig();
+  if (!result) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config } = result;
+  const configPath = join(root, CONFIG_FILE);
+
+  if (opts.addAgent) {
+    await addAgent(config, configPath);
+    return;
+  }
+
+  if (opts.removeAgent) {
+    removeAgent(config, configPath, opts.removeAgent);
+    return;
+  }
+
+  if (opts.set) {
+    setSetting(config, configPath, opts.set);
+    return;
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(config, null, 2));
+    return;
+  }
+
+  printConfig(config);
+}
+
+function printConfig(config) {
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Config'));
+  console.log(chalk.dim('  ' + '─'.repeat(40)));
+  console.log('');
+  console.log(`  ${chalk.dim('Project:')}  ${config.project}`);
+  console.log(`  ${chalk.dim('Version:')}  ${config.version}`);
+  console.log(`  ${chalk.dim('Log:')}      ${config.log}`);
+  console.log('');
+
+  console.log(`  ${chalk.dim('Rules:')}`);
+  for (const [key, val] of Object.entries(config.rules || {})) {
+    console.log(`    ${chalk.dim(key + ':')} ${val}`);
+  }
+  console.log('');
+
+  console.log(`  ${chalk.dim('Agents:')}   ${Object.keys(config.agents).length}`);
+  for (const [id, agent] of Object.entries(config.agents)) {
+    console.log(`    ${chalk.cyan(id)} — ${agent.name}`);
+    console.log(`    ${chalk.dim(agent.mandate.slice(0, 80))}${agent.mandate.length > 80 ? '...' : ''}`);
+    console.log('');
+  }
+
+  console.log(chalk.dim('  Commands:'));
+  console.log(`    ${chalk.bold('agentxchain config --add-agent')}        Add a new agent`);
+  console.log(`    ${chalk.bold('agentxchain config --remove-agent <id>')} Remove an agent`);
+  console.log(`    ${chalk.bold('agentxchain config --set <key> <val>')}   Update a setting`);
+  console.log(`    ${chalk.bold('agentxchain config --json')}              Output as JSON`);
+  console.log('');
+}
+
+async function addAgent(config, configPath) {
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'id',
+      message: 'Agent ID (lowercase, no spaces):',
+      validate: (val) => {
+        if (!val.match(/^[a-z0-9-]+$/)) return 'Use lowercase letters, numbers, and hyphens only.';
+        if (val === 'human' || val === 'system') return `"${val}" is a reserved ID.`;
+        if (config.agents[val]) return `Agent "${val}" already exists.`;
+        return true;
+      }
+    },
+    { type: 'input', name: 'name', message: 'Display name:' },
+    { type: 'input', name: 'mandate', message: 'Mandate (what this agent does):' }
+  ]);
+
+  config.agents[answers.id] = { name: answers.name, mandate: answers.mandate };
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  console.log('');
+  console.log(chalk.green(`  ✓ Added agent ${chalk.bold(answers.id)} (${answers.name})`));
+  console.log(`  ${chalk.dim('Agents now:')} ${Object.keys(config.agents).join(', ')}`);
+  console.log('');
+}
+
+function removeAgent(config, configPath, id) {
+  if (!config.agents[id]) {
+    console.log(chalk.red(`  Agent "${id}" not found.`));
+    console.log(`  ${chalk.dim('Available:')} ${Object.keys(config.agents).join(', ')}`);
+    process.exit(1);
+  }
+
+  const name = config.agents[id].name;
+  delete config.agents[id];
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  console.log('');
+  console.log(chalk.green(`  ✓ Removed agent ${chalk.bold(id)} (${name})`));
+  console.log(`  ${chalk.dim('Agents now:')} ${Object.keys(config.agents).join(', ')}`);
+  console.log('');
+}
+
+function setSetting(config, configPath, keyValPair) {
+  const parts = keyValPair.split(/\s+/);
+  if (parts.length < 2) {
+    console.log(chalk.red('  Usage: agentxchain config --set <key> <value>'));
+    console.log(chalk.dim('  Example: agentxchain config --set rules.max_consecutive_claims 3'));
+    process.exit(1);
+  }
+
+  const key = parts[0];
+  const rawVal = parts.slice(1).join(' ');
+  const segments = key.split('.');
+
+  let target = config;
+  for (let i = 0; i < segments.length - 1; i++) {
+    if (target[segments[i]] === undefined) {
+      target[segments[i]] = {};
+    }
+    target = target[segments[i]];
+  }
+
+  const lastKey = segments[segments.length - 1];
+  const oldVal = target[lastKey];
+
+  let val = rawVal;
+  if (rawVal === 'true') val = true;
+  else if (rawVal === 'false') val = false;
+  else if (!isNaN(rawVal) && rawVal !== '') val = Number(rawVal);
+
+  target[lastKey] = val;
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  console.log('');
+  console.log(chalk.green(`  ✓ Set ${chalk.bold(key)} = ${val}`));
+  if (oldVal !== undefined) console.log(chalk.dim(`    (was: ${oldVal})`));
+  console.log('');
+}