accelr8 3.8.1 → 4.0.0-next.1

package/README.md

@@ -1,8 +1,5 @@
 # accelr8
 
-Collaborative ascii canvas in your terminal. A real CLI app: mouse-driven TUI,
-real multiplayer, and live cursors that glide as your friends move them.
-
 ```
    ('-.                                ('-.               _  .-')
   ( OO ).-.                          _(  OO)             ( \( -O )
@@ -15,104 +12,341 @@ real multiplayer, and live cursors that glide as your friends move them.
   `--' `--'    `-----'     `-----'   `------'  `------'   `--' '--'   `----''
 ```
 
-## Install
+A multiplayer room in your terminal. Make a project, share its six-character
+code, and friends join with one command. Each project has chat, a shared ASCII
+canvas with live cursors, voice, and AI agents that answer when you @mention
+them. There is a radio station too.
 
 ```bash
 npm install -g accelr8
+accelr8
 ```
 
-## Use
+A room in a 120-column window (a real frame, blank rows trimmed):
 
-```bash
-accelr8                 # open the app
-accelr8 join XYMRAU     # jump straight into a friend's project
-accelr8 --name pat      # pick your display name (remembered)
+```
+  accelr8  night market sign                                                                           settings  maya ●
+   Chat ●   Canvas    Secrets    Team                                                                            ● live
+──━━━━━━────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+                                                                                                │ ONLINE · 2
+                                                                                                │ ● pat        chat
+                                                                                                │ ● maya       you
+                                                                                                │
+                                                                                                │ AGENTS · 0
+                                                                                                │ none yet
+                                                                                                │
+                                                                                                │ INVITE
+                                                                                                │ accelr8 join BQRY88
+                                                                                                │ [ copy ]
+                                                                                                │
+                                      · pat joined the project ·                                │
+ 21:24 pat ▸ first light. canvas is open, come paint the sign                                   │
+       pat ▸ thinking neon pink on black, a big 8 in the middle                                 │
+                                      · maya joined the project ·                               │
+ 21:24 maya ▸ on my way. bringing the pink, starting top left                                   │
+ 21:25 pat ▸ nice. @maya grab the canvas tab when you land                                      │
+ ❯                                                                                              │
+ night market sign · BQRY88 · 2 online         joined "night market sign"                        [tab] tabs · [^C] quit
 ```
 
-Create a project in the **Projects** tab, paint on the **Canvas** by clicking
-and dragging (right-click erases), and grab the join code from the **Members**
-tab. Everyone in a project sees everyone else's cursor move live.
+## Install
 
+```bash
+npm install -g accelr8
 ```
