@cordfuse/crosstalk 5.0.0-alpha.2

package/src/dlq.ts

@@ -0,0 +1,263 @@
+import {
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  unlinkSync,
+} from 'fs';
+import { resolve, join } from 'path';
+import { pathToFileURL } from 'url';
+import { now } from './filenames.js';
+import { serializeFrontmatter, parseFrontmatter } from './frontmatter.js';
+
+const QUARANTINE_THRESHOLD_ATTEMPTS = 4;
+const QUARANTINE_WINDOW_MS = 60 * 60 * 1000; // 1 hour
+
+export type DlqKind = 'dispatch' | 'config';
+
+export interface DlqEntry {
+  id: string;
+  kind: DlqKind;
+  actor: string;
+  channel: string; // "(config)" for kind=config without channel context
+  messageRelPath: string; // "(config)" for kind=config
+  attempts: number;
+  quarantined: boolean;
+  firstFailedAt: string;
+  lastFailedAt: string;
+  error: string;
+}
+
+export interface FoundDlqEntry {
+  id: string;
+  path: string;
+  entry: DlqEntry;
+}
+
+export interface WriteDlqResult {
+  id: string;
+  attempts: number;
+  quarantined: boolean;
+}
+
+function dlqDir(transportRoot: string): string {
+  return join(transportRoot, 'dlq');
+}
+
+export function findDlqEntry(
+  transportRoot: string,
+  kind: DlqKind,
+  actor: string,
+  channel: string,
+  messageRelPath: string,
+): FoundDlqEntry | null {
+  const dir = dlqDir(transportRoot);
+  if (!existsSync(dir)) return null;
+  for (const f of readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+    const path = join(dir, f);
+    try {
+      const { data } = parseFrontmatter<DlqEntry>(readFileSync(path, 'utf-8'));
+      if (
+        data.kind === kind &&
+        data.actor === actor &&
+        data.channel === channel &&
+        data.messageRelPath === messageRelPath
+      ) {
+        return { id: f.replace(/\.md$/, ''), path, entry: data };
+      }
+    } catch { /* skip unparseable */ }
+  }
+  return null;
+}
+
+export function isQuarantined(
+  transportRoot: string,
+  kind: DlqKind,
+  actor: string,
+  channel: string,
+  messageRelPath: string,
+): boolean {
+  return findDlqEntry(transportRoot, kind, actor, channel, messageRelPath)?.entry.quarantined ?? false;
+}
+
+export function isActorQuarantined(transportRoot: string, actor: string): boolean {
+  // Any config-kind DLQ entry for this actor that's quarantined gates the whole actor.
+  const dir = dlqDir(transportRoot);
+  if (!existsSync(dir)) return false;
+  for (const f of readdirSync(dir).filter((x) => x.endsWith('.md'))) {
+    try {
+      const { data } = parseFrontmatter<DlqEntry>(readFileSync(join(dir, f), 'utf-8'));
+      if (data.kind === 'config' && data.actor === actor && data.quarantined) return true;
+    } catch { /* skip */ }
+  }
+  return false;
+}
+
+export function writeDlqEntry(
+  transportRoot: string,
+  kind: DlqKind,
+  actor: string,
+  channelUuid: string,
+  messageRelPath: string,
+  error: string,
+): WriteDlqResult {
+  const dir = dlqDir(transportRoot);
+  mkdirSync(dir, { recursive: true });
+
+  const existing = findDlqEntry(transportRoot, kind, actor, channelUuid, messageRelPath);
+  const lastFailedAt = new Date().toISOString();
+
+  if (existing) {
+    const attempts = (existing.entry.attempts ?? 1) + 1;
+    const firstFailedAt = existing.entry.firstFailedAt;
+    const ageMs = Date.now() - new Date(firstFailedAt).getTime();
+    const quarantined =
+      existing.entry.quarantined ||
+      (attempts >= QUARANTINE_THRESHOLD_ATTEMPTS && ageMs < QUARANTINE_WINDOW_MS);
+
+    const updated: DlqEntry = {
+      ...existing.entry,
+      attempts,
+      lastFailedAt,
+      error: error.slice(0, 500),
+      quarantined,
+    };
+    writeFileSync(
+      existing.path,
+      serializeFrontmatter(updated as unknown as Record<string, unknown>, error),
+    );
+    return { id: existing.id, attempts, quarantined };
+  }
+
+  const ts = now();
+  const id = `${ts.fileTime}-${ts.hex}`;
+  const entry: DlqEntry = {
+    id,
+    kind,
+    actor,
+    channel: channelUuid,
+    messageRelPath,
+    attempts: 1,
+    quarantined: false,
+    firstFailedAt: ts.iso,
+    lastFailedAt,
+    error: error.slice(0, 500),
+  };
+  writeFileSync(
+    join(dir, `${id}.md`),
+    serializeFrontmatter(entry as unknown as Record<string, unknown>, error),
+  );
+  return { id, attempts: 1, quarantined: false };
+}
+
+export function deleteDlqEntry(transportRoot: string, id: string): boolean {
+  const path = join(dlqDir(transportRoot), `${id}.md`);
+  if (!existsSync(path)) return false;
+  unlinkSync(path);
+  return true;
+}
+
+function listEntries(transportRoot: string): { id: string; entry: DlqEntry }[] {
+  const dir = dlqDir(transportRoot);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .sort()
+    .map((f) => {
+      const raw = readFileSync(join(dir, f), 'utf-8');
+      const { data } = parseFrontmatter<DlqEntry>(raw);
+      return { id: f.replace(/\.md$/, ''), entry: data };
+    });
+}
+
+// ── CLI entry point ──
+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];
+}
+
+const isEntry = process.argv[1] ? import.meta.url === pathToFileURL(process.argv[1]).href : false;
+
+if (isEntry) {
+  const list = argv.includes('--list');
+  const show = flag('--show');
+  const retryId = flag('--retry');
+  const clear = argv.includes('--clear');
+
+  if (list || (!show && !retryId && !clear && argv.length === 0)) {
+    const entries = listEntries(transportRoot);
+    const quarantinedCount = entries.filter((e) => e.entry.quarantined).length;
+    console.log(`DLQ entries: ${entries.length} (${quarantinedCount} quarantined)`);
+    for (const { id, entry } of entries) {
+      const quarantineMark = entry.quarantined ? ' [QUARANTINED]' : '';
+      console.log(`  ${id}${quarantineMark}`);
+      console.log(`    kind=${entry.kind} actor=${entry.actor} channel=${entry.channel?.slice(0, 8)}`);
+      console.log(`    msg=${entry.messageRelPath}`);
+      console.log(`    error=${(entry.error || '').slice(0, 80)}`);
+      console.log(`    attempts=${entry.attempts}  first=${entry.firstFailedAt}  last=${entry.lastFailedAt}`);
+    }
+  } else if (show) {
+    const path = join(dlqDir(transportRoot), `${show}.md`);
+    if (!existsSync(path)) {
+      console.error(`No DLQ entry: ${show}`);
+      process.exit(1);
+    }
+    console.log(readFileSync(path, 'utf-8'));
+  } else if (clear) {
+    const dir = dlqDir(transportRoot);
+    if (!existsSync(dir)) {
+      console.log('dlq/ does not exist; nothing to clear');
+      process.exit(0);
+    }
+    const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
+    for (const f of files) unlinkSync(join(dir, f));
+    console.log(`Cleared ${files.length} DLQ entries`);
+  } else if (retryId) {
+    const path = join(dlqDir(transportRoot), `${retryId}.md`);
+    if (!existsSync(path)) {
+      console.error(`No DLQ entry: ${retryId}`);
+      process.exit(1);
+    }
+    const { data } = parseFrontmatter<DlqEntry>(readFileSync(path, 'utf-8'));
+    if (data.kind === 'dispatch') {
+      const cursorFile = join(transportRoot, 'cursors', data.actor, `${data.channel}.md`);
+      if (existsSync(cursorFile)) {
+        writeFileSync(cursorFile, '\n');
+      }
+      // Also clear the quarantine flag — otherwise dispatch would skip the
+      // message on the next tick and retry would be a no-op.
+      if (data.quarantined) {
+        data.quarantined = false;
+        writeFileSync(path, serializeFrontmatter(data as unknown as Record<string, unknown>, data.error));
+      }
+      console.log(
+        `Retried DLQ entry ${retryId}. Cursor for ${data.actor}@${data.channel.slice(0, 8)} cleared; quarantine flag reset.`,
+      );
+      console.log(
+        '  (DLQ entry kept — will be re-evaluated on next dispatch. If it fails again, attempts will increment.)',
+      );
+      console.log('  Run: npm run dispatch -- --once  (or wait for next tick)');
+    } else if (data.kind === 'config') {
+      // For config errors: clear the quarantine flag so the actor is retried.
+      data.quarantined = false;
+      writeFileSync(path, serializeFrontmatter(data as unknown as Record<string, unknown>, data.error));
+      console.log(
+        `Retried config DLQ entry ${retryId}. Quarantine flag cleared on ${data.actor}.`,
+      );
+      console.log('  Run: npm run dispatch -- --once  (or wait for next tick)');
+    } else {
+      console.error(`Unknown DLQ kind: ${data.kind}`);
+      process.exit(1);
+    }
+  } else {
+    console.error(
+      'Usage: npm run dlq -- [--list | --show <id> | --retry <id> | --clear]',
+    );
+    process.exit(1);
+  }
+}

