readyroom 0.1.7 → 0.2.0

package/README.md

@@ -50,6 +50,65 @@ share one place to ask and one place for you to answer.
 - **Three ways to run it, one program.** `npx` for one machine, Docker for an always-on box,
   a Cloudflare Worker for when your agents cannot reach either.
 
+## Screenshots
+
+The page is one flow — the human draining the queue — and one authenticated role, so every
+capture is a *state* of that single flow rather than a role of its own. A few representative
+moments, desktop first:
+
+<table>
+<tr>
+<td align="center"><b>Queue, grouped by stream</b></td>
+<td align="center"><b>Options and free text</b></td>
+<td align="center"><b>Option selected</b></td>
+<td align="center"><b>Recent (undoable 5 min)</b></td>
+</tr>
+<tr>
+<td><img src="docs/screenshots/pending-multi-stream.png" width="280" alt="Pending queue grouped by stream heading, with dotted low, double blocking, and solid normal urgency badges."></td>
+<td><img src="docs/screenshots/pending-options.png" width="280" alt="A blocking-urgency ticket with option buttons above a second free-text ticket."></td>
+<td><img src="docs/screenshots/option-selected.png" width="280" alt="A ticket with an option picked, showing a thick left border, a SELECTED marker, and the option button pressed."></td>
+<td><img src="docs/screenshots/recent-answered.png" width="280" alt="An answered ticket in the Recent section with a dashed border, STATUS: ANSWERED badge, the recorded answer, and an Undo button."></td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td align="center"><b>Attached media, expanded</b></td>
+<td align="center"><b>Marked up and annotated</b></td>
+</tr>
+<tr>
+<td><img src="docs/screenshots/pending-media.png" width="280" alt="A ticket with an attached screenshot expanded for inspection: the image on a drawing canvas with Box, Draw, and Clear markup tools, above the optional annotations editor."></td>
+<td><img src="docs/screenshots/media-annotated.png" width="280" alt="The attached image marked up with a red box, and a queued note reading 'nudge the title left by 8px' in the annotations editor."></td>
+</tr>
+</table>
+
+<table>
+<tr>
+<td align="center"><b>Token gate</b></td>
+<td align="center"><b>Token rejected (401)</b></td>
+<td align="center"><b>Polling fallback</b></td>
+<td align="center"><b>Phone width</b></td>
+</tr>
+<tr>
+<td><img src="docs/screenshots/token-gate.png" width="280" alt="First paint with no token: the token bar is visible and the status reads waiting for token."></td>
+<td><img src="docs/screenshots/token-rejected.png" width="280" alt="A wrong token was saved: a Token rejected (401) error banner with the token bar shown again."></td>
+<td><img src="docs/screenshots/status-polling.png" width="280" alt="The SSE endpoint is unavailable, so the status reads polling every 5s."></td>
+<td><img src="docs/screenshots/mobile-pending.png" width="150" alt="The populated multi-stream queue at phone width."></td>
+</tr>
+</table>
+
+There is also an empty board, an inline per-card validation error, and a failed-load banner —
+the page is captured at `1280x800` (desktop) and `390x844` (the two `mobile-*` shots). A full set
+of every screen and state, with a one-line description of each, is in
+[`docs/screenshots/MANIFEST.md`](docs/screenshots/MANIFEST.md) — regenerate the lot with
+
+```sh
+npm run screenshots
+```
+
+which starts its own isolated readyroom on `:8972`, drives each state, and tears it down. For how
+to actually use each of these screens, see [`docs/USAGE.md`](docs/USAGE.md).
+
 ## Vocabulary
 
 These words are used exactly, in code, comments, tool descriptions, and docs. No synonyms.
