@cordfuse/crosstalk 5.0.0-alpha.7 → 6.0.0-alpha.1

package/bin/crosstalk.js

@@ -2,40 +2,28 @@
 // crosstalk — subcommand dispatcher
 //
 // Walks up from cwd to find a Crosstalk transport (identified by
-// upstream/CROSSTALK-VERSION), then execs tsx against the requested
-// subcommand from the runtime's installed source. All args after the
-// subcommand are forwarded.
-//
-// Examples:
-//   crosstalk attach
-//   crosstalk send --to concierge "hello"
-//   crosstalk dlq --show abc123
-//   crosstalk dispatch
-//
-// init is a special case — it can run outside any transport (it CREATES
-// one). All other subcommands require a transport in the cwd tree.
+// 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).
 
 import { existsSync, statSync } from 'fs';
 import { resolve, join, dirname } from 'path';
 import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
 
 const SUBCOMMANDS = [
-  'dispatch', 'send', 'wake', 'status', 'init', 'dlq',
-  'open', 'channel', 'chat', 'attach', 'upgrade',
+  'dispatch', 'send', 'replies', 'wake', 'status', 'init', 'dlq', 'channel',
+  'chat', 'open', 'attach', 'upgrade',
 ];
-
-// Subcommands that operate outside an existing transport (they create or
-// inspect from anywhere).
 const STANDALONE_SUBCOMMANDS = new Set(['init']);
 
 function findTransportRoot(startDir) {
   let dir = resolve(startDir);
   while (true) {
     const versionFile = join(dir, 'upstream', 'CROSSTALK-VERSION');
-    if (existsSync(versionFile) && statSync(versionFile).isFile()) {
-      return dir;
-    }
+    if (existsSync(versionFile) && statSync(versionFile).isFile()) return dir;
     const parent = dirname(dir);
     if (parent === dir) return null;
     dir = parent;
@@ -44,8 +32,7 @@ function findTransportRoot(startDir) {
 
 function printUsage(exitCode = 0) {
   process.stdout.write(
-    `Usage: crosstalk <subcommand> [args...]\n\n` +
-    `Subcommands:\n` +
+    `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` +
@@ -55,72 +42,41 @@ function printUsage(exitCode = 0) {
 }
 
 const argv = process.argv.slice(2);
+if (argv.length === 0 || argv[0] === '-h' || argv[0] === '--help') printUsage(0);
 
-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);
 }
 
-const subcommand = argv[0];
-const forwardArgs = argv.slice(1);
-
-if (!SUBCOMMANDS.includes(subcommand)) {
-  process.stderr.write(
-    `crosstalk: unknown subcommand '${subcommand}'.\n` +
-    `Available: ${SUBCOMMANDS.join(', ')}\n`,
-  );
-  process.exit(2);
+const cmd = argv[0];
+if (!SUBCOMMANDS.includes(cmd)) {
+  console.error(`crosstalk: unknown subcommand '${cmd}'\n`);
+  printUsage(1);
 }
 
-// Resolve the runtime's source directory (sibling of bin/, both inside
-// the installed @cordfuse/crosstalk package).
-const binDir = dirname(fileURLToPath(import.meta.url));
-const runtimeRoot = dirname(binDir);
-const toolPath = join(runtimeRoot, 'src', `${subcommand}.ts`);
+const thisDir = dirname(fileURLToPath(import.meta.url));
+const srcFile = join(thisDir, '..', 'src', `${cmd}.ts`);
 
-if (!existsSync(toolPath)) {
-  process.stderr.write(
-    `crosstalk: tool source not found at ${toolPath}.\n` +
-    `The @cordfuse/crosstalk installation may be corrupted; try reinstalling.\n`,
-  );
-  process.exit(2);
-}
-
-// For non-standalone subcommands, locate the transport in the cwd tree.
-let workingDir = process.cwd();
-if (!STANDALONE_SUBCOMMANDS.has(subcommand)) {
-  const transportRoot = findTransportRoot(process.cwd());
-  if (!transportRoot) {
-    process.stderr.write(
-      `crosstalk: no transport found in current directory tree.\n` +
-      `Run from inside a directory containing upstream/CROSSTALK-VERSION,\n` +
-      `or use 'crosstalk init <name>' to scaffold a new transport.\n`,
+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);
   }
-  workingDir = transportRoot;
-}
-
-// Strip a single leading `--` separator if present (legacy npm run X -- ergonomics).
-const cleanedArgs = forwardArgs[0] === '--' ? forwardArgs.slice(1) : forwardArgs;
-
-// Resolve tsx directly from the runtime's own bundled node_modules. Going
-// through `npx tsx` was fragile in containers where the entrypoint changes
-// npm's global prefix (the bin shim would lstat the new prefix's lib/
-// directory and fail with ENOENT if tsx wasn't installed there too). Direct
-// invocation of the bundled tsx binary sidesteps the entire npm resolution
-// dance.
-const tsxBin = join(runtimeRoot, 'node_modules', '.bin', 'tsx');
-if (!existsSync(tsxBin)) {
-  process.stderr.write(
-    `crosstalk: bundled tsx not found at ${tsxBin}.\n` +
-    `The @cordfuse/crosstalk installation may be corrupted; try reinstalling.\n`,
-  );
-  process.exit(2);
+  cwd = root;
 }
 
-const result = spawnSync(tsxBin, [toolPath, ...cleanedArgs], {
-  cwd: workingDir,
+const require = createRequire(import.meta.url);
+const tsxCli = require.resolve('tsx/cli');
+const r = spawnSync(process.execPath, [tsxCli, srcFile, ...argv.slice(1)], {
+  cwd,
   stdio: 'inherit',
 });
-
-process.exit(result.status ?? 1);
+process.exit(r.status ?? 1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "5.0.0-alpha.7",
-  "description": "Crosstalk runtime — async messaging between agents over git. The crosstalk CLI plus dispatch, send, attach, chat, and supporting tools.",
+  "version": "6.0.0-alpha.1",
+  "description": "Crosstalk runtime — async messaging between agents over git, across machines.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/cordfuse/crosstalk",
@@ -20,10 +20,10 @@
   "scripts": {
     "build": "tsc --noEmit",
     "lint": "tsc --noEmit",
-    "test": "echo 'No tests yet'"
+    "test": "bun test"
   },
   "dependencies": {
-    "@cordfuse/turnq": "^0.3.4",
+    "@cordfuse/turnq": "^0.4.1",
     "@lydell/node-pty": "^1.2.0-beta.12",
     "tsx": "^4.20.0",
     "yaml": "^2.8.0"

package/src/activation.ts

@@ -0,0 +1,104 @@
+// The activation rule — pure functions, no I/O, exhaustively unit-tested.
+//
+// One rule (CROSSTALK.md "Activation"):
+//
+//   A message wakes its addressee if it has no `re:` (a new task), or its
+//   `re:` points at a message the addressee sent.
+//
+// `re:` is written by the runtime at send time, never inferred at read
+// time. It is a string or a list: a reply that answers a batch of N
+// messages records ALL N relPaths, so no answered message is ever lost to
+// batching.
+
+export interface ActivationMessage {
+  from: string;
+  to: string[];
+  re?: string | string[];
+}
+
+export function recipients(toField: unknown): string[] {
+  if (Array.isArray(toField)) return toField.map(String);
+  if (typeof toField === 'string') return [toField];
+  return [];
+}
+
+export function reList(reField: unknown): string[] {
+  if (Array.isArray(reField)) return reField.map(String);
+  if (typeof reField === 'string') return [reField];
+  return [];
+}
+
+// A recipient is `actor` or `actor@host`.
+export function extractActor(recipient: string): string {
+  const at = recipient.indexOf('@');
+  return at === -1 ? recipient : recipient.slice(0, at);
+}
+
+export function targetHost(recipient: string): string | null {
+  const at = recipient.indexOf('@');
+  return at === -1 ? null : recipient.slice(at + 1);
+}
+
+export interface RoutingResult {
+  addressed: boolean;
+  // Actor was named, but every instance targeted a different host — logged
+  // by the dispatcher so wrong-host routes are visible, never silent.
+  wrongHost: boolean;
+}
+
+export function matchRouting(
+  recipientList: string[],
+  actorName: string,
+  thisHost: string,
+): RoutingResult {
+  let actorNamedAtAll = false;
+  for (const r of recipientList) {
+    if (r === 'all') return { addressed: true, wrongHost: false };
+    if (extractActor(r) !== actorName) continue;
+    actorNamedAtAll = true;
+    const host = targetHost(r);
+    if (host === null || host === thisHost) return { addressed: true, wrongHost: false };
+  }
+  return { addressed: false, wrongHost: actorNamedAtAll };
+}
+
+export type WakeDecision = 'wake' | 'skip' | 'wrong-host';
+
+// `senderOf` resolves a channel relPath to the `from:` of the message there,
+// or undefined if no such message exists. A dangling `re:` entry (target
+// missing) wakes the addressee — fail open so a message is never silently
+// dropped; no loop is possible because the reply to it carries a
+// resolvable `re:`.
+export function decideWake(
+  msg: ActivationMessage,
+  actorName: string,
+  thisHost: string,
+  senderOf: (relPath: string) => string | undefined,
+): WakeDecision {
+  const routing = matchRouting(msg.to, actorName, thisHost);
+  if (!routing.addressed) return routing.wrongHost ? 'wrong-host' : 'skip';
+  if (msg.from === actorName) return 'skip';
+  const targets = reList(msg.re);
+  if (targets.length === 0) return 'wake';
+  for (const target of targets) {
+    const asker = senderOf(target);
+    if (asker === undefined || asker === actorName) return 'wake';
+  }
+  return 'skip';
+}
+
+// Split a channel's pending messages (already sorted by relPath) into
+// contiguous batches sized for the actor's concurrency. Contiguous so each
+// batch's highest relPath is monotone across batches — the cursor advances
+// safely per batch. When pending fits within concurrency, every batch is a
+// single message (parallel fan-out); when it exceeds, batches collapse into
+// ~concurrency invocations (fan-in stays O(1) per actor).
+export function splitForConcurrency<T>(msgs: T[], concurrency: number): T[][] {
+  if (concurrency <= 1 || msgs.length <= 1) return [msgs];
+  const chunkSize = Math.max(1, Math.ceil(msgs.length / concurrency));
+  const out: T[][] = [];
+  for (let i = 0; i < msgs.length; i += chunkSize) {
+    out.push(msgs.slice(i, i + chunkSize));
+  }
+  return out;
+}

package/src/attach.ts

@@ -52,7 +52,7 @@ process.stdout.write(`crosstalk: attaching to ${bin} (operator mode)\n`);
 
 let term;
 try {
-  term = ptySpawn(bin, args, {
+  term = ptySpawn(bin!, args, {
     name: process.env['TERM'] ?? 'xterm-256color',
     cols,
     rows,

package/src/channel.ts

@@ -1,6 +1,9 @@
+// crosstalk channel — create a new channel directory with its CHANNEL.md.
+
 import { mkdirSync, writeFileSync, existsSync } from 'fs';
 import { resolve, join } from 'path';
 import { randomUUID } from 'crypto';
+import { serializeFrontmatter } from './frontmatter.js';
 
 const transportRoot = resolve(process.cwd());
 const argv = process.argv.slice(2);
@@ -13,12 +16,10 @@ function flag(name: string): string | undefined {
 
 const name = flag('--name');
 const parent = flag('--parent');
-const createdBy = flag('--created-by') ?? process.env.USER ?? 'operator';
+const createdBy = flag('--created-by') ?? process.env['USER'] ?? 'operator';
 
 if (!name) {
-  console.error(
-    'Usage: npm run channel -- --name <name> [--parent <parent-uuid>] [--created-by <name>]',
-  );
+  console.error('Usage: crosstalk channel --name <name> [--parent <parent-uuid>] [--created-by <name>]');
   process.exit(1);
 }
 
@@ -37,24 +38,10 @@ const frontmatter: Record<string, unknown> = {
   created_by: createdBy,
   created_at: new Date().toISOString(),
 };
-if (parent) frontmatter.parent = parent;
-
-const lines = ['---'];
-for (const [k, v] of Object.entries(frontmatter)) {
-  lines.push(`${k}: ${v}`);
-}
-lines.push('---');
-lines.push('');
-lines.push(`# ${name}`);
-lines.push('');
-if (parent) {
-  lines.push(`Subchannel of \`${parent}\`.`);
-} else {
-  lines.push('Channel description goes here.');
-}
-lines.push('');
+if (parent) frontmatter['parent'] = parent;
 
-writeFileSync(join(dir, 'CHANNEL.md'), lines.join('\n'));
+const body = `# ${name}\n\n${parent ? `Subchannel of \`${parent}\`.` : 'Channel description goes here.'}\n`;
+writeFileSync(join(dir, 'CHANNEL.md'), serializeFrontmatter(frontmatter, body));
 
 console.log(`Created channel: ${uuid}`);
 console.log(`  name: ${name}`);

package/src/chat.ts

@@ -1,32 +1,32 @@
-// Participate in a crosstalk channel as a regular human, without
-// invoking any agent CLI locally. Sends messages by writing + committing
-// + pushing to the channel; polls the channel for replies addressed to
-// the operator; displays them.
+// crosstalk chat — participate in a channel as a human, without invoking
+// any agent CLI locally. Sends messages by writing + committing + pushing
+// to the channel; polls for the reply whose re: points back at the sent
+// message; displays it.
 //
-// Use this when a deployed crosstalk-server (or any other dispatcher) is
-// running against the transport and you want to chat with the dispatched
-// actors from a clean local clone. No Claude install needed locally, no
-// OAuth, no docker exec.
+// Use this when a dispatcher (local daemon, deployed crosstalk-server,
+// a peer's machine) is running against the transport and you want to chat
+// with the dispatched actors from a clean local clone. No agent CLI
+// needed locally, no auth.
 //
 // Difference from `open`:
 //   - `open` spawns the actor's CLI LOCALLY — needs claude/etc. installed,
 //     needs auth, doesn't use any remote dispatcher.
 //   - `chat` just produces messages and waits for the channel to fill in
-//     replies. Whatever's processing the channel (a container, a remote
-//     dispatcher, a peer) handles the work.
+//     replies. Whatever's processing the channel handles the work.
 //
 // Usage:
-//   npm run chat -- --channel <uuid> --to <actor> [--as <name>] [--tier <name>]
-//   npm run chat -- --channel <uuid> --to concierge --as steve
+//   crosstalk chat --channel <uuid> --to <actor> [--as <name>] [--tier <name>]
+//   crosstalk chat --channel <uuid> --to concierge --as steve
 
 import { resolve, join } from 'path';
-import { mkdirSync, writeFileSync, readdirSync, readFileSync, statSync, existsSync } from 'fs';
+import { mkdirSync, writeFileSync } from 'fs';
 import { createInterface } from 'readline/promises';
-import { spawnSync } from 'child_process';
 import { now, messageFilename } from './filenames.js';
-import { serializeFrontmatter, parseFrontmatter } from './frontmatter.js';
-import { gitCommitAndPush } from './transport.js';
+import { serializeFrontmatter } from './frontmatter.js';
+import { gitPull, gitCommitAndPush, listChannelMessages, ChannelMessage } from './transport.js';
+import { reList } from './activation.js';
 import { withLock } from './turnq.js';
+import { sendWakeSignal } from './state.js';
 
 const transportRoot = resolve(process.cwd());
 const argv = process.argv.slice(2);
@@ -39,119 +39,55 @@ function flag(name: string): string | undefined {
 
 const channelUuid = flag('--channel');
 const toActor = flag('--to');
-const fromName = flag('--as') ?? process.env.USER ?? 'steve';
+const fromName = flag('--as') ?? process.env['USER'] ?? 'operator';
 const tier = flag('--tier');
 const pollSeconds = Number(flag('--poll')) || 5;
 const replyTimeoutSeconds = Number(flag('--timeout')) || 600;
 
 if (!channelUuid || !toActor) {
   console.error(
-    'Usage: npm run chat -- --channel <uuid> --to <actor> [--as <name>] [--tier <name>] [--poll <seconds>] [--timeout <seconds>]',
+    'Usage: crosstalk chat --channel <uuid> --to <actor> [--as <name>] [--tier <name>] [--poll <seconds>] [--timeout <seconds>]',
   );
   process.exit(1);
 }
 
-interface ScannedMessage {
-  relPath: string;
-  ts: number;
-  from: string;
-  to: string[];
-  type: string;
-  body: string;
-}
-
-function recipients(toField: unknown): string[] {
-  if (Array.isArray(toField)) return toField.map(String);
-  if (typeof toField === 'string') return [toField];
-  return [];
-}
-
-function scanChannelMessages(): ScannedMessage[] {
-  const channelDir = join(transportRoot, 'data', 'channels', channelUuid!);
-  if (!existsSync(channelDir)) return [];
-  const results: ScannedMessage[] = [];
-  const walk = (dir: string, prefix: string): void => {
-    let entries: string[];
-    try { entries = readdirSync(dir); } catch { return; }
-    for (const entry of entries) {
-      const full = join(dir, entry);
-      const rel = prefix ? `${prefix}/${entry}` : entry;
-      let stat;
-      try { stat = statSync(full); } catch { continue; }
-      if (stat.isDirectory()) {
-        walk(full, rel);
-      } else if (entry.endsWith('.md') && entry !== 'CHANNEL.md') {
-        try {
-          const raw = readFileSync(full, 'utf-8');
-          const { data, body } = parseFrontmatter(raw);
-          const from = typeof data.from === 'string' ? data.from : '';
-          const type = typeof data.type === 'string' ? data.type : '';
-          const timestamp = typeof data.timestamp === 'string' ? data.timestamp : '';
-          if (!from || !type || !timestamp) continue;
-          results.push({
-            relPath: rel,
-            ts: new Date(timestamp).getTime(),
-            from,
-            to: recipients(data.to),
-            type,
-            body,
-          });
-        } catch { /* skip unparseable */ }
-      }
-    }
+async function sendMessage(body: string): Promise<string> {
+  const ts = now();
+  const dir = join(transportRoot, 'data', 'channels', channelUuid!, ts.pathDate);
+  mkdirSync(dir, { recursive: true });
+  const frontmatter: Record<string, unknown> = {
+    from: fromName,
+    to: toActor!,
+    type: 'text',
+    timestamp: ts.iso,
   };
-  walk(channelDir, '');
-  return results.sort((a, b) => a.ts - b.ts);
-}
+  if (tier) frontmatter['tier'] = tier;
+  const filename = messageFilename(ts);
+  writeFileSync(join(dir, filename), serializeFrontmatter(frontmatter, body));
 
-function gitPullQuiet(): boolean {
-  const r = spawnSync('git', ['pull', '--rebase', '--quiet'], {
-    cwd: transportRoot,
-    encoding: 'utf-8',
-  });
-  return r.status === 0;
-}
-
-async function sendMessage(body: string): Promise<void> {
-  await withLock('dispatch', async () => {
-    const ts = now();
-    const dir = join(transportRoot, 'data', 'channels', channelUuid!, ts.pathDate);
-    mkdirSync(dir, { recursive: true });
-    const frontmatter: Record<string, unknown> = {
-      from: fromName,
-      to: toActor!,
-      type: 'text',
-      timestamp: ts.iso,
-    };
-    if (tier) frontmatter.tier = tier;
-    const content = serializeFrontmatter(frontmatter, body);
-    writeFileSync(join(dir, messageFilename(ts)), content);
-
-    const r = gitCommitAndPush(
+  const r = await withLock(transportRoot, 'git', async () =>
+    gitCommitAndPush(
       transportRoot,
       `chat: ${fromName} -> ${toActor} in ${channelUuid!.slice(0, 8)}`,
-    );
-    if (!r.ok && r.error) {
-      // Same anti-pattern as send.ts: writing to errors/ from an operator-
-      // side command dirties the working tree and breaks subsequent
-      // git pull --rebase. Stay on stderr only.
-      const kind = r.committed ? 'push' : 'commit';
-      console.error(`(${kind} failed: ${r.error.slice(0, 200)} — message is local-only)`);
-    }
-  });
+    ),
+  );
+  sendWakeSignal(transportRoot);
+  if (!r.ok && r.error) {
+    const kind = r.committed ? 'push' : 'commit';
+    console.error(`(${kind} failed: ${r.error.slice(0, 200)} — message is local-only)`);
+  }
+  return `${ts.pathDate}/${filename}`;
 }
 
-async function waitForReplyAfter(thresholdTs: number): Promise<ScannedMessage | null> {
+// A reply is the message whose re: list contains the relPath we sent —
+// recorded by the dispatcher at write time, so the match is exact, not a
+// timestamp/addressing heuristic.
+async function waitForReplyTo(sentRelPath: string): Promise<ChannelMessage | null> {
   const deadline = Date.now() + replyTimeoutSeconds * 1_000;
   while (Date.now() < deadline) {
-    gitPullQuiet();
-    const messages = scanChannelMessages();
-    const reply = messages.find(
-      (m) =>
-        m.ts > thresholdTs &&
-        m.type === 'text' &&
-        m.from === toActor &&
-        m.to.includes(fromName),
+    gitPull(transportRoot);
+    const reply = listChannelMessages(transportRoot, channelUuid!).find((m) =>
+      reList(m.data['re']).includes(sentRelPath),
     );
     if (reply) return reply;
     await new Promise((r) => setTimeout(r, pollSeconds * 1_000));
@@ -183,11 +119,10 @@ async function main(): Promise<void> {
       const trimmed = userMsg.trim();
       if (!trimmed) continue;
 
-      const sentAt = Date.now();
-      await sendMessage(trimmed);
+      const sentRelPath = await sendMessage(trimmed);
       process.stdout.write(`(waiting for ${toActor}…) `);
 
-      const reply = await waitForReplyAfter(sentAt);
+      const reply = await waitForReplyTo(sentRelPath);
       if (!reply) {
         console.log(
           `\n(no reply within ${replyTimeoutSeconds}s — give up and try again, or check dispatch state)\n`,
@@ -195,11 +130,13 @@ async function main(): Promise<void> {
         continue;
       }
       process.stdout.write('\r' + ' '.repeat(40) + '\r');
-      console.log(`${toActor}> ${reply.body}\n`);
+      const replyFrom = typeof reply.data['from'] === 'string' ? reply.data['from'] : toActor;
+      console.log(`${replyFrom}> ${reply.body}\n`);
     }
   } finally {
     rl.close();
   }
+  process.exit(0);
 }
 
 main();