npm - @unifedev/thread-pages - Versions diffs - 0.3.2 → 1.1.0 - Mend

@unifedev/thread-pages 0.3.2 → 1.1.0

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 (95) hide show

package/README.md +77 -129
package/dist/server.js +11779 -11801
package/dist/server.meta.json +2 -2
package/docs/B1-OWN-FILES.md +133 -0
package/docs/FOR-PAGE-AUTHORS-1.1.md +167 -0
package/docs/UPGRADING.md +53 -0
package/package.json +26 -18
package/server.ts +3 -2175
package/src/agent/cli.ts +193 -0
package/src/agent/guide.ts +450 -0
package/src/agent/instruction.ts +59 -0
package/src/agent/seed/seed.ts +73 -0
package/{theme.ts → src/agent/seed/theme-css.ts} +9 -11
package/src/agent/starter-hub.ts +217 -0
package/src/bb/activity.ts +59 -0
package/src/bb/bb-host.ts +280 -0
package/src/bb/public-origin.ts +45 -0
package/src/config/settings.ts +82 -0
package/src/domain/capabilities/contract.ts +48 -0
package/src/domain/capabilities/index.ts +10 -0
package/src/domain/capabilities/protocol.ts +113 -0
package/src/domain/capabilities/registry.ts +48 -0
package/src/domain/capabilities/renamed.ts +34 -0
package/src/domain/capabilities/schema.ts +198 -0
package/src/domain/capabilities/specs.ts +479 -0
package/src/domain/eligibility.ts +43 -0
package/src/domain/errors.ts +116 -0
package/src/domain/html/document.ts +109 -0
package/src/domain/html/escape.ts +16 -0
package/src/domain/ids.ts +37 -0
package/src/domain/json/canonical.ts +19 -0
package/src/domain/json/strict-json.ts +139 -0
package/src/domain/limits.ts +98 -0
package/src/domain/rate-limit.ts +64 -0
package/src/domain/revision.ts +27 -0
package/src/domain/submissions/idempotency.ts +59 -0
package/src/domain/submissions/message.ts +42 -0
package/src/domain/submissions/parse.ts +105 -0
package/src/domain/tokens/action-token.ts +52 -0
package/src/domain/tokens/confirmation.ts +99 -0
package/src/domain/tokens/mac.ts +50 -0
package/src/generated/kernel-runtime.ts +3 -0
package/src/generated/shell-runtime.ts +3 -0
package/src/host/contract.ts +65 -0
package/src/host/types.ts +89 -0
package/src/pages/inline.ts +277 -0
package/src/pages/layout.ts +65 -0
package/src/pages/page-store.ts +170 -0
package/src/pages/site.ts +36 -0
package/src/plugin.ts +81 -0
package/src/runtime/kernel/anchors.ts +45 -0
package/src/runtime/kernel/api.ts +15 -0
package/src/runtime/kernel/bridge-client.ts +148 -0
package/src/runtime/kernel/dirty.ts +51 -0
package/src/runtime/kernel/forms.ts +114 -0
package/src/runtime/kernel/install.ts +156 -0
package/src/runtime/kernel/labels.ts +98 -0
package/src/runtime/kernel/main.ts +6 -0
package/src/runtime/kernel/readonly.ts +75 -0
package/src/runtime/shared/protocol.ts +125 -0
package/src/runtime/shell/confirm.ts +70 -0
package/src/runtime/shell/install.ts +79 -0
package/src/runtime/shell/main.ts +12 -0
package/src/runtime/shell/navigate.ts +64 -0
package/src/runtime/shell/poll.ts +125 -0
package/src/runtime/shell/relay.ts +185 -0
package/src/serving/action-request.ts +32 -0
package/src/serving/bridge/dispatcher.ts +112 -0
package/src/serving/bridge/handler.ts +37 -0
package/src/serving/bridge/handlers/index.ts +26 -0
package/src/serving/bridge/handlers/navigation.ts +43 -0
package/src/serving/bridge/handlers/reads.ts +186 -0
package/src/serving/bridge/handlers/writes.ts +175 -0
package/src/serving/bridge/selection-store.ts +58 -0
package/src/serving/bridge-route.ts +23 -0
package/src/serving/context.ts +34 -0
package/src/serving/document-route.ts +37 -0
package/src/serving/home-route.ts +23 -0
package/src/serving/responses.ts +81 -0
package/src/serving/routes.ts +26 -0
package/src/serving/session-access.ts +22 -0
package/src/serving/shell-html.ts +77 -0
package/src/serving/shell-route.ts +51 -0
package/src/serving/signing-key.ts +25 -0
package/src/serving/submit-route.ts +47 -0
package/src/serving/upload-route.ts +46 -0
package/tsconfig.json +10 -6
package/ARCHITECTURE.md +0 -230
package/PLUGIN_OVERVIEW.md +0 -83
package/authoring.ts +0 -368
package/bridge.ts +0 -1721
package/docs/MODEL.md +0 -211
package/docs/ROADMAP.md +0 -96
package/home.ts +0 -419
package/page.ts +0 -782