@@ -96,8 +155,14 @@ ask_human({
                               // when it is safe for the agent to proceed without a human.
   timeout_seconds?: number,   // optional. Default 1800. Max 86400.
   urgency?: "low" | "normal" | "blocking",  // optional. Default "normal".
-  stream?: string             // optional. Overrides the env/basename default.
-}) => { id: string, status: "pending", expires_at: string }
+  stream?: string,            // optional. Overrides the env/basename default.
+  media?: Array<{             // optional. Screenshots, audio, or video for the human to inspect.
+    mime_type: string,        //   an image/*, audio/*, or video/* type
+    data_base64: string,      //   standard base64 (a `data:<mime>;base64,` prefix is accepted)
+    filename?: string,
+    caption?: string
+  }>
+}) => { id: string, status: "pending", expires_at: string, media?: MediaRef[] }
 ```
 
 ### `wait_for_answer`
@@ -111,13 +176,19 @@ wait_for_answer({
   timeout_seconds?: number    // default 60, max 600
 }) => {
   id: string,
-  status: "pending" | "answered" | "expired",
+  status: "pending" | "answered" | "expired" | "cancelled",
   answer?: string,
   answered_by?: string,       // "human" | "default"
-  answered_at?: string
+  answered_at?: string,
+  media?: MediaRef[],         // the media you attached, echoed back
+  annotations?: Annotation[]  // the human's notes and any rendered markup copy
 }
 ```
 
+When the human drew on an attached image, the annotated copy is returned **as MCP `image`
+content** alongside the text, so an agent that only speaks MCP can see the markup without
+fetching a URL. `annotations[].annotated_media` also names a blob under `GET /api/media/{id}`.
+
 ### `list_pending`
 
 Lists the tickets still pending across every agent stream. Takes no arguments.
@@ -141,6 +212,30 @@ its own earlier guess. An answer that came from `default_answer` gets a clearly
 prefix — `DEFAULT ANSWER (applied on expiry; no human responded):` — because labelling the
 agent's own default as a human answer would be worse than no prefix at all.
 
+## Media and annotations
+
+Media is **optional**: most tickets have none, and a ticket with media is answered exactly like
+one without. Attach it with `ask_human`'s `media` array (up to 8 items, 8 MiB each, 24 MiB per
+ticket) when a decision needs a screenshot, a clip, or a recording rather than words.
+
+- **Stored out of band.** The bytes live in a media store, keyed by an id; the ticket carries
+  only a `MediaRef` (kind, MIME type, filename, caption, size). `GET /api/tickets` and
+  `tickets.json` therefore stay small, and the page fetches a blob only when you expand a card.
+- **Served same-origin.** `GET /api/media/{id}` returns the bytes under the same Bearer auth as
+  every other `/api/*` route. Nothing is fetched from an external origin.
+- **Expand and inspect.** Each attachment is collapsed behind a *Show N attachments* toggle.
+  Images open on a drawing canvas (`Box`, `Draw`, `Clear markup`); audio and video get a player.
+- **Annotate and send back.** The human can mark up an image and add notes (notes on audio/video
+  capture the playhead position). On **Answer**, a marked-up image is rendered to a PNG, uploaded
+  with `POST /api/media`, and referenced from the answer. Annotations are **optional**: the human
+  may answer with text, a chosen option, annotations, or any combination — but not nothing.
+- **Back to the agent.** `wait_for_answer` returns the annotations as structured fields, and any
+  rendered markup as MCP `image` content, so the agent sees exactly what the human marked.
+
+The three targets share the behaviour; only the storage differs. `FileTicketStore` writes blobs
+under `${READYROOM_STATE_DIR}/media/`, and `DurableObjectTicketStore` chunks each blob across rows
+because a Cloudflare SQLite row is capped at 2 MB.
+
 ## Three ways aboard
 
 They run the same program. They differ in where it lives and who can reach it.
@@ -213,6 +308,10 @@ services:
       - ./readyroom-state:/app/.state
 ```
 
+Copy this file to get a runnable setup without retyping it:
+[`examples/docker-compose.yml`](examples/docker-compose.yml) — set `READYROOM_TOKEN`, then
+`docker compose up -d`.
+
 The container runs the same Node entry as npx, in stdio-plus-HTTP mode, as a non-root user, and
 handles `SIGTERM`.
 
@@ -368,6 +467,34 @@ The stream is the path segment, so each agent gets its own URL.
 }
 ```
 
