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

package/GUIDE-CLI.md

@@ -0,0 +1,298 @@
+# Crosstalk CLI Guide
+
+Quick reference for the `crosstalk` CLI. Run `crosstalk <subcommand> --help` for flags.
+
+Requires: Node.js ≥ 20. All subcommands (except `init`) must be run from inside a transport (a directory containing `upstream/CROSSTALK-VERSION`).
+
+---
+
+## Setup
+
+### `crosstalk init`
+
+Scaffold a new transport in the current directory:
+
+```sh
+mkdir my-transport && cd my-transport
+git init
+crosstalk init
+```
+
+Creates `upstream/` (spec + protocol docs), `hosts/`, `data/`, and `local/actors/`. Commit and push to your git remote; that repo is now the message bus.
+
+> ### Multi-host: seed every host file before sending
+>
+> Each host's delivery waterline is the commit that first added **its** host
+> file to the transport. A message addressed to a host *before* that host's
+> file exists in history sits below the waterline and is never delivered.
+>
+> **Therefore, when adding a host to a multi-host bus, commit + push its
+> `hosts/<alias>.md` BEFORE anyone sends messages to it.** A host that joins
+> an existing transport must seed its host file first; messages sent to it
+> earlier won't be received.
+>
+> `crosstalk send` warns when `--to <actor>@<host>` names a host with no host
+> file in the transport, so the silent drop becomes a visible error at send
+> time.
+>
+> **Single-host operators don't need to think about this** — `crosstalk init`
+> seeds your host file at setup, before any messaging, so the ordering can
+> never bite you.
+
+---
+
+## Choosing and wiring an agent
+
+Crosstalk is **agent-agnostic**. An actor is any CLI that reads a prompt and
+prints a reply — there is no built-in model and no vendor requirement. You wire
+your agent in the host file, under the actor's tier, as a `cli:` string:
+
+```yaml
+# hosts/<your-host>.md
+---
+alias: my-laptop
+hostname: my-laptop
+actors:
+  concierge:
+    default:
+      cli: <your-agent-cli>      # the command crosstalk runs to invoke the agent
+---
+```
+
+### The contract
+
+When the dispatcher invokes an actor it:
+
+1. composes `system prompt + the message(s)` and **appends it as the last
+   argument to your CLI command**, then
+2. reads the CLI's **stdout** as the reply body, and expects exit code **0**.
+
+So a `cli:` works if the command runs **one prompt non-interactively** (taking
+the prompt as its trailing positional or flag-value) and **prints the answer
+to stdout**. Two things to get right per agent:
+
+- **Non-interactive / skip-approval flag.** Each agent has a flag that stops it
+  from pausing for confirmation or opening a TUI. Use it, or every dispatch will
+  hang until the 5-minute timeout and land in the DLQ.
+- **Trailing argument shape.** The dispatcher tacks the prompt on the end of
+  whatever you put in `cli:`. So `cli: codex exec` becomes
+  `codex exec "<prompt>"`, `cli: gemini -p` becomes `gemini -p "<prompt>"`,
+  and `cli: claude --print --dangerously-skip-permissions` becomes
+  `claude --print --dangerously-skip-permissions "<prompt>"`. Every modern
+  agent CLI is happy with one of those shapes.
+
+> For prompts larger than 64 KB (huge batches) the dispatcher falls back to
+> writing the prompt to **stdin** automatically — the default argv path covers
+> every supported agent, and the stdin fallback keeps things working past the
+> OS `ARG_MAX` limit.
+
+### Recipes
+
+Starting points — **verify flags against your installed CLI version**;
+vendors change them.
+
+| Agent | Example `cli:` | Notes |
+|---|---|---|
+| Claude Code | `claude --print --dangerously-skip-permissions` | accepts the prompt as a positional arg |
+| OpenAI Codex | `codex exec` | `exec` = non-interactive; add its bypass/sandbox flag |
+| Gemini CLI | `gemini -p` | `-p` one-shot prompt; add `--yolo` to skip approvals |
+| Qwen Code | `qwen -p` | Gemini-CLI-family flags |
+| opencode | `opencode run` | `run` = one-shot |
+| Antigravity | `agy -p` | `-p`/`--print` non-interactive |
+
+You can mix agents in one transport — different actors (or different hosts) can
+run entirely different vendors. Senders never know or care which agent answered.
+
+> **Privacy note for shared infrastructure.** The prompt is passed as an
+> argv arg, which means it's visible to anything that can read the
+> dispatcher process's `/proc/<pid>/cmdline` (e.g. `ps auxww`). On a single-
+> user laptop or dedicated dispatcher VM that's a non-issue; on multi-user
+> machines, plan accordingly.
+
+### Tiers (optional)
+
+A tier is a named CLI slot under an actor. The bare-string shorthand is `count: 1`;
+the object form adds `count:` for parallel instances. Senders may request a tier
+with `--tier <name>`; the dispatcher falls back to the first declared tier when
+the requested one is absent.
+
+```yaml
+actors:
+  junior-developer:
+    fast:
+      cli: gemini -p --yolo
+      count: 5            # five parallel slots picking up work independently
+```
+
+---
+
+## Sending messages
+
+### `crosstalk send --to <actor> --channel <uuid> "<body>"`
+
+Post a message to an actor. The channel must already exist (see `crosstalk channel`).
+
+```sh
+crosstalk send \
+  --to concierge \
+  --channel 56f57ff9-7031-4ab2-9b98-4f299d3240fb \
+  "What is the capital of France?"
+```
+
+Prints `Sent: <relPath>` — save that path if you need to check for replies.
+
+| Flag | Required | Notes |
+|---|---|---|
+| `--to <actor[,actor]>` | yes | bare name or `actor@host`; comma-separated list OK |
+| `--channel <uuid>` | yes | channel UUID |
+| `--from <actor>` | no | defaults to `$USER` / `operator` |
+| `--tier <name>` | no | request a specific model tier |
+| `--new` | no | suppress automatic `re:` linking (start new work, not a reply) |
+
+---
+
+## Running a dispatcher
+
+### `crosstalk dispatch`
+
+Start the dispatch loop in the current transport. Runs forever, polling for new messages and invoking actor CLIs.
+
+```sh
+crosstalk dispatch --poll 30 --json
+```
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--poll <seconds>` | `30` | quiet-tick interval; active ticks drop to 1s automatically |
+| `--host <alias>` | auto-detect | override which `hosts/<alias>.md` to load |
+| `--json` | off | structured JSON log lines |
+| `--log-file <path>` | none | mirror logs to a file |
+| `--once` | off | run one tick then exit (useful for testing) |
+
+> **macOS note — hostname auto-detect.** macOS's kernel hostname (`os.hostname()`) can drift across network state when the static **HostName** is unset (`configd` re-derives it from DHCP, reverse-DNS, or your VPN/Tailscale machine name). The dispatcher works around this on Darwin by also trying `scutil --get LocalHostName` and its `.local` form when matching against `hosts/<alias>.md`. If auto-detect still fails, either pin `--host <alias>` or pin your kernel hostname once:
+> ```sh
+> sudo scutil --set HostName <your-host-alias>
+> ```
+
+Dispatcher state (cursors, DLQ, heartbeat, error log) is stored under `$CROSSTALK_STATE_DIR` (default `~/.local/state/crosstalk/<transport-id>/`) — never in the transport repo.
+
+---
+
+## Observability
+
+### `crosstalk status`
+
+Print host file, active channels, cursor positions, DLQ count, and dispatcher heartbeat.
+
+```sh
+crosstalk status
+```
+
+### `crosstalk replies --re <relPath>[,<relPath>...]`
+
+Show which of your dispatched messages have replies. Matches via the runtime-written `re:` field — ground truth, not body-parsing.
+
+```sh
+crosstalk replies --re 2026/06/10/130847758Z-780a8b90.md
+```
+
+---
+
+## DLQ
+
+### `crosstalk dlq`
+
+Manage the dead-letter queue — messages that failed to dispatch repeatedly.
+
+```sh
+crosstalk dlq --list             # list quarantined entries
+crosstalk dlq --show <id>        # full detail for one entry
+crosstalk dlq --retry <id>       # re-queue for dispatch
+```
+
+A common first-run cause of DLQ entries: the actor's `cli:` isn't truly
+non-interactive (missing its skip-approval flag), so dispatches hang until the
+5-minute timeout. See **Choosing and wiring an agent**.
+
+---
+
+## Channels
+
+### `crosstalk channel --name <name>`
+
+Create a new channel and print its UUID.
+
+```sh
+crosstalk channel --name "sprint-42"
+```
+
+| Flag | Notes |
+|---|---|
+| `--name <name>` | required; unique within the transport |
+| `--parent <uuid>` | make this a subchannel; it reports back to the parent |
+
+---
+
+## Interactive
+
+### `crosstalk chat`
+
+Send a message and wait for the reply in one command. Useful for interactive sessions from the terminal.
+
+```sh
+crosstalk chat --to concierge --channel <uuid>
+```
+
+### `crosstalk open --actor <name>`
+
+Open an interactive REPL-style session with an actor — each exchange is a full dispatch cycle. Requires a TTY.
+
+```sh
+crosstalk open --actor concierge
+```
+
+### `crosstalk attach`
+
+Attach to a running dispatch loop's live log output (like `tail -f`, but structured).
+
+> Prefer talking to Crosstalk in plain language instead of memorising flags?
+> See **[GUIDE-PROMPTS.md](GUIDE-PROMPTS.md)** for the natural-language operator interface.
+
+---
+
+## Misc
+
+### `crosstalk wake`
+
+Poke the dispatcher to tick immediately. Rarely needed — `send` already signals the dispatcher.
+
+### `crosstalk version`
+
+Print the installed runtime version.
+
+### `crosstalk upgrade`
+
+Check whether the transport's protocol version matches the installed runtime and apply any necessary upgrades to `upstream/`.
+
+---
+
+## Common patterns
+
+**One-shot task from a script:**
+```sh
+UUID=$(crosstalk channel --name "batch-$(date +%s)" | grep -o '[0-9a-f-]\{36\}')
+crosstalk send --to concierge --channel "$UUID" "Summarise this file: ..." > /dev/null
+# dispatch loop will pick it up on next poll
+```
+
+**Check if fan-out replies are all in:**
+```sh
+# After dispatching to 5 peers, record their relPaths:
+crosstalk replies --re path1.md,path2.md,path3.md,path4.md,path5.md
+```
+
+**Troubleshooting a stuck dispatcher:**
+```sh
+crosstalk status          # check heartbeat freshness and DLQ count
+crosstalk dlq --list      # see what's quarantined
+```

package/GUIDE-PROMPTS.md

@@ -0,0 +1,132 @@
+# Crosstalk Natural-Language Guide
+
+You don't have to memorise the `crosstalk` CLI to use Crosstalk. You can just
+**talk to it.**
+
+Crosstalk has an *operator mode*: you open a conversation with an agent inside
+your transport and ask for things in plain language — "ask the test-runner on
+the server whether the build is green." The agent translates your words into the
+right `crosstalk` commands, waits for the answer, and tells you what came back —
+no UUIDs, no file paths, no git.
+
+This is the companion to the **[CLI guide](GUIDE-CLI.md)**. Same system, two
+front doors: type commands, or just speak.
+
+> Operator mode is **agent-agnostic**, like the rest of Crosstalk. Whatever
+> coding agent you already run — Claude Code, Codex, Gemini, Qwen, opencode,
+> Antigravity — can be your operator interface, as long as it can read the
+> transport's orientation file and run shell commands.
+
+---
+
+## Starting an operator conversation
+
+Pick whichever fits your setup:
+
+```sh
+# Purpose-built: open an actor in an interactive operator session
+crosstalk open --actor concierge
+```
+
+or simply **launch your agent CLI from inside the transport directory.** The
+transport ships an orientation file at its root (`CLAUDE.md`, and equivalents
+for other agents) that tells your agent it is in operator mode and how to drive
+Crosstalk. Start talking.
+
+> **Operator mode ≠ being an actor.** When you open a session this way, *you*
+> (through the agent) are the human's interface — you are not `concierge` or any
+> other actor, and you do **not** process incoming messages. Leave message
+> *processing* to the running dispatcher (`crosstalk dispatch`). Don't run
+> `crosstalk dispatch` or `crosstalk open` from an operator session — both
+> compete with the dispatcher.
+
+---
+
+## The phrasebook
+
+Say it however feels natural; these are the intents the operator agent
+recognises and what it does for you.
+
+| You say… | What happens |
+|---|---|
+| "ask concierge to summarise `report.md`" | sends the task to `concierge`, waits, surfaces the reply |
+| "ask the junior-dev on the server to run the tests" | sends to `junior-developer@server`, waits, reports back |
+| "ask everyone for a status update" | sends to `all`, collects the replies as they arrive |
+| "in the *sprint-42* channel, ask concierge to plan the work" | scopes the message to that channel |
+| "is the dispatcher alive?" / "check status" | runs `crosstalk status`, explains the heartbeat plainly |
+| "what's stuck?" / "what's in the dead-letter queue?" | runs `crosstalk dlq`, summarises the failures |
+| "retry that failed one" | runs `crosstalk dlq --retry <id>` |
+| "make a channel called *release-7*" | creates the channel, tells you it's ready |
+| "what channels exist?" | lists channels by their human names |
+| "tweak the concierge actor to be more terse" | edits `local/actors/concierge.md`, commits, pushes |
+| "pull the latest" | runs `git pull --rebase` |
+
+---
+
+## Coordinating a team in plain language
+
+The real power is fan-out. Tell the coordinator the goal and let it dispatch:
+
+> **You:** "Ask concierge to get three things done: update the changelog, run
+> the test suite on the server, and draft release notes — then summarise when
+> they're all back."
+
+Behind the scenes the coordinator sends one message per task to the right
+actors, ends its turn, and is automatically re-woken as each reply lands; when
+all are in, it aggregates and answers you. You just see:
+
+> *(waiting for concierge…)*
+> **concierge:** All three done. Changelog updated, 142 tests green on the
+> server, draft release notes attached below. …
+
+You never see the orchestration — only the result.
+
+---
+
+## What to expect
+
+- **It's asynchronous.** Each round-trip is roughly 5–30 seconds — your message
+  is committed and pushed, the recipient's dispatcher polls, the agent runs, its
+  reply is committed and pulled back. The operator agent will say something like
+  *"(waiting for concierge…)"* and surface the answer when it arrives.
+- **Replies are matched by fact, not by claim.** Crosstalk records which message
+  each reply answers, so "has it replied yet?" is always answered from ground
+  truth — a busy or confused actor can't fake completion.
+- **At-least-once delivery.** For anything with side effects (sending an email,
+  deploying), the operator agent — and the actors — check the channel for prior
+  completion before repeating. For lookups and advice, the occasional duplicate
+  is harmless.
+- **If nothing comes back** (~10 minutes), the operator agent will offer to
+  check `status` and the DLQ for clues — usually a dispatcher that's down or an
+  actor whose CLI isn't wired correctly (see
+  [GUIDE-CLI.md → Choosing and wiring an agent](GUIDE-CLI.md#choosing-and-wiring-an-agent)).
+
+---
+
+## Tips for good results
+
+- **Name the actor when it matters.** "ask concierge" reaches it on every host
+  that runs it; "ask concierge **on cachy**" pins it to one machine. Use the host
+  when *where* the work runs is part of the ask.
+- **Name the channel for threaded work.** If you don't, and there's more than one
+  channel, the operator agent will ask which one rather than guess.
+- **Be explicit for non-idempotent actions.** "deploy to staging" is a side
+  effect; say so clearly and the actor will verify it hasn't already happened.
+- **You don't need to know UUIDs or paths — ever.** If the operator agent starts
+  showing you raw file paths or git output, tell it to "talk to me like a person";
+  hiding that machinery is its job.
+
+---
+
+## When to drop to the CLI
+
+Natural language covers day-to-day operation. Reach for the
+**[CLI guide](GUIDE-CLI.md)** when you're:
+
+- scripting or automating (cron jobs, CI),
+- setting up hosts and wiring agent CLIs,
+- running the dispatcher itself, or
+- debugging cursors / the DLQ in detail.
+
+Both drive the exact same transport — use whichever is faster for the task in
+front of you.

package/README.md

@@ -0,0 +1,139 @@
+# Crosstalk
+
+**A shared message bus for humans and AI agents, built on git.**
+
+Crosstalk lets people and AI coding agents talk to each other asynchronously —
+across machines, across vendors, across time — using nothing but a git
+repository as the medium. The repo *is* the bus. There is no server to run, no
+database, no broker. If you can `git push`, you can participate.
+
+Crosstalk is **agent-agnostic by design.** It does not ship, embed, or require
+any particular model or vendor. An "actor" is just a command-line program that
+reads a prompt and prints a reply. Claude Code, Codex, Gemini CLI, Qwen Code,
+opencode, Antigravity — anything that follows that one contract can be an actor.
+Mix vendors freely in a single transport.
+
+---
+
+## Why
+
+- **No infrastructure.** The message bus is a git repo. Host it on GitHub, a
+  private Gitea, a USB stick — anything git speaks to.
+- **Durable and auditable.** Every message is a committed file. The whole
+  conversation is the git history.
+- **Cross-machine.** A dispatcher on each machine picks up messages addressed to
+  the actors that machine runs. Your laptop, a server, and a Raspberry Pi can all
+  share one transport.
+- **Vendor-neutral.** Bring whichever agent CLI you already use. No lock-in.
+- **Self-coordinating.** Filenames are collision-free; pushes rebase-retry.
+  A transport works with no central coordinator at all.
+
+---
+
+## The one contract
+
+A Crosstalk **actor** is any CLI that:
+
+1. accepts a prompt (the dispatcher appends it as the CLI's last argument), and
+2. prints its reply to **stdout**, then exits `0`.
+
+That's it. No SDK, no plugin, no adapter. If your agent's CLI can run one prompt
+non-interactively and print an answer, it works. See
+[GUIDE-CLI.md](GUIDE-CLI.md#choosing-and-wiring-an-agent) for ready-made `cli:`
+recipes per agent.
+
+---
+
+## 60-second quickstart
+
+```sh
+# 1. Install the runtime
+npm install -g @cordfuse/crosstalk
+
+# 2. Scaffold a transport (a git repo that is the message bus)
+mkdir my-bus && cd my-bus && git init
+crosstalk init .
+git add -A && git commit -m "initial transport" && git remote add origin <your-repo> && git push -u origin main
+
+# 3. Tell this machine which agent runs your actor.
+#    Edit hosts/<this-host>.md and set the actor's CLI to YOUR agent:
+#      actors:
+#        concierge:
+#          default:
+#            cli: <your-agent-cli>        # see the table below
+git add hosts && git commit -m "configure host" && git push
+
+# 4. Start the dispatch loop on this machine
+crosstalk dispatch &
+
+# 5. Send a message — the dispatcher invokes your agent and commits its reply
+crosstalk send --to concierge "What is the capital of France?"
+```
+
+### Pick your agent
+
+Set the actor's `cli:` in your host file to whichever you use. The dispatcher
+appends the prompt as the last argument to your `cli:` command — every modern
+agent CLI accepts it that way, so no wrapper is needed:
+
+| Agent | Example `cli:` |
+|---|---|
+| Claude Code | `claude --print --dangerously-skip-permissions` |
+| OpenAI Codex | `codex exec` |
+| Gemini CLI | `gemini -p` |
+| Qwen Code | `qwen -p` |
+| opencode | `opencode run` |
+| Antigravity | `agy -p` |
+
+Each agent also needs its own non-interactive / skip-approval flag so it doesn't
+block waiting for input — `claude` uses `--dangerously-skip-permissions`,
+others have equivalents. Confirm flags against your installed CLI version.
+See [GUIDE-CLI.md](GUIDE-CLI.md#choosing-and-wiring-an-agent).
+
+---
+
+## Two ways to use it
+
+- **[GUIDE-CLI.md](GUIDE-CLI.md)** — drive Crosstalk with the `crosstalk`
+  command: send, dispatch, channels, DLQ, status. For scripts and operators who
+  like a terminal.
+- **[GUIDE-PROMPTS.md](GUIDE-PROMPTS.md)** — drive Crosstalk in plain language.
+  Open an actor in operator mode and just *talk*: "ask the test-runner on the
+  server whether the build is green." The agent translates your words into
+  Crosstalk commands and surfaces the answer conversationally.
+
+---
+
+## Core concepts (one line each)
+
+- **Transport** — a git repo scaffolded by `crosstalk init`; the message bus.
+- **Channel** — a UUID directory under `data/channels/`; a conversation thread.
+- **Message** — a markdown file with YAML frontmatter; `crosstalk send` writes it.
+- **Actor** — a named participant whose system prompt lives in `local/actors/<name>.md`.
+- **Host file** — `hosts/<alias>.md`; declares which actors a given machine runs and with which CLI.
+- **Dispatcher** — `crosstalk dispatch`; the per-machine loop that invokes actors and writes their replies.
+
+Full protocol: **[upstream/CROSSTALK.md](transport/upstream/CROSSTALK.md)**.
+
+### Multi-host in one sentence
+
+Every machine commits its own `hosts/<alias>.md` to the transport, then runs
+`crosstalk dispatch`; address `actor@host` to target a specific machine, or a
+bare `actor` to reach it wherever it runs. (Provision each host's file *before*
+sending to it — see [GUIDE-CLI.md](GUIDE-CLI.md).)
+
+---
+
+## Running headless (Docker)
+
+A reference server image runs a dispatcher unattended against a remote
+transport. It's vendor-neutral too — pass whichever provider keys your actors
+need (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, …) and install
+the matching CLIs. See [server/ONBOARDING.md](server/ONBOARDING.md).
+
+---
+
+## Status
+
+Crosstalk 6.0. The protocol spec is versioned (`upstream/CROSSTALK-VERSION`);
+the runtime is published as [`@cordfuse/crosstalk`](https://www.npmjs.com/package/@cordfuse/crosstalk).