@cordfuse/crosstalkd 7.0.0-alpha.1

package/src/run.ts

@@ -0,0 +1,236 @@
+// crosstalkd run — dispatch a primitive or workflow.
+//
+// Primitive: write one or N (fanout) identical messages addressed to
+//   <model>[@<machine>] with an optional --as persona. Body comes from
+//   inline arg, file path, or stdin (`-`).
+//
+// Workflow: read a workflow document (file path or stdin `-`), parse
+//   its frontmatter (only `type: workflow` is required). Auto-create a
+//   child channel parented to the operator's current channel, then write
+//   the workflow doc as a marker message in the parent channel addressed
+//   to the reserved recipient `workflow`. The dispatcher's workflowTick
+//   (workflow.ts) handles execution: compile-pass → fanout → synthesize
+//   → route. No model is invoked through the activation loop for the
+//   marker itself.
+//
+// `re:` is the activation story (CROSSTALK.md "Activation"):
+//   inside a dispatched turn, CROSSTALK_DISPATCH_RE carries the relPath(s)
+//   of the message(s) being answered; run() links them automatically.
+//   `--new` suppresses that. Operators (no env) always send new tasks.
+
+import { resolve, join, basename, extname } from 'path';
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { now, messageFilename } from './filenames.js';
+import { parseFrontmatter, serializeFrontmatter } from './frontmatter.js';
+import { gitCommitAndPush, discoverChannels } from './transport.js';
+import { sendWakeSignal, readHeartbeat } from './state.js';
+
+const transportRoot = resolve(process.cwd());
+const argv = process.argv.slice(2);
+
+function flag(name: string): string | undefined {
+  const i = argv.indexOf(name);
+  if (i === -1 || i === argv.length - 1) return undefined;
+  return argv[i + 1];
+}
+
+function readStdin(): string {
+  try {
+    return readFileSync(0, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function resolveBody(arg: string | undefined): string {
+  if (arg == null) {
+    throw new Error('crosstalkd run: missing body argument (file path, inline string, or `-` for stdin)');
+  }
+  if (arg === '-') return readStdin();
+  if (existsSync(arg)) {
+    try {
+      if (statSync(arg).isFile()) return readFileSync(arg, 'utf-8');
+    } catch { /* fall through to inline */ }
+  }
+  return arg;
+}
+
+function autoChannel(): string {
+  const channels = discoverChannels(transportRoot);
+  if (channels.length === 1) return channels[0]!;
+  if (channels.length === 0) {
+    console.error("crosstalkd run: no channels found. Create one with 'crosstalkd channel <name>'.");
+    process.exit(1);
+  }
+  console.error('crosstalkd run: multiple channels found — specify one with --channel <uuid>.');
+  console.error("  Run 'crosstalkd status' to list channels.");
+  process.exit(1);
+}
+
+function reTargets(isNew: boolean): string[] {
+  return (isNew ? '' : process.env['CROSSTALK_DISPATCH_RE'] ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function defaultFrom(): string {
+  return process.env['CROSSTALK_DISPATCH_ACTOR']
+    ?? process.env['USER']
+    ?? 'operator';
+}
+
+interface WriteOptions {
+  channelUuid: string;
+  from: string;
+  to: string;
+  as?: string;
+  body: string;
+  re: string[];
+  extraFrontmatter?: Record<string, unknown>;
+  workflow?: boolean;
+}
+
+function writeMessage(opts: WriteOptions): string {
+  const ts = now();
+  const dir = join(transportRoot, 'data', 'channels', opts.channelUuid, ts.pathDate);
+  mkdirSync(dir, { recursive: true });
+
+  const fm: Record<string, unknown> = {
+    from: opts.from,
+    to: opts.to,
+    timestamp: ts.iso,
+  };
+  if (opts.as) fm['as'] = opts.as;
+  if (opts.workflow) fm['type'] = 'workflow';
+  if (opts.re.length === 1) fm['re'] = opts.re[0];
+  else if (opts.re.length > 1) fm['re'] = opts.re;
+  if (opts.extraFrontmatter) Object.assign(fm, opts.extraFrontmatter);
+
+  const filename = messageFilename(ts);
+  writeFileSync(join(dir, filename), serializeFrontmatter(fm, opts.body));
+  return join(ts.pathDate, filename);
+}
+
+function createChildChannel(parentUuid: string, derivedName: string): string {
+  const childUuid = randomUUID();
+  const channelDir = join(transportRoot, 'data', 'channels', childUuid);
+  mkdirSync(channelDir, { recursive: true });
+  const channelMd = serializeFrontmatter(
+    { name: derivedName, parent: parentUuid },
+    '',
+  );
+  writeFileSync(join(channelDir, 'CHANNEL.md'), channelMd);
+  return childUuid;
+}
+
+async function runPrimitive(): Promise<void> {
+  const to = flag('--to');
+  const as = flag('--as');
+  const fanoutRaw = flag('--fanout');
+  const fanout = fanoutRaw ? Math.max(1, parseInt(fanoutRaw, 10)) : 1;
+  const isNew = argv.includes('--new');
+  const from = flag('--from') ?? defaultFrom();
+  const bodyArg = argv[argv.length - 1];
+
+  if (!to || !bodyArg || bodyArg.startsWith('--')) {
+    console.error(
+      'Usage: crosstalkd run --type primitive --to <model>[@<machine>] [--as <actor>] [--fanout <n>] [--channel <uuid>] <body|file|->',
+    );
+    process.exit(1);
+  }
+
+  const body = resolveBody(bodyArg);
+  const channelUuid = flag('--channel') ?? process.env['CROSSTALK_DISPATCH_CHANNEL'] ?? autoChannel();
+  const re = reTargets(isNew);
+  const relPaths: string[] = [];
+  for (let i = 0; i < fanout; i++) {
+    relPaths.push(writeMessage({ channelUuid, from, to, as, body, re }));
+  }
+
+  const commitMsg = fanout === 1
+    ? `run: ${from} -> ${to} in ${channelUuid.slice(0, 8)}`
+    : `run: ${from} -> ${to} x${fanout} in ${channelUuid.slice(0, 8)}`;
+  const push = gitCommitAndPush(transportRoot, commitMsg);
+  sendWakeSignal(transportRoot);
+  if (!push.ok && push.error) {
+    console.error(`Wrote ${relPaths.length} locally:`);
+    for (const p of relPaths) console.error(`  ${p}`);
+    console.error(`but git ${push.committed ? 'push' : 'commit'} FAILED: ${push.error.slice(0, 300)}`);
+    process.exit(3);
+  }
+  for (const p of relPaths) console.log(`Sent: ${p}${re.length ? ` (re: ${re.join(', ')})` : ''}`);
+}
+
+async function runWorkflow(): Promise<void> {
+  const bodyArg = argv[argv.length - 1];
+  if (!bodyArg || bodyArg.startsWith('--')) {
+    console.error('Usage: crosstalkd run --type workflow [--channel <uuid>] <file|->');
+    process.exit(1);
+  }
+  const raw = resolveBody(bodyArg);
+  const parsed = parseFrontmatter<Record<string, unknown>>(raw);
+  const declaredType = parsed.data['type'];
+
+  if (declaredType !== 'workflow') {
+    console.error(`crosstalkd run --type workflow: document must declare 'type: workflow' in frontmatter (got: ${String(declaredType)})`);
+    process.exit(1);
+  }
+
+  const parentUuid = flag('--channel') ?? process.env['CROSSTALK_DISPATCH_CHANNEL'] ?? autoChannel();
+  const derivedName = bodyArg === '-' ? `workflow-${Date.now()}` : basename(bodyArg, extname(bodyArg));
+  const childUuid = createChildChannel(parentUuid, derivedName);
+  const from = flag('--from') ?? defaultFrom();
+  const re = reTargets(argv.includes('--new'));
+
+  // The marker is addressed to the reserved recipient `workflow`. The
+  // dispatcher's activation loop never wakes a model for it — workflowTick
+  // (workflow.ts) processes it directly: compile-pass → fanout → synthesize
+  // → final reply routed back here with re: <markerRelPath>.
+  //
+  // Multi-host ownership: record dispatch_host so that exactly one
+  // dispatcher progresses this workflow's phases. Without ownership, two
+  // dispatchers ticking inside the same poll window would both compile,
+  // both fan out, and rebase-conflict on PLAN.json. Owner = the alias of
+  // the dispatcher whose heartbeat lives in this machine's state dir.
+  // Falls back to no-ownership when there's no local dispatcher running
+  // (single-host single-machine case — any dispatcher that joins later
+  // claims the workflow).
+  const heartbeat = readHeartbeat(transportRoot);
+  const dispatchHost = heartbeat?.alias;
+  const extraFrontmatter: Record<string, unknown> = { child_channel: childUuid };
+  if (dispatchHost) extraFrontmatter['dispatch_host'] = dispatchHost;
+  const relPath = writeMessage({
+    channelUuid: parentUuid,
+    from,
+    to: 'workflow',
+    body: parsed.body,
+    re,
+    extraFrontmatter,
+    workflow: true,
+  });
+
+  const push = gitCommitAndPush(transportRoot, `run(workflow): ${from} child ${childUuid.slice(0, 8)}`);
+  sendWakeSignal(transportRoot);
+  if (!push.ok && push.error) {
+    console.error(`Wrote workflow locally: ${relPath}`);
+    console.error(`Child channel: ${childUuid}`);
+    console.error(`but git ${push.committed ? 'push' : 'commit'} FAILED: ${push.error.slice(0, 300)}`);
+    process.exit(3);
+  }
+  console.log(`Workflow dispatched: ${relPath}`);
+  console.log(`Child channel: ${childUuid} (parent: ${parentUuid.slice(0, 8)})`);
+}
+
+async function main(): Promise<void> {
+  const type = flag('--type');
+  if (type !== 'primitive' && type !== 'workflow') {
+    console.error("Usage: crosstalkd run --type <primitive|workflow> [flags] <body|file|->");
+    process.exit(1);
+  }
+  if (type === 'primitive') await runPrimitive();
+  else await runWorkflow();
+}
+
+main();

package/src/state.ts

@@ -0,0 +1,159 @@
+// Machine-local dispatcher state. NONE of this lives in the transport repo —
+// the repo carries conversation; each machine carries its own progress
+// through it. That separation is what makes the dispatcher's git operations
+// conflict-free: its commits only ever contain data/ (messages).
+//
+// v7 layout under the state dir (four files, no subdirectories):
+//   dispatcher.pid    — PID of the running dispatcher process
+//   cursor            — last-scanned git commit hash (single global cursor)
+//   heartbeat         — last tick timestamp + pid + version (JSON)
+//   wake.signal       — touched to wake the dispatch loop
+//   errors.log        — infra failures, JSONL, append-only (best-effort)
+//
+// Location: $CROSSTALK_STATE_DIR if set (exact dir — container-friendly),
+// else ~/.config/crosstalk/state/<basename(transportRoot)>/. v6 used a
+// hashed-origin-URL dir under ~/.local/state; v7 uses the working tree's
+// directory name for operator readability. Operators with two clones of
+// the same transport get two state dirs — acceptable; different working
+// trees may have genuinely different progress through the conversation.
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  appendFileSync,
+} from 'fs';
+import { join, basename } from 'path';
+import { homedir } from 'os';
+
+const resolved = new Map<string, string>();
+
+export function stateDir(transportRoot: string): string {
+  const cached = resolved.get(transportRoot);
+  if (cached) return cached;
+  let dir = process.env['CROSSTALK_STATE_DIR'];
+  if (!dir) {
+    dir = join(homedir(), '.config', 'crosstalk', 'state', basename(transportRoot));
+  }
+  mkdirSync(dir, { recursive: true });
+  resolved.set(transportRoot, dir);
+  return dir;
+}
+
+// ── cursor (single, machine-global) ──
+//
+// A cursor is the git commit hash the transport was last scanned at. NOT a
+// message relPath: filenames order by sender timestamp, but messages reach
+// origin in PUSH order — a message that loses a push race can land on
+// origin with a timestamp earlier than one already processed, and a
+// relPath cursor would skip it forever. Commit-based cursors can't.
+//
+// v6 kept one cursor per (actor × channel). v7 collapses to a single
+// machine-global cursor: a dispatcher processes everything new since the
+// cursor in one tick, regardless of channel or claimed model.
+
+const VALID_CURSOR = /^[0-9a-f]{40}$/;
+
+export function cursorPath(transportRoot: string): string {
+  return join(stateDir(transportRoot), 'cursor');
+}
+
+export function readCursor(transportRoot: string): string | null {
+  const p = cursorPath(transportRoot);
+  if (!existsSync(p)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(p, 'utf-8').trim();
+  } catch (err) {
+    logError(transportRoot, `cursor read failed: ${(err as Error).message}`);
+    return null;
+  }
+  if (raw.length === 0) return null;
+  if (!VALID_CURSOR.test(raw)) {
+    logError(transportRoot, `invalid cursor '${raw.slice(0, 80)}' — re-scanning from origin`);
+    return null;
+  }
+  return raw;
+}
+
+export function writeCursor(transportRoot: string, commit: string): void {
+  writeFileSync(cursorPath(transportRoot), commit + '\n');
+}
+
+// ── pidfile ──
+
+export function pidfilePath(transportRoot: string): string {
+  return join(stateDir(transportRoot), 'dispatcher.pid');
+}
+
+export function writePidfile(transportRoot: string): void {
+  try {
+    writeFileSync(pidfilePath(transportRoot), `${process.pid}\n`);
+  } catch { /* best-effort */ }
+}
+
+export function removePidfile(transportRoot: string): void {
+  try {
+    unlinkSync(pidfilePath(transportRoot));
+  } catch { /* already gone */ }
+}
+
+export function readPidfile(transportRoot: string): number | null {
+  try {
+    const raw = readFileSync(pidfilePath(transportRoot), 'utf-8').trim();
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── heartbeat + wake ──
+
+export function writeHeartbeat(transportRoot: string, version: string, alias?: string): void {
+  try {
+    const data: Record<string, unknown> = { ts: new Date().toISOString(), pid: process.pid, version };
+    if (alias) data['alias'] = alias;
+    writeFileSync(join(stateDir(transportRoot), 'heartbeat'), JSON.stringify(data) + '\n');
+  } catch { /* best-effort */ }
+}
+
+export function readHeartbeat(
+  transportRoot: string,
+): { ts: string; pid: number; version: string; alias?: string } | null {
+  try {
+    return JSON.parse(readFileSync(join(stateDir(transportRoot), 'heartbeat'), 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export function wakeSignalPath(transportRoot: string): string {
+  return join(stateDir(transportRoot), 'wake.signal');
+}
+
+export function sendWakeSignal(transportRoot: string): void {
+  try {
+    writeFileSync(wakeSignalPath(transportRoot), `${Date.now()}\n`);
+  } catch { /* best-effort */ }
+}
+
+// ── error log — infra failures, JSONL append, best-effort ──
+
+export function logError(transportRoot: string, message: string): void {
+  try {
+    const line = JSON.stringify({ ts: new Date().toISOString(), message: message.slice(0, 500) });
+    appendFileSync(join(stateDir(transportRoot), 'errors.log'), line + '\n');
+  } catch { /* best-effort */ }
+}
+
+export function countErrors(transportRoot: string): number {
+  try {
+    const raw = readFileSync(join(stateDir(transportRoot), 'errors.log'), 'utf-8');
+    return raw.split('\n').filter((l) => l.trim().length > 0).length;
+  } catch {
+    return 0;
+  }
+}

package/src/status.ts

@@ -0,0 +1,84 @@
+// crosstalkd status — transport + dispatcher health at a glance.
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { resolve, join } from 'path';
+import { discoverChannels } from './transport.js';
+import { stateDir, readCursor, readHeartbeat, countErrors } from './state.js';
+import { loadRegistry } from './models.js';
+
+const transportRoot = resolve(process.cwd());
+
+const versionFile = join(transportRoot, 'CROSSTALK-VERSION');
+const protocolVersion = existsSync(versionFile)
+  ? readFileSync(versionFile, 'utf-8').trim()
+  : '(missing)';
+
+console.log(`Crosstalk transport: ${transportRoot}`);
+console.log(`Protocol version:    ${protocolVersion}`);
+console.log(`Machine state dir:   ${stateDir(transportRoot)}`);
+console.log('');
+
+try {
+  const registry = loadRegistry(transportRoot);
+  console.log(`Models in registry: ${registry.all.size}`);
+  console.log(`Claimed on this machine: ${registry.claimed.size}`);
+  if (registry.claimed.size > 0) {
+    for (const name of registry.claimed.keys()) {
+      console.log(`  - ${name}`);
+    }
+  } else {
+    console.log('  (no model CLIs found on PATH — install one or edit data/models.yaml)');
+  }
+} catch (err) {
+  console.log(`Models: ERROR — ${(err as Error).message}`);
+}
+
+console.log('');
+
+const hb = readHeartbeat(transportRoot);
+if (hb) {
+  const ageS = Math.floor((Date.now() - new Date(hb.ts).getTime()) / 1000);
+  const label = ageS < 120 ? 'LIVE' : ageS > 300 ? 'STALE' : 'idle';
+  console.log(`Dispatch heartbeat: ${label} (pid ${hb.pid}, last tick ${ageS}s ago, ${hb.version})`);
+} else {
+  console.log('Dispatch heartbeat: never (no dispatch has run on this machine)');
+}
+
+const cursor = readCursor(transportRoot);
+if (cursor) {
+  console.log(`Cursor: ${cursor.slice(0, 12)} (global, machine-local)`);
+} else {
+  console.log('Cursor: (none yet — first tick will seed to HEAD)');
+}
+
+console.log('');
+
+const channels = discoverChannels(transportRoot);
+console.log(`Channels: ${channels.length}`);
+for (const ch of channels) {
+  const channelDir = join(transportRoot, 'data', 'channels', ch);
+  let name = '(no CHANNEL.md)';
+  let parent: string | null = null;
+  const chPath = join(channelDir, 'CHANNEL.md');
+  if (existsSync(chPath)) {
+    const raw = readFileSync(chPath, 'utf-8');
+    const nameMatch = raw.match(/^name:\s*(.+)$/m);
+    if (nameMatch) name = nameMatch[1]!.trim();
+    const parentMatch = raw.match(/^parent:\s*(.+)$/m);
+    if (parentMatch) parent = parentMatch[1]!.trim();
+  }
+  let msgCount = 0;
+  const walk = (d: string): void => {
+    for (const e of readdirSync(d)) {
+      const p = join(d, e);
+      if (statSync(p).isDirectory()) walk(p);
+      else if (e.endsWith('.md') && e !== 'CHANNEL.md') msgCount++;
+    }
+  };
+  try { walk(channelDir); } catch { /* ignore */ }
+  const parentSuffix = parent ? ` [child of ${parent.slice(0, 8)}]` : '';
+  console.log(`  ${ch.slice(0, 8)}... — ${name} (${msgCount} msgs)${parentSuffix}`);
+}
+
+console.log('');
+console.log(`Infrastructure errors logged: ${countErrors(transportRoot)}`);

package/src/stop.ts

@@ -0,0 +1,37 @@
+// crosstalkd stop — send SIGTERM to the running dispatcher and wait for it to exit.
+
+import { resolve } from 'path';
+import { spawnSync } from 'child_process';
+import { readPidfile, removePidfile } from './state.js';
+
+const transportRoot = resolve(process.cwd());
+
+function processRunning(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+const pid = readPidfile(transportRoot);
+if (pid === null) {
+  console.error('crosstalkd stop: no dispatcher.pid found — is dispatch running?');
+  process.exit(1);
+}
+
+if (!processRunning(pid)) {
+  console.error(`crosstalkd stop: pid ${pid} is not running — removing stale pidfile`);
+  removePidfile(transportRoot);
+  process.exit(1);
+}
+
+process.kill(pid, 'SIGTERM');
+
+const deadline = Date.now() + 5_000;
+while (Date.now() < deadline) {
+  if (!processRunning(pid)) {
+    console.log(`crosstalkd stop: dispatcher (pid ${pid}) stopped`);
+    process.exit(0);
+  }
+  spawnSync('sleep', ['0.1']);
+}
+
+console.error(`crosstalkd stop: pid ${pid} did not exit within 5s — try: kill -9 ${pid}`);
+process.exit(1);