@cordfuse/crosstalk 7.0.0-alpha.9 → 8.0.0-alpha.1

package/lib/resolve.js

@@ -10,14 +10,22 @@
 // identity from the operator's filesystem position). The new model is
 // position-independent — operator can be anywhere on disk.
 
-import { existsSync, readFileSync, mkdirSync, readdirSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { join } from 'path';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { homedir } from 'os';
 
 export const DEFAULT_CONTAINER_NAME = 'crosstalk';
 export const DEFAULT_API_PORT = 7000;
-export const CROSSTALK_LABEL = 'crosstalk.transport=true';
+
+// Client version exported for the skew-warn check in api-client.js. The
+// v7 DEFAULT_IMAGE export (resolved CROSSTALK_IMAGE env or
+// ghcr.io/cordfuse/crosstalk-server:<CLIENT_VERSION>) was removed in
+// v8-native — no container image to pull.
+const _thisDir = dirname(fileURLToPath(import.meta.url));
+const _pkg = JSON.parse(readFileSync(join(_thisDir, '..', 'package.json'), 'utf-8'));
+export const CLIENT_VERSION = _pkg.version;
 
 // Per-OS storage bases. User-mode (default) keeps everything under the
 // operator's home — no sudo/UAC, no Docker Desktop file-sharing allowlist
@@ -42,36 +50,83 @@ export function resolveBase(mode) {
       };
 
   if (mode !== 'user' && mode !== 'system') {
-    throw new Error(`CROSSTALK_STORAGE_MODE='${mode}' invalid — must be 'user' or 'system'.`);
+    throw new Error(`storage mode '${mode}' invalid — must be 'user' or 'system' (see CROSSTALK_USER_MODE).`);
   }
   return bases[mode];
 }
 
+/**
+ * Resolve the runtime mode: 'user' or 'system'.
+ *
+ * v8-native env-var convention: `CROSSTALK_USER_MODE=1` opts into user
+ * mode. Without it, the default is 'system' (matches @cordfuse/llmux's
+ * `LLMUX_USER_MODE` pattern — boolean opt-in to user mode, system is
+ * the production default).
+ *
+ * v7 used `CROSSTALK_STORAGE_MODE=user|system` and defaulted to 'user'.
+ * That string form is still honored for one transition release so
+ * operator scripts don't break instantly — a one-time stderr deprecation
+ * notice fires when it's read. v9 cuts the back-compat path.
+ *
+ * Truthy values for CROSSTALK_USER_MODE: '1', 'true', 'yes' (case
+ * insensitive). Anything else (including '0', 'false', empty) → false.
+ */
 export function storageMode() {
-  return (process.env.CROSSTALK_STORAGE_MODE ?? 'user').toLowerCase();
+  // v7 back-compat path (one transition release).
+  const legacy = process.env.CROSSTALK_STORAGE_MODE;
+  if (legacy !== undefined) {
+    const v = legacy.toLowerCase();
+    if (v === 'user' || v === 'system') {
+      if (!process.env._CROSSTALK_LEGACY_MODE_WARNED) {
+        process.stderr.write(
+          `crosstalk: CROSSTALK_STORAGE_MODE='${v}' is deprecated.\n` +
+          `  Use CROSSTALK_USER_MODE=1 to opt into user mode; otherwise system mode is the default.\n`,
+        );
+        process.env._CROSSTALK_LEGACY_MODE_WARNED = '1';
+      }
+      return v;
+    }
+    throw new Error(`CROSSTALK_STORAGE_MODE='${legacy}' invalid — must be 'user' or 'system'.`);
+  }
+  // v8 path: boolean opt-in to user mode, default system.
+  const userVar = (process.env.CROSSTALK_USER_MODE ?? '').toLowerCase();
+  const userMode = userVar === '1' || userVar === 'true' || userVar === 'yes';
+  return userMode ? 'user' : 'system';
 }
 
-// All storage paths for a given container name, derived from the resolved
+// All storage paths for a given transport name, derived from the resolved
 // base. None of these are validated for existence here — callers check
-// based on context (init pre-creates, up verifies, etc).
+// based on context (init pre-creates, server start verifies, etc).
+//
+// v8-native: `composeFile` retained for transitional reads of legacy
+// state directories (compose-mode upgrades), but no new compose files
+// are generated. `pidFile` and `logFile` are written by the host-spawned
+// engine (now `crosstalk daemon dispatch`) so `crosstalk server status`
+// and `crosstalk server stop` have a single source of truth without
+// querying docker.
 export function storagePaths(name, mode = storageMode()) {
   const base = resolveBase(mode);
   const root = join(base, name);
+  const state = join(root, 'crosstalk-state');
   return {
     base,
     mode,
     storageRoot:    root,
     transportDir:   join(root, 'transport'),
     crosstalkRoot:  join(root, 'crosstalk-root'),
-    crosstalkState: join(root, 'crosstalk-state'),
-    composeFile:    join(root, 'docker-compose.yml'),
+    crosstalkState: state,
+    composeFile:    join(root, 'docker-compose.yml'),  // legacy; not generated by v8
     portFile:       join(root, 'api-port'),
+    pidFile:        join(state, 'crosstalk.pid'),
+    logFile:        join(state, 'crosstalk.log'),
   };
 }
 
