@unifedev/thread-pages 0.3.2

package/ARCHITECTURE.md

@@ -0,0 +1,230 @@
+# Architecture
+
+Version 0.3.0 · September 2026
+
+This is the design and its reasoning. [docs/MODEL.md](./docs/MODEL.md) is the
+operator's view — where things are stored and how to reach them.
+[docs/ROADMAP.md](./docs/ROADMAP.md) is what is left.
+
+## Intent
+
+A Thread Page is a small application an agent writes for one task, for one
+person to read and answer from.
+
+Chat is a poor medium for the moments that matter: a comparison, a diagram, a set
+of choices, a thing only the user can decide. Those want a page. But a *fixed*
+page — a dashboard with slots — is worse than chat, because the shape of what
+needs saying changes with every task.
+
+So the plugin supplies no design. It supplies a secure host for a document the
+agent writes freshly each time, and a way for that document to talk back.
+
+Three properties follow, and everything else is downstream of them:
+
+1. **The page is a file the agent edits directly.** Not a template it fills, not
+   an API it posts to. Saving is publishing.
+2. **The agent's contract stays small.** One command, a short instruction, and
+   an optional guide it fetches only when the page needs more than prose.
+3. **Page code is untrusted.** It is generated, so it is sandboxed and given
+   narrow named capabilities rather than credentials.
+
+## The shape
+
+```
+~/.bb/thread-storage/<threadId>/thread-page.html     the page
+                              /thread-page-assets/   what it shows
+                              /thread-page-uploads/  what the user sent
+```
+
+An agent runs `bb thread-page init`, gets that path, and edits the file. The
+plugin serves it at a stable URL on the bb origin the user is already
+authenticated to — so the same link works on a laptop and a phone with no extra
+port, tunnel, or password.
+
+Nothing else is stored. Two small values live in bb's existing key-value table: a
+signing key, so open browser sessions survive a plugin reload, and a best-effort
+last-good copy per page, so a page still opens read-only when its machine is
+offline. There is no plugin database and no background service.
+
+## Trust boundary
+
+The page is generated code, so it is treated as hostile.
+
+**Inside the iframe** — `sandbox="allow-scripts allow-forms"`, opaque origin.
+Arbitrary HTML, CSS and JavaScript are allowed *because* the frame has no bb
+cookie, no mutation token, no parent DOM, no `localStorage`, no raw bb API, no
+CLI, and no filesystem access. CSP blocks ordinary `fetch` and subresources.
+Page-authored code can therefore be as creative as the task needs without that
+creativity being a security question.
+
+**Outside the iframe** — plugin-authored code on the bb origin. It holds the
+action token, makes the same-origin calls, owns navigation, and renders
+confirmations. The document URL carries render authority only, so page code never
+sees a credential that can change anything.
+
+**Between them** — one `MessagePort` and a fixed capability list. Each capability
+has its own validator, size and depth limits, effect class, and output
+projection. There is no generic "call bb" method, no path parameter, and no
+provider passthrough.
+
+### Confirmed effects
+
+Anything that reaches outside the current thread requires a confirmation the page
+cannot fake or word:
+
+1. The page invokes the method.
+2. The server refuses once, returning a signed challenge that carries **its own**
+   summary, derived from validated parameters.
+3. The trusted shell shows that summary in a dialog the sandbox cannot draw over.
+4. The server verifies the signature before acting.
+
+The challenge is bound to one request id, method, parameter fingerprint, page
+revision and thread, and expires in two minutes. So it cannot be forged, replayed,
+or reused to approve different parameters — a page cannot get "message thread A"
+approved and then quietly reuse it for thread B.
+
+### The honest limitation
+
+Page JavaScript can navigate its own frame and encode data in the destination
+URL. Browser sandbox flags do not close that channel, and CSP resource directives
+do not either. A page therefore has access to data already inside its own frame.
+
+It grants no bb authority. Closing it entirely would mean forbidding authored
+JavaScript and shipping a declarative renderer instead, which would cost the
+open-page model that is the point of the product. This is a stated trade, not an
+oversight.
+
+## Capabilities
+
+| Method | Effect | Confirmed |
+| --- | --- | --- |
+| `context.get` | read | |
+| `thread.activity` | read | |
+| `threads.snapshot` | read | |
+| `projects.list` | read | |
+| `providers.list` | read | |
+| `storage.get` | read | |
+| `thread.reply` | current-thread write | |
+| `storage.set` | current-thread write | |
+| `threads.openPage` | navigation | |
+| `threads.openBb` | navigation | |
+| `threads.continue` | cross-thread write | yes |
+| `threads.spawn` | cross-thread write | yes |
+| `projects.create` | cross-thread write | yes |
+| `threads.archive` | destructive | yes |
+| `threads.stop` | destructive | yes |
+| `navigation.openExternal` | navigation | yes |
+| `projects.browse` | device | yes |
+| `voice.captureAndTranscribe` | device | contract only |
+
+Adding a capability extends this list. It never requires a new page component,
+because no page component is built in.
+
+Two deliberate narrowings. `projects.browse` opens the host's native folder
+picker and returns an **opaque single-use token** plus a display string — never a
+filesystem path the page could reuse or leak; `projects.create` redeems it.
+`storage.*` is namespaced per thread, so pages cannot read each other's state
+despite sharing one table.
+
+## What the plugin renders, and what it does not
+
+The plugin owns exactly three pieces of UI, all of them chrome outside the
+sandbox:
+
+- the page title bar;
+- a **Sessions** link back to the home page;
+- a working indicator while the thread is mid-turn.
+
+The last two are worth explaining, because both could have been pushed onto
+agents and deliberately were not.
+
+**The Sessions link** is chrome so that no agent spends instruction budget on it
+and no page can forget it. The home page it points to is not special: any
+thread's page can be designated home with `bb thread-page home`, and it is an
+ordinary Thread Page afterwards.
+
+**The working indicator** answers "is it still writing?". Its state rides on the
+`x-thread-page-activity` header of the revision poll the shell already makes
+every ten seconds — so it costs no extra request, nothing in any page's HTML, and
+nothing in any agent's instructions. Its wording is a setting; blank hides it.
+
+Everything else is the page's.
+
+## The home page
+
+`bb thread-page home` designates a thread and, if that thread has no page yet,
+writes a session hub. The default groups sessions by project and gives each group
+its own look.
+
+The design point is that **a group is not a project**. A group is a label, a
+look, and a *set* of project ids, kept in the page's own scoped storage. One
+group per project is only the default; a project may appear in several groups,
+and regrouping is an edit to the page rather than a schema change.
+
+Per-group looks need no second document. The stylesheet's `data-world` attribute
+re-resolves every design token for a subtree, so a group can carry a different
+palette, typeface, shape language and button style inside one page. Separate
+linked pages remain possible through `threads.openPage`; they were not necessary.
+
+## The design system
+
+Five worlds — `paper`, `terminal`, `atrium`, `volume`, `bloom` — each declaring
+both light and dark palettes at once, with one resolver publishing the live half
+onto the tokens the rest of the sheet uses. A page picks one with `data-theme` on
+`<html>`, plus `data-mode` and `data-atmos`.
+
+It needs no class names: every rule keys off semantic structure, so plain HTML is
+already styled. Three class names exist for things structure cannot express —
+`.card`, `.needs-you`, `.label`.
+
+**The stylesheet travels inside each page** rather than being injected at render
+time. That means an agent can change any rule for one page, and a plugin update
+can never restyle a page the user has already read. The cost is that improvements
+to the design system only reach pages created afterwards; that trade favours the
+reader.
+
+A page may add one more `<style>` with two rules: everything inside
+`@scope (main)`, and colour and shape from `var(--token)` only. The second is
+what keeps a bespoke chart correct in all five worlds and in dark mode.
+
+## Instructions
+
+Three, and only the first is loaded per session.
+
+1. **The contract** — why the page matters, how to ask well, what belongs on a
+   page. Injected into eligible root threads. It holds only what changes
+   behaviour; every mechanical convention is absorbed by the runtime or the seed.
+2. **The seed comment** — the class names, the theme attributes, the escape-hatch
+   rule. Free, because the agent is already reading the file.
+3. **The guide** — `bb thread-page guide`. Unbounded, and paid for only by the
+   sessions that open it.
+
+There is no skill and no agent tool. Both would put the plugin in every session's
+context whether or not the task needs it.
+
+## Eligibility
+
+Only threads a user started get a page. Children, forks and hidden workers get
+`SKIP` and answer in chat, because they are not the ones being talked to. `init`
+rechecks this at call time rather than trusting the injected instruction.
+
+## Testing
+
+93 tests over three suites, none needing a browser:
+
+- `bridge.test.ts` — the capability contract in isolation: validators, limits,
+  effect classes, confirmation binding. No SDK, DOM, or filesystem.
+- `page.test.ts` — HTML parsing against malformed and adversarial documents,
+  kernel ordering, sandbox invariants, form and label derivation.
+- `server.test.ts` — routes, tokens, capabilities, uploads, assets, home, and the
+  working state, against a fake host.
+
+Browser verification is done by hand for the things tests cannot see. Several
+real defects were found only that way — an invalid CSP source that silently
+blocked every relative asset, an auth rule that rejected raw upload bodies, a
+`<select>`'s options leaking into an answer label, and a snapshot flag that
+selected archived threads instead of adding them. Each has a test now.
+
+The gap worth naming: there is no hostile-page corpus yet. The confirmation flow
+is tested against forgery, replay and parameter-swapping, but no test plays an
+attacker trying to reach the parent frame or steal a cookie.