package/src/filenames.ts

@@ -0,0 +1,28 @@
+import { randomBytes } from 'crypto';
+
+export interface Timestamp {
+  iso: string;
+  pathDate: string;
+  fileTime: string;
+  hex: string;
+}
+
+export function now(): Timestamp {
+  const d = new Date();
+  const iso = d.toISOString();
+  const yyyy = iso.slice(0, 4);
+  const mm = iso.slice(5, 7);
+  const dd = iso.slice(8, 10);
+  const time = iso.slice(11, 13) + iso.slice(14, 16) + iso.slice(17, 19);
+  const ms = iso.slice(20, 23);
+  return {
+    iso,
+    pathDate: `${yyyy}/${mm}/${dd}`,
+    fileTime: `${time}${ms}Z`,
+    hex: randomBytes(4).toString('hex'),
+  };
+}
+
+export function messageFilename(ts: Timestamp = now()): string {
+  return `${ts.fileTime}-${ts.hex}.md`;
+}

package/src/frontmatter.ts

@@ -0,0 +1,26 @@
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+
+export interface ParsedDocument<T = Record<string, unknown>> {
+  data: T;
+  body: string;
+}
+
+export function parseFrontmatter<T = Record<string, unknown>>(raw: string): ParsedDocument<T> {
+  if (!raw.startsWith('---')) return { data: {} as T, body: raw };
+  const lines = raw.split('\n');
+  let end = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === '---') { end = i; break; }
+  }
+  if (end === -1) return { data: {} as T, body: raw };
+  const yamlBlock = lines.slice(1, end).join('\n');
+  const body = lines.slice(end + 1).join('\n').replace(/^\n/, '');
+  const data = (parseYaml(yamlBlock) as T) ?? ({} as T);
+  return { data, body };
+}
+
+export function serializeFrontmatter(data: Record<string, unknown>, body: string): string {
+  const yaml = stringifyYaml(data).trimEnd();
+  const trailing = body.endsWith('\n') ? '' : '\n';
+  return `---\n${yaml}\n---\n\n${body}${trailing}`;
+}