- accelr8   collaborative ascii canvas                               you ●
-  Projects     Canvas     Members                                  ● live
-────────────────────────────────────────────────────────────────────────
- brush  █ ▓ ▒ ░ ● ◆ ★ ▲ ■ · # @ *  ⌫ erase                        clear
-┌─ canvas 100×30 ───────────────────────────────────────────────────────┐
-│      █                                                                 │
-│       █                    ▲ alice                                     │
-│        █                                                               │
-│                                       ▲ bob                            │
-└────────────────────────────────────────────────────────────────────────┘
- landing page redesign  ·  code XYMRAU  ·  3 online      [tab] switch  [q] quit
-```
 
-### Controls
+- Node.js 18 or newer. Tested on Node 22.
+- A terminal with mouse support. accelr8 needs an interactive terminal and
+  says so if it doesn't get one.
+- For voice and radio sound: ffmpeg and ffplay on your PATH. The first time you
+  join voice, accelr8 offers to install ffmpeg (Homebrew on macOS, winget or
+  Chocolatey on Windows) or shows the command to run on Linux.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `accelr8` | Open the app. |
+| `accelr8 join <CODE>` | Open straight into a project. |
+| `accelr8 radio` | Tune in to ACCELR8 radio in this terminal. |
+| `accelr8 serve` | Run your own sync server on port 8787. |
+| `accelr8 agent add` | Connect an AI account as an agent. |
+| `accelr8 agent list` | List the agents connected on this machine. |
+| `accelr8 agent remove <handle>` | Remove one. |
+| `accelr8 --intro` | Replay the opening film. |
+| `accelr8 -v`, `accelr8 --version` | Print the version. |
+| `accelr8 -h`, `accelr8 --help` | Print help. |
+
+| Option or variable | What it does |
+|---|---|
+| `--name <name>` | Your display name, up to 16 characters. Remembered for next time. |
+| `--server <url>` | The sync server to use. The default is the hosted one. |
+| `ACCELR8_SERVER=<url>` | Same as `--server`, for the app. The radio only reads `--server`. |
+| `--port <port>` | The port for `accelr8 serve`. |
+| `--clip <file or url>` | Radio only: play a video as ASCII instead of the visualizers. |
+| `ACCELR8_MIC=<index>` | The microphone voice uses (see `/voice mics`). |
+| `ACCELR8_RADIO_SINK=ffplay` | Radio only, macOS: play through ffplay instead of CoreAudio. |
+
+## The app
+
+accelr8 opens with a short film, then the logo. Any key or click skips ahead.
+Skip the logo and the film stops playing at launch. Skip it three launches in
+a row and the logo gets shorter too. Until then, letting the logo play to the
+end starts the count over and brings the film back. `accelr8 --intro` plays
+the whole show again, and watching it to the end brings everything back.
+
+### HOME
+
+HOME lists every project on the server you are connected to, with its join
+code, its member count and how many people are online. Click a row to open it.
+
+- `+ new project` (or `n`) names a new project and opens it.
+- `join by code` (or `j`) asks for a code.
+- `accounts` (or F2) connects AI accounts. See [Agents](#agents-chat-only).
+- `♫ radio` opens the radio in a new terminal window. On Linux, if nothing
+  opens, run `accelr8 radio`.
+
+accelr8 checks npm for a newer version in the background, at most every 6
+hours. When a check finds one, HOME shows `update to vX · press enter` from
+the next launch on. Enter (or `u`) runs `npm install -g accelr8@latest`. Start
+accelr8 again when it finishes. If it fails, run that command yourself.
+
+### Rooms
+
+A project is a room with four tabs: Chat, Canvas, Secrets and Team. Click a tab
+or press Tab to move between them. Outside chat, `1` to `4` also switch tabs. A
+colored dot on a tab shows who else is there, and Chat shows an unread count.
+
+Ctrl-P goes back to HOME and keeps you in the project. Ctrl-C quits. F1 opens
+the keyboard help.
+
+**Chat.** Type and press Enter. To start a new line, end the line with `\` and
+press Enter. `@` opens a list of agents and people, and Tab or Enter accepts
+one. Up and Down bring back what you sent, and Ctrl-A, Ctrl-E, Ctrl-W, Ctrl-U
+and Ctrl-K edit the line the way a shell does, and Esc clears it. PgUp, PgDn
+and the mouse wheel scroll, and End on an empty line jumps to the newest
+message. Teammates see what you type while you type it: `/ghost off` stops
+that and `/ghost on` starts it again.
+
+**Canvas.** One shared 100×30 grid per project. Pick a brush, then click and
+drag to paint in your color. Right-click erases a cell, and `clear` wipes the
+grid for everyone. Everyone's cursor moves live with their name on it. To see
+the whole grid at once, make the window at least 102 columns by 37 rows. From
+120 columns the sidebar appears, and the grid sits beside it whole from 126
+columns. In a smaller window you see part of the grid: the arrow keys, Page Up
+and Page Down and the scroll wheel move the view, Home goes back to the
+top-left corner, ‹ and › mark hidden columns, and the bottom edge says which
+part is showing.
+
+**Secrets.** A placeholder for now. Nothing is stored here.
+
+**Team.** A world map with a dot for each person online, placed by their time
+zone (hover a dot for the name and city). Below the map:
+
+- everyone in the project, online or not, and the tab each person is on;
+- the project's agents, with their owner and status;
+- the invite line `accelr8 join <CODE>`, with a copy button.
+
+### Window sizes
 
-| Input | Action |
+accelr8 reshapes itself to fit the window.
+
+| Window | Layout |
+|---|---|
+| 120 columns or more | The room adds a sidebar: who is online, agents, the invite. |
+| 80 to 119 columns | The standard room. |
+| under 80 columns, or under 22 rows | A one-row header. |
+| under 60 columns | Chat only. |
+| 15 rows or fewer | A ticker: who is here, the newest chat and the input. |
+| under 32 columns | Parked as an 8-ball that shows unread mentions and agent activity. |
+
+Read the table from the bottom up: the first row that matches wins. The
+smallest window accelr8 draws for is 20 columns by 6 rows. Below that, parts
+of the screen are cut off. While it is parked, keys do nothing except Ctrl-C
+(quit) and, in voice, Ctrl-G (mic). Make the window bigger to come back.
+
+### Settings
+
+Click `settings` at the top right.
+
+- **Theme:** midnight (the default), amber, matrix, mono or paper (light).
+- **Top nav:** underline, brackets, blocks or pipes.
+- **Notify on:** mentions (the default), all messages, or off. accelr8 rings
+  the terminal bell when chat is not on screen, at most once every 30 seconds.
+
+Settings save to `~/.accelr8/settings.json` as you change them.
+
+## Voice
+
+In a project, type `/voice` in chat to join the project's voice channel. You
+join muted and hear everyone who is in voice.
+
+| In chat | What it does |
 |---|---|
-| Mouse click | tabs, buttons, project rows, palette |
-| Click + drag on canvas | paint with the current brush |
-| Right-click on canvas | erase a cell |
-| `Tab` / `1` `2` `3` | switch tabs |
-| `q` / `Ctrl-C` | quit |
+| `/voice` | Join or leave voice. |
+| `/talk`, `/mute` or Ctrl-G | Open or close your mic. |
+| `/voice mic <index>` | Switch to another microphone. |
+| `/voice mics`, `/voice debug` | List microphones, or show the voice state. The panel shows in the chat-only layout (32 to 59 columns). |
+
+- Voice needs ffmpeg and ffplay on your PATH. If they are missing, `/voice`
+  offers to install ffmpeg.
+- There is no echo cancellation yet, so wear headphones.
+- Audio travels through the sync server as uncompressed 16 kHz mono, about
+  350 kbps for each person talking.
+- Every step of a call is logged to `~/.accelr8/voice.log`. Send that file
+  along when voice misbehaves.
+
+## Agents (chat only)
+
+Connect an AI account and it joins your projects as a named agent, such as
+`@mayasclaude`. When someone @mentions it, it answers in chat. API-key agents
+stream their reply as they write it. A reply from a Claude Code login appears
+when it is done.
+
+**Connect one.** Press F2 (or click `accounts` on HOME), or run
+`accelr8 agent add`.
 
-## How the live cursors work
+1. Provider: Anthropic or OpenAI.
+2. Key: paste an API key or, for Anthropic, use your Claude Code login if the
+   `claude` command is installed. `accelr8 agent add` also picks up
+   `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` from your environment.
+3. Handle: 3 to 20 lowercase letters, digits or hyphens, starting with a letter
+   or digit.
+4. Model. With a Claude Code login, the model follows your Claude Code setup.
 
-The terminal reports mouse motion via ANSI escape sequences (any-event
-tracking, `ESC[?1003h`). The app:
+Keys stay on your machine, in `~/.accelr8/accounts.json`, which only you can
+read. The server never sees them. It knows the agent's handle, provider and
+model.
 
-1. **Throttles** outgoing cursor positions to ~25/sec.
-2. **Interpolates** on the receiving side: each remote cursor lerps toward its
-   last reported position every frame (`x += (target - x) * 0.35`), so it
-   glides smoothly instead of teleporting between throttled updates.
+**How it runs.** Your agent runs inside your own accelr8, on your machine, with
+your key. It is online only while you have that project open. If you leave in
+the middle of a reply, the reply ends where it stopped.
 
-Sparse sends plus client-side smoothing is what makes it feel live.
+**Who can @mention it.** On the Team tab, click your agent and pick only me (the
+default), everyone in the project, or choose people. Agents can @mention other
+agents, and every hop is checked against the person who started it.
 
-## Sync server
+**What it can do.** Talk. API-key agents have no tools at all. A Claude Code
+login runs `claude -p` in plan mode, one turn per reply, with its shell, file
+and web tools blocked. The plan / approve / auto mode on the accounts screen is
+saved, but it changes nothing yet.
 
-By default the CLI talks to the hosted sync server (a Cloudflare Worker with a
-Durable Object, source in `worker/`). You can point it anywhere:
+Give any agent that other people can @mention an API key. Anthropic's terms do
+not allow sharing a Claude plan, so keep an agent on your Claude Code login set
+to only me.
+
+## ACCELR8 radio
+
+A synced station: everyone tuned in hears the same song at the same moment and
+sees the same visuals.
+
+- Run `accelr8 radio`, or click `♫ radio` on HOME to open it in a new terminal
+  window. On Linux the button can open nothing, so use the command there.
+- `m` mutes, `+` and `-` (or Up and Down) change the volume, `s` votes to skip,
+  and `q` or Esc quits. A song skips when 30% of listeners vote.
+- Sound needs ffmpeg and ffplay. Without them you get the visuals and no sound.
+  On macOS the sound goes straight to CoreAudio.
+- The station lives on the hosted server. `accelr8 serve` does not run one.
+- Diagnostics go to `~/.accelr8/radio.log`.
+
+## Self-hosting
+
+By default accelr8 talks to the hosted server, a Cloudflare Worker at
+`wss://accelr8-canvas.patonchain.workers.dev`. You can run your own:
 
 ```bash
-accelr8 --server ws://localhost:8787      # or export ACCELR8_SERVER=...
+accelr8 serve                 # sync server on port 8787
+accelr8 serve --port 9000     # another port
 ```
 
-### Self-hosting
+Then point accelr8 at it:
 
 ```bash
-accelr8 serve                 # starts a sync server on :8787
-accelr8 serve --port 9000     # custom port
+accelr8 --server ws://localhost:8787
+ACCELR8_SERVER=ws://localhost:8787 accelr8
 ```
 
-Expose it beyond your machine with a quick tunnel:
+To let friends in from outside your network, put a tunnel in front of it, for
+example:
 
 ```bash
 cloudflared tunnel --url http://localhost:8787
-# friends then run: accelr8 --server wss://something.trycloudflare.com
+# friends run: accelr8 --server wss://<your-tunnel>.trycloudflare.com
 ```
 
-Deploy your own copy of the hosted worker:
+- `accelr8 serve` keeps every project, its canvas and its chat (the last 2,000
+  messages) in `~/.accelr8/server-data.json`.
+- Chat, canvas, agents and voice all work on it. The radio does not.
+- Everyone connected to a server sees every project on it, with its join code.
+- Clients and the server must speak the same protocol version (3 today; the
+  changelog says when it changes). A client that does not match is told it is
+  outdated and quits, even when the server is the older one.
+- `worker/` is the hosted server: a Durable Object around the same room logic as
+  `accelr8 serve`, plus the radio station. To run your own copy, create the
+  R2 bucket named in `worker/wrangler.jsonc` on your Cloudflare account, then
+  run `npx wrangler@<x.y.z> deploy` in `worker/`, with an exact wrangler
+  version. A copy's radio still streams from the hosted server: the playlist
+  in `worker/src/worker.ts` builds every track URL from `A`, the hosted
+  server's `/audio` address, and your bucket goes unused. To play your own
+  music, upload the tracks to your bucket and point `A` at your worker's
+  `/audio`. The music is not in this repository.
 
-```bash
-cd worker && npx wrangler deploy
-```
+## Files
+
+Everything accelr8 keeps lives in `~/.accelr8/`.
+
+| File | What it holds |
+|---|---|
+| `identity.json` | Your id and display name. |
+| `settings.json` | Theme, top nav and notifications. |
+| `accounts.json` | Your AI accounts and their keys. Only you can read it. |
+| `agent-tokens.json` | Proof that you own your agents in each project. |
+| `update-check.json` | The last npm version check. |
+| `voice.log`, `radio.log` | Diagnostics. They grow until you delete them. |
+| `server-data.json` | Projects, canvases and chat, written by `accelr8 serve`. |
+
+## Limits today
+
+- No sign-in yet. Your id and name are made on your machine and servers do not
+  verify them, so agent access settings are not a security boundary.
+- Every project on a server is listed, with its code, for everyone connected to
+  it. Keep secrets out of chat.
+- Agents only chat, and only while their owner has the project open.
+- The Secrets tab is a placeholder.
+- Voice has no echo cancellation and sends uncompressed audio.
 
 ## Development
 
+From a checkout of this repository:
+
 ```bash
-npm install
-npm run dev              # run the TUI from source
-npm run serve            # run the sync server from source
-npm run smoketest        # headless two-client sync test (needs a server)
-npm run rendertest       # headless frame dumps of every screen
-npm run build            # bundle dist/cli.js
+npm ci
+npm run dev          # run the app from source
+npm run serve        # run the sync server from source
+npm run typecheck    # src/, tools/ and worker/
+npm test             # 34 suites and a render pass, no network
+npm run teste2e      # 6 suites, each on its own local server
+npm run build        # bundle into dist/
 ```
 
-Layout:
+- Run the tests with a throwaway HOME, for example `HOME=$(mktemp -d) npm test`.
+  When ffmpeg is installed, the voice test plays a half-second tone through
+  ffplay and writes `~/.accelr8/voice.log`.
+- `npm run teste2e` needs a server first. Start one with a throwaway HOME so
+  test projects stay out of your real data: `HOME=$(mktemp -d) npm run serve`.
+- `.github/workflows/ci.yml` is the CI job: all of the above on Node 22, plus an
+  audit and a check of what goes into the npm package.
+- `docs/RELEASE.md` is how to cut a release. `CHANGELOG.md` is the history.
+  `docs/DESIGN.md` is the design bible. Much of it is not built yet.
 
-- `src/protocol.ts` shared wire types + constants (fixed 100×30 logical canvas)
-- `src/cli.ts` entry point, arg parsing
-- `src/client.ts` the TUI: mouse/keyboard, flicker-free rendering, cursor lerp
-- `src/server.ts` self-host sync server (Node, `ws`)
-- `worker/` hosted sync server (Cloudflare Worker + Durable Object)
+| Path | What lives there |
+|---|---|
+| `src/cli.ts` | Entry point and argument parsing. |
+| `src/client.ts` | The app: rendering, mouse and keys, chat, canvas, voice wiring. |
+| `src/protocol.ts` | Wire types, the protocol version and limits. |
+| `src/room.ts` | RoomCore: all room behavior, shared by both servers. |
+| `src/server.ts` | `accelr8 serve`, on Node and `ws`. |
+| `worker/` | The hosted server: a Cloudflare Worker and its Durable Objects. |
+| `src/executor.ts`, `src/accounts.ts` | Agents: running them and storing accounts. |
+| `src/voice.ts` | Voice capture and playback through ffmpeg. |
+| `src/radio/` | ACCELR8 radio. |

package/dist/chunks/accounts-CCKXHSQQ.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import {
+  AuthLockTimeout,
+  DEFAULT_MAX_CALLS_PER_HOUR,
+  DEFAULT_MAX_CALLS_PER_REQUESTER_HOUR,
+  DEFAULT_MAX_OUTPUT_TOKENS,
+  DEFAULT_MODEL,
+  HANDLE_RE,
+  addAccount,
+  credentialsKey,
+  defaultHandle,
+  deleteCredentials,
+  detectClaudeCode,
+  detectEnvKeys,
+  getToken,
+  listCredentials,
+  loadAccounts,
+  loadCredentials,
+  loadLegacyIdentity,
+  loadTokens,
+  redact,
+  removeAccount,
+  saveAccounts,
+  saveCredentials,
+  saveToken,
+  withAuthLock
+} from "./chunk-FVC2UPMV.js";
+import "./chunk-62O2F73J.js";
+export {
+  AuthLockTimeout,
+  DEFAULT_MAX_CALLS_PER_HOUR,
+  DEFAULT_MAX_CALLS_PER_REQUESTER_HOUR,
+  DEFAULT_MAX_OUTPUT_TOKENS,
+  DEFAULT_MODEL,
+  HANDLE_RE,
+  addAccount,
+  credentialsKey,
+  defaultHandle,
+  deleteCredentials,
+  detectClaudeCode,
+  detectEnvKeys,
+  getToken,
+  listCredentials,
+  loadAccounts,
+  loadCredentials,
+  loadLegacyIdentity,
+  loadTokens,
+  redact,
+  removeAccount,
+  saveAccounts,
+  saveCredentials,
+  saveToken,
+  withAuthLock
+};

package/dist/chunks/{agentcli-ZI2O7ID7.js → agentcli-HL6V26E7.js}

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+import {
+  verifyAccount
+} from "./chunk-NRXIFJGR.js";
 import {
   DEFAULT_MODEL,
   addAccount,
@@ -6,9 +9,9 @@ import {
   detectClaudeCode,
   detectEnvKeys,
   loadAccounts,
-  removeAccount,
-  verifyAccount
-} from "./chunk-3JNUWI22.js";
+  removeAccount
+} from "./chunk-FVC2UPMV.js";
+import "./chunk-62O2F73J.js";
 
 // src/agentcli.ts
 import { createInterface } from "node:readline";