package/PLUGIN_OVERVIEW.md

@@ -0,0 +1,83 @@
+# Thread Pages
+
+Give every bb thread its own web page — written by the agent, for that one task.
+
+## What it does
+
+An agent working on a task usually has more to tell you than chat can carry: a
+comparison, a diagram, a set of choices, a thing only you can decide. Thread
+Pages gives it a real page to say it on.
+
+The agent runs one command, gets an HTML file, and edits it directly. Saving the
+file publishes it. You open one stable link — in bb, in a browser, on your
+phone — read the page, and answer from inside it. Your answer arrives as the
+agent's next message.
+
+The page is a complete HTML document the agent writes for the task at hand. Not
+a template with slots. If the task needs a chart, it writes a chart. If it needs
+an eight-screen wizard, a diagram you click, or three separate forms, it writes
+that. The plugin supplies the secure host, never the design.
+
+## Why it is built this way
+
+**Nothing to learn, nothing to load.** There is no skill in the agent's context,
+no page tool, no publish protocol, no runtime copied into your files. The
+standing instruction is two sentences. Deeper guidance is one optional command
+away, so a simple task never pays for it.
+
+**The page is a file.** It lives in the thread's own storage as ordinary HTML.
+The agent reads and writes it with the tools it already has. You can open it,
+diff it, or keep it.
+
+**Your bb, your page.** Pages are served through the bb origin you are already
+authenticated to, so they work over bb Connect and on mobile without exposing a
+second port or a public URL.
+
+**Safe by construction.** Page code runs in an opaque-origin sandbox with no bb
+cookie, no mutation token, no parent DOM, no raw API, and no general network
+access. Anything the page can ask bb to do goes through one narrow, validated
+capability at a time.
+
+## In the page
+
+- Any HTML, CSS, and JavaScript the task needs, including Web Components, SVG,
+  canvas, and multi-screen state.
+- Forms that reply to the thread with no code at all — blank answers included,
+  several forms at once, each with its own state.
+- File attachments, stored beside the thread and handed to the agent by path.
+- Images, stylesheets, fonts, and data from a confined per-thread asset folder.
+- Live thread activity, and a working indicator while the agent is mid-turn.
+- Listing, messaging, starting, stopping and archiving sessions from a page.
+- Update protection, so a page reload never eats what you were typing.
+- A read-only cached copy when the source machine goes offline.
+
+## Getting started
+
+Install the plugin, then turn on **Agent initialization hint** in its settings
+to have new sessions use their page automatically. Or leave it off and ask any
+agent to run `bb thread-page init`.
+
+The page seed and the instruction text are both settings, so you can change what
+every future page starts from without touching any existing page.
+
+## The home page
+
+`bb thread-page home` writes a session hub grouped by project, each group with
+its own look, and every other page then shows a **← Sessions** link back to it.
+
+Home is an ordinary page afterwards — ask the agent that owns it to regroup or
+restyle it. Groups are not tied to projects: a group is a label, a look, and a
+set of projects, so "Work" and "Side projects" are as valid as one-per-project,
+and a project can appear in both.
+
+## Current state
+
+Everything needed for daily use is implemented and verified in a browser: page
+authoring, forms, attachments, confined assets, live activity, the session hub,
+and the full capability set with trusted confirmations. Voice dictation has a
+defined contract but no handler yet.
+
+One limitation worth stating plainly: page JavaScript can navigate its own frame
+and put data in that URL. Browsers cannot prevent this while still allowing page
+scripts. It grants no bb authority, but a page you did not write is still code
+you are choosing to run.

