@cordfuse/crosstalk 7.0.0-beta.1 → 8.1.0

package/src/web/chat-page.ts

@@ -155,7 +155,7 @@ export function chatPage(d: ChatPageData): string {
 
 <section class="card picker-card">
   <h3>Interactive chat</h3>
-  <p class="sub">Spawns a fresh agent process on the host attached to your browser via WebSocket. Close the tab, hit the back arrow, or type <code>/exit</code> to terminate gracefully. Hit the red <code>×</code> in the topbar for an immediate SIGKILL when an agent is wedged. Async-by-design: no persistent sessions — for durable work, use the orch bus.</p>
+  <p class="sub">Opens a live terminal session with an agent, right in your browser. Type to interact; close the tab or type <code>/exit</code> to end it. Sessions aren't saved — for work you want to keep, send a message on a channel and let the dispatcher reply. (To force-stop a stuck agent, the red <code>×</code> in the top bar kills it immediately.)</p>
 
   <div class="pick-row">
     <label for="chat-agent">agent</label>

package/src/web/chat-pty.ts

@@ -17,7 +17,7 @@
 //
 // Async-by-design contract: NO persistent session. Each WS attach
 // spawns a fresh agent. There's no detach + reattach. If you want
-// durable state, send messages through the orch bus.
+// durable state, send messages on a channel (the dispatcher replies).
 
 import type { Server as HttpServer } from 'http';
 import type { Duplex } from 'stream';

package/src/web/dashboard.ts

@@ -9,6 +9,7 @@ export interface DashboardData {
   alias: string;
   version: string;
   transportRoot: string;
+  transportKind: string;
   heartbeat: { ts: string; pid: number; version: string; alias: string | undefined } | null;
   cursor: string | null;
   claimedModels: string[];
@@ -28,13 +29,46 @@ export function dashboardPage(d: DashboardData): string {
   const namedChannels = d.channels.filter(c => c.name).map(c => c.name as string);
   const cursorShort = d.cursor ? d.cursor.slice(0, 8) + '…' : '—';
 
+  // Plain-language status banner so the first thing a newcomer reads is
+  // "what state am I in / what do I do next", not raw telemetry. Derived
+  // entirely from existing fields — no new backend.
+  const claimed = d.claimedModels.length;
+  const pendingTotal = d.pendingWork.reduce((sum, p) => sum + p.count, 0);
+  const hbStale = hbAge === null || hbAge >= 300_000;
+  let stColor: string, stLabel: string, stHint: string;
+  if (hbStale) {
+    stColor = '#f85149';
+    stLabel = 'Dispatcher not running';
+    stHint = 'No recent heartbeat — the engine isn\'t processing the bus. Start it with <code>crosstalk server start</code>.';
+  } else if (claimed === 0) {
+    stColor = '#d29922';
+    stLabel = 'No agents connected yet';
+    stHint = 'Connect your first agent in a guided setup — Crosstalk detects your installed CLIs and wires one up live. <a href="/welcome"><strong>Set up an agent →</strong></a>';
+  } else if (d.channels.length === 0) {
+    stColor = '#7ee787';
+    stLabel = `Ready · ${claimed} agent${claimed === 1 ? '' : 's'} connected`;
+    stHint = 'Create a channel to start a conversation, or open an interactive <a href="/chat">Chat</a>.';
+  } else {
+    stColor = '#7ee787';
+    stLabel = `Live · ${claimed} agent${claimed === 1 ? '' : 's'}, ${d.channels.length} channel${d.channels.length === 1 ? '' : 's'}`;
+    stHint = pendingTotal > 0
+      ? `${pendingTotal} message${pendingTotal === 1 ? '' : 's'} awaiting a reply — the dispatcher picks them up on its next tick.`
+      : 'Every message on the bus has a reply.';
+  }
+
   const body = `
+<section class="card" style="border-left:3px solid ${stColor}">
+  <h3 style="color:${stColor}">${escapeHtml(stLabel)}</h3>
+  <p class="sub" style="margin-bottom:0">${stHint}</p>
+</section>
+
 <div class="grid cols-2">
   <section class="card">
     <h3>Engine</h3>
     <div class="kv"><span class="key">alias</span><span class="val brand">${escapeHtml(d.alias)}</span></div>
     <div class="kv"><span class="key">version</span><span class="val">${escapeHtml(d.version)}</span></div>
-    <div class="kv"><span class="key">transport</span><span class="val dim">${escapeHtml(d.transportRoot)}</span></div>
+    <div class="kv"><span class="key">transport</span><span class="val">${escapeHtml(d.transportKind)}</span></div>
+    <div style="font-size:11px;color:#7a7f87;word-break:break-all;margin:-2px 0 10px">${escapeHtml(d.transportRoot)}</div>
     <div class="kv"><span class="key">cursor</span><span class="val">${escapeHtml(cursorShort)}</span></div>
   </section>
 

package/src/web/layout.ts

@@ -154,6 +154,15 @@ function commonStyles(): string {
   .toast.show{opacity:1;transform:translateX(-50%) translateY(0)}
   .toast.ok{color:#7ee787;border-color:#1f4528}
   .toast.err{color:#f85149;border-color:#4a2329}
+  /* Persistent sidebar on wide screens: the drawer is always open and the
+     content is inset to the right of it, so every nav item is visible
+     without opening the hamburger. Phones keep the slide-in drawer. */
+  @media (min-width:1024px){
+    body{margin-left:300px;max-width:1180px}
+    #nav-drawer{left:0;transition:none;box-shadow:none}
+    #nav-backdrop{display:none}
+    #nav-toggle{display:none}
+  }
   `;
 }
 

package/src/web/stubs.ts

@@ -475,8 +475,8 @@ export function settingsPage(d: SettingsPageData): string {
     host: d.host, alias: d.alias, activeNav: 'settings', pageTitle: 'Settings',
     body: `
 <section class="card">
-  <h3>Engine settings <span class="chip">read-only — backlog</span></h3>
-  <p class="sub">Snapshot of the running engine. Editable settings are on the backlog — for now, restart the engine with different flags / env vars.</p>
+  <h3>Engine settings</h3>
+  <p class="sub">The running engine's configuration. Settings come from <code>data/crosstalk.yaml</code>, CLI flags, and environment variables — edit those and restart the engine to change them. This page reflects what's currently live.</p>
   <div class="kv"><span class="key">alias</span><span class="val brand">${escapeHtml(d.alias)}</span></div>
   <div class="kv"><span class="key">version</span><span class="val">${escapeHtml(d.version)}</span></div>
   <div class="kv"><span class="key">transport root</span><span class="val dim" style="font-size:11px">${escapeHtml(d.transportRoot)}</span></div>
@@ -497,7 +497,7 @@ export function aboutPage(opts: CommonOpts & { version: string; transportRoot: s
     body: `
 <section class="card">
   <h3>Crosstalk</h3>
-  <p class="sub">Async git-backed message bus + dispatcher for AI agent CLIs. Sibling product to <a href="https://github.com/cordfuse/llmux">@cordfuse/llmux</a> (interactive tmux-based session mux).</p>
+  <p class="sub">Async message bus + dispatcher for AI agent CLIs, carried by git or a plain (incl. shared) filesystem. Sibling product to <a href="https://github.com/cordfuse/llmux">@cordfuse/llmux</a> (interactive tmux-based session mux).</p>
   <div class="kv"><span class="key">engine version</span><span class="val brand">${escapeHtml(opts.version)}</span></div>
   <div class="kv"><span class="key">alias</span><span class="val">${escapeHtml(opts.alias)}</span></div>
   <div class="kv"><span class="key">host</span><span class="val">${escapeHtml(opts.host)}</span></div>

package/src/web/wizard.ts

@@ -0,0 +1,172 @@
+// wizard.ts — first-run onboarding, served at GET /welcome and linked from
+// the dashboard when no agent is claimed yet. Three steps:
+//   1. Connect an agent  — POST /api/onboarding/connect (writes crosstalk.yaml
+//      + optional key, SIGHUPs the dispatcher so the model is claimed live).
+//   2. Create a channel  — POST /channels.
+//   3. Send a message    — POST /messages, then hand off to the channel view
+//      where the dispatcher's reply lands.
+//
+// The client JS builds DOM with string concatenation (no client-side template
+// literals) so it nests cleanly inside this module's template string.
+
+import { page, escapeHtml, TOAST_HELPER } from './layout.js';
+
+export interface WizardPageData {
+  host: string;
+  alias: string;
+}
+
+export function wizardPage(d: WizardPageData): string {
+  const body = `
+<section class="card">
+  <h3>Welcome to Crosstalk</h3>
+  <p class="sub">Crosstalk is a message bus where AI agent CLIs talk to each other and to you. Three quick steps to your first conversation.</p>
+  <div class="wiz-steps">
+    <span class="wiz-step active" data-step="1">1 · Connect an agent</span>
+    <span class="wiz-step" data-step="2">2 · Create a channel</span>
+    <span class="wiz-step" data-step="3">3 · Send a message</span>
+  </div>
+</section>
+
+<section class="card wiz-panel" id="panel-1">
+  <h3>Connect an agent</h3>
+  <p class="sub">These agent CLIs are installed on this engine. Pick one — Crosstalk writes the config and claims it live, no restart.</p>
+  <div id="agent-list"><p class="empty">Detecting installed agents…</p></div>
+</section>
+
+<section class="card wiz-panel" id="panel-2" style="display:none">
+  <h3>Create your first channel</h3>
+  <p class="sub">A channel is a conversation thread. Name it anything lowercase (e.g. <code>general</code>).</p>
+  <div class="field"><label for="ch-name">channel name</label><input id="ch-name" value="general" autocomplete="off"></div>
+  <div class="actions"><button id="ch-back" type="button">← back</button><button class="primary" id="ch-create" type="button">Create channel</button></div>
+</section>
+
+<section class="card wiz-panel" id="panel-3" style="display:none">
+  <h3>Send your first message</h3>
+  <p class="sub">Addressed to <span id="m-model" class="chip brand"></span> on <span id="m-channel" class="chip"></span>. The dispatcher delivers the reply to the channel.</p>
+  <div class="field"><label for="m-body">message</label><textarea id="m-body">Say hello and tell me one thing you can help with.</textarea></div>
+  <div class="actions"><button id="m-back" type="button">← back</button><button class="primary" id="m-send" type="button">Send message</button></div>
+</section>
+
+<section class="card wiz-panel" id="panel-done" style="display:none">
+  <h3>You're set up</h3>
+  <p class="sub">Your message is on the bus. Open the channel to watch your agent reply.</p>
+  <div class="actions"><a id="done-link" class="chip brand" href="/">View the conversation →</a></div>
+</section>
+`;
+
+  const js = `
+${TOAST_HELPER}
+var state = { model: null, channel: null };
+function show(step){
+  var panels = document.querySelectorAll('.wiz-panel');
+  for (var i=0;i<panels.length;i++) panels[i].style.display = 'none';
+  document.getElementById('panel-'+step).style.display = '';
+  var steps = document.querySelectorAll('.wiz-step');
+  for (var j=0;j<steps.length;j++){
+    var n = steps[j].getAttribute('data-step');
+    steps[j].classList.toggle('active', String(step) === 'done' || n <= String(step));
+  }
+}
+function esc(s){ var d = document.createElement('div'); d.textContent = s == null ? '' : String(s); return d.innerHTML; }
+async function loadAgents(){
+  var list = document.getElementById('agent-list');
+  try{
+    var r = await fetch('/api/onboarding/agents');
+    var data = await r.json();
+    var installed = (data.agents || []).filter(function(a){ return a.installed; });
+    if (!installed.length){ list.innerHTML = '<p class="empty">No supported agent CLIs found on this engine PATH. Install one (claude, codex, gemini, …) and reload.</p>'; return; }
+    list.innerHTML = installed.map(function(a){
+      var badge = a.claimed ? '<span class="chip" style="color:#7ee787">connected</span>' : '';
+      var key = (a.needsKey && !a.claimed) ? '<input class="agent-key" placeholder="API key — optional, blank if already logged in" style="margin-top:8px" autocomplete="off">' : '';
+      // Already claimed (revisit, or claimed outside the wizard): nothing to
+      // POST — just let the row advance the wizard with this model, rather
+      // than stranding the user behind a disabled "done" button.
+      var btn = '<button class="primary use-btn" type="button">' + (a.claimed ? 'Continue →' : 'Use this') + '</button>';
+      return '<div class="agent-row" data-cli="' + esc(a.cli) + '" data-qualified="' + esc(a.provider + '/' + a.model) + '" data-claimed="' + (a.claimed ? '1' : '0') + '">' +
+        '<div style="flex:1 1 auto;min-width:0">' +
+          '<div><span class="chip brand">' + esc(a.label) + '</span> ' + badge + '</div>' + key +
+          '<div style="font-size:11px;color:#7a7f87;margin-top:4px">' + esc(a.keyHint) + '</div>' +
+        '</div>' + btn + '</div>';
+    }).join('');
+    var rows = list.querySelectorAll('.agent-row');
+    for (var i=0;i<rows.length;i++){
+      (function(row){
+        row.querySelector('.use-btn').addEventListener('click', function(){
+          if (row.getAttribute('data-claimed') === '1'){
+            state.model = row.getAttribute('data-qualified');
+            document.getElementById('m-model').textContent = state.model;
+            show(2);
+          } else {
+            connect(row);
+          }
+        });
+      })(rows[i]);
+    }
+  }catch(e){ list.innerHTML = '<p class="empty">Failed to load agents: ' + esc(e.message) + '</p>'; }
+}
+async function connect(row){
+  var cli = row.getAttribute('data-cli');
+  var keyEl = row.querySelector('.agent-key');
+  var btn = row.querySelector('.use-btn');
+  btn.disabled = true; btn.textContent = 'Connecting…';
+  try{
+    var r = await fetch('/api/onboarding/connect', { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify({ cli: cli, apiKey: keyEl ? keyEl.value : undefined }) });
+    var data = await r.json();
+    if (!r.ok) throw new Error(data.error || 'connect failed');
+    state.model = data.qualified;
+    document.getElementById('m-model').textContent = data.qualified;
+    showToast(data.qualified + ' connected', 'ok');
+    show(2);
+  }catch(e){ showToast(e.message, 'err'); btn.disabled = false; btn.textContent = 'Use this'; }
+}
+document.getElementById('ch-back').addEventListener('click', function(){ show(1); });
+document.getElementById('m-back').addEventListener('click', function(){ show(2); });
+async function createChannel(){
+  var name = document.getElementById('ch-name').value.trim();
+  if (!name){ showToast('channel name required', 'err'); return; }
+  try{
+    var r = await fetch('/channels', { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify({ name: name }) });
+    var data = await r.json();
+    if (!r.ok) throw new Error(data.error || 'create failed');
+    state.channel = name;
+    document.getElementById('m-channel').textContent = name;
+    show(3);
+  }catch(e){ showToast(e.message, 'err'); }
+}
+document.getElementById('ch-create').addEventListener('click', createChannel);
+document.getElementById('ch-name').addEventListener('keydown', function(e){ if (e.key === 'Enter') { e.preventDefault(); createChannel(); } });
+document.getElementById('m-send').addEventListener('click', async function(){
+  var text = document.getElementById('m-body').value.trim();
+  if (!text){ showToast('message required', 'err'); return; }
+  var btn = document.getElementById('m-send'); btn.disabled = true; btn.textContent = 'Sending…';
+  try{
+    var r = await fetch('/messages', { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify({ type:'primitive', channel: state.channel, to: state.model, body: text }) });
+    var data = await r.json();
+    if (!r.ok) throw new Error(data.error || 'send failed');
+    document.getElementById('done-link').href = '/c/' + encodeURIComponent(state.channel);
+    show('done');
+  }catch(e){ showToast(e.message, 'err'); btn.disabled = false; btn.textContent = 'Send message'; }
+});
+loadAgents();
+`;
+
+  const css = `
+  .wiz-steps{display:flex;gap:8px;flex-wrap:wrap;margin-top:10px}
+  .wiz-step{font-size:11px;color:#7a7f87;border:1px solid #1f2329;border-radius:12px;padding:4px 10px}
+  .wiz-step.active{color:#7cc4ff;border-color:#2d4a66}
+  .agent-row{display:flex;gap:12px;align-items:flex-start;padding:12px 0;border-bottom:1px solid #1f2329}
+  .agent-row:last-child{border-bottom:none}
+  .agent-key{width:100%}
+  `;
+
+  return page({
+    title: `crosstalk on ${escapeHtml(d.host)} · Welcome`,
+    host: d.host,
+    alias: d.alias,
+    pageTitle: 'Welcome',
+    extraCss: css,
+    body,
+    inlineScript: js,
+  });
+}

package/src/web/workflows.ts

@@ -100,7 +100,7 @@ export function workflowsListPage(d: WorkflowsListData): string {
   <div id="compose-step-prompt">
     <div class="field">
       <label for="cw-prompt">prompt</label>
-      <textarea id="cw-prompt" rows="4" placeholder="e.g. compare how claude, codex, and gemini would refactor src/auth/users.ts to use bun's built-in crypto instead of node:crypto"></textarea>
+      <textarea id="cw-prompt" rows="4" placeholder="e.g. ask claude, codex, and gemini to each review README.md for unclear setup steps, then synthesize their notes into one list"></textarea>
     </div>
     <div class="field">
       <label for="cw-compiler">compiler agent</label>

package/template/CLAUDE.md

@@ -1,6 +1,6 @@
 # Crosstalk transport
 
-You are inside a Crosstalk transport — a git repo that carries async messages between AI agents and humans across machines.
+You are inside a Crosstalk transport — a directory (a git repo, or a plain/shared filesystem) that carries async messages between AI agents and humans across machines.
 
 Read these before doing anything here:
 

package/template/CROSSTALK.md

@@ -2,7 +2,7 @@
 
 Version: 7
 
-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.
+Crosstalk is a shared file format that lets humans and AI agents communicate asynchronously across machines. **A directory is the message bus** — carried by git (the default: distributed, versioned, auditable) or a plain/shared filesystem (`transport: local`, including a mounted SMB/NFS share, no git required).
 
 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.
 
@@ -14,10 +14,10 @@ Every concept in Crosstalk maps to exactly one of these:
 
 | Noun | Definition |
 |---|---|
-| **Transport** | A git repo, scaffolded by `crosstalk init`. The bus. |
+| **Transport** | The bus — a directory scaffolded by `crosstalk transport init`. A git repo (default) or a plain/shared filesystem (`transport: local`). |
 | **Machine** | A host running the crosstalk engine (`crosstalk daemon dispatch`, spawned by `crosstalk server start` or systemd). Identifies itself via `CROSSTALK_ALIAS` (defaults to the transport name). |
-| **Message** | A markdown file with YAML frontmatter, committed to a channel. The unit of work. |
-| **Model** | A named agent invocation declared in `data/models.yaml` (e.g. `sonnet`, `codex-o3`). |
+| **Message** | A markdown file with YAML frontmatter, written to a channel. The unit of work. |
+| **Model** | A named agent invocation declared in `data/crosstalk.yaml` (e.g. `sonnet`, `codex-o3`). |
 | **Actor** | An optional persona file (`local/actors/<name>.md`) that prepends to a model's prompt. |
 | **Channel** | A UUID directory under `data/channels/`. A conversation thread. Optionally parented. |
 
@@ -31,7 +31,7 @@ Every concept in Crosstalk maps to exactly one of these:
   PROTOCOL.md                    # agent orientation, prepended to every dispatch
   CROSSTALK.md                   # this file
   data/
-    models.yaml                  # the shared model vocabulary
+    crosstalk.yaml               # providers + models (+ optional transport: key)
     channels/<uuid>/
       CHANNEL.md                 # { name, optional parent }
       YYYY/MM/DD/<msg>.md        # messages
@@ -42,7 +42,7 @@ Every concept in Crosstalk maps to exactly one of these:
 
 That is the complete committed surface. **Dispatcher bookkeeping (cursor, heartbeat, pidfile, wake signal) is machine-local state and never lives in the repo** — it is kept under `~/.config/crosstalk/state/<transport-name>/`. The repo carries conversation; each machine carries its own progress through it.
 
-There is no `hosts/` directory and no `upstream/` directory at all — v6's `upstream/`-vs-`local/` override hierarchy is gone. `local/` still exists as the home for actor persona files (`local/actors/<name>.md`). The model vocabulary in `data/models.yaml` is shared by everyone; each dispatcher claims the entries whose CLI is on its PATH.
+There is no `hosts/` directory and no `upstream/` directory at all — v6's `upstream/`-vs-`local/` override hierarchy is gone. `local/` still exists as the home for actor persona files (`local/actors/<name>.md`). The model vocabulary in `data/crosstalk.yaml` is shared by everyone; each dispatcher claims the entries whose CLI is on its PATH.
 
 ---
 
@@ -222,7 +222,7 @@ The model never sees state machinery: each invocation is a single-turn content t
 
 The `to:` field accepts:
 
-- `to: sonnet` — bare model name. Any dispatcher claiming `sonnet` may pick it up; first-grab wins via git push race.
+- `to: sonnet` — bare model name. Any dispatcher claiming `sonnet` may pick it up; first-grab wins (via git push race on the git transport, via collision-free filenames on the filesystem transport).
 - `to: sonnet@cachy` — narrowed to the dispatcher whose `--alias` is `cachy`.
 
 The model name is everything before the `@`; the machine alias is everything after. The `re:` activation rule ignores `@machine` suffixes — only addressing honors them.

package/template/PROTOCOL.md

@@ -49,7 +49,7 @@ You do not need to know whether the message you are processing was produced by a
 
 ## Delivery semantics
 
-**At-least-once.** Each dispatcher tracks one cursor recording the git commit the transport was last scanned at. If a machine crashes mid-tick, the next tick re-dispatches anything not past the cursor; a duplicate reply may land in the channel.
+**At-least-once.** Each dispatcher tracks one cursor recording where the transport was last scanned (a git commit on the git transport, an mtime watermark on the filesystem transport). If a machine crashes mid-tick, the next tick re-dispatches anything not 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 (sending email, file deletion, payments), check the channel for evidence of prior completion before acting.
 

package/template/README.md

@@ -4,7 +4,7 @@
 
 Source-of-truth content that `crosstalk daemon init` copies into every new transport. Not a runtime artifact, not a published package on its own — it lives here in the monorepo and gets bundled into the published npm tarball at `prepack` time (`package.json` copies `transport/` → `template/`).
 
-> **What Crosstalk is.** Crosstalk is an agent-agnostic swarm communication protocol built on git. A git repo is the message bus. Full background: **[the root README](../README.md)**.
+> **What Crosstalk is.** Crosstalk is an agent-agnostic swarm communication protocol over a shared directory. The bus is a directory — a git repo (default) or a plain/shared filesystem (`transport: local`). Full background: **[the root README](../README.md)**.
 
 ---