feat: web-actor architecture, plus actor_list and message_actor oneShot

The main agent becomes an orchestrator that delegates each environment
(WebVM, notebook, app, open web) to a per-environment sub-agent (an actor)
holding only that environment's tools. One delegation channel,
message_actor; the web actor is the single entry point for all web work.

Three things get better:
- Less context on the main agent: per-environment detail loads only on
  delegation, and the redundant web tools collapse into the web actor.
- Fewer tool calls: actor_list replaces five list tools, and message_actor
  oneShot drops a model turn on single-round delegations.
- Real isolation: the environment tools are off the main agent entirely,
  and untrusted page/VM/fetch output reaches the orchestrator only as a
  fenced reply.

Delegations run async and in parallel, show as inline cards you can stop,
report their cost, and survive a service-worker restart via a durable
inbox. Also lands the staged open-PR backlog (PDF reading, on-device OCR,
browser-native VM networking, session auto-resume, whole-extension type
coverage) and bumps the version to 0.2.0. See CHANGELOG.md [0.2.0].

Author: NotASithLord

CHANGELOG.md

@@ -10,10 +10,57 @@ storage formats may move until the surface stabilizes.
 
 ## [Unreleased]
 
-The staged integration of the open-PR backlog onto one verified branch
-(the next milestone). Highlights:
+_Nothing yet._
+
+---
+
+## [0.2.0] — 2026-06-29
+
+The big change is how peerd's agent is structured, landing with the
+staged backlog of open PRs on one verified branch. Three things get
+better:
+
+- **Less context on the main agent.** Each environment's operating
+  details (VM shell quirks, notebook isolation rules, app iframe gotchas,
+  whether to fetch or render a page) used to sit in the main prompt on
+  every turn, mostly unused. Now they live with the sub-agent that uses
+  them and load only when work is handed off. The main agent also drops
+  the web tools it no longer needs: web_search, read_article, call_api,
+  and submit_form all fold into the web actor.
+- **Fewer tool calls.** actor_list replaces five separate list tools with
+  one, so the agent makes one call and carries one list instead of five.
+  message_actor's oneShot skips a whole model turn when one round of work
+  is enough.
+- **Real isolation, not just convention.** The tools that operate
+  environments are no longer on the main agent at all, so even a confused
+  or prompt-injected agent can't reach them; it has to send a
+  permission-gated message. Page text, fetch bodies, and command output
+  stay inside the sub-agent and come back as a quoted, untrusted reply,
+  never as raw text the agent could be steered by.
 
 ### Added
+- **The actor architecture** (DESIGN-17 / DESIGN-18). The main agent now
+  acts as an orchestrator. It opens an environment (a WebVM, a notebook, a
+  built app, or the open web) and hands the work to that environment's own
+  sub-agent, called an actor, which holds only that environment's tools.
+  There is one way to delegate, message_actor. The web actor is the single
+  entry point for all web work and picks per task between a sessionless
+  fetch (fetch_url) and driving a real tab. Delegations run in the
+  background and in parallel, show up as cards in the chat you can watch
+  and stop, report their own cost, and survive a service-worker restart
+  because pending work is written to storage.
+- **API integrations (origin actors).** Send a message to a bare origin
+  like api.github.com and peerd forms a fetch-only, keyless,
+  origin-locked actor for it that remembers what it learns about that API
+  across messages.
+- **actor_list.** One tool that lists everything you can message: every
+  WebVM, notebook, app, open tab, and API integration, each with its type
+  and the handle to pass to message_actor. Replaces five separate list
+  tools.
+- **message_actor oneShot.** Set it when one round of work settles the
+  request, like a specific command or a read. The actor does the action
+  and hands back the raw result instead of spending an extra model turn to
+  restate it.
 - **PDF reading** (`read_pdf`) — pdf.js text-layer extraction in the
   offscreen document for born-digital PDFs; runner-only, output wrapped
   as untrusted web content.
@@ -32,6 +79,17 @@ The staged integration of the open-PR backlog onto one verified branch
   into the WebVM bridge.
 
 ### Changed
+- The main agent's browser tools are now just actor_list, open_tab, and
+  message_actor (plus capture). The low-level page tools and the tools
+  that write to an environment moved to the actors.
+- WebVM self-heal. When the browser freezes a backgrounded VM tab, peerd
+  now checks it and reloads it before a command lands on a dead shell. The
+  terminal output stripping was also fixed so output is not eaten when it
+  splits across a chunk.
+- The thinking and boot spinner is now the brand orb ring, one rainbow
+  sweep masked to a hollow ring.
+- The prose docs were removed. The code is the spec, and CLAUDE.md is the
+  short orientation map.
 - Service worker restructured into per-route modules with injected
   per-module state stores; handlers stay thin.
 - README reordered to lead with install + project conventions; Tesseract