package/README.md

@@ -0,0 +1,153 @@
+# Thread Pages
+
+`@unifedev/thread-pages` — part of [Unife](https://github.com/unifedev), a
+unified interface for everything. Thread Pages is the unified interface for
+working with AI agents; this plugin implements it for [bb](https://getbb.app).
+
+**Every agent session gets one web page, written for that task, that you can read
+and answer from on any device.**
+
+An agent usually has more to tell you than chat can carry: a comparison, a
+diagram, a set of choices, a thing only you can decide. Thread Pages gives it a
+page to say it on — and gives you a form to answer from, which arrives as the
+agent's next message.
+
+The page is a complete HTML document the agent writes for the task at hand. If it
+needs a chart, it writes a chart. If it needs a multi-screen flow, a diagram you
+click, or three separate forms, it writes that. The plugin supplies the secure
+host, never the design.
+
+## Install
+
+```sh
+bb plugin install git:https://github.com/unifedev/bb-thread-pages.git
+```
+
+Then turn on **Agent initialization hint** in the plugin's settings, so new
+sessions use their page automatically:
+
+```sh
+bb plugin config thread-pages set agentInstructions true
+```
+
+That is the whole setup. If this bb is paired with `bb connect`, every page is
+reachable from your phone immediately — there is no port to expose and nothing
+per-page to configure.
+
+## Using it
+
+The agent's whole workflow is one command:
+
+```sh
+bb thread-page init      # create or locate this thread's page; prints the link
+```
+
+Two others exist:
+
+```sh
+bb thread-page guide     # authoring reference, only when a page needs more
+bb thread-page home      # make this thread's page the home page
+```
+
+`bb thread-page home` writes a session hub grouped by project, with a filter,
+live status, and per-row open, prompt, stop and archive. Every other page then
+shows a **← Sessions** link back to it. Home is an ordinary page afterwards: ask
+the agent that owns it to regroup or restyle it.
+
+## Documentation
+
+- [docs/MODEL.md](./docs/MODEL.md) — **start here**: instructions, storage,
+  templates, and remote access
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — the design and its reasoning
+- [docs/ROADMAP.md](./docs/ROADMAP.md) — what is left
+- [PLUGIN_OVERVIEW.md](./PLUGIN_OVERVIEW.md) — marketplace description
+
+## What a page can do
+
+Authored freely inside the sandbox:
+
+- any HTML, CSS and JavaScript, including Web Components, SVG, canvas, and
+  multi-screen state;
+- forms that reply to the thread with no code at all — blank answers included,
+  several forms at once, each with its own state;
+- file attachments, stored beside the thread and handed to the agent by path;
+- images, stylesheets, fonts and data from a confined per-thread asset folder;
+- live thread activity, so a page can show what the agent is doing now;
+- small state that survives a reload.
+
+Through named capabilities, with confirmation where it matters:
+
+- list sessions, projects and providers;
+- message, start, stop or archive a session;
+- create a project through the host's native folder picker;
+- open another page, a bb thread, or an external link.
+
+The plugin also supplies three pieces of chrome outside the page: the title bar,
+the Sessions link, and a working indicator while the thread is mid-turn. Its
+wording is a setting; blank hides it.
+
+## Where things live
+
+```
+~/.bb/thread-storage/<threadId>/
+  thread-page.html            the page
+  thread-page-assets/          what it shows you
+  thread-page-uploads/         what you attached
+```
+
+The page is a normal file — read it, diff it, keep it. There is no database of
+pages and no separate publish step. Settings hold the instruction text and the
+new-page seed, so you can change what future pages start from without touching
+one that exists.
+
+## Access
+
+Thread Pages needs no port share. Its routes are part of the bb server, so the
+origin that reaches bb reaches your pages, behind the same owner login:
+
+```text
+https://<handle>.getbb.app/api/v1/plugins/thread-pages/http/page?threadId=<id>
+```
+
+`bb thread-page init` prints that absolute URL whenever this bb is connected, and
+a relative path when it is local-only. For private access instead, point
+Tailscale Serve at the whole bb loopback origin — never Funnel it, and never
+wildcard-bind bb.
+
+## Security
+
+The page is generated code, so it is treated as untrusted. It runs in an
+opaque-origin sandbox with no bb cookie, no mutation token, no parent DOM, no
+`localStorage`, no raw bb API, no CLI, no filesystem access, and no ordinary
+network access. Everything it can ask bb to do goes through one validated,
+named capability at a time.
+
+Anything reaching outside the current thread requires a confirmation the page
+cannot fake: the server answers once with a signed challenge carrying **its own**
+summary, the trusted shell shows that summary, and the server re-verifies the
+signature before acting. The challenge is bound to one request, method, parameter
+fingerprint, page revision and thread, and expires in two minutes.
+
+One limitation stated plainly: page JavaScript can navigate its own frame and put
+data in that URL. Browsers cannot prevent this while still allowing page scripts.
+It grants no bb authority, but a page is code you are choosing to run.
+
+## Development
+
+```sh
+npm ci
+bb plugin types --check .
+npm test
+npm run typecheck
+npm run build
+bb plugin reload thread-pages
+```
+
+93 tests cover the capability contract, token scope and tampering, HTML parsing
+against adversarial documents, sandbox and CSP invariants, forms, uploads,
+confined assets, the home page, and the confirmation flow against forgery,
+replay and parameter-swapping.
+
+## Licence
+
+MIT