@cordfuse/crosstalk 7.0.0-alpha.1 → 7.0.0-alpha.11

package/README.md

@@ -1,26 +1,97 @@
 # @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`](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.
 
-The host-side CLI for the Crosstalk protocol. Pairs with `@cordfuse/crosstalkd`, the daemon that runs inside the `crosstalk-server` container.
+> **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)**.
 
-- 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.
+## Install
 
-## Status (v7.0.0-dev.0)
+```sh
+npm install -g @cordfuse/crosstalk
+```
 
-- `crosstalk version` — works
-- All other subcommands — landing in P4–P6
+Requires: Node.js ≥ 20 + Docker on PATH + git on PATH. Works on Linux, macOS, Windows (Docker Desktop).
 
-## Install (post-publish; today this package is unpublished)
+---
+
+## Quickstart
 
 ```sh
-npm install -g @cordfuse/crosstalk
+# 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

@@ -30,6 +30,7 @@ const SUBCOMMANDS = {
   init:    'init.js',
   up:      'up.js',
   down:    'down.js',
+  rm:      'rm.js',
   restart: 'restart.js',
   pull:    'pull.js',
   logs:    'logs.js',

package/commands/channel.js

@@ -4,21 +4,19 @@
 // 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 { apiFor } from '../lib/api-client.js';
 import { reportAndExit } from '../lib/errors.js';
-import { positionals, has } from '../lib/argv.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 <name>      # create a channel
-  crosstalk channel list        # list channels
+  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
-
-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);
@@ -27,7 +25,8 @@ Not yet implemented (engine API needs PATCH/DELETE first):
 export async function run(argv) {
   if (has(argv, '--help') || has(argv, '-h')) usage(0);
 
-  const pos = positionals(argv, []);
+  const api = apiFor(argv);
+  const pos = positionals(argv, ['--rename', '--containername', '-c']);
   if (pos.length === 0) usage(1);
 
   // `crosstalk channel list` → list channels
@@ -50,16 +49,66 @@ export async function run(argv) {
     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');
+  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;
   }
 
-  const name = pos[0];
+  // 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 });
+    r = await api.post('/channels', { name: handle });
   } catch (err) {
     reportAndExit(err, 'crosstalk channel');
   }

package/commands/chat.js

@@ -1,74 +1,50 @@
-// crosstalk chat — the single interactive entry point into the container.
+// crosstalk chat — interactive entry 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)
+// 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)
 //
-// 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.
+// --agent is required for non-shell mode. There's no implicit default;
+// containers may have multiple agent CLIs installed, the operator
+// picks one explicitly.
 //
-//   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.
+// `--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 { spawn, spawnSync } from 'child_process';
-import { requireTransportRoot, containerName } from '../lib/transport.js';
+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'];
-// 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]
+`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.
 
-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).
+Supported agents: ${KNOWN_AGENTS.join(', ')}.
 
 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).
+  --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                              # interactive claude
+  crosstalk chat --agent claude               # interactive claude
   crosstalk chat --agent gemini               # interactive gemini
-  crosstalk chat --login                      # OAuth, claude
-  crosstalk chat --login --agent codex        # OAuth, codex
   crosstalk chat --shell                      # bash
 `,
   );
@@ -78,8 +54,8 @@ Examples:
 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.
+  // 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}`);
@@ -90,60 +66,48 @@ function runInteractive(container, command, env = {}) {
   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);
+  const { name } = requireInitialized(argv);
+  const api = apiFor(argv);
 
   if (has(argv, '--shell')) {
     return runInteractive(name, 'bash');
   }
 
-  const agent = flag(argv, '--agent') ?? 'claude';
+  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`,
@@ -151,9 +115,5 @@ export async function run(argv) {
     return 1;
   }
 
-  if (has(argv, '--login')) {
-    return await runLogin(name, agent);
-  }
-
   return runInteractive(name, agent);
 }

package/commands/down.js

@@ -1,18 +1,22 @@
-// crosstalk down — stop the engine container for this transport.
+// 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 { requireTransportRoot, composeFile } from '../lib/transport.js';
 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 [--volumes]
+`Usage: crosstalk down [--containername <name>]
 
-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).
+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);
@@ -21,17 +25,16 @@ installed CLIs + auth state; you'll have to re-install + re-auth).
 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`);
+  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 args = ['compose', '-f', composeYml, 'down'];
-  if (has(argv, '--volumes')) args.push('--volumes');
-
-  const r = spawnSync('docker', args, { cwd: root, stdio: 'inherit' });
+  const r = spawnSync('docker', ['compose', '-f', paths.composeFile, 'down'], {
+    stdio: 'inherit',
+  });
   return r.status ?? 1;
 }