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

package/README.md

@@ -0,0 +1,97 @@
+# @cordfuse/crosstalk — host client
+
+The host-side CLI for the Crosstalk protocol. Pairs with [`@cordfuse/crosstalkd`](https://www.npmjs.com/package/@cordfuse/crosstalkd) — the daemon running inside the [`crosstalk-server`](https://github.com/cordfuse/crosstalk/tree/main/server) container — and the [transport template](https://github.com/cordfuse/crosstalk/tree/main/transport) it scaffolds.
+
+> **What Crosstalk is.** An agent-agnostic swarm communication protocol built on git. A git repo is the message bus. Full background: **[github.com/cordfuse/crosstalk](https://github.com/cordfuse/crosstalk#why-crosstalk-exists)**.
+
+---
+
+## Install
+
+```sh
+npm install -g @cordfuse/crosstalk
+```
+
+Requires: Node.js ≥ 20 + Docker on PATH + git on PATH. Works on Linux, macOS, Windows (Docker Desktop).
+
+---
+
+## Quickstart
+
+```sh
+# 1. Scaffold a transport. Runtime-owned at <base>/crosstalk/transport/.
+crosstalk init
+
+# 2. Bring up the engine container.
+crosstalk up
+#    Generates <base>/crosstalk/docker-compose.yml and runs `docker
+#    compose up -d` for ghcr.io/cordfuse/crosstalk-server:<latest>.
+#    No cwd magic — works from any directory.
+
+# 3. Install an agent CLI inside the container, then authenticate.
+crosstalk chat --shell
+  npm install -g @anthropic-ai/claude-code
+  exit
+crosstalk chat --agent claude --login
+#    Auth URL opens in your default browser via xdg-open / open / start.
+#    Token saved in the /crosstalk-root volume so subsequent dispatched
+#    workers reuse it.
+
+# 4. Send your first message.
+crosstalk channel general
+crosstalk run --type primitive --to sonnet "What is the capital of France?"
+crosstalk replies <relPath printed by step above>
+```
+
+---
+
+## Subcommand surface
+
+Every name-resolved verb takes an optional `--containername <name>` (or `-c <name>`) flag. Bare verb = default container (literally named `crosstalk`).
+
+| Group | Subcommand | What it does |
+|---|---|---|
+| Meta | `crosstalk version` | Print client + engine versions (warns on skew) |
+| Protocol | `crosstalk init [-c <name>] [--remote <url>]` | Scaffold a transport at `<base>/<name>/transport/` |
+| Protocol | `crosstalk run --type primitive\|workflow ...` | Dispatch a primitive or workflow |
+| Protocol | `crosstalk replies <relPath>...` | Poll reply status |
+| Protocol | `crosstalk status` | Container name, transport host path, engine state, channels |
+| Protocol | `crosstalk channel <name> [--rename\|--delete]` | Channel operations |
+| Lifecycle | `crosstalk up` | Generate docker-compose, start the engine container |
+| Lifecycle | `crosstalk down` | Stop the engine container (keep storage) |
+| Lifecycle | `crosstalk rm [--force]` | Remove container AND wipe storage (cannot undo) |
+| Lifecycle | `crosstalk restart` | Down + up |
+| Lifecycle | `crosstalk pull` | Refresh the engine image |
+| Lifecycle | `crosstalk logs [-f]` | Stream the engine container's logs |
+| Interactive | `crosstalk chat --agent <name>` | Interactive session with an agent CLI inside the container |
+| Interactive | `crosstalk chat --agent <name> --login` | OAuth flow with browser-open URL handling |
+| Interactive | `crosstalk chat --shell` | Drop into bash inside the container (debug, install CLIs) |
+
+`--agent` is required for any non-shell chat — containers can have multiple installed CLIs, and the operator must pick explicitly. The error message names which ones are actually installed (queried from the engine's `/agents/installed` endpoint).
+
+---
+
+## What lives where
+
+- **Host** — `crosstalk` binary on PATH. Per-transport storage at `<base>/<name>/` (one tree per container).
+- **Container** (literally named whatever the operator picked at `init`, default `crosstalk`; image `ghcr.io/cordfuse/crosstalk-server`) — `crosstalkd` daemon, bind-mounted from:
+  - `<base>/<name>/transport/` → `/var/lib/crosstalk-transport` (runtime-owned git repo)
+  - `<base>/<name>/crosstalk-root/` → `/crosstalk-root` (operator CLIs + auth)
+  - `<base>/<name>/crosstalk-state/` → `/var/lib/crosstalk-state` (cursor + heartbeat)
+- **`<base>`** is per-OS user-mode: `$XDG_DATA_HOME/crosstalk` on Linux, `~/Library/Application Support/crosstalk` on macOS, `%LOCALAPPDATA%\crosstalk` on Windows. `CROSSTALK_STORAGE_MODE=system` switches to `/var/lib`-style paths.
+- **Engine HTTP API** — `127.0.0.1:<port>`. Default container = port 7000; named containers allocate at init from 7001 upward, recorded in `<base>/<name>/api-port`.
+- **Container identification** — every crosstalkd container gets the Docker label `crosstalk.transport=true`. The client uses the label for inventory queries, not name-pattern matching.
+
+---
+
+## Architecture
+
+Mirrors `docker` (host CLI) / `dockerd` (daemon). The split keeps the protocol-layer logic in one place (the engine) and exposes a clean operator surface on the host without forcing operators to manage Node/agent CLIs/OAuth tokens on their bare host.
+
+Client makes plain HTTP requests to the engine over loopback. No auth (same model as ollama, postgres-on-localhost, dockerd's local socket; the loopback bind is what gates exposure). Version skew detected via `X-Crosstalk-Engine-Version` response header — client warns once per process when the operator forgot to `crosstalk pull && crosstalk restart` after upgrading the client (or vice versa).
+
+---
+
+## License
+
+MIT.

package/bin/crosstalk.js

@@ -1,97 +1,84 @@
 #!/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',
+  rm:      'rm.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,118 @@
+// 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 { apiFor } from '../lib/api-client.js';
+import { reportAndExit } from '../lib/errors.js';
+import { positionals, has, flag } from '../lib/argv.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage:
+  crosstalk channel list                              # list channels
+  crosstalk channel <name>                            # create a channel
+  crosstalk channel <name-or-uuid> --rename <new>     # rename
+  crosstalk channel <name-or-uuid> --delete           # delete (with confirmation)
+  crosstalk channel --help
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const api = apiFor(argv);
+  const pos = positionals(argv, ['--rename', '--containername', '-c']);
+  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;
+  }
+
+  const handle = pos[0];
+  const renameTo = flag(argv, '--rename');
+  const wantDelete = has(argv, '--delete');
+
+  if (renameTo && wantDelete) {
+    process.stderr.write('crosstalk channel: --rename and --delete are mutually exclusive.\n');
+    return 1;
+  }
+
+  // Rename: PATCH /channels/<handle> { name: <new> }
+  if (renameTo) {
+    let r;
+    try {
+      r = await api.patch(`/channels/${encodeURIComponent(handle)}`, { name: renameTo });
+    } catch (err) {
+      reportAndExit(err, 'crosstalk channel');
+    }
+    if (r.noop) {
+      process.stdout.write(`No-op: ${handle} already named ${renameTo}.\n`);
+      return 0;
+    }
+    process.stdout.write(`Renamed: ${handle} -> ${r.name} (${r.uuid})\n`);
+    return 0;
+  }
+
+  // Delete: DELETE /channels/<handle>?confirm=<name>
+  // Engine returns 400 if confirm is missing/wrong, with the expected
+  // value in the error message. Client reads the channel's name first
+  // and passes it as confirm — operator's explicit --delete flag IS the
+  // confirmation for now. Interactive prompt deferred (would block on
+  // stdin in scripts).
+  if (wantDelete) {
+    let target;
+    try {
+      const all = await api.get('/channels');
+      target = all.channels.find((c) => c.uuid === handle || c.name === handle);
+    } catch (err) {
+      reportAndExit(err, 'crosstalk channel');
+    }
+    if (!target) {
+      process.stderr.write(`crosstalk channel: '${handle}' not found.\n`);
+      return 1;
+    }
+    const confirm = target.name ?? target.uuid;
+    let r;
+    try {
+      r = await api.delete(
+        `/channels/${encodeURIComponent(handle)}?confirm=${encodeURIComponent(confirm)}`,
+      );
+    } catch (err) {
+      reportAndExit(err, 'crosstalk channel');
+    }
+    process.stdout.write(`Deleted channel: ${r.name ?? '(unnamed)'} (${r.uuid})\n`);
+    return 0;
+  }
+
+  // No flags → create a channel with the given name.
+  let r;
+  try {
+    r = await api.post('/channels', { name: handle });
+  } 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,119 @@
+// crosstalk chat — interactive entry into the container.
+//
+// Modes (alpha.8):
+//   crosstalk chat --agent <name>     # interactive session with an agent CLI
+//   crosstalk chat --shell            # bash escape hatch (debug, install CLIs, run setup commands)
+//
+// --agent is required for non-shell mode. There's no implicit default;
+// containers may have multiple agent CLIs installed, the operator
+// picks one explicitly.
+//
+// `--login` was removed in alpha.8. Per-agent auth is now handled via
+// `data/crosstalk.yaml`'s per-provider `env_file:` (env-injected at
+// agent spawn time inside the engine) plus operator-run setup commands
+// for agents whose auth is a stateful CLI act (e.g. codex). Recipes are
+// documented in transport/auth/README.md.
+
+import { spawnSync } from 'child_process';
+import { requireInitialized } from '../lib/resolve.js';
+import { apiFor, ConnectError } from '../lib/api-client.js';
+import { flag, has } from '../lib/argv.js';
+
+const KNOWN_AGENTS = ['claude', 'codex', 'gemini', 'qwen', 'opencode', 'agy'];
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk chat --agent <name>
+       crosstalk chat --shell
+
+Opens an interactive session inside the engine container.
+
+--agent is REQUIRED for any chat mode. Containers can have multiple
+agent CLIs installed; the operator must say which one to invoke.
+
+Supported agents: ${KNOWN_AGENTS.join(', ')}.
+
+Modes:
+  --agent <name>   Interactive with the named agent CLI. Use the
+                   agent's own keys/commands for first-time setup
+                   (see transport/auth/README.md for recipes).
+  --shell          Drop into bash (install agent CLIs, debug, run
+                   one-time auth setup commands like
+                   \`codex login --with-api-key\`).
+
+Examples:
+  crosstalk chat --agent claude               # interactive claude
+  crosstalk chat --agent gemini               # interactive gemini
+  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 render their rich TUI normally and
+  // SIGWINCH propagates from the host's tty to the container's PTY.
+  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;
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const { name } = requireInitialized(argv);
+  const api = apiFor(argv);
+
+  if (has(argv, '--shell')) {
+    return runInteractive(name, 'bash');
+  }
+
+  const agent = flag(argv, '--agent');
+  if (!agent) {
+    // Query the engine for what's actually installed (vs the theoretical
+    // supported set). Gives a smarter error than "supported: claude,
+    // codex, gemini, qwen, opencode, agy" when only 1-2 are actually
+    // present in the container.
+    let installed = null;
+    try {
+      const r = await api.get('/agents/installed');
+      installed = r.installed;
+    } catch (err) {
+      if (!(err instanceof ConnectError)) {
+        // engine unreachable — fall through with no introspection
+      }
+    }
+    if (installed && installed.length === 0) {
+      process.stderr.write(
+        `crosstalk chat: no agent CLIs installed in this container.\n` +
+        `  Install one first:\n` +
+        `    crosstalk chat --shell\n` +
+        `    npm install -g @anthropic-ai/claude-code   # or your agent's installer\n`,
+      );
+      return 1;
+    }
+    const list = installed && installed.length > 0
+      ? `Installed in this container: ${installed.join(', ')}.`
+      : `Supported agents: ${KNOWN_AGENTS.join(', ')}.`;
+    process.stderr.write(
+      `crosstalk chat: --agent <name> is required.\n  ${list}\n`,
+    );
+    return 1;
+  }
+  if (!KNOWN_AGENTS.includes(agent)) {
+    process.stderr.write(
+      `crosstalk chat: unknown agent '${agent}'. Supported: ${KNOWN_AGENTS.join(', ')}\n`,
+    );
+    return 1;
+  }
+
+  return runInteractive(name, agent);
+}

