usebeeline 0.0.40 → 0.0.45

package/README.md

@@ -1,14 +1,205 @@
-# usebeeline
+<h1 align="center">beeline.</h1>
 
-Connect a supported coding-agent harness to Beeline:
+<p align="center">
+  <a href="https://www.npmjs.com/package/usebeeline"><img src="https://img.shields.io/npm/v/usebeeline?logo=npm&color=D7AF5F" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/usebeeline"><img src="https://img.shields.io/npm/dm/usebeeline?color=D7AF5F" alt="npm downloads" /></a>
+  <a href="https://www.npmjs.com/package/usebeeline"><img src="https://img.shields.io/node/v/usebeeline?color=D7AF5F" alt="node version" /></a>
+</p>
+
+<p align="center"><strong>Team messaging for agents and humans.</strong></p>
+<p align="center">One Room for your people and your coding agents. Talk it through, hand off the work, watch it merge.</p>
+
+`usebeeline` connects **a coding agent you already run — Claude Code, Codex, Goose, Pi, or Grok — to a Room in the Beeline app on your phone**. One command on the machine where the agent lives, and it walks into the conversation as a member: it reads what your teammates actually said, answers when it is tagged, and takes work away when someone asks it to. Nothing is retyped into a prompt box.
+
+The agent stays on your machine. Your provider key stays on your machine. What crosses the wire is the conversation, and — when repository work starts — a pull request.
+
+## One message
+
+In a Room bound to a repository, someone types:
+
+```text
+@codex the corner status line wraps onto two lines on small phones. fix it and open a PR.
+```
+
+Codex answers in the Room, opens a **corner** — an isolated worktree of the repository with one branch and one objective — works there, pushes, and opens the pull request. The Room shows the corner card, the checks, and the merge. Nobody left the chat.
+
+Other things people ask an agent in a Room:
+
+- “@claude what changed in the release job this week?”
+- “@pi read the crash log I just attached and tell me which commit did it.”
+- “@goose open a corner and take the deprecation warnings out of the auth tests.”
+- “@codex run the deploy script.” — the agent raises its hand for a command grant; you approve it on the card.
+- “@claude every weekday at 9, post yesterday's failed checks.” — it schedules itself.
+
+## Install
+
+On any machine that already runs your coding agents:
+
+```sh
+npx usebeeline connect
+```
+
+The command asks for the pairing code shown in the Beeline app, then four questions and no more:
+
+| Step | What it asks |
+| --- | --- |
+| Harness | Claude Code, Codex, Goose, Pi, or Grok |
+| Provider | Goose and Pi only — OpenRouter (default), OpenAI, Anthropic, Google, or xAI |
+| API key | Goose and Pi only — verified against the provider, then saved to `~/.config/beeline/providers.json` (mode `0600`) |
+| Model | Whatever the harness advertises, filtered as you type; OpenRouter defaults to GLM 5.3 Flash |
+
+It does **not** ask for a name or a soul. The server assigns the agent one of twelve animals nobody in your Workspace is already wearing, and prints it:
+
+```text
+│  Your agent is Foxy the fox.
+│
+◇  Name
+│  ● Keep Foxy  (default)
+│  ○ Rename this agent
+```
+
+Codex, Claude Code, and Grok use the sign-in they already have on that machine, so they are not asked for a key at all.
+
+You can pass the pairing code inline — `npx usebeeline connect XXXXXXXX-XXXXXXXX` — and the package also installs a `beeline` bin alias.
+
+**Requirements:** Node 20.11+, Linux x64, and systemd user services. The published daemon bundle is `linux-x64` only today; macOS is not shipped.
+
+## What happens
+
+1. `connect` redeems the app's one-time pairing code and receives an agent identity for your Workspace.
+2. It downloads the signed current daemon bundle into `~/.local/lib/beeline` and starts it as a supervised `systemd --user` service, one per agent.
+3. The agent appears in the Room. Tag it like a teammate.
+4. Given a repository-bound Room, the agent can open a corner and produce a pull request there.
+5. The daemon updates itself when a new release ships, draining any turn in flight first, and rolls back if the new bundle cannot answer.
+
+Your provider key is not part of any of that. `connect` sends the server the pairing code, the harness name, the provider name, and the model id — never the key. The key is written to your own config directory and handed to the harness as an environment variable when it runs.
+
+## Rooms and corners
+
+A Room and a corner are the same conversation surface with different permissions.
+
+**In a Room, the agent can:**
+
+- read the repository checkout, run searches, read git history — the filesystem is mounted **read-only**;
+- use every MCP tool mounted into its session, and web search where the harness has it (Codex and Claude Code get theirs turned on in the isolated home);
+- read files and photos people share (downloaded to the session for it — it never fetches a URL) and attach a file back to its reply;
+- address any other member, human or agent, by writing `@name`;
+- schedule itself to run again later, once or repeatedly;
+- ask for something outside the sandbox with a grant request;
+- open a corner.
+
+**In a Room, the agent cannot:** write to the repository, commit, push, or open a pull request. There is one way to start write work, and it is `open_corner`.
+
+**A corner** is a fresh worktree, its own branch, one owning agent, and one fixed objective of at most 24 words. In it the agent works, commits, pushes the branch, runs `gh pr create`, and prints the pull request URL. It then waits for the server's own checks fact — not for whatever `gh` printed locally — and merges only when the checks passed and no human has put the corner on hold. The merge webhook archives the corner and reaps the worktree.
+
+The corner receives a GitHub App token scoped to **that one repository**, installed as a worktree-local git credential helper. Your host credential stores are masked out of the sandbox.
+
+**Direct messages** are strictly conversational: no repository binding, no corners.
+
+## Security posture
+
+- **The filesystem boundary is the sandbox, not a tool list.** Room sessions run under bubblewrap with a read-only view of the checkout, a private `/tmp`, and an isolated home. Every mounted MCP tool is approved tool-by-tool because the sandbox — not an allowlist — is what holds the line.
+- **When the sandbox cannot be built, the daemon says so and keeps serving.** A host with no `bwrap`, or a kernel that refuses unprivileged user namespaces, is logged once at start and every session afterwards runs unwrapped; the read-only rule then rests on the harness's own permission callback, which Codex, Claude Code, and Grok honour. Pi does not ask before it writes, so a Pi Room is only as read-only as its sandbox.
+- **Write access requires a corner.** A corner is a separate worktree on its own branch with a repository-scoped GitHub App token, and it is opened by an explicit host-governed call, never inferred.
+- **Reach outside the sandbox is a grant.** The agent asks — `path`, `host`, `secret`, `device`, `budget`, or `command` — and a card goes to its owner in the Room with the exact ask and the reason. You approve once, always, or deny, and the decision is a line in the transcript. Approving a command grant is word-for-word: an approved `npm test` does not approve `npm test && curl …`, and a command carrying shell metacharacters is refused before it is ever offered.
+- **Yolo mode** flips a single agent to auto-approval, is settable only by the agent's owner or a Workspace manager, and never covers a budget grant.
+- **Provider keys never reach Beeline's servers.** They live in your config directory at mode `0600` and reach only the harness process you already trust with them.
+- **Honest about what is not built yet:** today a `command` grant is the one kind that actually changes what a running agent may do. `path`, `host`, `secret`, `device`, and `budget` grants are requested, decided, and recorded, but are not yet applied to the sandbox.
+
+## Command reference
+
+```text
+beeline connect [XXXXXXXX-XXXXXXXX]   Install and connect an app-authorized agent
+beeline start [agent-pubkey]          Start — or cleanly restart — this repo's agent
+beeline stop --agent <agent-pubkey>   Stop and disable the supervised agent
+beeline update [--check|--status|--rollback|--force]
+                                      Self-update the installed bundle
+```
+
+Runtime state lives in `${XDG_STATE_HOME:-~/.local/state}/beeline/agents/<agent-pubkey>/`. The active bundle is `~/.local/lib/beeline`.
+
+## Tool reference
+
+Two MCP surfaces are mounted into every agent session.
+
+`beeline-readonly-mcp` — reading, in a Room and in a corner:
+
+| Tool | What it does |
+| --- | --- |
+| `list_files`, `read_file` | Walk and read the checkout |
+| `search_text` | Search the checkout |
+| `git_log`, `git_show`, `git_diff`, `git_status` | Read repository history and state |
+| `read_agent_file` | Read the agent's approved skills or Workspace memory |
+| `write_memory` | Replace the agent's private Workspace `MEMORY.md` — the only memory write a Room allows |
+
+`beeline-agent` — acting, host-governed:
+
+| Tool | Where | What it does |
+| --- | --- | --- |
+| `open_corner` | Top-level Rooms | Open one write-enabled corner with a ≤24-word objective |
+| `pr_checks_status` | Corners | Read the server-posted checks verdict and human hold state |
+| `attach_file` | Everywhere | Attach one file from the checkout or scratch dir to the reply |
+| `create_schedule`, `list_schedules`, `delete_schedule` | Everywhere | Run a prompt again later — interval minutes or a 5-field cron |
+| `request_grant` | Everywhere | Ask the owner for reach outside the sandbox |
+| `run_granted_command` | Everywhere | Run a command an approved grant covers, outside the sandbox |
+
+## The app
+
+Beeline is on both stores:
+
+- [App Store](https://apps.apple.com/app/id6803948500)
+- [Google Play](https://play.google.com/store/apps/details?id=app.usebeeline.mobile)
+
+Sign in with GitHub, and the app hands you the pairing code that `npx usebeeline connect` asks for.
+
+## Beta
+
+Beeline is `0.0.x` and moves fast. Concretely, today: the daemon bundle ships for Linux x64 only; corners assume a GitHub repository the app can reach; five sandbox grant kinds are recorded but not yet enforced; and releases are cut by hand rather than on every merge. The pieces described above are the ones that work.
+
+## One README for GitHub and npm
+
+`packages/usebeeline/README.md` is the canonical file. The repository's root `README.md` is a byte-for-byte copy of it, generated by `npm run readme:sync` and enforced in CI by `npm run readme:check`, so the GitHub front page and the npm listing always publish the same text. Edit the canonical file, then run the sync.
+
+Because one file is rendered from two directories, every link in it is absolute.
+
+## Development
 
 ```sh
-npx usebeeline connect <PAIRING_CODE_FROM_THE_APP>
+git clone https://github.com/Beeline-Work/beeline.git
+cd beeline
+npm install
+npx turbo run build
+npm run lint
+npx turbo run test
 ```
 
-The package also exposes a `beeline` bin alias. The connect command uses the
-short-lived code minted by the Beeline app, installs the signed current daemon bundle into
-the canonical `~/.local` layout, and starts the supervised user service.
+The published CLI is a single bundled file built from `apps/body`:
+
+```sh
+npm run build -w @beeline/body
+npm run build -w usebeeline     # esbuild apps/body/dist/cli.js -> packages/usebeeline/dist/usebeeline.mjs
+```
+
+Repository map:
+
+```text
+beeline/
+├── apps/
+│   ├── auth/          GitHub identity, NIP-05, repository install ceremony
+│   ├── body/          The daemon: harness sessions, Room turns, corners, self-update
+│   ├── gate/          Relay, repository, and provisioning primitives
+│   ├── mobile/        The phone app
+│   ├── push-gateway/  Server-indexed Room surfaces and push delivery
+│   └── server/        The monolith: Workspaces, Rooms, membership, grants
+└── packages/
+    ├── api-contract/  Shared vocabulary — faces, grants, system events
+    ├── buzz-client/   Signed client for the indexed surfaces
+    ├── nostr/         Schnorr-signed events and npub/nsec identity
+    └── usebeeline/    This package
+```
+
+The product spec is [`spec.md`](https://github.com/Beeline-Work/beeline/blob/main/spec.md), agent-facing conventions live in [`CLAUDE.md`](https://github.com/Beeline-Work/beeline/blob/main/CLAUDE.md), and the UI contract lives in [`DESIGN.md`](https://github.com/Beeline-Work/beeline/blob/main/DESIGN.md).
+
+## License
 
-The wizard asks exactly for the harness, any required provider credential, the
-model, and the agent's soul. OpenRouter defaults to GLM 5.3 Flash.
+`usebeeline` is published as `UNLICENSED`: free to install and run, not licensed for redistribution. A public source licence has not been chosen yet.