package/src/init.ts

@@ -0,0 +1,157 @@
+// crosstalk init <directory> — scaffold a new transport
+//
+// Copies the bundled transport template (markdown spec, agent pointer
+// files, default actor profiles) into the target directory, then adds
+// host-specific scaffolding (host file for this machine, first channel,
+// runtime state directories).
+//
+// Template lookup order:
+//   1. <runtime_root>/template/   — bundled at publish time (production)
+//   2. <runtime_root>/../transport/  — monorepo layout (local dev)
+//
+// If neither exists, exits with a clear error.
+
+import { existsSync, mkdirSync, writeFileSync, cpSync } from 'fs';
+import { resolve, join, dirname } from 'path';
+import { hostname as osHostname } from 'os';
+import { randomUUID } from 'crypto';
+import { fileURLToPath } from 'url';
+
+const argv = process.argv.slice(2);
+const force = argv.includes('--force');
+
+const positional = argv.filter((a) => !a.startsWith('--'));
+if (positional.length === 0) {
+  console.error('Usage: crosstalk init <directory> [--force]');
+  console.error('       crosstalk init .                  (scaffold into current dir)');
+  process.exit(1);
+}
+
+const targetDir = resolve(positional[0]);
+
+if (existsSync(join(targetDir, 'upstream', 'CROSSTALK-VERSION')) && !force) {
+  console.error(`crosstalk init: ${targetDir} already contains a transport.`);
+  console.error('Pass --force to overwrite.');
+  process.exit(1);
+}
+
+// Locate the bundled transport template.
+const thisFileDir = dirname(fileURLToPath(import.meta.url));
+const runtimeRoot = resolve(thisFileDir, '..');
+const candidates = [
+  join(runtimeRoot, 'template'),
+  join(runtimeRoot, '..', 'transport'),
+];
+const templateDir = candidates.find((c) => existsSync(join(c, 'upstream', 'CROSSTALK-VERSION')));
+
+if (!templateDir) {
+  console.error('crosstalk init: cannot find the transport template.');
+  console.error('Looked in:');
+  for (const c of candidates) console.error(`  ${c}`);
+  console.error('The @cordfuse/crosstalk installation may be corrupted; try reinstalling.');
+  process.exit(1);
+}
+
+mkdirSync(targetDir, { recursive: true });
+
+// Copy the template, excluding the template's own README.md (operator
+// gets a fresh README, generated below).
+function copyTemplate(): void {
+  cpSync(templateDir!, targetDir, {
+    recursive: true,
+    force,
+    filter: (src) => !src.endsWith('/transport/README.md') && !src.endsWith('\\transport\\README.md'),
+  });
+}
+copyTemplate();
+
+// Host file: per-machine actor declaration.
+const hostname = osHostname();
+const hostsDir = join(targetDir, 'hosts');
+mkdirSync(hostsDir, { recursive: true });
+const hostPath = join(hostsDir, `${hostname}.md`);
+if (!existsSync(hostPath) || force) {
+  writeFileSync(
+    hostPath,
+    `---
+alias: ${hostname}
+hostname: ${hostname}
+actors:
+  concierge:
+    claude:
+      cli: claude --print --dangerously-skip-permissions
+---
+
+Host file for ${hostname}. One actor (concierge) on Claude Code by default.
+Add more actors as you need them; declare each tier under its CLI invocation.
+
+To add an actor with multiple parallel slots (e.g. 10 junior-developer instances
+each picking up messages independently), use \`count: N\` under the tier:
+
+    actors:
+      junior-developer:
+        haiku:
+          cli: claude --model claude-haiku-4-5 --print --dangerously-skip-permissions
+          count: 10
+`,
+  );
+}
+
+// First channel.
+const chId = randomUUID();
+const channelDir = join(targetDir, 'data', 'channels', chId);
+mkdirSync(channelDir, { recursive: true });
+const channelMd = join(channelDir, 'CHANNEL.md');
+if (!existsSync(channelMd) || force) {
+  writeFileSync(
+    channelMd,
+    `---
+name: general
+created_by: ${process.env['USER'] || 'operator'}
+created_at: ${new Date().toISOString()}
+---
+
+General channel. First channel of this transport.
+`,
+  );
+}
+
+// Runtime state directories (cursors, dlq, errors) — start empty.
+for (const d of ['cursors', 'dlq', 'errors']) {
+  const dir = join(targetDir, d);
+  mkdirSync(dir, { recursive: true });
+  const keep = join(dir, '.gitkeep');
+  if (!existsSync(keep)) writeFileSync(keep, '');
+}
+
+// Fresh transport README replacing the template's self-description.
+const readmePath = join(targetDir, 'README.md');
+if (!existsSync(readmePath) || force) {
+  writeFileSync(
+    readmePath,
+    `# Transport
+
+A Crosstalk transport created by \`crosstalk init\`.
+
+- Spec: \`upstream/CROSSTALK.md\`
+- Agent orientation: \`upstream/PROTOCOL.md\` and \`upstream/OPERATOR.md\`
+- Your custom actor profiles: \`local/actors/\`
+- Host configuration for this machine: \`hosts/${hostname}.md\`
+
+To run dispatch: \`crosstalk dispatch\`. To chat with deployed actors via your
+preferred agent CLI: \`crosstalk attach\`.
+`,
+  );
+}
+
+console.log('');
+console.log(`Transport initialized at ${targetDir}`);
+console.log(`  host file:           hosts/${hostname}.md`);
+console.log(`  first channel UUID:  ${chId}`);
+console.log('');
+console.log('Next steps:');
+console.log(`  cd ${targetDir}`);
+console.log('  git init && git add -A && git commit -m "initial transport"');
+console.log('  crosstalk status         # verify scaffold');
+console.log('  crosstalk dispatch       # run dispatch loop locally');
+console.log('  crosstalk attach         # chat with actors via your preferred CLI');

