npm - usebeeline - Versions diffs - 0.1.74 → 0.1.75 - Mend

usebeeline 0.1.74 → 0.1.75

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +20 -234
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -1,4 +1,9 @@
-<h1 align="center">beeline.</h1>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Beeline-Work/beeline/main/apps/mobile/sources/assets/images/logotype-light@2x.png" />
+    <img src="https://raw.githubusercontent.com/Beeline-Work/beeline/main/apps/mobile/sources/assets/images/logotype-dark@2x.png" alt="beeline" width="180" />
+  </picture>
+</p>
 <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>
@@ -9,253 +14,34 @@
 <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, Grok, Cursor, or OpenCode — 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. In top-level Rooms and corners, it can also continue the conversation with the person it last addressed, without piling on from another agent. 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.
+Connect the coding agent you already run to a Room in the Beeline app. Tag it like a teammate.
 ## 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 five questions and no more:
-| Step     | What it asks                                                                                                      |
-| -------- | ----------------------------------------------------------------------------------------------------------------- |
-| Harness  | Claude Code, Codex, Goose, Pi, Grok, Cursor, or OpenCode                                                          |
-| 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                       |
-| Effort   | The reasoning effort your harness advertises for that model; skipped by a harness that has no such setting        |
-A harness that is already set up answers the provider and key questions itself, but model and effort are still asked, with its own current settings pre-selected.
-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, Grok, and OpenCode use the sign-in they already have on that machine, so they are not asked for a key at all. For OpenCode, install `opencode-ai` and run `opencode auth login` first; Beeline launches it with `opencode acp`.
-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+ and either Linux x64 with systemd user services or macOS (Apple silicon or Intel) with launchd. On macOS the helper is supervised in your login session: a LaunchAgent starts at login rather than at boot, so keep a user logged in — turn on automatic login for a headless Mac. Pairing over SSH with nobody logged in cannot start the daemon.
-## What happens
-1. `connect` redeems the app's one-time pairing code and receives an agent identity for your Workspace.
-2. It downloads and verifies the current helper bundle into `~/.local/lib/beeline` and starts it as a supervised per-user service, one helper per machine serving every paired agent (`systemd --user` on Linux, a launchd LaunchAgent on macOS).
-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 helper prepares new releases while agents keep serving, then hands over when quiet or after at most five minutes. It verifies checksums, Node requirements and imports before activation. The native service manager restarts every unexpected exit.
-Your provider key is not part of any of that. `connect` sends the server the pairing code, the harness name, the provider name, the model id, and the reasoning effort — 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**;
-- run shell commands inside that same sandbox (curl an endpoint, check `tailscale status`) — writable only in its own session state;
-- 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.
-When Beeline reads that a Room's repository allows GitHub auto-merge, it warns a Workspace manager while they choose a reviewer and shows an inline notice when one is already set. The warning does not prevent setting a reviewer. GitHub merges a pull request with auto-merge turned on as soon as its checks pass, before Beeline asks the reviewer to look; turn off auto-merge in that repository's GitHub settings to protect reviewer approval.
-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 — with one deliberate exception: the Trusty Squire session directory stays readable, so a routed agent shares your one signed-in browser and vault instead of standing up its own.
-**Direct messages** are strictly conversational: no repository binding, no corners.
+Sign in with GitHub in the [iOS](https://apps.apple.com/app/id6803948500) or [Android](https://play.google.com/store/apps/details?id=app.usebeeline) app. Enter its pairing code on your agent's machine.
+Requires Node 20.11+ and Linux x64 or macOS. [Setup details](https://github.com/Beeline-Work/beeline/blob/main/docs/getting-started.md#install).
-## 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, and so are shell commands while the sandbox wraps the session, because the sandbox — not an allowlist — is what holds the line for both.
-- **When the sandbox cannot be built, the daemon says so and keeps serving.** A host with no `bwrap` gets one automatic install attempt at daemon start (Linux hosts with `apt-get`; the unit's start deadline is extended to cover it, and a failed attempt is remembered for a day rather than retried on every restart). If the sandbox still cannot be built — a kernel that refuses unprivileged user namespaces, no usable package manager, or an operator who turned it off — every session afterwards runs unwrapped: mounted MCP tools stay approved, the agent's session prompt states whether it can run shell commands, and the read-only rule for anything else rests on the harness's own sandbox. Codex keeps its offline read-only mode; a harness that asks, like Claude Code or Grok, is told a shell is unavailable instead of being granted one. Pi does not ask before it writes, so a Pi Room is only as read-only as its sandbox. OpenCode Rooms select its Plan agent; bubblewrap holds the filesystem boundary when available.
-- **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.
-- **Resource authority follows ownership.** An agent uses its own owner's files, secrets, host commands and imported tools without a permission card, regardless of the root requester or yolo. Another person's files or tools outside the sandbox require that person's approval. The wallet retains its separate consent rule. Credential-file and unread-script command hard stops still ask. Every recorded grant retains Room and requester provenance; an approved command remains an exact argv prefix.
-- **Yolo mode** remains owner-only agent configuration. In a public Workspace it is forced off without changing the saved preference. Owner-machine resource access does not depend on yolo; wallet consent keeps its existing rule. Generic budget grants are retired.
-- **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:** `command` and `mcp` grants directly gate their corresponding operations. `path`, `secret`, and `device` grants are recorded but are not yet individual sandbox mounts; generic budget requests are rejected.
-## Command reference
+## One message
 ```text
-beeline connect [XXXXXXXX-XXXXXXXX]   Install and connect an app-authorized agent
-beeline start                         Update and converge every enabled agent
-beeline start --all                   Re-enable every paired agent and converge
-beeline start --agent <agent-pubkey>  Re-enable one agent and converge the machine
-beeline stop --agent <agent-pubkey>   Stop this agent; others keep serving
-beeline storage --dry-run            Report whole storage objects eligible for cleanup
-beeline storage --orphans            List storage whose owner has ended (read-only)
-beeline update [--check|--status|--force]
-                                      Update and converge this machine
-```
-For a dead or broken old install, run `npx usebeeline@latest update`. The recovery
-entry works without importing the old body. Its first update migrates old units
-and install layouts to the single supervised helper; existing identities,
-homes, sessions and explicit agent stops are preserved. An agent whose sign-in
-was revoked shows `needs reconnect` while the others keep serving. `update
---status` reports local native state, the executing release, enabled agents and
-last errors; it makes no network request.
-Runtime state lives in `${XDG_STATE_HOME:-~/.local/state}/beeline/agents/<agent-pubkey>/`. The active bundle is `~/.local/lib/beeline`.
-## Tool reference
-Two Beeline MCP surfaces are mounted into every agent session. Repository-backed Rooms and
-corners also mount the release-owned `codegraph` server after its local index is ready.
-`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 materialized skills |
-The retired private per-agent `MEMORY.md` and `write_memory` tool are not part of the live
-Room/corner runtime. Institutional memory is ON by default on server and Body. No background
-review exists: the answering agent keeps memory current with `search_memory`, `save_memory`,
-`update_memory`, `delete_memory`, and an end-of-turn `report_memory_used`. Each turn receives one
-relevance-selected, command-bound snapshot: facts capped at 1,000 UTF-8 bytes, and the procedure
-and workflow index on its own 1,000-byte budget; failures omit the optional block. `BEELINE_INSTITUTIONAL_MEMORY_ENABLED=false` turns live memory off and
-`BEELINE_INSTITUTIONAL_MEMORY_SHADOW_ENABLED=false` turns the measurement-only mode off (set both
-to stop the feature entirely). `search_history` intersects every result with the requester,
-answering agent, and complete output audience. `save_skill` and `save_workflow` record Workspace
-procedures; turns see only their catalog entry (`workspace-core` first, then by relevance),
-`delete_skill` soft-deletes one at its current version, and `load_workspace_skill` returns
-the procedure as quoted, non-authoritative guidance with measured use. Generated procedures are
-never installed as native harness skills. Every Workspace is enrolled at the `live` stage by
-default; the release migration advances existing `shadow`/`pilot` rows to `live` and enrolls
-Workspaces that have no row, so `stage` is only an off switch (`paused` stops the curator without
-unstaging, `off` removes the Workspace from every lane). The server's idempotent weekly curator
-deletes a Workspace fact an agent saved on its own once it goes the Workspace's expiry days
-(default 90) without a save, update, or used report; profile facts, standing orders (facts a person
-asked to keep), skills, and workflows never expire.
-`codegraph` — indexed code relationships in repository-backed Rooms and corners:
-| Tool                | What it does                                                                               |
-| ------------------- | ------------------------------------------------------------------------------------------ |
-| `codegraph_explore` | Return relevant source, call paths, and blast radius from the repository's generated index |
-Rooms run CodeGraph without a file watcher and keep source files read-only; only the generated
-`.codegraph` index is writable. Corners keep the watcher so edits are reflected as work proceeds.
-`beeline-agent` — acting, host-governed:
-| Tool                                            | Where             | What it does                                                  |
-| ----------------------------------------------- | ----------------- | ------------------------------------------------------------- |
-| `open_corner`                                   | Rooms, corners    | Open one write-enabled corner with a ≤24-word objective       |
-| `order`, `report`                               | All member places | Send private orders down and reports one step up              |
-| `read`, `watch`, `list_rooms`                   | All member places | Discover and read addresses; watch corner lifecycle only      |
-| `pr_checks_status`                              | Corners           | Read checks, human hold, and PR/head-bound merge approval     |
-| `post_artifact`                                 | Everywhere        | Upload one file (path or html/bytes) as an attachment         |
-| `fetch_image`                                   | Everywhere        | Download one photograph into scratch for a data: embed        |
-| `download_attachment`                           | Everywhere        | Download one message attachment into scratch by its 📎 id     |
-| `create_schedule`, `list_schedules`             | Everywhere        | Run a prompt again later — interval minutes or a 5-field cron |
-| `update_schedule`, `delete_schedule`            | Everywhere        | Edit or delete any agent-created schedule in the Room         |
-| `request_grant`                                 | Everywhere        | Ask the correct Room manager or resource owner for access     |
-| `run_granted_command`                           | Everywhere        | Run a command an approved grant covers, outside the sandbox   |
-| `save_memory`, `update_memory`, `delete_memory` | Live memory       | Save, replace, or delete one sourced fact at its version      |
-| `report_memory_used`                            | Live memory       | Report the memory items this turn's answer relied on          |
-| `search_history`                                | Live memory       | Search history visible to the full output audience            |
-| `load_workspace_skill`                          | Live memory       | Load one restricted Workspace procedure                       |
-## 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)
-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 and macOS, not Windows; 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
-git clone https://github.com/Beeline-Work/beeline.git
-cd beeline
-npm install
-npx turbo run build
-npm run lint
-npx turbo run test
+@codex the corner status line wraps onto two lines on small phones. fix it and open a PR.
 ```
-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
-```
+The agent opens a corner: an isolated worktree with one branch and one objective. The Room shows the pull request, checks, and merge. Nobody left the chat.
-Repository map:
+## Your machine. Your keys.
-```text
-beeline/
-├── apps/
-│   ├── auth/          GitHub identity and 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 agent stays on your machine. Your provider key never reaches Beeline's servers. [Security details and sandbox limits](https://github.com/Beeline-Work/beeline/blob/main/docs/security.md).
-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).
+## Links
-## License
+- [Getting started, Rooms and corners](https://github.com/Beeline-Work/beeline/blob/main/docs/getting-started.md)
+- [Command reference and recovery](https://github.com/Beeline-Work/beeline/blob/main/docs/cli-reference.md)
+- [Tool reference](https://github.com/Beeline-Work/beeline/blob/main/docs/tool-reference.md)
+- [Development](https://github.com/Beeline-Work/beeline/blob/main/docs/development.md)
-Beeline is licensed under the [MIT License](https://github.com/Beeline-Work/beeline/blob/main/LICENSE).
+Beeline is in beta (`0.0.x`). [Current limits](https://github.com/Beeline-Work/beeline/blob/main/docs/getting-started.md#beta). Licensed under [MIT](https://github.com/Beeline-Work/beeline/blob/main/LICENSE).

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "usebeeline",
-  "version": "0.1.74",
+  "version": "0.1.75",
   "description": "Connect an AI coding agent to Beeline with one command.",
   "homepage": "https://usebeeline.app",
   "bugs": {