+### Directing an agent to use readyroom (`AGENTS.md`)
+
+Paste the block below into your project's `AGENTS.md` (or `CLAUDE.md`) so the agent knows
+readyroom is available and how to reach it. It goes at the top level of that file, alongside
+your other project instructions.
+
+````markdown
+## Asking a human
+
+When you reach a decision you cannot make alone — a choice with real consequences, a
+preference only the operator holds, or anything you would otherwise guess at — ask the
+operator through the `readyroom` MCP server instead of guessing or blocking.
+
+- `ask_human` — enqueue a question and return immediately. It never waits. Pass `question`
+  (one sentence), and optionally `options` (2-5 mutually exclusive choices), `context`,
+  `default_answer`, `timeout_seconds`, `urgency`, and `stream`. It returns
+  `{ id, status: "pending" }`.
+- `wait_for_answer` — block for the human's answer to a ticket you enqueued. Pass the `id`.
+  It returns immediately if the ticket is already answered or expired; if it is still
+  pending, continue with independent work and call it again later. Do not poll in a tight loop.
+- `list_pending` — list the tickets still pending across every agent stream. Takes no arguments.
+- `cancel_ticket` — withdraw a ticket you no longer need answered. Pass the `id`.
+
+A delivered human answer is prefixed with `HUMAN ANSWER:`. An answer applied from
+`default_answer` on expiry is prefixed `DEFAULT ANSWER (applied on expiry; no human
+responded):` — never treat that as a human answer.
+````
+
 ### Auth and secrets
 
 `src/security.ts` holds both guards.
@@ -537,7 +664,9 @@ The Worker has no state dir, no bind address, and no daemon role. Three conseque
 ## The readyroom page
 
 The page is a **status board**, not a chat log. It shows what is waiting and clears when you
-have answered — which is why there is no markdown parser and no message history.
+have answered — which is why there is no markdown parser and no message history. For a
+walkthrough of opening it, reading a ticket, and answering one, see
+[`docs/USAGE.md`](docs/USAGE.md).
 
 `public/index.html`. One file, shared by all three targets. All CSS and JS inline. No CDN, no
 external origin, no build step. It renders correctly when opened from the server with the
@@ -549,7 +678,8 @@ network otherwise cut. It is inlined at build time into each target's bundle.
 - **Grouped by stream.** Tickets grouped under a stream heading, newest stream first. You need
   to know which agent is asking.
 - **Card contents.** Stream name, ticket age (`4m`), urgency badge, the question, the context,
-  option buttons, a free-text field, and an Answer button.
+  any attached media behind an expand-for-inspection toggle (with drawing and notes), option
+  buttons, a free-text field, and an Answer button.
 - **Keyboard-first.** `j`/`k` move between tickets, `1`-`5` pick an option, `Enter` submits, `u`
   undoes the last answer. Draining a queue with a mouse is the slow path.
 - **Tab title carries the count.** `(3) readyroom`.
@@ -573,8 +703,10 @@ GET  /healthz          -> 200, body "ok"
 GET  /                 -> the readyroom page (index.html)
 GET  /api/tickets      -> { tickets: Ticket[] }   pending + last 5 min of answered
 GET  /api/events       -> text/event-stream of ticket changes   (501 on the Worker)
-POST /api/answer       -> { id, answer, answered_by? } -> 200 | 404 | 409 already answered
+POST /api/answer       -> { id, answer?, answered_by?, annotations? } -> 200 | 400 | 404 | 409
 POST /api/undo         -> { id } -> 200 | 409 outside the undo window
