@frod.io/bridge 0.7.0

package/README.md

@@ -0,0 +1,269 @@
+# Frod.io bridge — your computer is a desk
+
+You already have Claude Code on your computer, with your own sign-in, skills,
+memory and tools. The bridge makes that Claude a **session of the platform**:
+agents you choose run on your computer, take `@mentions` from Teams and
+Telegram, read their Inbox, sit in the Office, run blueprint steps and file
+into the map — governed and metered like every other agent — and nothing of
+yours leaves your machine.
+
+## One command to join
+
+On an agent's page in Mission Control, **Join from your computer** gives you a
+one-time code and shows the command to run (the code lasts 15 minutes and
+works once). The bridge is a public package, `@frod.io/bridge` — nobody needs a
+checkout of the platform repository:
+
+```
+npx @frod.io/bridge@latest join <code> --api https://api.agentic.frod.io [--name "Wafeek's Mac"] [--workdir ~/frod-work] [--max-sessions 2] [--no-install]
+```
+
+`npx` only bootstraps the command. `join` itself:
+
+- checks that `claude` is installed and signed in (`claude auth login`);
+- exchanges the code for a token and keeps it in your OS keychain — macOS's
+  `security`, set up so the item trusts `/usr/bin/security` and never pops a
+  dialog; Linux's `secret-tool`; anywhere else a 0600 file, and it says so;
+- writes `~/.frod/bridge.json` (no secret in it);
+- **installs the very package it just ran** into
+  `~/.frod/bridge/versions/<version>/`, with `~/.frod/bridge/current` a
+  symlink to it (a junction on Windows) — the npx cache is never where the
+  bridge actually runs from;
+- writes the run-at-login entry so it points at
+  `node ~/.frod/bridge/current/dist/cli.js run` (macOS launchd agent
+  `io.frod.bridge`, Linux systemd user unit `frod-bridge.service`, Windows
+  scheduled task *Frod.io bridge*);
+- and starts it.
+
+Pass `--no-install` to join without any of the install/run-at-login steps —
+useful if you'd rather run `install` or `run` by hand afterwards.
+
+**You join once.** A computer is *yours* on the platform, not an agent's.
+Every further agent is attached in Mission Control — on that agent's page,
+**Join from your computer → Attach an existing computer** — and the change
+reaches a running bridge at once, no restart. `status` lists the agents this
+computer hosts and how each runs.
+
+## Other commands
+
+All of these work either as `npx @frod.io/bridge@latest <command>` or, once
+you've joined, as `node ~/.frod/bridge/current/dist/cli.js <command>`:
+
+- `install` — on a computer already joined (from an old checkout, or an
+  earlier package), stages this package into `versions/`, rewrites the
+  run-at-login entry to point at it, leaves the keychain item exactly as it
+  is, and restarts the bridge — any session running here ends, so do it
+  when the desk is clear.
+- `run` — runs the bridge in the foreground.
+- `status` — what the platform sees, and which agents run here.
+- `leave` — see below. `uninstall` — removes the run-at-login entry only
+  (the installed versions under `~/.frod/bridge` stay; delete the folder if
+  you like). `--version` — prints the version this command is.
+
+## What the platform decides, per agent (in Mission Control)
+
+For every agent on your computer the workspace owner chooses:
+
+- **Model** — the computer's default, Opus, Sonnet or Haiku (an alias Claude
+  Code understands), **Effort** — low, medium, high.
+- **Ask / Never ask.** *Ask* (the default): a shell command, the web, a file
+  outside the session folder, a connector that sends or changes something —
+  each becomes a decision on the owner's phone (Approve / Reject) before it
+  runs. *Never ask — acts on its own*: the same calls run without waiting, and
+  **every one of them is recorded** — an activity line the owner can read and a
+  notice in the session's transcript with the exact words the gate would have
+  used. Only the workspace owner can set it; an agent can never set it for
+  itself; it is never the default.
+
+## What the platform sees
+
+- The **transcript** of every session it opens here (what the agent said, the
+  tools it called and their results), its **cost** at the model's list rate
+  from the token counts Claude Code reports (the ledger says *billed to
+  subscription (list rate)*), and its **working folder** (`<workdir>/sessions/<id>`,
+  or the run checkout for a repository step).
+- That this computer is **connected or offline**, its name, OS and Claude Code
+  version, and how many sessions it is running (up to `--max-sessions`, across
+  all its agents).
+- Every permission decision, and — under *Never ask* — every call that would
+  have asked.
+
+## What it never sees
+
+- Your Claude sign-in, your `~/.claude` settings, skills, plugins and MCP
+  servers — they load as they always do; the platform only *adds* its own
+  system prompt and its own tools on top.
+- Any file outside the session folder unless the agent asks and a person
+  approves (or the owner chose *Never ask*).
+- Your git credentials: repository steps clone and push **with your own
+  access**, only ever the run branch, and the platform verifies the commit on
+  its side before it counts.
+- Any platform secret: the session's tools reach the Knowledge Hub, the
+  Library and every connector through doors on the platform, on a per-session
+  token that dies with the session. No database credential, no connector
+  credential and no API key is ever on this computer (the platform walks every
+  spec for them before it is sent).
+
+## It updates itself
+
+Every time the bridge connects, the platform announces the current version,
+signed. If this computer is behind, the bridge downloads the new tarball and
+checks it two ways before trusting it — its sha512 against the hash the
+platform announced, and an ed25519 signature over `version|integrity` against
+a public key built into the bridge. Both have to pass: a compromised registry
+alone can't push a version, and neither can a compromised platform alone. A
+tarball that fails either check is deleted, the old version keeps running,
+the log says `bridge.update_refused` with the reason, and the computer card
+says "Update to `<v>` refused: `<reason>`."
+
+A tarball that passes is extracted to `versions/<new>/`, and then the bridge
+**waits** — never in the middle of a turn, never with a prompt — until this
+computer hosts no live session, logging
+`update ready, waiting for the desk to clear` once an hour (the computer card
+says the same). When the desk is clear, it swaps `current` atomically, logs
+`bridge.updated {from, to}`, and restarts through the supervisor: it exits
+with code 75, a non-zero exit that launchd's `KeepAlive SuccessfulExit=false`
+and systemd's `Restart=on-failure` both bring straight back up — a clean exit
+(code 0) is deliberately a final goodbye, not a restart signal. Windows'
+scheduled task has no restart-on-failure, so there the bridge relaunches the
+new version itself, detached; if that fails, the next logon starts it.
+
+The keychain item is never touched by an update. You'll see `Updated to <v>`
+in `~/.frod/bridge.log` and the new version on the computer card. Two
+versions are kept under `versions/`; older ones are pruned.
+
+A bridge still run from a checkout — the old way,
+`npx tsx apps/bridge/src/cli.ts run` — never updates itself; its card says
+"update it by hand: `npx @frod.io/bridge@latest install`."
+
+## The compatibility contract
+
+The platform decides what a computer's bridge can be trusted with by the
+version it announces when it says hello — for example
+`0.7.0/claude 2.1.261/codex 0.153.2/grok 1.0.13`. Three lines are drawn on the
+platform side (`apps/orchestration-api/src/services/session-doors.ts`):
+
+- below bridge `0.2.0` — connectors are never attached (an older bridge
+  couldn't gate them, so it isn't offered the choice);
+- below `0.6.0` — no repository tools;
+- below `0.7.0` — the Inbox and orchestration tools run from a checkout of the
+  platform as separate processes on your computer; at or above, they're
+  served by the platform the same way the Knowledge Hub and the Library are,
+  which is exactly why the package needs no checkout at all.
+
+The rule behind these lines: one is only ever raised in the same commit as
+the feature that needs it, and a computer running an older bridge is told, in
+its own session's prompt, plainly, what it doesn't have — it is never handed
+a door it can't work.
+
+## Leaving
+
+```
+npx @frod.io/bridge@latest leave
+```
+
+revokes the token on the platform, forgets the computer there (each agent goes
+back to running where it did before — on the platform, or from its desk),
+removes the token from the keychain and the run-at-login entry. The workspace
+owner can do the same from Mission Control (**Settings → Your computers →
+Disconnect**), which takes the computer off the floor at once.
+
+## Files on this computer
+
+| Path | What |
+|---|---|
+| `~/.frod/bridge.json` | settings; no secret |
+| the OS keychain, item `io.frod.bridge` | the host token |
+| `~/.frod/bridge/versions/<version>/` | one installed copy of the package |
+| `~/.frod/bridge/current` | a symlink (junction on Windows) to the version that's running |
+| `~/.frod/sessions.json` | which Claude Code session each platform session ran as (for resume) |
+| `~/.frod/bridge.log` | the log — tokens are redacted before anything is written |
+| `<workdir>/sessions/<id>` | a session's folder (the default) |
+| the folder the owner chose | a session's folder when the agent's binding names a **working folder on this computer** (see below) |
+| `<workdir>/runs/<run id>` | a repository step's checkout (pruned after a week) |
+
+## A working folder per agent (day block 2026-09-03)
+
+The workspace owner may give an agent a **working folder on this computer** in
+Mission Control (the agent's page → Your computer → Change). The platform stores
+the path as typed and sends it with each session; **this computer decides**
+whether it allows it (`src/workdir.ts`):
+
+- allowed: the folder is, or is under, `workdir` in `bridge.json`
+  (`~/frod-work` by default) **or** one of the folders listed under
+  `"allowedRoots"` in `bridge.json` — a list you edit by hand; `~/` means your
+  home. A folder that does not exist yet is created (0700).
+- refused: anything else — outside every root, a relative path, a climb out with
+  `..`, a symlink that escapes. The session fails at once with the words
+  *"Wafeek's Mac does not allow that folder — allowed: …"*; nothing runs in a
+  folder you did not choose.
+
+The folder becomes the session's cwd and the free zone of its permission policy
+(reads and edits there are free; outside it, they ask — and Claude Code's own
+files and any `.git` **at any depth** under it ask too). A repository step
+ignores it and works in `runs/<run id>` as before. `status` prints the allowed
+folders.
+
+Two quirks of the containment check, both fail-closed and deliberate:
+`"allowedRoots": ["/"]` allows **nothing under it** (the check is `root + "/"`, and
+`"//"` matches no path — list real folders); and the check is
+case-sensitive, so on a case-insensitive disk (macOS default) a folder typed as
+`~/Frod-Work/x` is refused when the root is `~/frod-work` — type it as the root
+is spelled.
+
+## Adapters
+
+The bridge talks to a tool through one small interface — `start`, `prompt`,
+`cancel`, `stop` (`src/adapters/types.ts`). **`claude`**
+(`src/adapters/claude.ts`) is required — `join` checks it's installed and
+signed in, and it drives Claude Code's headless CLI with your subscription.
+**`codex`** (`src/adapters/codex.ts`) and **`grok`** (`src/adapters/grok.ts`)
+are optional: each is offered only when it's installed *and* signed in on
+this computer. Which agent runs on which adapter is decided in Mission
+Control, not here. Grok Build runs in its `workspace` sandbox, and the bridge
+answers its permission questions by the same Ask / Never-ask policy as the
+others. Each adapter is one file.
+
+## Running at login
+
+- **macOS** — a launchd user agent `io.frod.bridge`, running
+  `node ~/.frod/bridge/current/dist/cli.js run` — the same entry shape that
+  has run from a checkout on Wafeek's Mac since 2026-09-03; the packaged
+  entry runs there when his Mac is upgraded last, by him.
+- **Linux** — a systemd user unit `~/.config/systemd/user/frod-bridge.service`
+  running the same command (`systemctl --user enable --now
+  frod-bridge.service`; on a headless box `loginctl enable-linger $USER` once).
+  Written and enabled by `install`; proven in a container on 2026-09-06 — the
+  unit is written correctly, but `systemctl --user` doesn't exist in a
+  container, so the manual command is printed instead. Not yet proven on a
+  real Linux machine.
+- **Windows** — a scheduled task *Frod.io bridge* at logon
+  (`schtasks /Create`), also pointing at `current`. If it refuses, the exact
+  command is printed. Not yet proven on a real Windows machine.
+
+## Publishing
+
+`.github/workflows/deploy-bridge.yml` runs on every push to `main` that
+touches `apps/bridge/**`: it runs the tests, the type check and the bundle,
+then `npm pack` and a smoke test of the packed tarball in a clean directory,
+writes release notes from the commit subjects since the last published
+version, runs `npm publish --access public`, signs the release
+with an ed25519 key held in the `BRIDGE_SIGNING_KEY` secret, and calls
+`POST /api/bridge/releases` (with the `BRIDGE_RELEASE_TOKEN` secret) so the
+platform starts announcing it to connecting bridges.
+
+The version published is always the package's own: bump
+`apps/bridge/package.json` in the commit that should ship. The workflow
+refuses to publish a version already on the registry, and never bumps
+anything itself. Three secrets gate the workflow's last three steps, and if
+one is missing the workflow says in words which one.
+
+## For developers
+
+- `npm test -w @frod.io/bridge`
+- `npm run build -w @frod.io/bridge` — bundles `dist/cli.js` with esbuild and
+  runs `tsc` for types.
+- `npm run pack:check` — packs the tarball and smoke-tests it in a clean
+  directory, the same check the publish workflow runs.
+- The bundle test asserts that every adapter and every door starts correctly
+  from `dist/cli.js` alone, with no checkout of the platform on disk.