package/src/agent/instruction.ts ADDED Viewed

@@ -0,0 +1,59 @@
+/**
+ * The standing instruction, injected into eligible new sessions when the
+ * `agentInstructions` setting is on. It is paid for by every session, so it
+ * holds only what changes behaviour; the host truncates instructions at
+ * 4096 characters, so it must stay under that. spec R6.14–R6.17
+ */
+export const DEFAULT_AGENT_INSTRUCTION = `# The page is the conversation
+The reader does not read chat. Every turn you write or update one HTML page;
+they read it and answer from inside it, and the answer arrives as your next
+message. Chat carries the link and one line. A page they cannot answer from is
+a dead end.
+Start every turn with \`bb thread-page init\`. It prints the page path and the
+link. Read an existing page before editing it; saving publishes it at once and
+an open page reloads itself. If init says SKIP, this session is a helper:
+answer in chat and stay off the page.
+## Every page ends with a way to answer
+Any <form> is wired automatically; nothing is required and blank is a real
+answer. Plain semantic HTML is already styled: <fieldset><legend> names a
+group, a wrapping <label> names one control, <small> is a hint, several
+<button name value> give one-click answers.
+Asking well is most of the work: buttons and radios for decisions, checkboxes
+for multi-select, free text only where the answer is genuinely open. A scale
+needs a meaning at both ends, never a bare 1-to-5. Always leave one open field
+for what you failed to anticipate: a form that permits only the answers you
+expect takes the decision away from the reader.
+## What belongs on the page
+What you did, at the level they could explain to someone else; decisions that
+are theirs, with the options and your recommendation; what only they can
+supply; anything a wrong assumption of yours would make costly. Report
+failures, skipped steps and your own mistakes plainly. Conclusion first.
+## One agent, one page
+Your page is yours alone: you never read or write another agent's page. To
+create another interface — a dashboard, a console, a second view — start a
+session with instructions to build it; that agent writes its own page. Link to
+it, or suggest making it home. A page that should stay put is one whose forms
+start fresh sessions instead of messaging you: nothing then asks you to
+rewrite it. If you want another agent's page changed, talk to that agent.
+## The home page
+One page is home; every other page links back to it in chrome you never
+write. init says whether one exists. When the reader asks for one place to
+see and steer their sessions, build it in a session dedicated to it: run
+\`bb thread-page home\` there and follow \`bb thread-page guide\` §The home page.
+## More
+A page that needs more than prose and a form — files beside it, a chart, live
+session state, starting or steering sessions, links — runs
+\`bb thread-page guide\` first.`;

package/src/agent/seed/seed.ts ADDED Viewed

