@cordfuse/crosstalk 7.0.0-alpha.2 → 7.0.0-alpha.4

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

@@ -24,13 +24,63 @@
 
 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'];
-// 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<>"']+/;
+
+// URL extraction that survives agent TUI rendering. Naive regex against
+// raw stdout fails because agent CLIs (Claude in particular) draw a box
+// around the URL with line wraps every ~N chars; the captured URL is
+// truncated at the first wrap, with ANSI control chars leaking in at
+// the cut point. Real example from alpha.3 macOS test: extracted URL
+// ended with `%18%6b…` (CAN char + box-drawing artifact) instead of
+// the `redirect_uri=…` param, breaking OAuth.
+//
+// Approach:
+//   1. ANSI-strip everything (CSI / OSC / SS3 escapes).
+//   2. Strip control chars (0x00-0x1F except LF, plus DEL).
+//   3. Join line wraps that occur INSIDE a URL-safe character run —
+//      `<url-char>\n<url-char>` → `<url-char><url-char>`. Preserves real
+//      `<url-char>\n<non-url-char>` boundaries.
+//   4. Match `https?://<url-chars>+` against the joined buffer.
+//   5. Only fire when the character AFTER the matched URL is a true
+//      terminator (whitespace, end-of-buffer) — guards against acting
+//      on a partial URL still being written.
+
+const URL_SAFE_CLASS = "a-zA-Z0-9%/?#&=+\\-._~:@!$()*,;";
+const URL_RE = new RegExp(`https?://[${URL_SAFE_CLASS}]+`);
+
+function extractCompleteUrl(rawBuffer) {
+  // Strip ANSI CSI escapes (\x1B[ ... terminator).
+  let clean = rawBuffer.replace(/\x1B\[[0-9;?]*[a-zA-Z]/g, '');
+  // Strip ANSI OSC escapes (\x1B] ... BEL or ST).
+  clean = clean.replace(/\x1B\][^\x07\x1B]*(?:\x07|\x1B\\)/g, '');
+  // Strip SS3 escapes (\x1BO + one char).
+  clean = clean.replace(/\x1BO./g, '');
+  // Strip remaining single-char escapes that slipped through.
+  clean = clean.replace(/\x1B[^a-zA-Z0-9]/g, '');
+  // Strip control chars except LF (0x0A); we use LF for line-wrap rejoin.
+  clean = clean.replace(/[\x00-\x09\x0B-\x1F\x7F]/g, '');
+  // Rejoin URL-character wrap points: `<url-char>\n<url-char>` becomes
+  // `<url-char><url-char>`. Doesn't merge `<url-char>\n<space>` etc.
+  const safeRe = new RegExp(`[${URL_SAFE_CLASS}]\\n[${URL_SAFE_CLASS}]`, 'g');
+  let prev;
+  do {
+    prev = clean;
+    clean = clean.replace(safeRe, (m) => m[0] + m[2]);
+  } while (clean !== prev);
+
+  const match = clean.match(URL_RE);
+  if (!match) return null;
+  // Require a terminator after the URL — without it, the URL may still
+  // be growing in subsequent stdout chunks. Terminator = whitespace,
+  // quote/angle, or end-of-buffer-with-trailing-newline.
+  const after = clean.slice(match.index + match[0].length);
+  if (after.length === 0) return null;       // EOF-as-grow case, wait
+  if (!/^[\s<>"']/.test(after)) return null; // URL still continuing
+  return match[0];
+}
 
 function openInBrowser(url) {
   const cmd =
@@ -106,27 +156,29 @@ function runLogin(container, agent) {
   //
   // 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.
+  // automatically for every agent we support.
+  //
+  // No COLUMNS=1000 env: making the agent render the URL "unwrapped" via
+  // a wide terminal claim doesn't reliably propagate to the in-container
+  // PTY, and even when it does Claude's TUI hard-wraps anyway. The
+  // extractCompleteUrl() function joins wrapped URL fragments on the
+  // host side, so the agent's rendering width is irrelevant. As bonus,
+  // dropping COLUMNS=1000 fixes daily-chat soft-wrap weirdness in
+  // long-form prose (agents see the real host terminal width).
   return new Promise((resolve) => {
     const child = spawn(
       'docker',
-      [
-        'exec', '-it',
-        '--env', 'COLUMNS=1000', // fallback for browser-open failure
-        '--env', 'LINES=40',
-        container,
-        agent,
-      ],
+      ['exec', '-it', container, agent],
       { stdio: ['inherit', 'pipe', 'inherit'] },
     );
     let opened = false;
+    let buffer = '';
     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];
+      buffer += chunk.toString();
+      const url = extractCompleteUrl(buffer);
+      if (!url) return;
       opened = true;
       const ok = openInBrowser(url);
       process.stdout.write(
@@ -152,10 +204,33 @@ export async function run(argv) {
 
   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 (containers can have ` +
-      `multiple agent CLIs installed; pick one explicitly).\n` +
-      `Supported: ${KNOWN_AGENTS.join(', ')}\n`,
+      `crosstalk chat: --agent <name> is required.\n  ${list}\n`,
     );
     return 1;
   }

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.2';
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.4';
 
 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.2 -f server/Dockerfile .
+    docker build -t crosstalk-server:7.0.0-alpha.4 -f server/Dockerfile .
   Then run:
-    CROSSTALK_IMAGE=crosstalk-server:7.0.0-alpha.2 crosstalk init mytransport
+    CROSSTALK_IMAGE=crosstalk-server:7.0.0-alpha.4 crosstalk init mytransport
 `,
   );
   process.exit(exit);

package/commands/status.js

@@ -18,7 +18,22 @@ export async function run(_argv) {
 
   process.stdout.write(`Claimed models: ${s.claimed_models.length}\n`);
   if (s.claimed_models.length === 0) {
-    process.stdout.write('  (no model CLIs found inside the container — install one or edit data/models.yaml)\n');
+    // Two failure shapes look the same in claimed_models=0: (a) no CLIs
+    // installed at all, (b) CLIs installed but data/models.yaml has no
+    // entries referencing them. Ask /agents/installed to distinguish so
+    // the operator gets a directly-actionable hint.
+    let installed = null;
+    try {
+      const r = await api.get('/agents/installed');
+      installed = r.installed;
+    } catch { /* ignore — fall back to generic message */ }
+    if (installed && installed.length > 0) {
+      process.stdout.write(
+        `  (${installed.join(', ')} installed in the container but no data/models.yaml entry references them — add one to claim)\n`,
+      );
+    } else {
+      process.stdout.write('  (no model CLIs found inside the container — install one via `crosstalk chat --shell` and add an entry to data/models.yaml)\n');
+    }
   } else {
     for (const m of s.claimed_models) process.stdout.write(`  - ${m}\n`);
   }

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.2';
+  ?? 'ghcr.io/cordfuse/crosstalk-server:7.0.0-alpha.4';
 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.2",
+  "version": "7.0.0-alpha.4",
   "description": "Crosstalk client — host-side CLI that talks to the crosstalkd daemon running inside the crosstalk-server container.",
   "type": "module",
   "license": "MIT",