@cordfuse/crosstalk 6.0.0-alpha.9 → 7.0.0-alpha.1

package/README.md

@@ -0,0 +1,26 @@
+# @cordfuse/crosstalk — host client
+
+> **README is a stub.** Full operator-facing docs land in the docs-consolidation pass. The body below is intentionally short; it covers what's actually implemented today.
+
+The host-side CLI for the Crosstalk protocol. Pairs with `@cordfuse/crosstalkd`, the daemon that runs inside the `crosstalk-server` container.
+
+- Operator installs this package: `npm install -g @cordfuse/crosstalk`
+- Operator runs `docker compose up -d` to bring up the `crosstalk-server` container (which runs `crosstalkd`)
+- Operator runs `crosstalk <subcommand>` — the client talks to the daemon's HTTP API on `127.0.0.1:7000`
+
+This split mirrors `docker` (host CLI) / `dockerd` (daemon). The client never reads or writes transport files directly — all protocol operations go through the API.
+
+## Status (v7.0.0-dev.0)
+
+- `crosstalk version` — works
+- All other subcommands — landing in P4–P6
+
+## Install (post-publish; today this package is unpublished)
+
+```sh
+npm install -g @cordfuse/crosstalk
+```
+
+## License
+
+MIT.

package/bin/crosstalk.js

@@ -1,97 +1,83 @@
 #!/usr/bin/env node
-// crosstalk — subcommand dispatcher
+// crosstalk — host-side client for the crosstalkd daemon.
 //
-// Walks up from cwd to find a Crosstalk transport (identified by
-// upstream/CROSSTALK-VERSION), then runs the requested subcommand from the
-// runtime's installed source via tsx. All args after the subcommand are
-// forwarded. `init` is the one subcommand that runs outside a transport
-// (it creates one).
+// Thin subcommand dispatcher. Routes operator commands to either:
+//   - the engine's HTTP API on 127.0.0.1:<port> (protocol commands)
+//   - the local docker daemon (lifecycle: up, down, restart, pull, logs)
+//   - `docker exec -it <container>` via a PTY wrapper (chat, shell)
+//
+// Subcommands and their groups:
+//
+//   Protocol (HTTP API):  run, replies, status, channel, init
+//   Lifecycle (docker):   up, down, restart, pull, logs
+//   Interactive (pty):    chat, shell
+//   Observability:        version
+//
+// P3 only ships `version` as a proof-of-life. Other subcommands land
+// in P4 (protocol), P5 (lifecycle), P6 (interactive).
 
-import { existsSync, statSync } from 'fs';
-import { resolve, join, dirname } from 'path';
-import { spawnSync, spawn } from 'child_process';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
-import { createRequire } from 'module';
+import { existsSync } from 'fs';
 
-const SUBCOMMANDS = [
-  'dispatch', 'stop', 'send', 'replies', 'wake', 'status', 'init', 'dlq', 'channel',
-  'chat', 'open', 'attach', 'upgrade',
-];
-const STANDALONE_SUBCOMMANDS = new Set(['init']);
+const SUBCOMMANDS = {
+  // each entry is the file in commands/ to load
+  version: 'version.js',
+  run:     'run.js',
+  replies: 'replies.js',
+  status:  'status.js',
+  channel: 'channel.js',
+  init:    'init.js',
+  up:      'up.js',
+  down:    'down.js',
+  restart: 'restart.js',
+  pull:    'pull.js',
+  logs:    'logs.js',
+  chat:    'chat.js',
+};
 