-// Container name from --containername flag, defaulting to `crosstalk`.
-// Validates the name is a sane Docker container name + filesystem dir
-// name: lowercase alphanumeric, `_.-`, no leading dot/hyphen.
+// Transport name from --containername (preferred: --name in v8) flag,
+// defaulting to `crosstalk`. The flag is still --containername for now
+// to keep operator muscle memory + scripted invocations working through
+// the v7→v8 transition. Validates the name is sane filesystem dir name:
+// lowercase alphanumeric, `_.-`, no leading dot/hyphen.
 const NAME_RE = /^[a-z0-9][a-z0-9_.-]*$/;
 export function parseContainerName(argv) {
   let name = DEFAULT_CONTAINER_NAME;
@@ -132,37 +187,51 @@ export function pickFreePort(name, mode = storageMode()) {
   throw new Error('Could not find a free port between 7001 and 7999.');
 }
 
-// True if `<base>/<name>/transport/.git` exists. The cheapest signal that
-// a transport has been initialized for this name.
+// True if the transport has been scaffolded for this name. Checks the
+// CROSSTALK-VERSION marker that `daemon init` writes for EVERY transport —
+// git and local-fs alike. (Was '.git', which wrongly rejected no-git local
+// transports: `server start` reported "no transport 'mc'".)
 export function isInitialized(name) {
   const paths = storagePaths(name);
-  return existsSync(join(paths.transportDir, '.git'));
+  return existsSync(join(paths.transportDir, 'CROSSTALK-VERSION'));
 }
 
-// True if a running container exists for this name. Uses Docker as the
-// source of truth, filtered by our label to avoid confusing
-// operator-named-`crosstalk` containers from other workloads.
+// True if the crosstalk engine is running for this transport. Source of truth:
+// the PID file in crosstalk-state/. PID is verified alive with kill(0)
+// (no signal sent, just an EPERM/ESRCH probe). Stale PID files (e.g.,
+// after an unclean shutdown) are treated as not-running and the file is
+// best-effort removed.
+//
+// v8-native: replaces the docker-ps query. The legacy isRunning that
+// shelled out to docker for v7 lifecycle has been removed; if you find
+// a caller that still expects container semantics, it's a leftover from
+// the docker era and should be migrated to PID semantics.
 export function isRunning(name) {
-  const r = spawnSync(
-    'docker',
-    ['ps', '--filter', `label=${CROSSTALK_LABEL}`, '--filter', `name=^${name}$`, '--format', '{{.Names}}'],
-    { encoding: 'utf-8' },
-  );
-  if (r.status !== 0) return false;
-  return r.stdout.trim().split('\n').includes(name);
+  const paths = storagePaths(name);
+  if (!existsSync(paths.pidFile)) return false;
+  let pid;
+  try { pid = Number(readFileSync(paths.pidFile, 'utf-8').trim()); }
+  catch { return false; }
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0); // no-op signal; throws if not alive / not ours
+    return true;
+  } catch {
+    // Stale PID file — sweep it so subsequent start doesn't get confused.
+    try { writeFileSync(paths.pidFile, ''); } catch { /* best effort */ }
+    return false;
+  }
 }
 
-// True if a stopped container exists (less common path; usually `down`
-// removes the container). Checked separately so `up` can decide whether
-// to `docker rm` and recreate.
-export function containerExists(name) {
-  const r = spawnSync(
-    'docker',
-    ['ps', '-a', '--filter', `label=${CROSSTALK_LABEL}`, '--filter', `name=^${name}$`, '--format', '{{.Names}}'],
-    { encoding: 'utf-8' },
-  );
-  if (r.status !== 0) return false;
-  return r.stdout.trim().split('\n').includes(name);
+/** Read the recorded PID for a running transport, or undefined. */
+export function runningPid(name) {
+  const paths = storagePaths(name);
+  if (!existsSync(paths.pidFile)) return undefined;
+  let pid;
+  try { pid = Number(readFileSync(paths.pidFile, 'utf-8').trim()); }
+  catch { return undefined; }
+  if (!Number.isInteger(pid) || pid <= 0) return undefined;
+  try { process.kill(pid, 0); return pid; } catch { return undefined; }
 }
 
 // Look up the resolved name+paths from argv, validate that init has run,
@@ -183,7 +252,7 @@ export function requireInitialized(argv) {
   if (!isInitialized(name)) {
     process.stderr.write(
       `crosstalk: no transport '${name}' on this machine.\n` +
-      `  Run 'crosstalk init${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to set one up.\n`,
+      `  Run 'crosstalk transport init${name === DEFAULT_CONTAINER_NAME ? '' : ` --containername ${name}`}' to set one up.\n`,
     );
     process.exit(2);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@cordfuse/crosstalk",
-  "version": "7.0.0-alpha.9",
-  "description": "Crosstalk client — host-side CLI that talks to the crosstalkd daemon running inside the crosstalk-server container.",
+  "version": "8.0.0-alpha.1",
+  "description": "Crosstalk — agent-agnostic swarm communication protocol over a shared directory (git or filesystem transport). Operator CLI + daemon in one binary.",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/cordfuse/crosstalk",
@@ -14,10 +14,33 @@
   },
   "files": [
     "bin/",
-    "lib/",
     "commands/",
-    "README.md"
+    "lib/",
+    "src/",
+    "template/",
+    "deploy/",
+    "README.md",
+    "GUIDE-CLI.md",
+    "GUIDE-PROMPTS.md"
   ],
+  "scripts": {
+    "build": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "prepack": "cp -r transport template",
+    "postpack": "rm -rf template"
+  },
+  "dependencies": {
+    "@types/ws": "^8.18.1",
+    "node-pty": "^1.1.0",
+    "tsx": "^4.20.0",
+    "ws": "^8.21.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
   "engines": {
     "node": ">=20"
   },

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;
+}