@cordfuse/crosstalk 6.0.0-alpha.9 → 7.0.0-alpha.2

package/src/turnq.ts

@@ -1,91 +0,0 @@
-// Advisory turn coordination via @cordfuse/turnq.
-//
-// The lock is an OPTIMIZATION, never a correctness requirement — git
-// arbitrates (collision-free filenames + push rejection/rebase retry).
-// So: wait a bounded time for the turn, then proceed without it. A turnq
-// bug or outage can never wedge a dispatcher; it just costs an occasional
-// rebase. Failures are loud (errors.log), never silently fallen back.
-//
-// Env vars:
-//   TURNQ_URL      — optional, e.g. http://turnq:3003 (unset → local flock)
-//   TURNQ_API_KEY  — required when TURNQ_URL is set
-//   TURNQ_CHANNEL  — optional namespace prefix (default: "crosstalk")
-
-import { createCoordinator } from '@cordfuse/turnq/coordinator';
-import { logError } from './state.js';
-
-const TURN_WAIT_MS = 15_000;
-
-interface Coordinator {
-  withTurn<T>(channel: string, fn: () => Promise<T>): Promise<T>;
-  close(): void;
-}
-
-let coordinatorPromise: Promise<Coordinator> | null = null;
-
-function getCoordinator(): Promise<Coordinator> {
-  if (!coordinatorPromise) {
-    const url = process.env['TURNQ_URL'];
-    const apiKey = process.env['TURNQ_API_KEY'];
-    coordinatorPromise = createCoordinator(
-      url ? { url, apiKey, fallback: false } : {},
-    );
-  }
-  return coordinatorPromise;
-}
-
-function channelFor(name: string): string {
-  const prefix = process.env['TURNQ_CHANNEL'] ?? 'crosstalk';
-  return `${prefix}/${name}`;
-}
-
-// Run `fn` while holding the named turn if it can be acquired within
-// TURN_WAIT_MS; otherwise (timeout, coordinator error, server down) log
-// and run `fn` anyway. `fn` runs exactly once — the `ran` guard is safe
-// because the event loop is single-threaded.
-export async function withLock<T>(transportRoot: string, name: string, fn: () => Promise<T>): Promise<T> {
-  let ran = false;
-  const runOnce = (): Promise<T> => {
-    ran = true;
-    return fn();
-  };
-
-  let coordinator: Coordinator;
-  try {
-    coordinator = await getCoordinator();
-  } catch (err) {
-    coordinatorPromise = null;
-    logError(transportRoot, 'turnq', `coordinator init failed — proceeding without lock: ${(err as Error).message}`);
-    return runOnce();
-  }
-
-  return new Promise<T>((resolve, reject) => {
-    const timer = setTimeout(() => {
-      if (ran) return;
-      logError(transportRoot, 'turnq', `turn '${name}' not granted within ${TURN_WAIT_MS}ms — proceeding without lock`);
-      runOnce().then(resolve, reject);
-    }, TURN_WAIT_MS);
-    timer.unref?.();
-
-    coordinator
-      .withTurn(channelFor(name), async () => {
-        clearTimeout(timer);
-        if (ran) return; // timeout path already ran fn; release the turn immediately
-        await runOnce().then(resolve, reject);
-      })
-      .catch((err) => {
-        clearTimeout(timer);
-        if (ran) return;
-        logError(transportRoot, 'turnq', `turn '${name}' failed — proceeding without lock: ${(err as Error).message}`);
-        runOnce().then(resolve, reject);
-      });
-  });
-}
-
-export async function closeCoordinator(): Promise<void> {
-  if (!coordinatorPromise) return;
-  try {
-    (await coordinatorPromise).close();
-  } catch { /* best-effort */ }
-  coordinatorPromise = null;
-}

package/src/upgrade.ts