-function findTransportRoot(startDir) {
-  let dir = resolve(startDir);
-  while (true) {
-    const versionFile = join(dir, 'upstream', 'CROSSTALK-VERSION');
-    if (existsSync(versionFile) && statSync(versionFile).isFile()) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
+const argv = process.argv.slice(2);
+const thisDir = dirname(fileURLToPath(import.meta.url));
 
 function printUsage(exitCode = 0) {
   process.stdout.write(
-    `Usage: crosstalk <subcommand> [args...]\n\nSubcommands:\n` +
-    SUBCOMMANDS.map((s) => `  ${s}`).join('\n') +
-    `\n\nMost subcommands require you to be inside a Crosstalk transport\n` +
-    `(a directory containing upstream/CROSSTALK-VERSION). 'init' can run\n` +
-    `from anywhere to scaffold a new transport.\n`,
+`Usage: crosstalk <subcommand> [args...]
+
+The host-side client for crosstalkd. Most commands talk to the engine's
+HTTP API on 127.0.0.1; lifecycle commands talk to the local docker daemon.
+
+Subcommands:
+${Object.keys(SUBCOMMANDS).map((s) => `  ${s}`).join('\n')}
+
+If your engine listens on a non-default port, set CROSSTALK_API_PORT.
+
+v7.0.0-dev — many subcommands are not implemented yet (see bin/crosstalk.js).
+`,
   );
   process.exit(exitCode);
 }
 
-const argv = process.argv.slice(2);
 if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') printUsage(0);
 
-if (argv[0] === '--version' || argv[0] === 'version') {
-  const require = createRequire(import.meta.url);
-  const { version } = require('../package.json');
-  process.stdout.write(`${version}\n`);
-  process.exit(0);
+if (argv[0] === '--version') {
+  // delegate to the version command so the engine-side number can also
+  // be queried in a uniform place
+  argv[0] = 'version';
 }
 
 const cmd = argv[0];
-if (!SUBCOMMANDS.includes(cmd)) {
-  console.error(`crosstalk: unknown subcommand '${cmd}'\n`);
+const file = SUBCOMMANDS[cmd];
+if (!file) {
+  process.stderr.write(`crosstalk: unknown subcommand '${cmd}'\n\n`);
   printUsage(1);
 }
 
-const thisDir = dirname(fileURLToPath(import.meta.url));
-const srcFile = join(thisDir, '..', 'src', `${cmd}.ts`);
-
-let cwd = process.cwd();
-if (!STANDALONE_SUBCOMMANDS.has(cmd)) {
-  const root = findTransportRoot(cwd);
-  if (!root) {
-    console.error(
-      `crosstalk ${cmd}: not inside a Crosstalk transport ` +
-      `(no upstream/CROSSTALK-VERSION found from ${cwd} upward).`,
-    );
-    process.exit(2);
-  }
-  cwd = root;
+const modulePath = join(thisDir, '..', 'commands', file);
+if (!existsSync(modulePath)) {
+  process.stderr.write(`crosstalk: command file missing for '${cmd}' (expected ${modulePath})\n`);
+  process.exit(2);
 }
 
-const require = createRequire(import.meta.url);
-const tsxCli = require.resolve('tsx/cli');
-
-// dispatch is long-running: use async spawn so SIGTERM/SIGINT forwarded to
-// the tsx child kills the whole chain cleanly. All other subcommands are
-// short-lived and spawnSync is fine.
-if (cmd === 'dispatch') {
-  const child = spawn(process.execPath, [tsxCli, srcFile, ...argv.slice(1)], {
-    cwd,
-    stdio: 'inherit',
-  });
-  const forward = (sig) => { try { child.kill(sig); } catch {} };
-  process.on('SIGTERM', () => forward('SIGTERM'));
-  process.on('SIGINT',  () => forward('SIGTERM'));
-  child.on('exit', (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
-} else {
-  const r = spawnSync(process.execPath, [tsxCli, srcFile, ...argv.slice(1)], {
-    cwd,
-    stdio: 'inherit',
-  });
-  process.exit(r.status ?? 1);
-}
+const mod = await import(modulePath);
+const exit = await mod.run(argv.slice(1));
+process.exit(typeof exit === 'number' ? exit : 0);

package/commands/channel.js

@@ -0,0 +1,69 @@
+// crosstalk channel <name> — create a channel via POST /channels.
+//
+// P4 only ships create. --rename and --delete need PATCH/DELETE
+// endpoints that haven't been added to the engine yet; they land
+// when the engine gains them.
+
+import { api } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+import { positionals, has } from '../lib/argv.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage:
+  crosstalk channel <name>      # create a channel
+  crosstalk channel list        # list channels
+  crosstalk channel --help
+
+Not yet implemented (engine API needs PATCH/DELETE first):
+  crosstalk channel <name-or-uuid> --rename <new>
+  crosstalk channel <name-or-uuid> --delete
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const pos = positionals(argv, []);
+  if (pos.length === 0) usage(1);
+
+  // `crosstalk channel list` → list channels
+  if (pos[0] === 'list') {
+    let r;
+    try {
+      r = await api.get('/channels');
+    } catch (err) {
+      reportAndExit(err, 'crosstalk channel list');
+    }
+    if (r.channels.length === 0) {
+      process.stdout.write('(no channels)\n');
+      return 0;
+    }
+    for (const ch of r.channels) {
+      const name = ch.name ?? '(unnamed)';
+      const parentSuffix = ch.parent ? ` [child of ${ch.parent.slice(0, 8)}]` : '';
+      process.stdout.write(`${ch.uuid}  ${name}${parentSuffix}\n`);
+    }
+    return 0;
+  }
+
+  // Otherwise: create a channel with the given name.
+  if (has(argv, '--rename') || has(argv, '--delete')) {
+    process.stderr.write('crosstalk channel: --rename and --delete are not implemented yet (engine API needs PATCH/DELETE).\n');
+    return 1;
+  }
+
+  const name = pos[0];
+  let r;
+  try {
+    r = await api.post('/channels', { name });
+  } catch (err) {
+    reportAndExit(err, 'crosstalk channel');
+  }
+  process.stdout.write(`Created channel: ${r.uuid}\n`);
+  process.stdout.write(`  name: ${r.name}\n`);
+  return 0;
+}

package/commands/chat.js

@@ -0,0 +1,159 @@
+// crosstalk chat — the single interactive entry point into the container.
+//
+// Modes:
+//   crosstalk chat                       # default agent (claude), interactive
+//   crosstalk chat --agent <name>        # interactive with a specific agent
+//   crosstalk chat --login [--agent X]   # OAuth setup flow with browser-open
+//   crosstalk chat --shell               # bash escape hatch (sysadmin / debug)
+//
+// Login flow design (root-cause fix, not a bandaid):
+//   The container has no DISPLAY / no browser / no xdg-open. So the agent
+//   CLI prints a URL and expects the operator to manually open it. THIS
+//   wrapper runs on the HOST — where the browser lives. It intercepts the
+//   URL on the agent's stdout and opens it directly via the OS-native
+//   browser launcher (`open` / `xdg-open` / `wslview` / `start`). Operator
+//   never has to read or copy-paste the URL.
+//
+//   COLUMNS=1000 is still set under --login as a contingency: if browser
+//   open fails (headless SSH session, missing xdg-open, etc.), the URL
+//   still renders unwrapped in the terminal for manual copy. That's the
+//   fallback, not the primary mechanism.
+
+import { spawn, spawnSync } from 'child_process';
+import { requireTransportRoot, containerName } from '../lib/transport.js';
+import { flag, has } from '../lib/argv.js';
+
+const KNOWN_AGENTS = ['claude', 'codex', 'gemini', 'qwen', 'opencode', 'agy'];
+// Conservative URL regex: matches the leading https://...token boundary,
+// stops at whitespace/quote/angle. False positives are bounded to --login
+// mode where the first URL printed is almost certainly the auth URL.
+const URL_RE = /https?:\/\/[^\s<>"']+/;
+
+function openInBrowser(url) {
+  const cmd =
+    process.platform === 'darwin'         ? 'open'      :
+    process.platform === 'win32'          ? 'start'     :
+    process.env['WSL_DISTRO_NAME']        ? 'wslview'   :
+    /* default Linux */                     'xdg-open';
+  try {
+    const r = spawnSync(cmd, [url], { stdio: 'ignore' });
+    return r.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk chat [--agent <name>] [--login] [--shell]
+
+Opens an interactive session inside the engine container — the single
+PTY-wrapped entry point for everything you'd do inside the container
+(daily chat, OAuth setup, sysadmin).
+
+Modes:
+  (default)             Interactive with the default agent (claude)
+  --agent <name>        Use a specific agent. Supported:
+                        ${KNOWN_AGENTS.join(', ')}
+  --login               First-time auth flow. Intercepts the OAuth URL on
+                        the agent's stdout and opens it in your default
+                        browser via the OS-native launcher. Falls back to
+                        printing the URL unwrapped if no browser is
+                        reachable (headless / SSH session).
+  --shell               Drop into bash (install agent CLIs, debug,
+                        inspect state).
+
+Examples:
+  crosstalk chat                              # interactive claude
+  crosstalk chat --agent gemini               # interactive gemini
+  crosstalk chat --login                      # OAuth, claude
+  crosstalk chat --login --agent codex        # OAuth, codex
+  crosstalk chat --shell                      # bash
+`,
+  );
+  process.exit(exit);
+}
+
+function runInteractive(container, command, env = {}) {
+  // Full TTY passthrough — docker exec -it gives the container a real
+  // PTY, and stdio: 'inherit' forwards stdin/stdout/stderr from the
+  // operator's terminal. Agent CLIs get to render their rich TUI
+  // normally.
+  const envFlags = [];
+  for (const [k, v] of Object.entries(env)) {
+    envFlags.push('--env', `${k}=${v}`);
+  }
+  const r = spawnSync('docker', ['exec', '-it', ...envFlags, container, command], {
+    stdio: 'inherit',
+  });
+  return r.status ?? 1;
+}
+
+function runLogin(container, agent) {
+  // Login mode: tee the agent's stdout so we can spot the auth URL and
+  // open it in the operator's browser. The container still has a real
+  // PTY (docker exec -it allocates one inside the container regardless
+  // of host stdio configuration), so the agent CLI renders into a TTY;
+  // we just pipe the bytes on the host side to inspect them.
+  //
+  // No agent-specific "login" subcommand — we just run the agent's
+  // default interactive entry point. First-run auth flow happens
+  // automatically for every agent we support. Operator can pass
+  // --agent <name> to target a specific one.
+  return new Promise((resolve) => {
+    const child = spawn(
+      'docker',
+      [
+        'exec', '-it',
+        '--env', 'COLUMNS=1000', // fallback for browser-open failure
+        '--env', 'LINES=40',
+        container,
+        agent,
+      ],
+      { stdio: ['inherit', 'pipe', 'inherit'] },
+    );
+    let opened = false;
+    child.stdout.on('data', (chunk) => {
+      process.stdout.write(chunk);
+      if (opened) return;
+      const match = chunk.toString().match(URL_RE);
+      if (!match) return;
+      const url = match[0];
+      opened = true;
+      const ok = openInBrowser(url);
+      process.stdout.write(
+        ok
+          ? `\n[crosstalk chat] Opened auth URL in your default browser.\n`
+          : `\n[crosstalk chat] Could not auto-open browser. Open this URL manually:\n  ${url}\n`,
+      );
+    });
+    child.on('exit', (code) => resolve(code ?? 0));
+    child.on('error', () => resolve(1));
+  });
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const root = requireTransportRoot();
+  const name = containerName(root);
+
+  if (has(argv, '--shell')) {
+    return runInteractive(name, 'bash');
+  }
+
+  const agent = flag(argv, '--agent') ?? 'claude';
+  if (!KNOWN_AGENTS.includes(agent)) {
+    process.stderr.write(
+      `crosstalk chat: unknown agent '${agent}'. Supported: ${KNOWN_AGENTS.join(', ')}\n`,
+    );
+    return 1;
+  }
+
+  if (has(argv, '--login')) {
+    return await runLogin(name, agent);
+  }
+
+  return runInteractive(name, agent);
+}

package/commands/down.js

@@ -0,0 +1,37 @@
+// crosstalk down — stop the engine container for this transport.
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { requireTransportRoot, composeFile } from '../lib/transport.js';
+import { has } from '../lib/argv.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk down [--volumes]
+
+Stops the engine container for the transport in the current directory.
+With --volumes, also removes the persistent volumes (clears operator-
+installed CLIs + auth state; you'll have to re-install + re-auth).
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const root = requireTransportRoot();
+  const composeYml = composeFile(root);
+  if (!existsSync(composeYml)) {
+    process.stderr.write(`crosstalk down: no docker-compose.yml at ${composeYml}\n`);
+    process.stderr.write(`  (this transport was probably never brought up — nothing to do)\n`);
+    return 0;
+  }
+
+  const args = ['compose', '-f', composeYml, 'down'];
+  if (has(argv, '--volumes')) args.push('--volumes');
+
+  const r = spawnSync('docker', args, { cwd: root, stdio: 'inherit' });
+  return r.status ?? 1;
+}

package/commands/init.js

@@ -0,0 +1,105 @@
+// crosstalk init <dir> — scaffold a new transport via docker.
+//
+// Doesn't go through the engine HTTP API — there's no running engine
+// at init time. Instead, runs the engine in a one-shot container with
+// a bind-mount of the target directory, and lets crosstalkd's init
+// subcommand write the template files directly.
+//
+//   docker run --rm \
+//     -v "$(realpath <dir>):/init-target" \
+//     --user "$(id -u):$(id -g)" \
+//     <image> \
+//     crosstalkd init /init-target
+//
+// The --user flag is critical: without it, the template files would
+// land owned by root (the container's user). Setting it to the
+// operator's UID/GID keeps file ownership sane.
+
+import { mkdirSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { spawnSync } from 'child_process';
+import { has, positionals } from '../lib/argv.js';
+
+const DEFAULT_IMAGE = process.env.CROSSTALK_IMAGE
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.1';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage:
+  crosstalk init <dir>        # scaffold a new transport at <dir>
+
+  Image:  ${DEFAULT_IMAGE}
+  Override:  CROSSTALK_IMAGE=<image-tag> crosstalk init <dir>
+
+  The image must be pullable (or already present locally). For local dev
+  before the GHCR publish pipeline ships, build the image first:
+    docker build -t crosstalk-server:7.0.0-alpha.1 -f server/Dockerfile .
+  Then run:
+    CROSSTALK_IMAGE=crosstalk-server:7.0.0-alpha.1 crosstalk init mytransport
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+  const pos = positionals(argv, []);
+  if (pos.length === 0) usage(1);
+
+  const target = resolve(pos[0]);
+  if (!existsSync(target)) mkdirSync(target, { recursive: true });
+
+  // Resolve uid/gid via process.getuid() — POSIX only. On Windows the
+  // --user flag is omitted; Docker Desktop handles ownership differently.
+  const uid = typeof process.getuid === 'function' ? process.getuid() : null;
+  const gid = typeof process.getgid === 'function' ? process.getgid() : null;
+  const userArgs = (uid != null && gid != null) ? ['--user', `${uid}:${gid}`] : [];
+
+  // --entrypoint crosstalkd overrides the image's default ENTRYPOINT
+  // (which is the dispatcher entrypoint.sh requiring TRANSPORT_GIT_URL).
+  // For init we want to call crosstalkd directly with no env requirements.
+  const args = [
+    'run', '--rm',
+    '-v', `${target}:/init-target`,
+    ...userArgs,
+    '--entrypoint', 'crosstalkd',
+    DEFAULT_IMAGE,
+    'init', '/init-target',
+  ];
+
+  const r = spawnSync('docker', args, { stdio: 'inherit' });
+  if (r.status !== 0) {
+    process.stderr.write(`crosstalk init: docker run exited ${r.status}\n`);
+    process.stderr.write(`  command was: docker ${args.join(' ')}\n`);
+    return r.status ?? 1;
+  }
+
+  // Auto git init + initial commit so the transport is ready for
+  // `crosstalk up` immediately. Engine expects a git repo (cursor +
+  // commit operations on every tick). Doing this on the host so the
+  // commit author uses the operator's local git config — not the
+  // container's default.
+  //
+  // Best-effort: if any git step fails, print a warning but don't fail
+  // the init (operator can complete the steps manually).
+  const gitSteps = [
+    ['init', '--quiet', '--initial-branch=main'],
+    ['add', '-A'],
+    ['commit', '--quiet', '-m', 'initial transport'],
+  ];
+  for (const args of gitSteps) {
+    const gr = spawnSync('git', args, { cwd: target, stdio: 'pipe' });
+    if (gr.status !== 0) {
+      const stderr = gr.stderr?.toString().trim() ?? '';
+      process.stderr.write(
+        `crosstalk init: \`git ${args.join(' ')}\` failed (transport scaffolded but not committed)\n`,
+      );
+      if (stderr) process.stderr.write(`  ${stderr.split('\n').join('\n  ')}\n`);
+      process.stderr.write(`  Finish manually: cd ${target} && git init && git add -A && git commit -m "initial transport"\n`);
+      return 0;  // not fatal — scaffold succeeded
+    }
+  }
+  process.stdout.write(`\nGit initialized; transport is ready for \`crosstalk up\`.\n`);
+  return 0;
+}

package/commands/logs.js

@@ -0,0 +1,39 @@
+// crosstalk logs — tail the engine container's logs.
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { requireTransportRoot, composeFile } from '../lib/transport.js';
+import { has } from '../lib/argv.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk logs [-f|--follow] [-n <lines>]
+
+Streams the engine container's stdout/stderr. -f to follow (Ctrl-C to stop).
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const root = requireTransportRoot();
+  const composeYml = composeFile(root);
+  if (!existsSync(composeYml)) {
+    process.stderr.write(`crosstalk logs: no docker-compose.yml — run 'crosstalk up' first.\n`);
+    return 1;
+  }
+  const args = ['compose', '-f', composeYml, 'logs'];
+  if (has(argv, '-f') || has(argv, '--follow')) args.push('--follow');
+  // Pass through tail count if provided.
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '-n' || argv[i] === '--tail') {
+      args.push('--tail', argv[i + 1] ?? '100');
+      i++;
+    }
+  }
+  const r = spawnSync('docker', args, { cwd: root, stdio: 'inherit' });
+  return r.status ?? 1;
+}

package/commands/pull.js

@@ -0,0 +1,24 @@
+// crosstalk pull — refresh the engine image.
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { requireTransportRoot, composeFile } from '../lib/transport.js';
+import { has } from '../lib/argv.js';
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) {
+    process.stdout.write('Usage: crosstalk pull\n');
+    return 0;
+  }
+  const root = requireTransportRoot();
+  const composeYml = composeFile(root);
+  if (!existsSync(composeYml)) {
+    process.stderr.write(`crosstalk pull: no docker-compose.yml — run 'crosstalk up' first.\n`);
+    return 1;
+  }
+  const r = spawnSync('docker', ['compose', '-f', composeYml, 'pull'], {
+    cwd: root,
+    stdio: 'inherit',
+  });
+  return r.status ?? 1;
+}

package/commands/replies.js

@@ -0,0 +1,39 @@
+// crosstalk replies <relPath> [<relPath>...] — poll reply status.
+//
+// Exit 0 if all targets have REPLIED or FAILED, exit 2 while any PENDING
+// — agents can poll cheaply in a loop. Mirrors crosstalkd replies.
+
+import { api } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+import { positionals, has } from '../lib/argv.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write('Usage: crosstalk replies <relPath> [<relPath>...]\n');
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+  const targets = positionals(argv, []);
+  if (targets.length === 0) usage(1);
+
+  let resp;
+  try {
+    resp = await api.get(`/replies?relPaths=${encodeURIComponent(targets.join(','))}`);
+  } catch (err) {
+    reportAndExit(err, 'crosstalk replies');
+  }
+
+  let pending = 0;
+  for (const r of resp.replies) {
+    if (r.status === 'PENDING') {
+      process.stdout.write(`PENDING  ${r.target}\n`);
+      pending++;
+    } else {
+      const tag = r.status === 'FAILED' ? 'FAILED  ' : 'REPLIED ';
+      process.stdout.write(`${tag} ${r.target}  <- ${r.from} (${r.replyRelPath})\n`);
+    }
+  }
+  return pending > 0 ? 2 : 0;
+}