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

package/README.md

@@ -1,26 +1,92 @@
 # @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.
+crosstalk init mytransport
+cd mytransport
+
+# 2. Bring up the engine container for this transport.
+crosstalk up
+#    Generates docker-compose.yml in the transport root and runs
+#    `docker compose up -d` for ghcr.io/cordfuse/crosstalk-server:<latest>.
+#    Bind-mounts $PWD as the transport — any `git remote add` from the
+#    host is immediately visible to the engine.
+
+# 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.
+#    Operator never has to copy-paste it. Token saved in the /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
+
+| Group | Subcommand | What it does |
+|---|---|---|
+| Meta | `crosstalk version` | Print client + engine versions (warns on skew) |
+| Protocol | `crosstalk init <dir>` | Scaffold a transport + `git init` |
+| Protocol | `crosstalk run --type primitive\|workflow ...` | Dispatch a primitive or workflow |
+| Protocol | `crosstalk replies <relPath>...` | Poll reply status |
+| Protocol | `crosstalk status` | Engine heartbeat, claimed models, channels |
+| Protocol | `crosstalk channel <name> [--rename\|--delete]` | Channel operations |
+| Lifecycle | `crosstalk up` | Generate docker-compose, start engine container |
+| Lifecycle | `crosstalk down [--volumes]` | Stop the engine container |
+| 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, `~/path/to/mytransport/` (the operator's transport directory, bind-mounted).
+- **Container** (`crosstalk-server`, image `ghcr.io/cordfuse/crosstalk-server`) — `crosstalkd` daemon, dispatch state in named volume `crosstalk-state:/var/lib/crosstalkd-state`, operator-installed agent CLIs + auth tokens in named volume `crosstalk-root:/root`.
+- **Engine HTTP API** — `127.0.0.1:7000` (compose `127.0.0.1:HOST:CONTAINER` port mapping is the actual security boundary; engine binds 0.0.0.0 inside the container).
+- **Transport bind-mount** — `$PWD:/var/lib/crosstalk-transport`. Operator git commands on the host are seen by the engine immediately.
+
+---
+
+## 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/commands/channel.js

@@ -6,19 +6,17 @@
 
 import { api } 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,7 @@ 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 pos = positionals(argv, ['--rename']);
   if (pos.length === 0) usage(1);
 
   // `crosstalk channel list` → list channels
@@ -50,16 +48,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,10 +1,13 @@
 // 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)
+//   crosstalk chat --agent <name>            # interactive with a specific agent
+//   crosstalk chat --agent <name> --login    # OAuth setup flow with browser-open
+//   crosstalk chat --shell                   # bash escape hatch (sysadmin / debug)
+//
+// --agent is required for non-shell modes. There's no implicit default
+// (containers may have multiple agent CLIs installed; the operator
+// must say which one to invoke).
 //
 // Login flow design (root-cause fix, not a bandaid):
 //   The container has no DISPLAY / no browser / no xdg-open. So the agent
@@ -21,6 +24,7 @@
 
 import { spawn, spawnSync } from 'child_process';
 import { requireTransportRoot, containerName } from '../lib/transport.js';
+import { api, ConnectError } from '../lib/api-client.js';
 import { flag, has } from '../lib/argv.js';
 
 const KNOWN_AGENTS = ['claude', 'codex', 'gemini', 'qwen', 'opencode', 'agy'];
@@ -46,29 +50,33 @@ function openInBrowser(url) {
 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> [--login]
+       crosstalk chat --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).
 
+--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:
-  (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).
+  --agent <name>        Interactive with the named agent.
+  --agent <name> --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).
+                        inspect state). No --agent needed.
 
 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 --agent claude --login       # OAuth, claude
+  crosstalk chat --agent codex  --login       # OAuth, codex
   crosstalk chat --shell                      # bash
 `,
   );
@@ -143,7 +151,38 @@ export async function run(argv) {
     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`,

package/commands/init.js