@@ -0,0 +1,73 @@
+import { escapeHtml } from "../../domain/html/escape.ts";
+import { THEME_CSS } from "./theme-css.ts";
+/**
+ * The document a new page starts from: complete, valid, with a working
+ * captured form, its own stylesheet, and a short comment stating the
+ * conventions while the agent is already reading the file. spec R6.18–R6.23
+ */
+export const DEFAULT_PAGE_SEED = `<!doctype html>
+<html lang="en" data-theme="volume" data-mode="system" data-atmos="on">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+  <title>{{TITLE}}</title>
+  <style>${THEME_CSS}</style>
+</head>
+<body>
+  <div class="atmosphere" aria-hidden="true"></div>
+  <div class="wrap">
+  <header class="brief-head">
+    <h1>{{TITLE}}</h1>
+    <p class="brief-meta"><span>{{DATE}}</span></p>
+  </header>
+  <!--
+    Everything below is yours: this whole file, including the stylesheet in
+    the head. Rewrite it however the task needs. Two things the file cannot
+    tell you, because they are behaviour rather than markup:
+    1. Every form element in this document is captured and delivered to this
+       session as a message. That includes a dialog form you only meant as a
+       local confirm; put data-thread-page-manual on any form that is not
+       meant to answer. Nothing is required and blank is a real answer.
+    2. window.prompt, alert, confirm and window.open do nothing here — the
+       sandbox silences them. Build the input into the page instead.
+    The look is three attributes on the html element. data-theme: paper,
+    terminal, atrium, volume or bloom. data-mode: system, light or dark.
+    data-atmos: on or off.
+    If this page should stay put — a dashboard, a console, a page nobody
+    should have to rewrite — delete the reply form below and let its buttons
+    start fresh sessions instead. See the guide.
+    Everything else — files beside this one, charts, live session state,
+    starting sessions, links, limits — is in: bb thread-page guide
+    This comment deliberately names no HTML tags. An earlier version spelled
+    them out, and every agent that edited its page by string surgery found
+    tags here that were not in the document. Keep it that way.
+  -->
+  <main>
+    <p>Replace this with what changed and what you need from the reader.</p>
+    <form data-title="{{TITLE}}">
+      <label>Reply
+        <textarea name="reply" rows="4"></textarea>
+      </label>
+      <button name="action" value="Reply">Reply</button>
+    </form>
+  </main>
+  </div>
+</body>
+</html>
+`;
+/** Applies the seed's substitutions; both are escaped. spec R6.21 */
+export function renderSeed(template: string, title: string, now: Date = new Date()): string {
+  const date = now.toLocaleDateString("en-GB", { day: "numeric", month: "long", year: "numeric" });
+  return template.replaceAll("{{TITLE}}", escapeHtml(title)).replaceAll("{{DATE}}", escapeHtml(date));
+}

package/{theme.ts → src/agent/seed/theme-css.ts} RENAMED Viewed

@@ -1,15 +1,8 @@
 /**
- * The Thread Pages design system.
- *
- * Five worlds, each declaring both palettes at once as --l-* and --d-*, 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> and needs no class names: every
- * rule keys off semantic structure (fieldset/legend, a wrapping label, small,
- * button), so plain HTML is already styled.
- *
- * This is carried into each new page by the seed rather than injected at render
- * time, so a page owns its own look and a plugin update never restyles work the
- * user already read.
+ * The design system carried by the default seed: five worlds, each with a
+ * light and a dark palette, keyed off semantic HTML. Reviewed from the
+ * prototype, not redesigned (RW-16). A page owns its copy and may change
+ * any rule. spec R4.36, R4.37
  */
 export const THEME_CSS = String.raw`
   :root {
@@ -44,6 +37,11 @@ export const THEME_CSS = String.raw`
   *, *::before, *::after { box-sizing: border-box; }
