@agora-build/atem 0.6.18 → 0.7.1

package/README.md

@@ -1,6 +1,6 @@
 # @agora-build/atem
 
-A terminal that connects builders, Agora platform, and AI agents. Manage Agora projects and tokens, route tasks between [Astation](https://github.com/Agora-Build/Astation) and AI coding agents, generate diagrams, drive voice-powered coding workflows, and more -- all from a single CLI/TUI.
+A terminal that connects builders, Agora platform, and AI agents. Manage Agora projects and tokens, route tasks between [Astation](https://github.com/Agora-Build/Astation) and AI coding agents, and more -- all from a single CLI/TUI.
 
 ## Install
 
@@ -34,16 +34,18 @@ atem repl                               # Interactive REPL with AI command inter
 ```bash
 atem login                              # Log in with Agora Console (opens browser)
 atem logout                             # Log out from SSO
-atem pair                               # Pair with Astation, then verify this device
+atem status                             # Account, pairing, verification and credentials (offline, read-only)
+atem pair                               # Pair with Astation, then verify this device (shows the status when already paired)
 atem pair --save                        # Same, and keep credentials for offline use
-atem unpair [--yes]                     # Remove all Astation pairings (asks first)
+atem pair verify                        # Verify this device with the paired Astation (no re-pairing)
+atem unpair [--yes]                     # Remove all Astation pairings and saved sessions (asks first)
 ```
 
 `atem login` unlocks a limited set: project list, tokens for the active
 project, and the dev servers (`serv rtc`, `serv convo`, `serv webhooks`).
 Pairing with Astation unlocks the full set: vault, sync, memory, skills,
-`atem cred`, and Astation-driven remote agent control, voice coding, mark
-tasks and diagrams. `serv files`, `config`, and tokens from
+`atem cred`, and Astation-driven terminal viewing, chat and mark
+tasks. `serv files`, `config`, and tokens from
 `AGORA_APP_ID`/`AGORA_APP_CERTIFICATE` need neither.
 
 `atem pair` receives your Agora login from Astation, then verifies the device:
@@ -52,15 +54,23 @@ atem and your Mac each show a 12-character safety code. If they match, type
 Either side can finish first. atem reads that `y` from the terminal itself,
 never from piped input or keys typed earlier, so run `atem pair` in an
 interactive terminal. If verification fails, the pairing stays saved, Astation
-is told, and `atem pair` exits nonzero; run it again to verify. A connected or SSO-paired session alone does not
-mean the device is verified; check `atem cred status`. With `--save`
+is told, and `atem pair` exits nonzero; run `atem pair verify` to retry. A connected or SSO-paired session alone does not
+mean the device is verified; check `atem status`. With `--save`
 the credentials keep working when Astation disconnects; without it they stop
 5 minutes after the disconnect (atem asks when `--save` isn't given).
 
+Once paired, `atem pair` only prints the status (`Already paired. Verify this
+device: atem pair verify · Replace the pairing: atem unpair, then atem pair`):
+it never pairs again or changes keys, trust or sessions. `atem pair verify`
+verifies the existing pairing on the runtime's Astation link, does nothing when the
+device is already verified, and refuses after a revocation (run `atem unpair`,
+which sets the revoked keys aside, then `atem pair`). `atem status` reads only
+local files and an already running key agent; it never connects, so
+authorization and relay show as `unknown (stale)`.
+
 ### Device keys (`atem cred`)
 
 ```bash
-atem cred status                        # Show whether this device is verified, its home Astation and its key agent
 atem cred unlock                        # Unlock this device's keys (approve with Touch ID on your Mac)
 atem cred lock                          # Wipe unlocked keys and stop the key agent
 atem cred projects                      # Send known Git projects to Astation's credential picker (keys must be unlocked)
@@ -68,7 +78,9 @@ atem cred projects                      # Send known Git projects to Astation's
 
 This device's keys are sealed on disk under a storage key that only the paired
 Mac (the home Astation) holds. `atem cred unlock` asks the Mac for it (Touch
-ID) and starts a background `atem key-agent` that holds the keys in memory.
+ID) and starts a background `atem key-agent` that holds the keys in memory;
+on a device no Astation verified it stops with `This device isn't verified.
+Run atem pair verify first.` and never starts pairing or verification.
 `atem cred lock` wipes them and stops the agent. After upgrading atem, run
 `atem cred lock` then `atem cred unlock` to pick up the new agent.
 
@@ -203,7 +215,7 @@ such as timestamps and ciphertext sizes; it is not authoritative for device
 trust or encryption state. Migration cannot prove that a server erased old
 plaintext backups.
 
-The device must be verified (`atem pair`) and unlocked (`atem cred unlock`).
+The device must be verified (`atem pair`, or `atem pair verify` to retry) and unlocked (`atem cred unlock`).
 While it is locked, `atem sync` keeps changes queued. Switching encryption on
 or off migrates existing data; each verified atem finishes its part at its next
 `atem cred unlock` (`atem sync` alone doesn't contact Astation). **Turning on**
@@ -226,9 +238,6 @@ atem serv attach 3                      # …or by index from `atem serv list`
 atem serv rtc                           # Launch RTC test page (HTTPS)
 atem serv rtc --channel test --port 8443
 atem serv rtc --background              # Run as background daemon
-atem serv diagrams                      # Host diagrams from SQLite (HTTP)
-atem serv diagrams --port 9000
-atem serv diagrams --background
 atem serv files ~/docs                  # Serve a directory or file over HTTPS (Markdown rendered)
 atem serv files ~/docs --background     # Port auto-picked; reused next run
 atem serv webhooks                      # Receive Agora webhooks locally (auto-tunneled via ngrok)
@@ -252,8 +261,6 @@ done
 
 **`serv rtc`** — RTC test page: join/leave, publish/subscribe audio+video, token generation, RTM messaging, RTC encryption (8 modes; gcm2 modes auto-generate a copyable salt).
 
-**`serv diagrams`** — SQLite-backed HTTP server for hosting AI-generated HTML diagrams.
-
 **`serv files`** — serves a directory (or a single file) over HTTPS. Markdown is rendered to HTML; append `?raw=1` to any URL for the raw bytes. Useful for browsing AI-generated docs on a remote machine.
 
 **`serv webhooks`** — local receiver for Agora webhook events (ConvoAI: `agent_joined`, `agent_left`, `agent_history`, `agent_error`, `agent_metrics`, …; RTC NCS events). Validates `Agora-Signature-V2` (HMAC-SHA256) when a `secret` is configured in `webhooks.toml`; accepts unsigned events otherwise with a warning. Live web console at `http://127.0.0.1:9090/` shows incoming events; each event also prints a one-line summary to stdout. Default tunnel provider is **ngrok**; set `tunnel_provider = "cloudflared"` for zero-auth quick tunnels. Use `--no-tunnel` if you're running cloudflared / ngrok separately for stable URLs across atem restarts.
@@ -263,31 +270,48 @@ done
 ### AI Agents (WIP)
 
 ```bash
-atem agent list                         # Scan and list detected AI agents
 atem agent launch                       # Open the original Claude Code CLI in an Atem terminal
 atem agent launch codex                 # Open the original Codex CLI in an Atem terminal
 atem agent launch claude --continue     # Arguments after the agent type go to that CLI: continue the last Claude session
 atem agent launch codex resume --last   # Continue the last Codex session
 atem agent launch claude -- --help      # Use -- to read the agent's own help
-atem agent connect <WS_URL>             # Connect to ACP agent and show info
-atem agent prompt <WS_URL> "text"       # Send prompt to ACP agent
-atem agent probe <WS_URL>              # Probe URL for ACP support
-atem agent visualize "topic"            # Generate visual HTML diagram via ACP agent
+atem agent list                         # The sessions the background runtime holds
+atem agent attach ses-…                 # Reopen a session (screen restored)
+atem agent stop ses-…                   # Stop a session
 ```
 
 `atem agent launch [claude|claude-code|codex] [ARGS]...` runs the installed
 `claude` or `codex` CLI, unchanged, in a full-screen Atem terminal. It uses
 your working directory and your own login for that CLI. Nothing here replaces
-the CLI with an API conversation. It works without Astation. If you are
-paired, Astation can view the same session and take control of it (one
-viewer per session; while Astation holds control, local typing is refused until you press
-the prefix, then `g`). Quitting Atem ends the session.
+the CLI with an API conversation. It works without Astation.
+
+Sessions belong to a background `atem runtime` (started on demand, one per
+profile; it exits after 10 minutes with no sessions and no frontends), and each agent runs in its own `atem
+worker` process. Closing the terminal window or hiding it (prefix, then `h`)
+leaves the session running; `atem agent attach` reopens it. Several Claude
+and Codex sessions can run at once, and they keep running if the runtime
+itself restarts. The runtime also holds this machine's one Astation
+connection: `atem pair`, `atem pair verify`, `atem cred unlock` and `atem cred
+projects` run on it (they start the runtime if needed) and never open their
+own, so pairing never disconnects a running session. When an agent that
+printed something ends, its last output and a short summary are saved under
+`~/.config/atem/logs/<session id>/`.
+
+If you are paired and verified, Astation can view each session, take control
+of it (one controller at a time, on a lease Astation keeps renewing; typing
+locally takes control back at once), and chat with the agent: sending a
+prompt takes control when nobody holds it (if another device does, Astation
+asks before taking over), the whole retained conversation can be scrolled
+back page by page, and each finished prompt names its reply messages.
+Every remote request names the exact session and speaks atem-session r8
+(Astation must be current: older clients are refused); old `agentInput`,
+`agentPrompt`, voice and `userCommand` messages were removed.
 
 Atem's own keys start with a prefix, Ctrl+] by default. Press it, then:
 
 | Key | Action |
 |-----|--------|
-| `h` | Hide the terminal; the agent keeps running |
+| `h` or `m` | Hide the terminal; the agent keeps running |
 | `g` | Take control back locally |
 | `x` | Stop the agent |
 | `r` | Redraw the screen |
@@ -295,20 +319,77 @@ Atem's own keys start with a prefix, Ctrl+] by default. Press it, then:
 | `c` | Copy the visible text (tmux buffer inside tmux, otherwise OSC 52) |
 | `?` | Help and recent notices |
 
+The bottom row reads, for example,
+`Atem | Claude | Local | Astation ✓ | Notice | Ctrl+] then ?:help`:
+
+- `Claude` or `Codex` is the agent on screen.
+- `Local` means your keyboard drives the agent; `Remote` means Astation holds
+  control. Typing takes it back (prefix, then `g`, does it without typing).
+- `Astation ✓` means the runtime's Astation link is authenticated; `Astation
+  ✗` means none (not paired, Astation unreachable, or re-authenticating).
+  Every reconnect or re-authentication is a new remote attachment: Astation
+  views again and asks for control again.
+- `Notice` appears once Atem has recorded a warning or status message. Press
+  the prefix, then `?`, to read the recent notices (newest first).
+
 Press the prefix twice to send it to the agent. To change it, set
 `terminal_prefix = "Ctrl-a"` in `~/.config/atem/config.toml`, or
 `ATEM_TERMINAL_PREFIX` (which wins over the file). Ctrl+], Ctrl+\ or
 Ctrl+<letter> other than i or m are accepted. The `CLAUDE_CLI_BIN`/`CLAUDE_CLI_ARGS`
 and `CODEX_CLI_BIN`/`CODEX_CLI_ARGS` variables still override the command.
-See [`designs/terminal-v1-implementation.md`](https://github.com/Agora-Build/Atem/blob/main/designs/terminal-v1-implementation.md).
+See [`designs/agent-runtime.md`](https://github.com/Agora-Build/Atem/blob/main/designs/agent-runtime.md).
+
+**Chat from Astation.** Astation can open a chat view of a Claude session
+launched with `atem agent launch claude`: your prompts appear as messages and
+Claude's replies come from its own session log, with a status of ready,
+working, waiting or unknown. Atem adds its hooks with `--settings` for that run
+only; your `~/.claude` settings are not changed. A prompt sent from chat needs
+control of the session, is typed into Claude once, and is reported as
+accepted, then complete (or failed) when Claude's turn ends.
+Codex works the same way once you allow Atem's Codex hooks (asked
+once on the first `atem agent launch codex`, see below): Atem reads Codex's
+own session log, so Codex shows ready, working, waiting or unknown. Codex
+reports nothing before its first prompt, so type the first prompt in the
+terminal; after that chat prompts work. Replies arrive whole (no streaming),
+and Codex's chat has no reasoning text or error details.
+Interrupt from chat stops a running turn only. See
+[`designs/agent-chat-host.md`](https://github.com/Agora-Build/Atem/blob/main/designs/agent-chat-host.md).
+
+**Approve prompts from Astation and your phone.** When Claude Code or Codex
+asks for permission to run a tool, Astation shows the request as a card (in
+a Claude chat view too) and Atem asks the relay to notify your devices
+with control. A card shows the tool and a short summary — the command's first
+line or the file path, never file contents — and offers **Allow once**,
+**Always allow** (Claude: one of the rules Claude itself suggests, with where
+it is saved; Codex, for shell commands only: **Always allow this command** —
+exactly this command in this folder, for the rest of this Codex process, kept
+by Atem; later runs of
+the very same command are allowed without asking and show as "auto allowed",
+and the rule can be revoked from Astation) or **Deny** (with an optional
+note for the agent).
+Answering needs no control of the session: any of your devices that can
+control it answers, whoever is typing, and the first answer wins. The
+finished card shows how it ended. The terminal can
+always answer instead: Claude keeps its own dialog on screen (the first
+answer wins), and for Codex any key you type in the terminal hands the
+prompt back to Codex's own dialog. If nobody answers, nothing is allowed:
+after the hook's wait (Claude 10 min, Codex 5 min) the agent asks in the
+terminal as usual. Claude gets the hook with `--settings` for each launch;
+to turn it off, set `approvals_hook = false` under `[claude]` in
+`~/.config/atem/config.toml` (Claude sessions launched afterwards keep their
+prompts in the terminal).
+The first `atem agent launch codex` asks once whether to add Atem's hooks
+(one per Codex event, for approvals and chat) to `~/.codex/hooks.json`, after
+your own (a backup is kept as `hooks.json.atem-bak`); to turn them off later,
+set `hooks = false` under `[codex]` in `~/.config/atem/config.toml` — the next
+`atem agent launch codex` removes them. See §6a and the r8 appendix of the [session protocol](https://github.com/Agora-Build/Atem/blob/main/designs/protocol/atem-session-v1.md).
 
 ## TUI Modes
 
 | Mode | Description |
 |------|-------------|
 | **Main Menu** | Navigate between features |
-| **Claude Chat** | Claude Code CLI integration via PTY |
-| **Codex Chat** | Codex terminal integration via PTY |
+| **Agent Sessions** | The runtime's Claude/Codex sessions: launch or attach |
 | **Token Gen** | Generate Agora RTC/RTM tokens locally |
 | **Projects** | Browse Agora projects via API |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agora-build/atem",
-  "version": "0.6.18",
+  "version": "0.7.1",
   "description": "A terminal that connects people, Agora platform, and AI agents.",
   "bin": {
     "atem": "bin/atem"