@@ -21,7 +21,7 @@ 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';
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.3';
 
 function usage(exit = 0) {
   const w = exit === 0 ? process.stdout : process.stderr;
@@ -34,9 +34,9 @@ function usage(exit = 0) {
 
   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 .
+    docker build -t crosstalk-server:7.0.0-alpha.3 -f server/Dockerfile .
   Then run:
-    CROSSTALK_IMAGE=crosstalk-server:7.0.0-alpha.1 crosstalk init mytransport
+    CROSSTALK_IMAGE=crosstalk-server:7.0.0-alpha.3 crosstalk init mytransport
 `,
   );
   process.exit(exit);

package/commands/up.js

@@ -16,7 +16,7 @@ import { requireTransportRoot, transportName, composeFile } from '../lib/transpo
 import { has } from '../lib/argv.js';
 
 const DEFAULT_IMAGE = process.env.CROSSTALK_IMAGE
-  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.1';
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.3';
 const DEFAULT_API_PORT = Number(process.env.CROSSTALK_API_PORT) || 7000;
 
 function usage(exit = 0) {

package/commands/version.js

@@ -16,6 +16,8 @@ const clientPkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
 export async function run(_argv) {
   process.stdout.write(`crosstalk client: ${clientPkg.version}\n`);
   try {
+    // Skew detection happens passively in api-client.js via the
+    // X-Crosstalk-Engine-Version response header — no duplication here.
     const v = await api.get('/version');
     process.stdout.write(`crosstalkd engine: ${v.version} (alias: ${v.alias})\n`);
   } catch (err) {

package/lib/api-client.js

@@ -11,6 +11,38 @@
 //
 // No auth: the engine binds 127.0.0.1 only and there's no token. Same
 // model as ollama / postgres-on-localhost.
+//
+// Version skew: engine sets X-Crosstalk-Engine-Version on every
+// response. We compare it to the client's package.json version on each
+// call and emit one warning per process if they don't match. Pre-1.0
+// client and engine ship in lockstep; mismatches usually mean the
+// operator upgraded one without the other.
+
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+const CLIENT_VERSION = (() => {
+  try {
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    return JSON.parse(readFileSync(join(thisDir, '..', 'package.json'), 'utf-8')).version;
+  } catch {
+    return 'unknown';
+  }
+})();
+
+let skewWarned = false;
+
+function checkSkew(engineVersion) {
+  if (skewWarned || !engineVersion || engineVersion === CLIENT_VERSION) return;
+  skewWarned = true;
+  process.stderr.write(
+    `[WARN] Version skew: client ${CLIENT_VERSION}, engine ${engineVersion}.\n` +
+    `       Pre-1.0 client and engine ship in lockstep. Likely fix:\n` +
+    `         crosstalk pull && crosstalk restart    # if engine is behind\n` +
+    `         npm install -g @cordfuse/crosstalk     # if client is behind\n\n`,
+  );
+}
 
 export const DEFAULT_API_PORT = 7000;
 
@@ -71,10 +103,13 @@ async function call(method, path, body, opts = {}) {
   } catch (err) {
     throw new ConnectError(port, err.message || String(err));
   }
+  checkSkew(res.headers.get('x-crosstalk-engine-version'));
   return parseJsonOrThrow(res);
 }
 
 export const api = {
-  get: (path, opts) => call('GET', path, undefined, opts),
-  post: (path, body, opts) => call('POST', path, body, opts),
+  get:    (path, opts)        => call('GET',    path, undefined, opts),
+  post:   (path, body, opts)  => call('POST',   path, body,       opts),
+  patch:  (path, body, opts)  => call('PATCH',  path, body,       opts),
+  delete: (path, opts)        => call('DELETE', path, undefined,  opts),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "7.0.0-alpha.1",
+  "version": "7.0.0-alpha.3",
   "description": "Crosstalk client — host-side CLI that talks to the crosstalkd daemon running inside the crosstalk-server container.",
   "type": "module",
   "license": "MIT",