package/commands/down.js

@@ -0,0 +1,40 @@
+// crosstalk down — stop a transport's container, keep storage.
+//
+// alpha.6: name-resolved. --volumes flag retires (no named volumes in
+// the bind-mount model). Reversible — next `up` resumes against the
+// preserved <base>/<name>/ storage.
+
+import { existsSync } from 'fs';
+import { spawnSync } from 'child_process';
+import { has } from '../lib/argv.js';
+import { requireInitialized, DEFAULT_CONTAINER_NAME } from '../lib/resolve.js';
+
+function usage(exit = 0) {
+  const w = exit === 0 ? process.stdout : process.stderr;
+  w.write(
+`Usage: crosstalk down [--containername <name>]
+
+Stops the engine container for a transport. Storage at <base>/<name>/
+is preserved — next 'crosstalk up' resumes against it. Use
+'crosstalk rm' if you want to wipe storage as well.
+`,
+  );
+  process.exit(exit);
+}
+
+export async function run(argv) {
+  if (has(argv, '--help') || has(argv, '-h')) usage(0);
+
+  const { name, paths } = requireInitialized(argv);
+  if (!existsSync(paths.composeFile)) {
+    process.stderr.write(
+      `crosstalk down: '${name}' has no compose file (never brought up). Nothing to do.\n`,
+    );
+    return 0;
+  }
+
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'down'], {
+    stdio: 'inherit',
+  });
+  return r.status ?? 1;
+}