package/src/open.ts

@@ -0,0 +1,183 @@
+import { resolve, join } from 'path';
+import { spawnSync } from 'child_process';
+import { mkdirSync, writeFileSync, existsSync, readFileSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { createInterface } from 'readline/promises';
+import { statSync } from 'fs';
+import { findHostFile, loadActorProfile, pickTier, tokenizeCli } from './actor.js';
+import { now, messageFilename } from './filenames.js';
+import { serializeFrontmatter } from './frontmatter.js';
+import { writeDlqEntry } from './dlq.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];
+}
+
+const actorName = flag('--actor');
+let channelUuid = flag('--channel');
+const hostOverride = flag('--host');
+const operatorName = flag('--as') ?? process.env.USER ?? 'steve';
+
+if (!actorName) {
+  console.error('Usage: npm run open -- --actor <name> [--channel <uuid>] [--host <alias>] [--as <name>]');
+  process.exit(1);
+}
+
+const host = findHostFile(transportRoot, hostOverride);
+if (!host.actors[actorName]) {
+  console.error(`Actor '${actorName}' not declared in host file ${host.alias}`);
+  process.exit(1);
+}
+
+if (!channelUuid) {
+  channelUuid = randomUUID();
+  const dir = join(transportRoot, 'data', 'channels', channelUuid);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(
+    join(dir, 'CHANNEL.md'),
+    `---
+name: open-${actorName}-${now().fileTime}
+created_by: ${operatorName}
+created_at: ${new Date().toISOString()}
+---
+
+Interactive session channel — \`npm run open\` invocation.
+`,
+  );
+  console.log(`(created channel ${channelUuid})`);
+}
+
+const protocolPath = join(transportRoot, 'upstream', 'PROTOCOL.md');
+const actorProfilePath = join(transportRoot, 'local', 'actors', `${actorName}.md`);
+const fwActorProfilePath = join(transportRoot, 'upstream', 'actors', `${actorName}.md`);
+
+interface CachedPrompt {
+  systemPrompt: string;
+  protocolMtime: number;
+  profileMtime: number;
+  profilePath: string;
+}
+
+function mtime(p: string): number {
+  try { return statSync(p).mtimeMs; } catch { return 0; }
+}
+
+function loadComposedPrompt(): CachedPrompt {
+  const profile = loadActorProfile(transportRoot, actorName!);
+  const protocolPrompt = existsSync(protocolPath)
+    ? readFileSync(protocolPath, 'utf-8').trim()
+    : '';
+  const systemPrompt = [protocolPrompt, profile.systemPrompt]
+    .filter((p) => p.length > 0)
+    .join('\n\n---\n\n');
+  const profilePath = existsSync(actorProfilePath) ? actorProfilePath : fwActorProfilePath;
+  return {
+    systemPrompt,
+    protocolMtime: mtime(protocolPath),
+    profileMtime: mtime(profilePath),
+    profilePath,
+  };
+}
+
+let cached = loadComposedPrompt();
+
+function getCurrentSystemPrompt(): string {
+  const currentProtocolMtime = mtime(protocolPath);
+  const currentProfileMtime = mtime(cached.profilePath);
+  if (currentProtocolMtime !== cached.protocolMtime || currentProfileMtime !== cached.profileMtime) {
+    console.log('(reloaded actor profile + PROTOCOL.md after detected mtime change)\n');
+    cached = loadComposedPrompt();
+  }
+  return cached.systemPrompt;
+}
+
+const { cli } = pickTier(host.actors[actorName]);
+
+function logToChannel(from: string, to: string, body: string): void {
+  const ts = now();
+  const dir = join(transportRoot, 'data', 'channels', channelUuid!, ts.pathDate);
+  mkdirSync(dir, { recursive: true });
+  const content = serializeFrontmatter(
+    { from, to, type: 'text', timestamp: ts.iso },
+    body,
+  );
+  writeFileSync(join(dir, messageFilename(ts)), content);
+}
+
+console.log(`crosstalk v4 open — actor=${actorName} channel=${channelUuid.slice(0, 8)}`);
+console.log('Type a message and press Enter. Ctrl-C or Ctrl-D to exit.');
+console.log('');
+
+async function main(): Promise<void> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+
+  try {
+    while (true) {
+      let userMsg: string;
+      try {
+        userMsg = await rl.question('you> ');
+      } catch {
+        break;
+      }
+      if (userMsg === undefined || userMsg === null) break;
+      const trimmed = userMsg.trim();
+      if (!trimmed) continue;
+
+      const ts = now();
+      const userMsgRelPath = `${ts.pathDate}/${messageFilename(ts)}`;
+      logToChannel(operatorName, actorName!, trimmed);
+
+      const fullPrompt = `${getCurrentSystemPrompt()}\n\n---\n\n${trimmed}`;
+      const parts = tokenizeCli(cli);
+      if (parts.length === 0) {
+        console.error('\n[open] tokenized cli is empty — check host file\n');
+        continue;
+      }
+      const result = spawnSync(parts[0], parts.slice(1), {
+        input: fullPrompt,
+        encoding: 'utf-8',
+        timeout: 5 * 60_000,
+      });
+
+      if (result.status !== 0) {
+        const r = writeDlqEntry(
+          transportRoot,
+          'dispatch',
+          actorName!,
+          channelUuid!,
+          userMsgRelPath,
+          `cli exit=${result.status} (open mode)\n${(result.stderr || '').slice(0, 1000)}`,
+        );
+        const quarantineMark = r.quarantined ? ' [QUARANTINED]' : '';
+        console.error(`\n[cli exit=${result.status} → dlq:${r.id}${quarantineMark}] ${(result.stderr || '').slice(0, 200)}\n`);
+        continue;
+      }
+
+      const reply = (result.stdout || '').trim();
+      if (reply.length === 0) {
+        const r = writeDlqEntry(
+          transportRoot,
+          'dispatch',
+          actorName!,
+          channelUuid!,
+          userMsgRelPath,
+          'cli returned empty reply (open mode)',
+        );
+        console.error(`\n[empty reply → dlq:${r.id}] (run dlq --show ${r.id} for context)\n`);
+        continue;
+      }
+
+      console.log(`${actorName}> ${reply}\n`);
+      logToChannel(actorName!, operatorName, reply);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+main();