@@ -1,211 +0,0 @@
-// crosstalk upgrade — sync the transport's upstream/ against the runtime's
-// bundled template.
-//
-// The transport's upstream/ contains runtime-managed files: spec, agent
-// orientation prompts, protocol version pin, default actor profiles. When
-// the operator updates their runtime (via `npm update -g @cordfuse/crosstalk`),
-// the bundled template ships with a newer spec; this command copies those
-// files into the operator's transport so they catch up.
-//
-// What this command DOES touch:
-//   - upstream/CROSSTALK.md, PROTOCOL.md, OPERATOR.md
-//   - upstream/CROSSTALK-VERSION
-//   - upstream/actors/ (default actor profile starter set)
-//
-// What this command NEVER touches:
-//   - local/ — operator-owned actor profiles and identity
-//   - hosts/ — operator-owned host files
-//   - data/ — channels and memories
-//   - root pointer files (CLAUDE.md etc.) — only updated if a --pointers flag
-//     is passed, since they rarely change and overwriting them surprises
-//     operators who've customized them
-// (Dispatcher state — cursors, dlq, error logs — lives outside the repo
-// in the state dir and is never in scope.)
-//
-// Usage:
-//   crosstalk upgrade           — sync upstream/ from runtime template
-//   crosstalk upgrade --dry-run — show what would change, no writes
-//   crosstalk upgrade --pointers — also overwrite the entry pointer files
-
-import { existsSync, readFileSync, cpSync, statSync, readdirSync, mkdirSync } from 'fs';
-import { resolve, join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const transportRoot = resolve(process.cwd());
-const argv = process.argv.slice(2);
-const dryRun = argv.includes('--dry-run');
-const updatePointers = argv.includes('--pointers');
-
-const POINTER_FILES = [
-  'CLAUDE.md', 'AGENTS.md', 'GEMINI.md', 'QWEN.md', 'ANTIGRAVITY.md', 'OPENCODE.md',
-  '.windsurfrules',
-  '.amazonq/rules/crosstalk.md',
-  '.continue/rules/crosstalk.md',
-  '.cursor/rules/crosstalk.mdc',
-  '.github/copilot-instructions.md',
-];
-
-function locateTemplate(): string {
-  const thisFileDir = dirname(fileURLToPath(import.meta.url));
-  const runtimeRoot = resolve(thisFileDir, '..');
-  const candidates = [
-    join(runtimeRoot, 'template'),
-    join(runtimeRoot, '..', 'transport'),
-  ];
-  const found = candidates.find((c) => existsSync(join(c, 'upstream', 'CROSSTALK-VERSION')));
-  if (!found) {
-    console.error('crosstalk upgrade: cannot find the bundled transport template.');
-    console.error('Looked in:');
-    for (const c of candidates) console.error(`  ${c}`);
-    process.exit(1);
-  }
-  return found;
-}
-
-function readVersion(p: string): string | null {
-  try { return readFileSync(p, 'utf-8').trim(); } catch { return null; }
-}
-
-function listFilesRelative(dir: string): string[] {
-  const out: string[] = [];
-  const walk = (d: string, prefix: string): void => {
-    if (!existsSync(d)) return;
-    for (const entry of readdirSync(d)) {
-      const full = join(d, entry);
-      const rel = prefix ? `${prefix}/${entry}` : entry;
-      const st = statSync(full);
-      if (st.isDirectory()) walk(full, rel);
-      else out.push(rel);
-    }
-  };
-  walk(dir, '');
-  return out;
-}
-
-function classifyChange(templatePath: string, transportPath: string): 'add' | 'modify' | 'unchanged' {
-  if (!existsSync(transportPath)) return 'add';
-  const a = readFileSync(templatePath, 'utf-8');
-  const b = readFileSync(transportPath, 'utf-8');
-  return a === b ? 'unchanged' : 'modify';
-}
-
-// ── Sanity checks ─────────────────────────────────────────────────────
-
-const transportVersionPath = join(transportRoot, 'upstream', 'CROSSTALK-VERSION');
-if (!existsSync(transportVersionPath)) {
-  console.error(`crosstalk upgrade: not a transport (no upstream/CROSSTALK-VERSION).`);
-  console.error(`Run from inside a transport directory, or use 'crosstalk init' to scaffold one.`);
-  process.exit(2);
-}
-
-const templateDir = locateTemplate();
-const templateUpstream = join(templateDir, 'upstream');
-const transportUpstream = join(transportRoot, 'upstream');
-
-const fromVersion = readVersion(transportVersionPath) ?? '?';
-const toVersion = readVersion(join(templateUpstream, 'CROSSTALK-VERSION')) ?? '?';
-
-// Detect downgrade.
-const parseMM = (v: string): [number, number] => {
-  const m = v.match(/^(\d+)\.(\d+)/);
-  return m ? [Number(m[1]), Number(m[2])] : [0, 0];
-};
-const [fromMaj, fromMin] = parseMM(fromVersion);
-const [toMaj, toMin] = parseMM(toVersion);
-const isDowngrade = toMaj < fromMaj || (toMaj === fromMaj && toMin < fromMin);
-if (isDowngrade) {
-  console.error(`crosstalk upgrade: bundled template is OLDER than your transport.`);
-  console.error(`  transport: ${fromVersion}`);
-  console.error(`  template:  ${toVersion}`);
-  console.error(`Your runtime is older than the runtime that scaffolded this transport.`);
-  console.error(`To upgrade your runtime: npm update -g @cordfuse/crosstalk`);
-  process.exit(3);
-}
-
-console.log(`crosstalk upgrade${dryRun ? ' (dry-run)' : ''}`);
-console.log('');
-console.log(`  transport CROSSTALK-VERSION: ${fromVersion}`);
-console.log(`  template  CROSSTALK-VERSION: ${toVersion}`);
-console.log('');
-
-// ── Plan the changes ──────────────────────────────────────────────────
-
-const upstreamFiles = listFilesRelative(templateUpstream);
-const changes: { rel: string; kind: 'add' | 'modify' | 'unchanged' }[] = [];
-
-for (const rel of upstreamFiles) {
-  const fromPath = join(templateUpstream, rel);
-  const toPath = join(transportUpstream, rel);
-  changes.push({ rel, kind: classifyChange(fromPath, toPath) });
-}
-
-const adds = changes.filter((c) => c.kind === 'add');
-const mods = changes.filter((c) => c.kind === 'modify');
-const same = changes.filter((c) => c.kind === 'unchanged');
-
-console.log(`upstream/ changes:`);
-console.log(`  ${adds.length} new file${adds.length === 1 ? '' : 's'}`);
-console.log(`  ${mods.length} modified`);
-console.log(`  ${same.length} unchanged`);
-
-if (adds.length > 0 || mods.length > 0) {
-  console.log('');
-  for (const c of [...adds, ...mods].slice(0, 20)) {
-    console.log(`  [${c.kind === 'add' ? '+' : '~'}] upstream/${c.rel}`);
-  }
-  if (adds.length + mods.length > 20) {
-    console.log(`  … and ${adds.length + mods.length - 20} more`);
-  }
-}
-
-if (updatePointers) {
-  console.log('');
-  console.log(`pointer files (with --pointers):`);
-  for (const pf of POINTER_FILES) {
-    const fromPath = join(templateDir, pf);
-    const toPath = join(transportRoot, pf);
-    if (!existsSync(fromPath)) continue;
-    const kind = classifyChange(fromPath, toPath);
-    if (kind !== 'unchanged') console.log(`  [${kind === 'add' ? '+' : '~'}] ${pf}`);
-  }
-}
-
-// ── Apply or stop ─────────────────────────────────────────────────────
-
-if (dryRun) {
-  console.log('');
-  console.log('Dry run — no changes written. Re-run without --dry-run to apply.');
-  process.exit(0);
-}
-
-if (adds.length === 0 && mods.length === 0 && !updatePointers) {
-  console.log('');
-  console.log('Already in sync. Nothing to do.');
-  process.exit(0);
-}
-
-console.log('');
-console.log('Applying...');
-
-// Copy upstream/ recursively. cpSync with force=true handles both add and modify.
-cpSync(templateUpstream, transportUpstream, { recursive: true, force: true });
-console.log(`  ✓ upstream/ synced`);
-
-if (updatePointers) {
-  for (const pf of POINTER_FILES) {
-    const fromPath = join(templateDir, pf);
-    const toPath = join(transportRoot, pf);
-    if (!existsSync(fromPath)) continue;
-    mkdirSync(dirname(toPath), { recursive: true });
-    cpSync(fromPath, toPath, { force: true });
-  }
-  console.log(`  ✓ pointer files synced`);
-}
-
-console.log('');
-console.log(`Spec ${fromVersion} → ${toVersion}.`);
-console.log(`Commit the upstream/ changes when ready:`);
-console.log(`  git add upstream/${updatePointers ? ' ' + POINTER_FILES.slice(0, 3).join(' ') + ' ...' : ''}`);
-console.log(`  git commit -m "spec: upgrade to ${toVersion}"`);
-console.log('');
-console.log('Your local/, hosts/, and data/ were not touched.');

package/src/wake.ts

@@ -1,7 +0,0 @@
-// crosstalk wake — poke the local dispatcher to tick immediately.
-
-import { resolve } from 'path';
-import { sendWakeSignal } from './state.js';
-
-sendWakeSignal(resolve(process.cwd()));
-console.log('wake signal sent');

package/template/CLAUDE.md

@@ -1,12 +0,0 @@
-# Crosstalk transport
-
-You are inside a Crosstalk transport — a git repo that carries async
-messages between AI agents across machines.
-
-Read these before doing anything here:
-
-1. `upstream/PROTOCOL.md` — how to behave when dispatched (start here)
-2. `upstream/CROSSTALK.md` — the full protocol spec, if you need details
-
-Do not edit files under `data/` by hand — messages are written only by
-`crosstalk send` and the dispatcher.

package/template/gitignore

@@ -1,4 +0,0 @@
-.DS_Store
-Thumbs.db
-node_modules/
-.turnq/

package/template/upstream/CROSSTALK-VERSION

@@ -1 +0,0 @@
-6.0

package/template/upstream/CROSSTALK.md

@@ -1,298 +0,0 @@
-# Crosstalk
-
-Version: 6.0
-
-Crosstalk is a shared file format over git that lets humans and AI agents communicate
-asynchronously across machines. The git repository is the message bus. No special
-software is required to participate beyond git itself.
-
-Design rule for this spec: every feature must be explainable in one sentence.
-The runtime records facts at write time; it never reconstructs them by inference
-at read time.
-
----
-
-## Participants
-
-**Humans** — operators who post messages directly or via a chat tool and read replies.
-
-**Machines** — agents (Claude, Codex, etc.) invoked by a dispatcher to process
-messages addressed to them and reply.
-
-The most common machine participant is a **worker**: `to: concierge` means
-"I need something done." The worker acts and replies. The sender may be human
-or machine; the worker does not distinguish.
-
----
-
-## Transport layout
-
-```
-<transport>/
-  upstream/                  # runtime-managed: spec, agent orientation, defaults
-    CROSSTALK.md             #   this file
-    CROSSTALK-VERSION        #   must be exactly: 6.0
-    PROTOCOL.md              #   agent orientation prompt
-    actors/<name>.md         #   default actor profiles
-  local/                     # operator-owned: never touched by the runtime
-    actors/<name>.md         #   custom actor profiles (override upstream by name)
-  hosts/
-    <alias>.md               # one per machine running a dispatcher
-  data/
-    channels/<uuid>/
-      CHANNEL.md             # optional channel metadata
-      YYYY/MM/DD/HHMMSSmmmZ-<hex>.md   # messages
-    memories/<stamp>-<hex>.md          # shared persistent notes
-```
-
-That is the complete committed surface. **Dispatcher bookkeeping (cursors, dead-letter
-queue, error logs, lock state) is machine-local state and never lives in the repo** —
-it is kept under `$CROSSTALK_STATE_DIR` (default `~/.local/state/crosstalk/<transport-id>/`,
-where `<transport-id>` is derived from the origin URL). The repo carries conversation;
-each machine carries its own progress through it.
-
----
-
-## Channels
-
-A channel is a UUID v4 directory under `data/channels/`. Any participant may create
-one by creating the directory and committing. An optional `CHANNEL.md` declares
-metadata:
-
-```
----
-name: dogfood-sprint
-created_by: steve
-created_at: 2026-06-09T17:00:00.000Z
-parent: <uuid>          # optional — makes this a subchannel
----
-
-Free-form description. Serves as a mini system prompt scoped to the channel.
-```
-
-`name` is required and unique within the transport; the other fields are optional.
-A subchannel is just a channel with a `parent:`; it reports back by posting to the
-parent channel. There is no close signal — a finished channel simply goes quiet.
-
----
-
-## Messages
-
-Every message is a markdown file with YAML frontmatter:
-
-```
----
-from: alice
-to: concierge
-type: text
-timestamp: 2026-06-09T19:00:00.000Z
----
-
-Message body here.
-```
-
-### Frontmatter fields
-
-| Field | Required | Notes |
-|---|---|---|
-| `from` | yes | logical actor name — unverified; trust boundary is repo access |
-| `to` | yes | name, list of names, or `all`; may carry `@host` suffix (see Routing) |
-| `type` | yes | always `text` in 6.0 |
-| `timestamp` | yes | ISO 8601 UTC |
-| `re` | no | relPath (or list of relPaths) of the message(s) this one answers — **written by the runtime, never by hand** |
-| `tier` | no | requested model tier for the recipient (see Host files) |
-
-Readers must ignore unknown fields.
-
-### The `re:` field — causality is recorded, not inferred
-
-A message **without** `re:` is a new task. A message **with** `re:` is a reply to the
-message(s) at the listed relPath(s) (paths relative to the channel directory). Like
-`to:`, the field is a string for one target and a list for several — a reply that
-answers a batch records **every** message it answers, so batching never makes an
-answered message look unanswered.
-
-The runtime sets `re:` from facts it directly observes:
-
-- When an actor answers via stdout, the runtime writes the reply with `re:` listing
-  every message in the dispatched batch from that asker.
-- When a dispatched actor uses `crosstalk send`, the runtime injects the triggering
-  relPath(s) into the environment and `send` records them automatically. An actor can
-  suppress this (`--new`) to start genuinely new work.
-- Messages written by operators (chat tools, hand-authored) carry no `re:` — they
-  are new tasks by definition.
-
-Actors never compute or hand-write `re:`. Because the field is set by the machinery
-that already knows the answer, a confused or dishonest actor cannot mislabel a reply
-as a task or vice versa.
-
-### Filenames
-
-`data/channels/<uuid>/YYYY/MM/DD/HHMMSSmmmZ-<hex>.md` — current UTC time plus a
-hex suffix of at least 8 characters from a CSPRNG. Filenames sort chronologically
-and are collision-free by construction, so concurrent writers on different machines
-never produce git conflicts in message files.
-
----
-
-## Activation — when does a message wake its addressee?
-
-One rule:
-
-> **A message wakes its addressee if it has no `re:` (a new task), or any `re:`
-> entry points at a message the addressee sent.**
-
-Consequences:
-
-- Tasks always wake the actor they address.
-- A reply wakes whoever asked the question, and no one else.
-- A reply addressed to someone who never asked (an FYI, a broadcast copy) is visible
-  in the channel but does not wake them — fan-in cannot oscillate.
-- Self-sent messages never wake their sender.
-
-There are no other wake conditions and no inference. The dispatcher evaluates this
-rule with two field reads.
-
----
-
-## Delivery semantics
-
-**At-least-once.** Each dispatcher tracks a per-actor, per-channel cursor (local
-state, not in the repo) recording the git commit the channel was last scanned at —
-"new" means *added to git since that commit*, never "later filename timestamp",
-because messages reach origin in push order, not timestamp order. If a machine
-crashes mid-tick, the next tick re-dispatches anything not yet past the cursor;
-a duplicate reply may land in the channel.
-
-For idempotent work (lookups, computation, advice) duplicates are harmless. For
-non-idempotent side effects, the actor must check the channel for evidence of prior
-completion before acting. Crosstalk does not provide exactly-once semantics.
-
-**Batched delivery.** When a dispatcher wakes an actor, it hands over ALL pending
-messages addressed to that actor in that channel in a single invocation. One
-activation drains the mailbox — a coordinator that fanned out to 10 peers wakes
-once and sees all 10 replies together.
-
-The transport is an **append-only log**. No retraction, no deletion at the protocol
-level. Retention is the operator's concern at the git/storage layer.
-
----
-
-## Actors
-
-Each participant has a profile at `local/actors/<name>.md` (operator-owned) or
-`upstream/actors/<name>.md` (defaults; `local/` wins on name collision). The body
-is the actor's system prompt.
-
-```
----
-name: concierge
-description: "General-purpose worker and coordinator."
----
-
-## System Prompt
-You are the general-purpose worker in this Crosstalk transport. ...
-```
-
-`name` (matching the filename stem) and `description` are required; the rest of the
-frontmatter is free. Actors are added, edited, and removed by committing files.
-
----
-
-## Host files
-
-A host file at `hosts/<alias>.md` declares one machine running a dispatcher and the
-actors it serves. Each operator commits and maintains their own.
-
-```
----
-alias: cachy
-hostname: steve-cachyos
-actors:
-  concierge:
-    claude: claude --print --dangerously-skip-permissions
-  junior-developer:
-    haiku:
-      cli: claude --model claude-haiku-4-5 --print --dangerously-skip-permissions
-      count: 5
----
-```
-
-| Field | Required | Notes |
-|---|---|---|
-| `alias` | yes | the host's name in `actor@host` addressing |
-| `hostname` | no | OS hostname, used for dispatcher auto-detection |
-| `actors` | yes | actor → tier map |
-
-A **tier** is a named CLI slot. The bare-string shorthand means `count: 1`; the
-object form adds `count:` (parallel invocations) per tier. Tier names are
-operator-defined labels (`haiku`, `opus`, `flash`); senders may request one with
-the `tier:` message field, and the dispatcher falls back to the first declared
-tier when the requested one doesn't exist.
-
-On startup a dispatcher finds its own host file by matching `hostname:` (or via an
-explicit `--host <alias>` override). No match → log clearly and idle; never crash.
-
----
-
-## Routing
-
-The `to:` field accepts:
-
-- `to: concierge` — bare name. Every host that declares the actor dispatches it.
-- `to: junior-developer@cachy` — narrowed to the host whose `alias` is `cachy`;
-  other hosts skip it (and log the skip, so wrong-host routes are visible).
-- `to: [a, b@mac]` — lists mix freely.
-- `to: all` — every participant.
-
-The actor name is everything before the `@`; the host alias is everything after.
-The `re:` activation rule ignores host suffixes — only addressing honors them.
-
-Use bare names for work-pool patterns where any machine will do; use `@host` when
-the orchestration depends on which machine runs the work. This addressing is the
-entirety of Crosstalk's multi-host model.
-
----
-
-## Identity and trust
-
-`from:` is an unverified string. The trust boundary is repository access: anyone who
-can push can claim any name. `to:` is a routing hint, not access control — every
-message is visible to anyone with repo access. Operators who need confidentiality
-or verified identity must secure the repository itself.
-
----
-
-## Memories
-
-Shared persistent notes any participant may read or write, at
-`data/memories/YYYYMMDDTHHMMSSmmmZ-<hex>.md`:
-
-```
----
-from: concierge
-timestamp: 2026-06-09T19:00:00.000Z
-subject: Steve prefers TypeScript for all new tooling
-scope: global              # or a channel uuid
-supersedes: <filename>     # optional — replaces an earlier memory
----
-
-Body.
-```
-
-When loading, skip any memory named in another memory's `supersedes:`. Agents use
-`data/memories/` instead of their model-native memory systems.
-
----
-
-## Coordination
-
-Git is self-coordinating: filenames are collision-free and non-fast-forward pushes
-are rejected and retried with `git pull --rebase`. A transport therefore works with
-no coordinator at all.
-
-Dispatchers MAY use a turn coordinator (cordfuse/turnq) to reduce push contention —
-locally via file lock, or across hosts via a shared turnq server. Coordination is
-**advisory**: a dispatcher waits for its turn with a bounded timeout and proceeds
-anyway on timeout or coordinator failure, letting git arbitrate. A coordinator
-outage may cost push retries; it can never stall message processing.