+  /* A class rule that sets display outranks the user-agent rule for the
+     hidden attribute, so a page that styles .banner with display:flex would
+     render a hidden banner as an empty bar. This keeps hidden meaning hidden. */
+  [hidden] { display: none !important; }
   html { -webkit-text-size-adjust: 100%; }
   body {

package/src/agent/starter-hub.ts ADDED Viewed

@@ -0,0 +1,217 @@
+/**
+ * The starter home page: the `<main>` an agent drops into its page to get a
+ * working session hub. It is the guide's worked example (§The home page) and
+ * the shape a person gets when they ask for a home page.
+ *
+ * Design: dense and attention-first. A sticky bar with search and a view
+ * toggle; projects that need the reader first; per project the sessions that
+ * need attention plus the five most recent, with "Show 10 more" — the same
+ * rule the host's own sidebar uses; one line per session with the state, the
+ * title (opens the page, or the session in bb when there is no page), how
+ * long ago, and the actions that matter: bb, Stop, Archive.
+ */
+export const STARTER_HUB_MAIN = String.raw`<div class="hub-bar">
+  <input type="search" data-search placeholder="Find a session…  (press /)" aria-label="Find a session" autocomplete="off">
+  <span class="hub-views" role="group" aria-label="View">
+    <button type="button" data-view="attention" aria-pressed="true">Needs you</button>
+    <button type="button" data-view="all" aria-pressed="false">All</button>
+  </span>
+  <button type="button" data-refresh title="Refresh">↻</button>
+  <span class="hub-meta" data-meta></span>
+</div>
+<p data-error class="needs-you" hidden></p>
+<div data-groups aria-live="polite"></div>
+<p class="hub-foot">Rows follow bb: no archived sessions, sub-agents hidden, five per project then “more”. This page belongs to the session that built it; ask that session to change it.</p>
+<style>
+/* The hub is a list, so it takes the width the seed's prose does not need. */
+.wrap { max-width: 68rem; }
+@scope (main) {
+  .hub-bar { position: sticky; top: 0; z-index: 1; display: flex; flex-wrap: wrap; gap: .5rem; align-items: center; padding: .6rem 0; background: var(--bg); border-bottom: var(--rule-w) solid var(--rule); }
+  .hub-bar input[type="search"] { flex: 1 1 16rem; min-width: 0; margin: 0; padding: .45rem .6rem; font: inherit; font-size: .92rem; color: var(--ink); background: var(--surface); border: var(--rule-w) solid var(--rule); border-radius: calc(var(--radius) * .7); }
+  .hub-views { display: inline-flex; border: var(--rule-w) solid var(--rule); border-radius: calc(var(--radius) * .7); overflow: hidden; }
+  .hub-views button, .hub-bar > button { margin: 0; padding: .4rem .7rem; font: inherit; font-size: .85rem; font-weight: 600; color: var(--ink-2); background: var(--surface); border: 0; border-radius: 0; box-shadow: none; cursor: pointer; }
+  .hub-views button[aria-pressed="true"] { color: var(--bg); background: var(--accent); }
+  .hub-bar > button[data-refresh] { border: var(--rule-w) solid var(--rule); border-radius: calc(var(--radius) * .7); }
+  .hub-meta { margin-left: auto; font-size: .78rem; color: var(--ink-3); font-variant-numeric: tabular-nums; }
+  .group { margin-top: 1rem; }
+  .group-head { display: flex; align-items: baseline; gap: .6rem; padding: .3rem 0; border-bottom: var(--rule-w) solid var(--rule-soft); }
+  .group-head h2 { margin: 0; font-size: .95rem; cursor: pointer; }
+  .group-head .counts { font-size: .75rem; color: var(--ink-3); font-variant-numeric: tabular-nums; }
+  .group-head .counts b { color: var(--ok); font-weight: 600; }
+  .group-head .counts i { color: var(--accent); font-style: normal; font-weight: 600; }
+  .group-head .counts s { color: var(--flag); text-decoration: none; font-weight: 600; }
+  .group-head button { margin: 0 0 0 auto; padding: .15rem .55rem; font: inherit; font-size: .78rem; font-weight: 600; color: var(--accent); background: transparent; border: var(--rule-w) solid var(--rule); border-radius: calc(var(--radius) * .6); box-shadow: none; cursor: pointer; }
+  .row { display: grid; grid-template-columns: .6rem minmax(0, 1fr) auto auto; gap: .6rem; align-items: center; min-height: 2.1rem; padding: .1rem 0; border-bottom: var(--rule-w) solid var(--rule-soft); }
+  .row .dot { width: .55rem; height: .55rem; border-radius: 50%; background: var(--rule); }
+  .row[data-status="working"] .dot { background: var(--ok); }
+  .row[data-status="waiting"] .dot { background: var(--flag); }
+  .row[data-status="failed"] .dot { background: var(--flag); box-shadow: 0 0 0 2px color-mix(in srgb, var(--flag) 35%, transparent); }
+  .row[data-unread="true"] .dot { outline: 2px solid var(--accent); outline-offset: 1px; }
+  @media (prefers-reduced-motion: no-preference) { .row[data-status="working"] .dot { animation: hub-pulse 1.4s ease-in-out infinite; } }
+  @keyframes hub-pulse { 0%, 100% { opacity: 1 } 50% { opacity: .3 } }
+  .row .title { margin: 0; padding: .2rem 0; font: inherit; font-size: .92rem; text-align: left; color: var(--ink); background: transparent; border: 0; border-radius: 0; box-shadow: none; cursor: pointer; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .row[data-unread="true"] .title { font-weight: 700; }
+  .row .title:hover, .row .title:focus-visible { color: var(--accent); }
+  .row .when { font-size: .75rem; color: var(--ink-3); font-variant-numeric: tabular-nums; white-space: nowrap; }
+  .row .when em { font-style: normal; color: var(--flag); }
+  .row .acts { display: flex; gap: .3rem; }
+  .row .acts button { margin: 0; padding: .1rem .5rem; font: inherit; font-size: .75rem; font-weight: 600; color: var(--ink-2); background: transparent; border: var(--rule-w) solid var(--rule); border-radius: calc(var(--radius) * .6); box-shadow: none; cursor: pointer; }
+  .row .acts button:hover:not(:disabled) { color: var(--accent); border-color: var(--accent); }
+  .row .acts button[data-danger]:hover:not(:disabled) { color: var(--flag); border-color: var(--flag); }
+  .more { margin: .3rem 0 0; padding: .2rem 0; font: inherit; font-size: .78rem; color: var(--accent); background: transparent; border: 0; box-shadow: none; cursor: pointer; }
+  .starter { margin: .5rem 0 0; display: grid; gap: .4rem; }
+  .starter textarea { width: 100%; min-height: 3.2rem; margin: 0; padding: .5rem .65rem; font: inherit; font-size: .88rem; line-height: 1.5; color: var(--ink); background: var(--surface); border: var(--rule-w) solid var(--rule); border-radius: calc(var(--radius) * .7); resize: vertical; }
+  .starter textarea:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+  .starter button { justify-self: start; margin: 0; padding: .4rem .9rem; font: inherit; font-size: .85rem; font-weight: 600; color: var(--bg); background: var(--accent); border: var(--rule-w) solid var(--accent); border-radius: calc(var(--radius) * .7); box-shadow: none; cursor: pointer; }
+  .starter button:disabled { opacity: .6; cursor: default; }
+  .starter .say { font-size: .78rem; color: var(--ink-3); }
+  .empty { margin: .6rem 0; font-size: .85rem; color: var(--ink-3); }
+  .hub-foot { margin-top: 1.5rem; font-size: .75rem; color: var(--ink-3); }
+  @media (max-width: 40rem) { .row { grid-template-columns: .6rem minmax(0, 1fr) auto; } .row .when { display: none; } }
+}
+</style>
+<script>
+(async () => {
+  const tp = window.threadPage;
+  const $ = (s) => document.querySelector(s);
+  const groupsEl = $("[data-groups]"), errorEl = $("[data-error]"), metaEl = $("[data-meta]"), searchEl = $("[data-search]");
+  const PER_PROJECT = 5, MORE = 10;
+  const el = (tag, text, cls) => { const n = document.createElement(tag); if (text !== undefined) n.textContent = text; if (cls) n.className = cls; return n; };
+  const fail = (m) => { errorEl.hidden = false; errorEl.textContent = m; };
+  // Needs you: running, waiting on you, or unread — a failed session only until you have looked at it.
+  const needsYou = (s) => s.status === "working" || s.status === "waiting" || s.unread;
+  const recency = (s) => Math.max(s.attentionAtMs || 0, s.updatedAtMs || 0);
+  const ago = (ms) => { const d = Date.now() - ms; if (d < 60e3) return "now"; if (d < 3600e3) return Math.round(d / 60e3) + "m"; if (d < 86400e3) return Math.round(d / 3600e3) + "h"; return Math.round(d / 86400e3) + "d"; };
+  let projects = [], sessions = [], prefs = { view: "attention", collapsed: {} };
+  const expanded = {}, starters = new Set();
+  async function loadPrefs() {
+    try { const r = await tp.invoke("storage.get", { key: "home.prefs" }); if (r.found && r.value && typeof r.value === "object") prefs = { view: "attention", collapsed: {}, ...r.value }; } catch {}
+  }
+  const savePrefs = () => tp.invoke("storage.set", { key: "home.prefs", value: prefs }).catch(() => {});
+  async function fetchAll() {
+    const out = []; let cursor = null;
+    for (let page = 0; page < 5; page += 1) {
+      const r = await tp.invoke("sessions.snapshot", cursor ? { limit: 200, cursor } : { limit: 200 });
+      out.push(...r.sessions); cursor = r.nextCursor; if (!cursor) break;
+    }
+    return out;
+  }
+  function act(label, run, danger) {
+    const b = el("button", label); b.type = "button"; if (danger) b.dataset.danger = "";
+    b.addEventListener("click", async (e) => { e.stopPropagation(); b.disabled = true;
+      try { await run(); } catch (err) { if (err.code !== "cancelled") fail((err.code ? err.code + ": " : "") + err.message); }
+      finally { b.disabled = false; } });
+    return b;
+  }
+  function row(s) {
+    const r = el("div", undefined, "row"); r.dataset.status = s.status; r.dataset.unread = String(!!s.unread);
+    const title = el("button", s.title || "(untitled)", "title"); title.type = "button";
+    title.title = s.page.available ? "Open its page" : "No page yet — opens the session in bb";
+    title.addEventListener("click", () => tp.invoke(s.page.available ? "pages.open" : "sessions.openHost", { sessionId: s.id }).catch((e) => fail(e.message)));
+    const when = el("span", undefined, "when");
+    if (s.status === "failed") when.append(el("em", "failed · ")); else if (s.status === "waiting") when.append(el("em", "needs you · ")); else if (s.status === "working") when.append(el("em", "working · "));
+    when.append(document.createTextNode(ago(recency(s))));
+    const acts = el("span", undefined, "acts");
+    if (s.page.available) acts.append(act("bb", () => tp.invoke("sessions.openHost", { sessionId: s.id })));
+    if (s.status === "working") acts.append(act("Stop", async () => { await tp.invoke("sessions.stop", { sessionId: s.id }); await load(); }, true));
+    acts.append(act(s.unread ? "Read" : "Unread", async () => { const r = await tp.invoke("sessions.markRead", { sessionId: s.id, read: !!s.unread }); s.unread = r.unread; render(); }));
+    acts.append(act("Archive", async () => { await tp.invoke("sessions.archive", { sessionId: s.id }); sessions = sessions.filter((x) => x.id !== s.id); render(); }, true));
+    r.append(el("span", undefined, "dot"), title, when, acts);
+    return r;
+  }
+  function starter(project) {
+    const box = el("div", undefined, "starter");
+    const text = el("textarea"); text.placeholder = "What should the new session in " + project.name + " do? Say what to report and what not to change."; text.setAttribute("aria-label", text.placeholder);
+    const say = el("span", undefined, "say");
+    const go = act("Start session", async () => {
+      const prompt = text.value.trim(); if (!prompt) { say.textContent = "Say what it should do."; return; }
+      say.textContent = "Waiting for your confirmation…";
+      try { await tp.invoke("sessions.start", { projectId: project.id, prompt }); say.textContent = "Started."; text.value = ""; starters.delete(project.id); await load(); }
+      catch (e) { say.textContent = e.code === "cancelled" ? "Nothing started." : e.message; }
+    });
+    box.append(text, go, say);
+    return box;
+  }
+  function render() {
+    const q = searchEl.value.trim().toLowerCase();
+    const view = q ? "all" : prefs.view;
+    groupsEl.textContent = "";
+    let shown = 0, attention = 0;
+    const byProject = new Map(projects.map((p) => [p.id, []]));
+    for (const s of sessions) { if (byProject.has(s.projectId)) byProject.get(s.projectId).push(s); }
+    const order = projects.slice().sort((a, b) => {
+      const A = byProject.get(a.id), B = byProject.get(b.id);
+      const na = A.filter(needsYou).length, nb = B.filter(needsYou).length;
+      if ((na > 0) !== (nb > 0)) return na > 0 ? -1 : 1;
+      return Math.max(0, ...B.map(recency)) - Math.max(0, ...A.map(recency));
+    });
+    for (const project of order) {
+      const all = byProject.get(project.id).sort((a, b) => recency(b) - recency(a));
+      attention += all.filter(needsYou).length;
+      let list = q ? all.filter((s) => (s.title || "").toLowerCase().includes(q) || project.name.toLowerCase().includes(q)) : view === "attention" ? all.filter(needsYou) : all;
+      if (view === "attention" && !q && list.length === 0) continue;
+      const group = el("section", undefined, "group");
+      const head = el("div", undefined, "group-head");
+      const h = el("h2", project.name); h.title = "Collapse or expand";
+      h.addEventListener("click", () => { prefs.collapsed[project.id] = !prefs.collapsed[project.id]; savePrefs(); render(); });
+      const counts = el("span", undefined, "counts");
+      const w = all.filter((s) => s.status === "working").length, u = all.filter((s) => s.unread).length, f = all.filter((s) => s.status === "waiting" || (s.status === "failed" && s.unread)).length;
+      counts.append(document.createTextNode(all.length + " "));
+      if (w) counts.append(el("b", w + " working ")); if (u) counts.append(el("i", u + " unread ")); if (f) counts.append(el("s", f + " need you"));
+      const add = act("+ New", async () => { if (starters.has(project.id)) starters.delete(project.id); else starters.add(project.id); render(); });
+      head.append(h, counts, add);
+      group.append(head);
+      if (!prefs.collapsed[project.id]) {
+        let visible = list;
+        if (view === "all" && !q) { const limit = PER_PROJECT + (expanded[project.id] || 0); visible = list.filter((s, i) => i < limit || needsYou(s)); }
+        for (const s of visible) group.append(row(s));
+        if (visible.length < list.length) { const more = el("button", "Show " + Math.min(MORE, list.length - visible.length) + " more of " + list.length, "more"); more.type = "button"; more.addEventListener("click", () => { expanded[project.id] = (expanded[project.id] || 0) + MORE; render(); }); group.append(more); }
+        if (list.length === 0) group.append(el("p", q ? "No match." : "Nothing here.", "empty"));
+        shown += visible.length;
+      }
+      if (starters.has(project.id)) group.append(starter(project));
+      groupsEl.append(group);
+    }
+    if (!groupsEl.children.length) groupsEl.append(el("p", view === "attention" ? "Nothing needs you right now." : "No sessions.", "empty"));
+    for (const b of document.querySelectorAll("[data-view]")) b.setAttribute("aria-pressed", String(b.dataset.view === prefs.view));
+    metaEl.textContent = shown + " shown · " + attention + " need you · " + sessions.length + " total";
+  }
+  async function load() {
+    try {
+      errorEl.hidden = true;
+      const [p, s] = await Promise.all([tp.invoke("projects.list"), fetchAll()]);
+      projects = p.projects; sessions = s; render();
+    } catch (e) { fail((e.code ? e.code + ": " : "") + e.message); }
+  }
+  for (const b of document.querySelectorAll("[data-view]")) b.addEventListener("click", () => { prefs.view = b.dataset.view; savePrefs(); render(); });
+  $("[data-refresh]").addEventListener("click", () => load());
+  searchEl.addEventListener("input", render);
+  document.addEventListener("keydown", (e) => {
+    if (e.key === "/" && document.activeElement !== searchEl && !/^(INPUT|TEXTAREA)$/.test(document.activeElement?.tagName)) { e.preventDefault(); searchEl.focus(); }
+    if (e.key === "Escape" && document.activeElement === searchEl) { searchEl.value = ""; render(); searchEl.blur(); }
+  });
+  document.addEventListener("visibilitychange", () => { if (document.visibilityState === "visible") load(); });
+  await loadPrefs();
+  await load();
+  tp.watch("session.activity", { limit: 1 }, () => load(), { intervalMs: 15000 });
+})();
+</script>`;
+/** The starter hub indented for a Markdown code block. */
+export function starterHubForGuide(): string {
+  return STARTER_HUB_MAIN.split("\n")
+    .map((line) => (line.length ? `    ${line}` : ""))
+    .join("\n");
+}

package/src/bb/activity.ts ADDED Viewed

@@ -0,0 +1,59 @@
+import type { SessionState } from "../domain/capabilities/specs.ts";
+import type { ActivityItem } from "../host/types.ts";
+/**
+ * bb's thread vocabulary → the product's session state. RW-6
+ *
+ *   active, starting, provisioning, stopping → working
+ *   error                                    → failed
+ *   a pending interaction                    → waiting
+ *   everything else                          → idle
+ */
+export function sessionStateOf(thread: { status?: unknown; runtime?: unknown }, hasPendingInteraction: boolean): SessionState {
+  const runtime = asRecord(thread.runtime);
+  const display = typeof runtime?.displayStatus === "string" ? runtime.displayStatus : typeof thread.status === "string" ? thread.status : "idle";
+  if (["active", "starting", "provisioning", "stopping"].includes(display)) return "working";
+  if (display === "error") return "failed";
+  if (hasPendingInteraction) return "waiting";
+  return "idle";
+}
+const FALLBACK_LABELS: Record<string, readonly [string, string]> = {
+  agentMessage: ["Writing", "Wrote"],
+  reasoning: ["Thinking", "Thought"],
+};
+/** Thread events (`item/started`, `item/completed`) → presented activity, newest last. */
+export function activityItemsOf(events: readonly unknown[], limit: number): ActivityItem[] {
+  const out: ActivityItem[] = [];
+  for (const raw of events) {
+    const event = asRecord(raw);
+    if (!event) continue;
+    if (event.type !== "item/started" && event.type !== "item/completed") continue;
+    const done = event.type === "item/completed";
+    const data = asRecord(event.data);
+    const item = asRecord(data?.item) ?? data;
+    if (!item || typeof item.type !== "string") continue;
+    const presentation = asRecord(item.presentation);
+    const labels = asRecord(presentation?.label);
+    const presented = labels?.[done ? "completed" : "pending"];
+    const fallback = FALLBACK_LABELS[item.type];
+    const label = typeof presented === "string" ? presented : fallback ? fallback[done ? 1 : 0] : null;
+    if (!label) continue;
+    const detail = presentation?.title ?? item.command ?? item.text ?? item.name ?? "";
+    const atMs = typeof event.createdAt === "number" && Number.isFinite(event.createdAt) ? Math.max(0, Math.trunc(event.createdAt)) : 0;
+    out.push({
+      kind: item.type.slice(0, 80),
+      done,
+      atMs,
+      label: label.trim().slice(0, 80) || (done ? "Completed" : "Working"),
+      text: String(detail).replace(/\s+/g, " ").trim().slice(0, 200),
+    });
+  }
+  out.reverse();
+  return out.slice(-limit);
+}
+export function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}