README.md

@@ -39,9 +39,14 @@ peerd uses *the browser* as its runtime and its security model. It builds
 on decades of hardened browser platform work (V8 isolates for sandboxing,
 WebCrypto for the vault, WebAuthn passkeys to unlock it, opaque-origin
 iframes, Subresource Integrity) and writes none of its own cryptographic
-or process-isolation code. The agent that holds your keys never reads a
-raw page; a disposable runner with no keys and no network does, and its
-output comes back fenced as untrusted. Every action the agent drives is
+or process-isolation code. The agent that holds your keys never operates
+an environment itself: each browser tab, VM, notebook, and app is driven
+by its own keyless actor sub-agent that exclusively holds that
+environment's tools. The main agent acts as an orchestrator. It delegates
+a goal to an actor and gets back a summary fenced as untrusted, so raw
+page text and command output never reach the context that holds your
+keys, and a confused or prompt-injected main agent has no tool to touch
+an environment with in the first place. Every action an actor drives is
 verified against the live page before it counts as done. (More at
 [peerd.ai](https://peerd.ai).)
 
@@ -214,7 +219,7 @@ works today, its public API, known limitations, and TODOs:
 | **`p`** · cyan | [`peerd-provider`](extension/peerd-provider/README.md) | Model adapters — Anthropic, OpenRouter, Ollama (streaming, caching, cost, retries) |
 | **`e`** · red | [`peerd-egress`](extension/peerd-egress/README.md) | Security — the vault, the egress chokepoint, the denylist, the audit log |
 | **`e`** · amber | [`peerd-engine`](extension/peerd-engine/README.md) | Sandboxes — WebVMs, Notebooks, Apps, and the headless worker |
-| **`r`** · green | [`peerd-runtime`](extension/peerd-runtime/README.md) | The agent — loop, tools, do/get/check, memory, skills, review, goal mode, voice |
+| **`r`** · green | [`peerd-runtime`](extension/peerd-runtime/README.md) | The orchestrator — agent loop, tools, the `message_actor` delegation channel, actors, sessions, memory, skills, review, goal mode, voice |
 | **`d`** · magenta | [`peerd-distributed`](extension/peerd-distributed/README.md) | The dweb — the peer-to-peer network (preview channel only) |
 
 The brand IS the architecture: cross-module imports go through each
@@ -227,15 +232,24 @@ module's `index.js`, never deep paths; nothing outside
 peerd's safety is *who is allowed to do what*: small boundaries
 enforced by the browser platform, not by peerd's own crypto. Two
 principles run through all of it: **the agent that holds your keys never
-touches a raw page or runs untrusted code**, and **the agent never gets the
-final word on correctness; every action is verified against the live page
-before it counts as done.**
+touches a raw page or runs untrusted code** — the environment-operating
+tools are not even attached to it, they belong to per-environment actor
+sub-agents — and **the agent never gets the final word on correctness;
+every action is verified against the live page before it counts as done.**
+
+The orchestrator delegates; an actor does the work. Each tab, VM,
+notebook, and app is owned by one actor that holds only that
+environment's tools, runs without keys, and hands back a fenced summary.
+So isolation between environments is structural, not a convention: even a
+fully prompt-injected main agent cannot reach an environment it was not
+asked to, because it never held the tool.
 
 | Actor | Trusted with | Never |
 |---|---|---|
 | **The vault** (`peerd-egress/vault`) | your API keys + secrets, decrypted only after Touch ID / passkey / passphrase unlock; idle auto-lock | leaving the device — keys go only to the provider you chose |
-| **The main agent** (`peerd-runtime/loop`) | the conversation, planning, tool dispatch | reading raw page bytes or running untrusted code directly |
-| **The disposable runner** (`peerd-runtime/runner`) | driving + reading the page via do/get/check | holding keys or its own network; its output returns `wrapUntrusted`-fenced |
+| **The orchestrator** (`peerd-runtime/loop`) | the conversation, planning, delegating a goal to an actor via `message_actor` | holding any environment's tools, reading raw page bytes, or running untrusted code directly |
+| **An actor** (`peerd-runtime/subagent`) | driving ONE tab / VM / notebook / app — it exclusively holds that environment's tools, keyless | touching another environment, holding keys, or returning anything to the orchestrator except a `wrapUntrusted`-fenced summary |
+| **The disposable runner** (`peerd-runtime/runner`) | driving + reading a page keyless via do/get/check — the lineage a web actor and subagents use | holding keys or its own network; its output returns `wrapUntrusted`-fenced |
 | **The egress chokepoint** (`safeFetch` / `webFetch`) | every outbound byte — provider allowlist + denylist + SSRF guard | being bypassed; a bare `fetch` is lint-forbidden |
 | **The sandboxes** (WebVM · Notebook · App) | running code — V8 isolates + opaque-origin iframes | extension access; their HTTP routes back through egress |
 | **Web content** | nothing by default | being trusted — all of it is fenced as untrusted input |
@@ -306,14 +320,20 @@ see, focus, and close, grouped under "peerd" in the tab strip and
 surviving browser restarts: the WebVM, the Notebook, and the App. The
 fourth, the headless worker (`js_run`), runs the Notebook's sealed worker
 offscreen with no tab: ephemeral, for the agent's own quick compute. The
-agent picks the lightest kind that fits the task.
+orchestrator picks the lightest kind that fits the task, bootstraps the
+instance, and then delegates the work to that instance's actor; the
+tool lists below are the surface an actor drives, not the main agent. One
+main-agent tool spans all of them: **`actor_list`** enumerates every
+addressable actor — WebVMs, Notebooks, Apps, open tabs, and API
+integrations — each tagged with its `type` and the handle to pass to
+`message_actor`, so discovery is one call instead of five.
 
 **WebVM**: CheerpX-emulated Debian (sandboxed Linux). Own disk (IDB
 overlay), own bash, own POSIX. ~10s first boot. Use it when you need
 real binaries, a shell, or multi-language stacks.
 
 ```
-vm_list   vm_create   vm_boot   vm_import   vm_write_file   vm_delete
+vm_create   vm_boot   vm_import   vm_write_file   vm_delete
 ```
 
 HTTP egress from the VM (curl / wget / git clone) is intercepted by
@@ -328,7 +348,7 @@ worker's only network, routed through `peerd-egress` so it's honest. Each
 `peerd.self.writeFile`/`readFile` to the OPFS file tree.
 
 ```
-js_list   js_create   js_notebook   js_run   js_write_file   js_read_file   js_delete
+js_create   js_notebook   js_run   js_write_file   js_read_file   js_delete
 ```
 
 **Headless worker** is the same sealed worker as a Notebook, but headless:
@@ -344,7 +364,7 @@ search across name, tags, and body. `app_update` auto-reloads the open
 tab so iterations show live.
 
 ```
-app_list   app_create   app_update   app_open   app_search   app_delete
+app_create   app_update   app_open   app_search   app_delete
 ```
 
 ## Tests

docs/DECISIONS.md

@@ -624,3 +624,38 @@ This is the **first** non-`self` `peerd.*` capability wired for Apps;
 `egress` goes first because its blast radius is the most contained of the
 five modules, and the grant/quota machinery built here is the template the
 others inherit (#21).
+
+## 28. An actor is a per-instance agent; the binding is a routing pointer, not an owner gate
+
+DESIGN-17 P0 (`docs/specs/DESIGN-17-actor-agents.md` + `DESIGN-17-DEV-NOTES.md`).
+Three structural choices worth recording:
+
+**A third `SessionKind`, `actor`.** Each tab-hosted instance (WebVM /
+Notebook / App) is owned by one agent — an actor — that exclusively holds
+that environment's MUTATING tools and is addressed only by `message_actor`.
+The per-environment tooling LEAVES the main agent (context optimized, and
+non-eroding because it never returns), and "who may touch this instance" becomes
+STRUCTURAL instead of a convention. An actor is "a session with parentage"
+(the subagent precedent, #SUBAGENTS) — no new shape, just `kind:'actor'` +
+two binding fields. Hidden from `/chats` (reached via its instance, not the
+chat list), like a subagent.
+
+**The capability tier is a dispatch-gate refusal, not descriptor hygiene.** The
+exposure axis is binary `main`/not-`main` and cannot keep instance tools off a
+*subagent*, so a deny-set alone is bypassable by a one-line
+`spawn_subagent({tools:['app_delete']})`. The wall is `exposureGate`: the
+mutating tier is refused for every ctx whose marker isn't `actor`, and an
+actor is positively scoped to its own kind + pinned to its own instance.
+Only MUTATION is tiered — reads stay global and id-addressable.
+
+**The instance→actor binding is a ROUTING pointer (`actorSessionId`), not
+a per-call owner gate.** A `session === record.owner` check on every mutation
+carries transfer-on-settle and brick-the-instance failure modes; the routing
+pointer is one-directional addressing — mutation is gated by the capability
+tier, not the pointer — so if the actor session is gone, mint a fresh one and
+the instance is never bricked. Minting is lazy (the first `message_actor`).
+
+The actor structure is the foundation for later per-tab JS-safety isolation
+(relocate only the inner loop into a per-tab worker — the wrapper stays SW-side),
+purpose-tuned per-actor model tiers, an in-browser actor mesh, and A2A across
+peers — but P0 is the structure + its security, behind a flag, attended-only.