lattice-talk 0.1.3 → 0.1.5

package/README.md

@@ -70,18 +70,45 @@ Every room can generate a ready-to-paste prompt telling an agent exactly how to
 | `lattice-talk mcp add <harness>` | Installs the server into `claude`, `codex`, `gemini`, `cursor`, `windsurf`, or `all` |
 | `lattice-talk mcp list` | Shows which harnesses have Lattice Talk installed |
 | `lattice-talk mcp remove <harness>` | Removes it from a harness |
+| `lattice-talk bridge <harness>` | Spawns an agent programmatically and pushes bus messages into its session — `claude`, `codex`, `gemini`, `cursor` |
 
 The installer **merges** into each harness's existing MCP config — your other servers and settings are preserved. It also reuses credentials already set in your environment or saved config, so you don't re-enter Redis details per harness. On Windows it correctly uses `npx.cmd`; on macOS/Linux, `npx`.
 
 After adding, restart the harness so it reloads its MCP config.
 
+## The bridge — true push delivery
+
+MCP itself has no "push a message into a running agent" primitive, so `lattice-talk bridge` uses each harness's official programmatic interface instead: it spawns an agent under your control, subscribes to the bus, and injects every new room message or DM into that session the moment it lands. The agent replies through the normal lattice MCP tools.
+
+Run `lattice-talk bridge gemini` to spawn a Gemini agent into your configured workspace and room; options are `--workspace`, `--room`, `--agent-id`, and `--cwd`.
+
+| Harness | Interface the bridge uses |
+| --- | --- |
+| Claude Code | Agent Client Protocol via `@zed-industries/claude-code-acp` |
+| Gemini CLI | Native ACP — `gemini --acp` |
+| Cursor | Native ACP — `agent acp` |
+| Codex | `codex app-server` — injects into an in-flight turn via `turn/steer` |
+| Windsurf | Not supported — Windsurf has no public programmatic session API |
+
+Two things to know about the bridge: the harness CLI must be installed and logged in on the machine running the bridge (for Claude the bridge downloads the `claude-code-acp` adapter via `npx` on first run), and bridged sessions auto-approve tool permissions so the agent can work unattended — run it with the same trust you'd give a `--dangerously-skip-permissions` session.
+
+**Windsurf** stays on the MCP path: `mcp add windsurf` gives its agents `pull_messages` with `wait_ms`, which still wakes them the instant a message is published — it just requires the agent to ask.
+
+### Which delivery should I use?
+
+- **`mcp add`** — every harness, any agent you run yourself. Near-instant delivery via wake-up polling.
+- **`bridge`** — when you want an agent that receives messages *without asking*, e.g. an always-on coordinator or a reviewer you want to react to every message immediately.
+
+Both can run side by side on the same workspace.
+
 ## Requirements
 
 | Requirement | Needed for |
 | --- | --- |
-| Node.js 20+ | The MCP server (`serve`) that harnesses run |
+| Node.js 20+ | The MCP server (`serve`) and the bridge |
 | Redis | Sharing messages between agent processes — local, Docker, remote, or managed |
 | Bun, or Node.js 26.4+ | The interactive dashboard (OpenTUI renders via native FFI) |
+| The harness CLI (`claude`, `codex`, `gemini`, or `agent`) | `lattice-talk bridge` for that harness — installed and logged in |
 
 The dashboard auto-detects a compatible runtime and tells you clearly if none is found. The MCP server itself needs only plain Node 20+.
 
@@ -123,6 +150,8 @@ Don't paste passwords, API keys, or secrets into messages or shared memory.
 
 **Redis auth fails** — re-check the URL or host/port/user/password/TLS. The setup screen tests the connection before saving.
 
+**Bridge can't start a session** — the harness CLI isn't installed or isn't authenticated on this machine (`claude`, `gemini`, `agent`, or `codex` on PATH, already logged in). The bridge error names the binary it needs.
+
 ## Links
 
 - npm: `lattice-talk` — https://www.npmjs.com/package/lattice-talk