@cordfuse/crosstalk 6.0.0-alpha.10 → 6.0.0-alpha.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/GUIDE-CLI.md +1 -1
  2. package/GUIDE-PROMPTS.md +0 -0
  3. package/README.md +90 -93
  4. package/package.json +3 -3
  5. package/src/init.ts +6 -1
  6. package/template/README.md +94 -0
  7. package/template/upstream/PROTOCOL.md +7 -5
package/GUIDE-CLI.md CHANGED
@@ -144,7 +144,7 @@ Prints `Sent: <relPath>` — save that path if you need to check for replies.
144
144
  | Flag | Required | Notes |
145
145
  |---|---|---|
146
146
  | `--to <actor[,actor]>` | yes | bare name or `actor@host`; comma-separated list OK |
147
- | `--channel <uuid>` | yes | channel UUID |
147
+ | `--channel <uuid>` | only if multiple channels exist | Auto-detected when the transport has exactly one channel; required to disambiguate when there are several. |
148
148
  | `--from <actor>` | no | defaults to `$USER` / `operator` |
149
149
  | `--tier <name>` | no | request a specific model tier |
150
150
  | `--new` | no | suppress automatic `re:` linking (start new work, not a reply) |
package/GUIDE-PROMPTS.md CHANGED
File without changes
package/README.md CHANGED
@@ -1,139 +1,136 @@
1
- # Crosstalk
2
-
3
- **A shared message bus for humans and AI agents, built on git.**
4
-
5
- Crosstalk lets people and AI coding agents talk to each other asynchronously —
6
- across machines, across vendors, across time — using nothing but a git
7
- repository as the medium. The repo *is* the bus. There is no server to run, no
8
- database, no broker. If you can `git push`, you can participate.
9
-
10
- Crosstalk is **agent-agnostic by design.** It does not ship, embed, or require
11
- any particular model or vendor. An "actor" is just a command-line program that
12
- reads a prompt and prints a reply. Claude Code, Codex, Gemini CLI, Qwen Code,
13
- opencode, Antigravity — anything that follows that one contract can be an actor.
14
- Mix vendors freely in a single transport.
15
-
16
- ---
17
-
18
- ## Why
19
-
20
- - **No infrastructure.** The message bus is a git repo. Host it on GitHub, a
21
- private Gitea, a USB stick — anything git speaks to.
22
- - **Durable and auditable.** Every message is a committed file. The whole
23
- conversation is the git history.
24
- - **Cross-machine.** A dispatcher on each machine picks up messages addressed to
25
- the actors that machine runs. Your laptop, a server, and a Raspberry Pi can all
26
- share one transport.
27
- - **Vendor-neutral.** Bring whichever agent CLI you already use. No lock-in.
28
- - **Self-coordinating.** Filenames are collision-free; pushes rebase-retry.
29
- A transport works with no central coordinator at all.
1
+ # @cordfuse/crosstalk — runtime
2
+
3
+ > Part of the [Crosstalk repo](https://github.com/cordfuse/crosstalk) — the
4
+ > root README has the full problem statement, solution overview, and
5
+ > repository layout. The other tiers in the same repo are the
6
+ > [transport template](../transport/) and the
7
+ > [reference server image](../server/).
8
+
9
+ The `crosstalk` command-line tool. Installs as a single Node.js binary; runs
10
+ on a developer laptop or inside a server container. Provides every operator
11
+ verb in the Crosstalk protocol: scaffold a transport, send messages, run
12
+ the dispatcher loop, manage channels, retry the DLQ.
13
+
14
+ > **What Crosstalk is.** Crosstalk is an agent-agnostic swarm communication
15
+ > protocol built on git: a git repo is the message bus. Any CLI that accepts a
16
+ > prompt and prints a reply can be an actor; messages are committed files;
17
+ > coordination is peer-to-peer with no broker. Full background and problem
18
+ > space:
19
+ > **[github.com/cordfuse/crosstalk](https://github.com/cordfuse/crosstalk#the-problem)**.
30
20
 
31
21
  ---
32
22
 
33
- ## The one contract
23
+ ## Install
34
24
 
35
- A Crosstalk **actor** is any CLI that:
25
+ ```sh
26
+ npm install -g @cordfuse/crosstalk
27
+ ```
36
28
 
37
- 1. accepts a prompt (the dispatcher appends it as the CLI's last argument), and
38
- 2. prints its reply to **stdout**, then exits `0`.
29
+ Requires Node.js ≥ 20. Works on Linux and macOS. Windows is untested.
39
30
 
40
- That's it. No SDK, no plugin, no adapter. If your agent's CLI can run one prompt
41
- non-interactively and print an answer, it works. See
42
- [GUIDE-CLI.md](GUIDE-CLI.md#choosing-and-wiring-an-agent) for ready-made `cli:`
43
- recipes per agent.
31
+ To verify:
44
32
 
45
- ---
33
+ ```sh
34
+ crosstalk --version
35
+ ```
46
36
 
47
37
  ## 60-second quickstart
48
38
 
49
39
  ```sh
50
- # 1. Install the runtime
51
- npm install -g @cordfuse/crosstalk
52
-
53
- # 2. Scaffold a transport (a git repo that is the message bus)
40
+ # 1. Scaffold a transport (a git repo that is the message bus)
54
41
  mkdir my-bus && cd my-bus && git init
55
42
  crosstalk init .
56
- git add -A && git commit -m "initial transport" && git remote add origin <your-repo> && git push -u origin main
43
+ git add -A && git commit -m "initial transport"
44
+ git remote add origin <your-repo-url> && git push -u origin main
57
45
 
58
- # 3. Tell this machine which agent runs your actor.
59
- # Edit hosts/<this-host>.md and set the actor's CLI to YOUR agent:
46
+ # 2. Edit hosts/<this-host>.md to wire your agent's CLI under the actor.
47
+ # For example, to use Claude Code as `concierge`:
60
48
  # actors:
61
49
  # concierge:
62
50
  # default:
63
- # cli: <your-agent-cli> # see the table below
51
+ # cli: claude --print --dangerously-skip-permissions
64
52
  git add hosts && git commit -m "configure host" && git push
65
53
 
66
- # 4. Start the dispatch loop on this machine
54
+ # 3. Start the dispatch loop on this machine
67
55
  crosstalk dispatch &
68
56
 
69
- # 5. Send a message — the dispatcher invokes your agent and commits its reply
57
+ # 4. Send a message — the dispatcher invokes your agent and commits its reply
70
58
  crosstalk send --to concierge "What is the capital of France?"
71
59
  ```
72
60
 
73
- ### Pick your agent
61
+ The dispatcher invokes the configured CLI by appending the composed prompt as
62
+ the CLI's last argument (with automatic stdin fallback for prompts > 64 KB),
63
+ so almost any modern agent CLI works without a per-vendor wrapper.
74
64
 
75
- Set the actor's `cli:` in your host file to whichever you use. The dispatcher
76
- appends the prompt as the last argument to your `cli:` command — every modern
77
- agent CLI accepts it that way, so no wrapper is needed:
65
+ ## Subcommand reference
78
66
 
79
- | Agent | Example `cli:` |
67
+ | Subcommand | Purpose |
80
68
  |---|---|
81
- | Claude Code | `claude --print --dangerously-skip-permissions` |
82
- | OpenAI Codex | `codex exec` |
83
- | Gemini CLI | `gemini -p` |
84
- | Qwen Code | `qwen -p` |
85
- | opencode | `opencode run` |
86
- | Antigravity | `agy -p` |
87
-
88
- Each agent also needs its own non-interactive / skip-approval flag so it doesn't
89
- block waiting for input — `claude` uses `--dangerously-skip-permissions`,
90
- others have equivalents. Confirm flags against your installed CLI version.
91
- See [GUIDE-CLI.md](GUIDE-CLI.md#choosing-and-wiring-an-agent).
69
+ | `crosstalk init <dir>` | Scaffold a new transport into the given directory (copies the [template](../transport/)). |
70
+ | `crosstalk send --to <actor> [...]` | Write a message into a channel and push it. Auto-detects the channel if there's only one. |
71
+ | `crosstalk dispatch` | Run the per-machine dispatch loop. Polls for new messages, invokes actor CLIs, commits + pushes replies. |
72
+ | `crosstalk stop` | Stop the running dispatcher on this machine cleanly. Reads `dispatcher.pid` and sends SIGTERM. |
73
+ | `crosstalk status` | Print host file, channels, cursors, DLQ count, dispatcher heartbeat. |
74
+ | `crosstalk replies --re <relPath>` | Check which dispatched messages have replies. |
75
+ | `crosstalk dlq [--retry <id>]` | Inspect or retry dead-letter entries. |
76
+ | `crosstalk channel --name <name>` | Create a new channel; prints the UUID. |
77
+ | `crosstalk chat / open / attach` | Interactive operator entrypoints. |
78
+ | `crosstalk wake` | Poke a running dispatcher to tick immediately. |
79
+ | `crosstalk upgrade` | Reconcile the transport's protocol version against this runtime. |
80
+ | `crosstalk version` | Print runtime version. |
81
+
82
+ Detailed flag reference for every subcommand: **[GUIDE-CLI.md](./GUIDE-CLI.md)**
83
+ (also published alongside this package).
84
+
85
+ For natural-language operator use ("ask concierge to summarise this file") see
86
+ **[GUIDE-PROMPTS.md](./GUIDE-PROMPTS.md)**.
92
87
 
93
88
  ---
94
89
 
95
- ## Two ways to use it
90
+ ## What ships in this package
96
91
 
97
- - **[GUIDE-CLI.md](GUIDE-CLI.md)** — drive Crosstalk with the `crosstalk`
98
- command: send, dispatch, channels, DLQ, status. For scripts and operators who
99
- like a terminal.
100
- - **[GUIDE-PROMPTS.md](GUIDE-PROMPTS.md)** — drive Crosstalk in plain language.
101
- Open an actor in operator mode and just *talk*: "ask the test-runner on the
102
- server whether the build is green." The agent translates your words into
103
- Crosstalk commands and surfaces the answer conversationally.
92
+ - `bin/crosstalk.js` — the subcommand dispatcher; `npm install -g` links it as `crosstalk`.
93
+ - `src/` — TypeScript source; the runtime is executed via [tsx](https://www.npmjs.com/package/tsx) at run time (no compile step at install).
94
+ - `template/` — a snapshot of the [transport template](../transport/) at publish time. `crosstalk init` copies from here.
95
+ - `GUIDE-CLI.md`, `GUIDE-PROMPTS.md` — operator guides published alongside this package.
104
96
 
105
97
  ---
106
98
 
107
- ## Core concepts (one line each)
99
+ ## Local development
108
100
 
109
- - **Transport** — a git repo scaffolded by `crosstalk init`; the message bus.
110
- - **Channel** — a UUID directory under `data/channels/`; a conversation thread.
111
- - **Message** — a markdown file with YAML frontmatter; `crosstalk send` writes it.
112
- - **Actor** — a named participant whose system prompt lives in `local/actors/<name>.md`.
113
- - **Host file** — `hosts/<alias>.md`; declares which actors a given machine runs and with which CLI.
114
- - **Dispatcher** — `crosstalk dispatch`; the per-machine loop that invokes actors and writes their replies.
101
+ ```sh
102
+ # In the repo root
103
+ cd runtime
104
+ npm install
105
+ npm run build # tsc --noEmit type-check
106
+ node bin/crosstalk.js --version # invoke the dev binary directly
107
+ ```
115
108
 
116
- Full protocol: **[upstream/CROSSTALK.md](transport/upstream/CROSSTALK.md)**.
109
+ The runtime is type-checked but not transpiled — `tsx` runs the TypeScript
110
+ sources directly at invocation time. No build step is required for an
111
+ end-user install.
117
112
 
118
- ### Multi-host in one sentence
113
+ To work on the source while testing against a local transport, point the
114
+ binary at the dev path:
119
115
 
120
- Every machine commits its own `hosts/<alias>.md` to the transport, then runs
121
- `crosstalk dispatch`; address `actor@host` to target a specific machine, or a
122
- bare `actor` to reach it wherever it runs. (Provision each host's file *before*
123
- sending to it — see [GUIDE-CLI.md](GUIDE-CLI.md).)
116
+ ```sh
117
+ cd /path/to/your/transport
118
+ node /path/to/crosstalk/runtime/bin/crosstalk.js status
119
+ ```
124
120
 
125
121
  ---
126
122
 
127
- ## Running headless (Docker)
123
+ ## Dependencies
128
124
 
129
- A reference server image runs a dispatcher unattended against a remote
130
- transport. It's vendor-neutral too — pass whichever provider keys your actors
131
- need (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, …) and install
132
- the matching CLIs. See [server/ONBOARDING.md](server/ONBOARDING.md).
125
+ - [`@cordfuse/turnq`](https://www.npmjs.com/package/@cordfuse/turnq) — advisory
126
+ turn-coordination for serializing the commit+push window across hosts.
127
+ Optional in single-host setups; falls back to a local lockfile when no
128
+ turnq URL is configured.
129
+ - [`tsx`](https://www.npmjs.com/package/tsx) — run TypeScript directly without a build step.
130
+ - [`yaml`](https://www.npmjs.com/package/yaml) — frontmatter parsing.
133
131
 
134
132
  ---
135
133
 
136
- ## Status
134
+ ## License
137
135
 
138
- Crosstalk 6.0. The protocol spec is versioned (`upstream/CROSSTALK-VERSION`);
139
- the runtime is published as [`@cordfuse/crosstalk`](https://www.npmjs.com/package/@cordfuse/crosstalk).
136
+ MIT. See [LICENSE](https://github.com/cordfuse/crosstalk/blob/main/LICENSE) in the repo.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cordfuse/crosstalk",
3
- "version": "6.0.0-alpha.10",
3
+ "version": "6.0.0-alpha.11",
4
4
  "description": "Crosstalk runtime — async messaging between agents over git, across machines.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -23,8 +23,8 @@
23
23
  "build": "tsc --noEmit",
24
24
  "lint": "tsc --noEmit",
25
25
  "test": "bun test",
26
- "prepack": "cp -r ../transport template && cp ../README.md ../GUIDE-CLI.md ../GUIDE-PROMPTS.md .",
27
- "postpack": "rm -rf template README.md GUIDE-CLI.md GUIDE-PROMPTS.md"
26
+ "prepack": "cp -r ../transport template && cp ../GUIDE-CLI.md ../GUIDE-PROMPTS.md .",
27
+ "postpack": "rm -rf template GUIDE-CLI.md GUIDE-PROMPTS.md"
28
28
  },
29
29
  "dependencies": {
30
30
  "@cordfuse/turnq": "^0.4.2",
package/src/init.ts CHANGED
@@ -49,10 +49,15 @@ if (!templateDir) {
49
49
  }
50
50
 
51
51
  mkdirSync(targetDir, { recursive: true });
52
+ // Skip the template directory's own README — that's the meta-readme
53
+ // documenting the seed template itself, not content the operator wants
54
+ // inside their transport. (The init step writes a fresh README.md for
55
+ // the operator's transport later in this script.)
56
+ const templateReadme = join(templateDir, 'README.md');
52
57
  cpSync(templateDir, targetDir, {
53
58
  recursive: true,
54
59
  force,
55
- filter: (src) => !src.endsWith('/transport/README.md') && !src.endsWith('\\transport\\README.md'),
60
+ filter: (src) => src !== templateReadme,
56
61
  });
57
62
  // npm strips .gitignore from published packages; the template ships it as
58
63
  // `gitignore` and we rename it here.
package/template/README.md ADDED
@@ -0,0 +1,94 @@
1
+ # transport/ — the seed template
2
+
3
+ > Part of the [Crosstalk repo](../README.md) — the root README has the full
4
+ > problem statement, solution overview, and repository layout. The other
5
+ > tiers in the same repo are the [runtime](../runtime/) (the `crosstalk`
6
+ > CLI itself) and the [reference server image](../server/).
7
+
8
+ Source-of-truth content that `crosstalk init` copies into every new
9
+ transport. Not a runtime artifact, not a published package on its own —
10
+ it lives here in the monorepo so a single edit propagates to the npm
11
+ tarball at build time.
12
+
13
+ > **What Crosstalk is.** Crosstalk is an agent-agnostic swarm communication
14
+ > protocol built on git. A git repo is the message bus. Full background:
15
+ > **[the root README](../README.md)**.
16
+
17
+ ---
18
+
19
+ ## What lives here
20
+
21
+ | File | Purpose in the scaffolded transport |
22
+ |---|---|
23
+ | `upstream/CROSSTALK-VERSION` | Protocol version this transport is on. The runtime checks compatibility on every boot and refuses to dispatch against an incompatible version. |
24
+ | `upstream/CROSSTALK.md` | **The protocol specification.** Every behavioral rule the runtime obeys — message shape, activation, batching, cursors, durability semantics — is defined here. Authoritative. |
25
+ | `upstream/PROTOCOL.md` | Agent-facing orientation: prepended to every actor's system prompt so a fresh agent invocation knows it's running inside a Crosstalk transport and what's expected of it. |
26
+ | `upstream/OPERATOR.md` | Operator-facing orientation: what an *interactive* session opened against this transport (`crosstalk open`, `crosstalk chat`) is and isn't allowed to do. |
27
+ | `upstream/actors/concierge.md` | Default actor profile. Acts as the example for how to write a custom actor under `local/actors/<name>.md` in a real transport. |
28
+ | `CLAUDE.md` | Repo-style orientation file written for an AI coding agent that lands inside the transport directory. Mirrors the librarian / monorepo convention used across Cordfuse projects. |
29
+ | `gitignore` | Becomes the transport's `.gitignore` after init renames it. (npm strips files literally named `.gitignore` from published tarballs; we ship it without the leading dot and the runtime renames it on copy.) |
30
+
31
+ What does **not** live here:
32
+
33
+ - `data/channels/<uuid>/` — created on demand by `crosstalk init` and `crosstalk channel`.
34
+ - `hosts/<alias>.md` — generated by `crosstalk init` per host based on the
35
+ machine's hostname; the template doesn't predetermine the host name.
36
+ - `local/actors/<name>.md` — operator-authored, not in the template.
37
+ - `README.md` for the operator's own transport — that's their content,
38
+ not ours.
39
+
40
+ ---
41
+
42
+ ## How `crosstalk init` consumes this
43
+
44
+ At publish time, `runtime/package.json`'s `prepack` script copies this
45
+ entire directory into `runtime/template/`, which is what ships inside
46
+ the npm tarball:
47
+
48
+ ```json
49
+ "prepack": "cp -r ../transport template && cp ../README.md ../GUIDE-CLI.md ../GUIDE-PROMPTS.md ."
50
+ ```
51
+
52
+ At install time, `crosstalk init <dir>` then:
53
+
54
+ 1. Finds the bundled template (first under `runtime/template/`, falling back to `../transport/` in a monorepo dev checkout).
55
+ 2. Recursively copies the template into the target directory.
56
+ 3. Renames the copied `gitignore` to `.gitignore`.
57
+ 4. Generates `hosts/<hostname>.md` from the current machine's hostname.
58
+ 5. Generates the first channel directory `data/channels/<uuid>/CHANNEL.md`.
59
+
60
+ The runtime never reads from this directory at dispatch time — only at
61
+ `init` time, and only from the bundled copy.
62
+
63
+ ---
64
+
65
+ ## Editing the template
66
+
67
+ Anything in this directory is the source of truth for every future
68
+ transport scaffolded by `crosstalk init`. Edit conservatively:
69
+
70
+ - **`upstream/CROSSTALK.md`** — only when changing the protocol itself.
71
+ Bump `upstream/CROSSTALK-VERSION` in the same change. Update
72
+ `runtime/src/upgrade.ts`'s migration logic as needed.
73
+ - **`upstream/PROTOCOL.md`** — when the agent-facing contract changes
74
+ (new envelope fields, new activation rules). Agents inherit this at
75
+ dispatch time, so changes affect every actor immediately on upgrade.
76
+ - **`upstream/OPERATOR.md`** — when interactive session boundaries
77
+ change (e.g. forbidding `crosstalk dispatch` from inside an operator
78
+ session).
79
+ - **`upstream/actors/concierge.md`** — the default actor's prompt; touch
80
+ only when the default's character or capabilities should change.
81
+ - **`CLAUDE.md`** — orientation for repo-savvy agents that land inside
82
+ a transport directory. Keep aligned with the
83
+ [librarian](https://github.com/steve-krisjanovs/librarian) conventions.
84
+
85
+ Existing transports do **not** automatically pick up template changes.
86
+ Operators get the new content by running `crosstalk upgrade`, which
87
+ reconciles their `upstream/` against the installed runtime's bundled
88
+ template version.
89
+
90
+ ---
91
+
92
+ ## License
93
+
94
+ MIT. See [LICENSE](../LICENSE).
package/template/upstream/PROTOCOL.md CHANGED
@@ -26,11 +26,13 @@ single message, an empty reply is a protocol violation — you were addressed; r
26
26
 
27
27
  You have shell access from the transport root.
28
28
 
29
- - `crosstalk send --channel <uuid> --to <actor> "<body>"` — proactively message
30
- someone (replying to your prompt needs no tool — just answer). Sends are
31
- automatically linked (`re:`) to the message you are currently processing; pass
32
- `--new` to start unrelated work instead. `--tier <name>` requests a model tier.
33
- Prints `Sent: <relPath>` — keep that relPath if you are orchestrating (see below).
29
+ - `crosstalk send --to <actor> "<body>"` — proactively message someone (replying
30
+ to your prompt needs no tool — just answer). Pass `--channel <uuid>` only if
31
+ the transport has more than one channel (otherwise the single channel is
32
+ auto-detected). Sends are automatically linked (`re:`) to the message you are
33
+ currently processing; pass `--new` to start unrelated work instead.
34
+ `--tier <name>` requests a model tier. Prints `Sent: <relPath>` — keep that
35
+ relPath if you are orchestrating (see below).
34
36
  - `crosstalk replies --re <relPath>[,<relPath>...]` — shows which of your dispatched
35
37
  messages have replies. This is ground truth: replies are matched by the
36
38
  runtime-written `re:` field, not by anything a peer claims in its body.