+POST /api/media        -> { mime_type, data_base64 } -> 201 { media: MediaRef }
+GET  /api/media/{id}   -> the blob bytes (Content-Type from the stored MIME) | 404
 POST /mcp/{stream}     -> the Streamable HTTP MCP endpoint (Origin-guarded)
 ```
 
@@ -583,18 +715,22 @@ Unknown route -> `404`. Known route, wrong method -> `405`. The Node target addi
 
 ## CI/CD
 
-Four GitHub Actions workflows:
+Five GitHub Actions workflows:
 
+- **`.github/workflows/release.yml`** — on every push to `main` (that is, every merged PR): runs
+  [semantic-release](https://semantic-release.gitbook.io) over the conventional-commit messages
+  since the last tag, then versions, changelogs, tags, and publishes the release. It is the
+  entry point; the four below are its downstream stages.
 - **`.github/workflows/ci.yml`** — on push and PR: `npm ci`, typecheck, build,
   `wrangler deploy --dry-run`, `docker build`.
 - **`.github/workflows/publish.yml`** — on the default branch and `v*` tags: buildx for
   `linux/amd64,linux/arm64` (arm64 is required; the deploy target is a Pi), push to GHCR, auth
   via the built-in `GITHUB_TOKEN` with `packages: write` (no PAT, no repo secrets),
-  `docker/metadata-action` tags (`latest` on the default branch, semver on `v*`, `sha-<short>`),
-  GHA build cache scoped per image, one matrix entry per image. Supply chain:
+  `docker/metadata-action` tags (`latest` on the default branch and on `v*`, semver on `v*`,
+  `sha-<short>`), GHA build cache scoped per image, one matrix entry per image. Supply chain:
   `provenance: mode=max`, `sbom: true`, and `actions/attest-build-provenance` pushed to the
   registry.
-- **`.github/workflows/publish-npm.yml`** — on `v*` tags: `npm publish` with provenance, using
+- **`.github/workflows/npm-publish.yml`** — on `v*` tags: `npm publish` with provenance, using
   npm Trusted Publishing (OIDC) rather than a stored token. It needs `id-token: write` and the
   trusted-publisher entry configured on the package.
 - **`.github/workflows/deploy-worker.yml`** — on `v*` tags: `wrangler deploy` with
@@ -605,6 +741,48 @@ Four GitHub Actions workflows:
 
 `.github/dependabot.yml` covers `github-actions`, `npm`, and `docker`.
 
+### Releasing
+
+Merging a PR to `main` cuts the release. There is no version to bump and no tag to push:
+`release.yml` runs [semantic-release](https://semantic-release.gitbook.io), which reads the
+commit messages since the last release and picks the version by the usual convention:
+
+| Commit | Version bump |
+| --- | --- |
+| `fix: …` | patch |
+| `feat: …` | minor |
+| any type carrying a `BREAKING CHANGE:` footer | minor while `0.x`, major from `1.0` |
+| `docs:`, `chore:`, `refactor:`, `test:`, … | no release |
+
+It writes `CHANGELOG.md` and the new version into `package.json`, commits them
+(`chore(release): vX.Y.Z [skip ci]`), tags `vX.Y.Z`, and opens the GitHub Release. A merge whose
+commits are all non-releasing finishes green and publishes nothing.
+
+**Pre-1.0 behaviour.** While the version is still `0.x`, a breaking change bumps **minor** rather
+than major, so a `BREAKING CHANGE:` never jumps you to 1.0.0 by surprise. That downgrade lives in
+`release.config.js` and switches itself off the moment the current version's major is no longer
+`0`. To reach 1.0 deliberately, run `npm run release:major` — it bumps and tags `v1.0.0` — and
+from the next release on breaking changes bump major again.
+
+**Why the release workflow dispatches the others instead of leaning on the tag.** A tag pushed
+by a workflow's built-in `GITHUB_TOKEN` does not start other workflows: GitHub suppresses runs
+for events caused by `GITHUB_TOKEN` to prevent recursion, so the `v*` triggers above would stay
+silent. `workflow_dispatch` is the one event that rule exempts, so `release.yml` dispatches
+`npm-publish.yml`, `publish.yml`, and (when enabled) `deploy-worker.yml` on the new tag itself.
+The whole pipeline therefore runs on the built-in token — **no PAT and no repo secret**. If you
+ever switch `release.yml` to a PAT or a GitHub App token, remove that dispatch step, or the tag
+trigger and the dispatch will both fire.
+
+The `npm run release:patch|minor|major` scripts still work as a manual fallback — they push a
+tag, and the `v*` triggers pick it up — but with semantic-release they are no longer part of the
+normal flow.
+
+semantic-release, `@semantic-release/changelog`, and `@semantic-release/git` are
+devDependencies; the other release plugins resolve from semantic-release itself. The release job
+deliberately does **not** request `id-token: write`, so the OIDC token never sits beside
+installed dependency code: publishing stays in `npm-publish.yml`, whose two-job split keeps the
+token out of the build.
+
 ### npm publishing
 
 Trusted publishing (OIDC) is used, so no `NODE_AUTH_TOKEN` is stored. **The very first publish
@@ -621,6 +799,7 @@ npm run typecheck    # tsc --noEmit
 npm run build        # esbuild -> dist/server.mjs (single file, HTML inlined)
 npm run build:worker # wrangler deploy --dry-run --outdir dist/worker
 npm run dev:worker   # wrangler dev
+npm run screenshots  # capture every page state into docs/screenshots/
 ```
 
 Repo conventions: