@unifedev/thread-pages 0.3.2 → 1.0.3

package/src/agent/cli.ts

@@ -0,0 +1,193 @@
+import type { BbPluginApi, PluginCliContext, PluginCliResult } from "@get-bb/plugin-sdk";
+import { describeIneligible, ineligibleReason } from "../domain/eligibility.ts";
+import { PageError, errorText } from "../domain/errors.ts";
+import { isSessionId } from "../domain/ids.ts";
+import { LIMITS } from "../domain/limits.ts";
+import type { SessionRecord } from "../host/types.ts";
+import { ENTRY_FILE, LEGACY_ENTRY_FILE, UPLOAD_DIR, entryPath, joinPath, legacyEntryPath } from "../pages/layout.ts";
+import { homeUrl, pageUrl, type ServingContext } from "../serving/context.ts";
+import { renderSeed } from "./seed/seed.ts";
+
+/**
+ * `bb thread-page init | home [--clear] | guide | status`. spec 06 §The command, RW-11
+ */
+export interface CliDeps {
+  serving: ServingContext;
+  guide: string;
+  /** The exact instruction a new eligible session receives now, or null when none would. */
+  effectiveInstruction(): string | null;
+}
+
+export function registerCli(bb: BbPluginApi, deps: CliDeps): void {
+  bb.cli.register({
+    name: "thread-page",
+    summary: "The page this session writes for its reader: create it, print the authoring guide, make it home",
+    commands: [
+      { name: "init", summary: "Create this session's page if absent; print its path and link", usage: "bb thread-page init" },
+      { name: "guide", summary: "Print the authoring guide (forms, files, capabilities, limits)", usage: "bb thread-page guide" },
+      { name: "home", summary: "Make this session's page the home page every page links back to", usage: "bb thread-page home [--clear]" },
+      { name: "status", summary: "Show settings, the instruction new sessions get, and this session's page", usage: "bb thread-page status" },
+    ],
+    async run(argv, context) {
+      const [command, ...rest] = argv;
+      try {
+        switch (command) {
+          case "init":
+            return rest.length === 0 ? await init(deps, context) : usage();
+          case "guide":
+            return rest.length === 0 ? { exitCode: 0, stdout: `${deps.guide}\n` } : usage();
+          case "home":
+            if (rest.length === 0) return await home(deps, context);
+            if (rest.length === 1 && rest[0] === "--clear") return await clearHome(deps);
+            return usage("bb thread-page home [--clear]");
+          case "status":
+            return rest.length === 0 ? await status(deps, context) : usage();
+          default:
+            return usage();
+        }
+      } catch (error) {
+        deps.serving.host.log.warn(`cli ${command ?? ""}: ${errorText(PageError.is(error) ? (error.cause ?? error) : error)}`);
+        return { exitCode: 1, stderr: `Could not run thread-page ${command ?? ""}: ${errorText(error)}\n` };
+      }
+    },
+  });
+}
+
+function usage(text = "bb thread-page <init|guide|home [--clear]|status>"): PluginCliResult {
+  return { exitCode: 2, stderr: `Usage: ${text}\n` };
+}
+
+async function currentSession(deps: CliDeps, context: PluginCliContext): Promise<{ id: string; session: SessionRecord } | { skip: string }> {
+  if (!context.threadId) return { skip: "no current session" };
+  const session = await deps.serving.host.sessions.get(context.threadId);
+  if (!session) return { skip: "the current session does not exist" };
+  const reason = ineligibleReason(session);
+  if (reason) return { skip: describeIneligible(reason) };
+  return { id: session.id, session };
+}
+
+function skipLine(reason: string): PluginCliResult {
+  return { exitCode: 0, stdout: `state: SKIP — ${reason}; this session has no page. Answer normally in chat and do not create one.\n` };
+}
+
+async function link(deps: CliDeps, path: string): Promise<string> {
+  const origin = await deps.serving.host.origin.public();
+  return origin ? `${origin}${path}` : path;
+}
+
+async function ensurePage(deps: CliDeps, id: string, title: string): Promise<{ absolutePath: string; state: "created" | "existing"; legacy: boolean; problem: string | null }> {
+  const { serving } = deps;
+  const location = await serving.host.sessions.storage(id);
+  const seed = renderSeed(serving.settings.current().pageSeedHtml, title);
+  const outcome = await serving.host.files.write(location, ENTRY_FILE, Buffer.from(seed, "utf8"), { onlyIfAbsent: true });
+  const state = outcome === "written" ? "created" : "existing";
+  let problem: string | null = null;
+  if (state === "created") {
+    await serving.pages.remember(id, seed);
+  } else {
+    try {
+      await serving.pages.load(id);
+    } catch (error) {
+      problem = PageError.is(error) ? error.message : errorText(error);
+    }
+  }
+  const legacy = await serving.host.files
+    .exist(location.hostId, [legacyEntryPath(location.rootPath)])
+    .then((existence) => existence[legacyEntryPath(location.rootPath)] === true)
+    .catch(() => false);
+  return { absolutePath: entryPath(location.rootPath), state, legacy, problem };
+}
+
+/** Tells the agent whether the reader has a home page, and how one comes to exist. */
+async function homeLine(deps: CliDeps, current: string): Promise<string> {
+  const home = deps.serving.settings.current().homeSessionId;
+  if (isSessionId(home)) {
+    return home === current
+      ? "home: this page is the home page; every other page links back to it."
+      : `home: ${await link(deps, homeUrl(deps.serving.routeBase))}  (every page links back to it; you never write that link)`;
+  }
+  return "home: none set. If the reader wants one place to see and steer their sessions, run `bb thread-page home` in a session dedicated to it and build the hub from `bb thread-page guide` §The home page.";
+}
+
+async function init(deps: CliDeps, context: PluginCliContext): Promise<PluginCliResult> {
+  const current = await currentSession(deps, context);
+  if ("skip" in current) return skipLine(current.skip);
+  const { absolutePath, state, legacy, problem } = await ensurePage(deps, current.id, current.session.title);
+  const url = await link(deps, pageUrl(deps.serving.routeBase, current.id));
+  const lines = [
+    `page: ${absolutePath}`,
+    `link: [Open the Thread Page](${url})`,
+    state === "created"
+      ? "state: NEW — seeded; make this page fit the task, keep a way to answer, then reply in chat with the link and one line."
+      : "state: EXISTING — read it before editing; update it this turn, keep a way to answer, then reply in chat with the link and one line.",
+    `site: files beside ${ENTRY_FILE} are served relatively (nested paths included); ${UPLOAD_DIR}/ holds what the reader attaches.`,
+    "guide: bb thread-page guide  (files, charts, live session state, starting sessions, links, limits)",
+    await homeLine(deps, current.id),
+  ];
+  if (problem) lines.push(`warning: the existing page cannot be served — ${problem}`);
+  if (legacy) lines.push(`note: a ${LEGACY_ENTRY_FILE} from the previous plugin version is beside it; it is not served. Move what you want from it into ${ENTRY_FILE}.`);
+  return { exitCode: 0, stdout: `${lines.join("\n")}\n` };
+}
+
+async function home(deps: CliDeps, context: PluginCliContext): Promise<PluginCliResult> {
+  const current = await currentSession(deps, context);
+  if ("skip" in current) return { exitCode: 2, stderr: `Cannot make this session home: ${current.skip}. Run it from a visible root session.\n` };
+  const { serving } = deps;
+  const previous = serving.settings.current().homeSessionId;
+  const lines: string[] = [];
+  if (isSessionId(previous) && previous !== current.id) {
+    const other = await serving.host.sessions.get(previous).catch(() => null);
+    lines.push(`warning: home was ${other ? `“${other.title}” (${previous})` : previous}; it now points here instead.`);
+  }
+  const { state } = await ensurePage(deps, current.id, current.session.title);
+  await serving.settings.set({ homeSessionId: current.id });
+  const url = await link(deps, homeUrl(serving.routeBase));
+  lines.push(
+    `home: ${current.id}`,
+    `link: [Sessions](${url})`,
+    "Every other page now shows a “← Sessions” link back to this one.",
+    state === "created"
+      ? "state: NEW — a plain seed was created for this session; build the hub yourself (sessions.snapshot, projects.list, pages.open, sessions.start). See bb thread-page guide §The home page."
+      : "state: EXISTING — this session's page was left untouched.",
+  );
+  return { exitCode: 0, stdout: `${lines.join("\n")}\n` };
+}
+
+async function clearHome(deps: CliDeps): Promise<PluginCliResult> {
+  await deps.serving.settings.set({ homeSessionId: null });
+  return { exitCode: 0, stdout: "home: cleared — pages no longer show a Sessions link.\n" };
+}
+
+async function status(deps: CliDeps, context: PluginCliContext): Promise<PluginCliResult> {
+  const { serving } = deps;
+  const settings = serving.settings.current();
+  const instruction = deps.effectiveInstruction();
+  const lines = [
+    "# Thread Pages status",
+    "",
+    `agentInstructions: ${settings.agentInstructions ? "on" : "off"}`,
+    `workingLabel: ${settings.workingLabel ? JSON.stringify(settings.workingLabel) : "(blank — indicator hidden)"}`,
+    `homeSessionId: ${settings.homeSessionId || "(none — pages show no Sessions link)"}`,
+    `site strategy: ${serving.site.name}`,
+    `limits: entry ${LIMITS.entryDocumentBytes / (1024 * 1024)} MiB, upload ${LIMITS.uploadFileBytes / (1024 * 1024)} MiB × ${LIMITS.uploadsPerForm}, rate ${LIMITS.ratePerMinute}/min`,
+    "",
+    "## Instruction a new eligible session receives now",
+    "",
+    instruction ?? "(none — agentInstructions is off)",
+  ];
+  const current = await currentSession(deps, context);
+  lines.push("", "## This session");
+  if ("skip" in current) {
+    lines.push(`no page: ${current.skip}`);
+  } else {
+    const location = await serving.host.sessions.storage(current.id);
+    lines.push(`page: ${joinPath(location.rootPath, ENTRY_FILE)}`, `link: ${await link(deps, pageUrl(serving.routeBase, current.id))}`);
+    try {
+      const page = await serving.pages.load(current.id);
+      lines.push(`revision: ${page.revision}${page.stale ? " (offline copy)" : ""}`);
+    } catch (error) {
+      lines.push(`revision: ${PageError.is(error) ? error.message : errorText(error)}`);
+    }
+  }
+  return { exitCode: 0, stdout: `${lines.join("\n")}\n` };
+}

package/src/agent/guide.ts

@@ -0,0 +1,355 @@
+import type { CapabilityRegistry } from "../domain/capabilities/registry.ts";
+import { LIMITS, kibibytes, mebibytes } from "../domain/limits.ts";
+import { ENTRY_FILE, UPLOAD_DIR } from "../pages/layout.ts";
+import type { SiteStrategy } from "../pages/site.ts";
+import { starterHubForGuide } from "./starter-hub.ts";
+
+/**
+ * The authoring guide, printed by `bb thread-page guide`. Assembled from
+ * prose, the limits table and the capability registry at load, so every
+ * number and every capability in it is the implementation's own.
+ * spec R6.24–R6.26
+ */
+export function buildGuide(registry: CapabilityRegistry, site: SiteStrategy): string {
+  return [
+    intro(),
+    plainHtml(),
+    forms(),
+    uploads(),
+    ownFiles(site),
+    runtimeApi(),
+    capabilities(registry),
+    startingSessions(),
+    network(),
+    unavailable(),
+    composition(),
+    home(),
+    accessibility(),
+    limits(),
+    limitations(site),
+  ].join("\n\n");
+}
+
+const intro = () => `# Thread Pages — authoring guide
+
+A page is a complete HTML document you edit directly; saving publishes it. It
+runs in a sandboxed frame on an opaque origin with no host credentials, and
+talks to the host only through captured forms and \`window.threadPage\`. Use
+the smallest shape that makes the task easier: plain semantic HTML first, a
+mini-app only when the shape of the thing is not prose.
+
+Your page root is your session's storage directory (\`$BB_THREAD_STORAGE\`):
+
+    ${ENTRY_FILE}       the entry document — the page
+    <any files>      served beside it, nested directories included
+    ${UPLOAD_DIR}/         files the reader attached, named by the host`;
+
+const plainHtml = () => `## What plain HTML already gives you
+
+The seed carries its own stylesheet, so semantic HTML is already styled.
+
+    h2, p, ul, table      the page's type scale and rhythm
+    form                  a panel wired to your session, with a status line
+    fieldset + legend     a named group; the legend becomes the question
+    label wrapping one    the label becomes that answer's name
+    small inside a label  a hint (never part of the answer's name)
+    input type=range      a slider with a live value readout
+    input type=file       uploaded on submit, path sent to you
+    details/summary       detail on demand; add name="x" for an accordion
+    div.card              a boxed aside
+    p.needs-you           a flagged block, for what is blocked on the reader
+    span.label            a small uppercase tag
+
+Three class names; everything else keys off what the element is. The look is
+three attributes on <html>: data-theme (paper | terminal | atrium | volume |
+bloom), data-mode (system | light | dark), data-atmos (on | off). Extra CSS
+goes in one more <style>, everything inside @scope (main), colour and shape
+from var(--token) only — that is what keeps a bespoke chart right in every
+world and in dark mode. You may replace the stylesheet entirely; the page is
+yours.`;
+
+const forms = () => `## Forms
+
+Every <form> in the document is captured and delivered to your session as a
+message — no JavaScript needed. Add data-thread-page-manual to a form your
+own script owns; the host then leaves it entirely alone.
+
+- Nothing is required and blank is a real answer: native validation is
+  suppressed, and a blank field arrives as "(left blank)".
+- Answer names come from, in order: data-label on the control, the enclosing
+  fieldset's legend, aria-label, the wrapping label's text, a <label for>,
+  the field name. Hints, options and nested controls are excluded.
+- Groups collapse: one checkbox is Yes/No; several checkboxes with one name
+  are a list of the checked values; radios are the one checked value or
+  blank; a multiple <select> is a list.
+- The submit button's value leads the message as **Action**, so several
+  <button name="action" value="…"> give one-click answers.
+- Each form has its own pending, dirty and status state. While a submission
+  is in flight its controls are disabled; afterwards the status line says
+  "Sent (queued)" or why it failed.
+- Typing into a captured form marks the page dirty, so a new version of the
+  page does not reload under the reader. Custom state the host cannot see:
+  window.threadPage.setDirty(true|false).
+
+The message you receive looks like:
+
+    The user answered the form on your Thread Page — <form's data-title or the h1>.
+
+    **Action**
+    Approve
+
+    **Which approach**
+    second
+
+    **Anything else**
+    (left blank)
+
+### The dialog trap
+
+A <form method="dialog"> inside a <dialog> is a form, so it is captured too.
+If you write one as a purely local confirm and forget the opt-out attribute,
+pressing its button **sends a real message you did not intend**, and because
+its buttons carry control-flow values, you receive a plausible fabricated
+decision:
+
+    The user answered the form on your Thread Page — <the page's heading>.
+
+    **Action**
+    confirm
+
+Nothing marks it as accidental, and if a turn is running it arrives on the
+next one, detached from what caused it. Put data-thread-page-manual on every
+dialog form that is not meant to answer you.`;
+
+const uploads = () => `## Files the reader sends you
+
+A captured form may contain <input type="file"> (multiple is fine). On submit
+the files are uploaded first, then the submission is delivered naming them:
+
+    **Attached files**
+    - \`$BB_THREAD_STORAGE/${UPLOAD_DIR}/20260908-161200-3f9a1c-report.pdf\` (…, 48213 bytes)
+
+Read them from there with your normal tools. Limits: ${mebibytes(LIMITS.uploadFileBytes)} per file,
+${LIMITS.uploadsPerForm} files per form (extras are dropped visibly). Names are generated by
+the host; the reader's filename is only a suffix. An upload that fails shows
+in the form's status line and no submission claims the missing file.`;
+
+const ownFiles = (site: SiteStrategy) => `## Files you show the reader
+
+Put them beside ${ENTRY_FILE} and reference them relatively — nested paths,
+spaces and punctuation in names are all fine:
+
+    <link rel="stylesheet" href="style.css">
+    <script src="app.js"></script>
+    <img src="figures/chart.png" alt="…">
+
+No permission, no declaration, no API: writing a file into your page root is
+enough. Keep everything inside your own page root; another agent's page is
+not yours to write.${
+  site.name === "core-storage"
+    ? `
+
+**One limitation on this host:** \`fetch("data.json")\` of your own file from
+page script is refused (403) — the host's file route rejects the sandbox's
+\`Origin: null\`. Subresources (<script>, <link>, <img>) load normally, so
+load data with <script src="data.js"> or inline it in the document. Remote
+fetches work (see Network).`
+    : `
+
+Page script may also fetch its own files as data: \`await fetch("data.json")\`.`
+}`;
+
+const runtimeApi = () => `## window.threadPage
+
+The complete page-facing API; it is frozen and cannot be replaced.
+
+    window.threadPage.version               // 1
+    await window.threadPage.invoke(method, params)
+    const stop = window.threadPage.watch(method, params, (value, error) => {…}, { intervalMs })
+    window.threadPage.setDirty(true | false)
+
+- \`invoke\` resolves with the capability's result and rejects with an Error
+  whose \`code\` is one of: invalid_json, invalid_request, invalid_params,
+  invalid_response, request_too_large, response_too_large,
+  unsupported_version, unknown_method, stale_page, confirmation_required,
+  confirmation_invalid, cancelled, not_found, conflict, unavailable,
+  rate_limited, handler_error, invalid_result. Calls made before the page is
+  connected are queued, never lost.
+- \`watch\` polls a read capability: default every ${LIMITS.watchDefaultMs / 1000} s, clamped to
+  ${LIMITS.watchMinMs / 1000} s–${LIMITS.watchMaxMs / 60_000} min, paused while the tab is hidden. Errors go to the
+  listener's second argument. Call the returned function to stop; a page that
+  never calls watch causes no polling.
+- \`stale_page\` means the page changed under the call: the shell offers a
+  reload. \`cancelled\` means the reader declined a confirmation — a normal
+  outcome every page calling a confirmed capability must handle, not an error.
+
+Check what is enabled rather than assume: \`(await invoke("context.get")).capabilities\`.`;
+
+function capabilities(registry: CapabilityRegistry): string {
+  const rows = registry.list().map((spec) => {
+    const status = spec.implemented ? (spec.confirmed ? "confirmed in trusted chrome" : "no confirmation") : "not implemented on this host: unknown_method";
+    const lines = [`### \`${spec.method}\` — ${spec.effect} · ${status}`, "", spec.description, "", `Parameters: ${spec.doc.params}`, "", `Result: ${spec.doc.result}`];
+    if (spec.doc.notes) lines.push("", spec.doc.notes);
+    return lines.join("\n");
+  });
+  return `## Capabilities
+
+Every way a page can affect anything outside itself. Effects: read;
+own-session-write; cross-session-write, destructive and device (always
+confirmed); navigation (confirmed when it leaves this host). A confirmed
+capability shows a dialog in trusted chrome with the host's own wording; you
+do not build it and cannot word it. Every capability validates its
+parameters exactly — unknown keys are refused — and returns only the fields
+listed here.
+
+${rows.join("\n\n")}`;
+}
+
+const startingSessions = () => `## Starting work from a page
+
+\`sessions.start\` is how a page that should stay put comes to exist: its
+buttons start fresh sessions instead of messaging you, so nothing asks you to
+rewrite it. It succeeds with only a project and a prompt:
+
+    await window.threadPage.invoke("sessions.start", {
+      projectId, prompt: "Run the test suite. Report failures only; change nothing."
+    });
+
+What you get when you say nothing, and how to say otherwise:
+
+- environment: the project's default. Otherwise \`environment: { sameAs: sessionId }\`
+  runs in the same environment as that session.
+- provider, model, reasoningLevel: the project's defaults. Otherwise name ids
+  from \`providers.list\`.
+- title: the host's own. Otherwise \`title\`.
+- The session is a visible root owned by the reader, never a child of yours.
+
+The confirmation names the project and the prompt. Handle \`cancelled\`:
+
+    try { await invoke("sessions.start", {…}); say("Started."); }
+    catch (e) { say(e.code === "cancelled" ? "Nothing started." : e.message); }
+
+\`sessions.send\` steers an existing session the same way; it refuses your own
+session — use \`session.reply\` for that.`;
+
+const network = () => `## Network
+
+Pages have internet access: fetch any origin, load remote fonts, scripts,
+stylesheets, images and media, open WebSockets. The page still holds no host
+credential — reaching a URL and acting as the host are different things.
+
+Two consequences to know: page script runs in the reader's browser, so it can
+reach what that device can reach, including its own network; and script can
+navigate its own frame with data in the URL. Both are accepted, documented
+properties of the model, not bugs to work around.`;
+
+const unavailable = () => `## What the sandbox silences
+
+These do nothing, silently — the worst failure mode — so never rely on them:
+
+- \`window.open\` — use \`pages.open\` for another page, \`sessions.openHost\`
+  for the host application, and a plain <a href="https://…"> or
+  \`navigation.openExternal\` for the web.
+- \`window.prompt\`, \`alert\`, \`confirm\` — build the input or the question into
+  the page (an <input>, a <dialog> with data-thread-page-manual, a second
+  form), or use a confirmed capability, which renders its own dialog.
+- top-level navigation — \`pages.open\` and \`sessions.openHost\` navigate the
+  reader's view in place through trusted chrome; the back button returns.
+
+An ordinary <a href="https://…"> works: the host intercepts the click and
+routes it through \`navigation.openExternal\`, which confirms and names the
+destination. Same-document fragments (#section) work natively. The trust
+boundary is not configurable: no setting widens the sandbox.`;
+
+const composition = () => `## One agent, one page
+
+Your page is yours alone. You never read or write another agent's page, and
+the host provides no mechanism to. If the reader wants a dashboard, a console
+or a second view, start a session with instructions to build it; that agent
+writes its own page. Link to it with \`pages.open\`, or suggest making it home.
+If you want another agent's page changed, send that agent a message with
+\`sessions.send\` rather than editing its file. Do not create a session merely
+to hold a page: a page that stays put is owned by a real agent that built it
+and then stopped.`;
+
+const home = () => `## The home page
+
+One page is home; every other page shows a "← Sessions" link back to it in
+chrome you never write. \`bb thread-page home\` sets the pointer for the
+current session (\`--clear\` removes it) and creates the plain seed if the
+session has no page yet; it never touches an existing page. Home is an
+ordinary page — a hub is one an agent builds, and the right place to build it
+is a session dedicated to it, so nothing else ever rewrites it.
+
+### Setting one up, step by step
+
+1. In the session that should own it (start one for the purpose if you are
+   mid-task), run \`bb thread-page home\`. It prints the link every page will
+   carry.
+2. Replace <main> in that session's index.html with the starter hub below,
+   then stop. The page stays put because its buttons open other pages or
+   start fresh sessions; nothing messages this session.
+3. Tell the reader the link and that the hub is theirs to change: they can
+   ask this session to regroup, restyle or add jobs any time.
+
+### A starter hub
+
+Complete and working as written; drop it into <main>. It follows what the
+reader already sees in bb: no archived sessions, sub-agents hidden, the
+sessions that need them first (working, waiting on them, unread — a failed
+session only until they have looked), five recent per project then "Show
+more", one line per session, search with "/", Read/Unread, Stop, Archive and
+start-a-session with the confirmations handled. Views and
+collapsed projects persist in \`storage\`. It widens the page for the list;
+that is allowed — the page owns its stylesheet.
+
+${starterHubForGuide()}
+
+Refresh on a slow watch, not a tight timer: the page shares a rate budget of
+${LIMITS.ratePerMinute} requests a minute with its own forms. Grouping is yours to change: a
+group can be any set of projects, and \`data-theme\` on a group's element can
+give it its own look.`;
+
+const accessibility = () => `## Before you save
+
+- Read it once at 320px wide, once in dark mode, once with reduced motion.
+- Every action reachable by keyboard; nothing pointer-only.
+- Inline SVG for diagrams and charts, with var(--accent) inside it; a zero
+  gets a visible stub or the eye reads missing data.
+- grep -o '#[0-9a-fA-F]\\{3,8\\}' ${ENTRY_FILE} inside your <style> should be empty.`;
+
+const limits = () => `## Limits
+
+| Limit | Value |
+| --- | --- |
+| Entry document | ${mebibytes(LIMITS.entryDocumentBytes)}, refused above, never truncated |
+| Other files in the page root | ${mebibytes(25 * 1024 * 1024)} per file (${mebibytes(10 * 1024 * 1024)} for images), the host's read limit |
+| Upload per file | ${mebibytes(LIMITS.uploadFileBytes)} |
+| Uploads per form | ${LIMITS.uploadsPerForm} |
+| Submission body | ${kibibytes(LIMITS.submissionBodyBytes)} excluding uploaded bytes; ${LIMITS.answersPerSubmission} answers; ${LIMITS.answerValueChars} characters per answer |
+| Capability payload | ${kibibytes(LIMITS.capabilityPayloadBytes)} request and response, depth ${LIMITS.capabilityJsonDepth}, ${LIMITS.capabilityJsonNodes} nodes |
+| Prompt | ${kibibytes(LIMITS.promptChars)} characters (sessions.start, sessions.send) |
+| session.reply result | ${kibibytes(LIMITS.resultTextBytes)} |
+| Title | ${LIMITS.titleChars} characters |
+| storage value | ${kibibytes(LIMITS.storageValueBytes)} per key; keys ${LIMITS.storageKeyChars} characters |
+| sessions.snapshot | ${LIMITS.snapshotDefault} default, ${LIMITS.snapshotMax} maximum per call |
+| session.activity | ${LIMITS.activityDefault} default, ${LIMITS.activityMax} maximum |
+| Page session (action token) | ${LIMITS.actionTokenMs / 3_600_000} hours, then the shell reloads or asks |
+| Confirmation | ${LIMITS.confirmationMs / 60_000} minutes to answer the dialog |
+| Folder selection | ${LIMITS.selectionTokenMs / 60_000} minutes, single use |
+| Submission idempotency | ${LIMITS.idempotencyRecords} records, ${LIMITS.idempotencyMs / 60_000} minutes |
+| Rate limit | ${LIMITS.ratePerMinute} accepted requests a minute and ${LIMITS.rateConcurrent} in flight, per page; refused with rate_limited |
+| Shell revision poll | every ${LIMITS.shellPollMs / 1000} s while visible |
+| watch interval | ${LIMITS.watchDefaultMs / 1000} s default, ${LIMITS.watchMinMs / 1000} s–${LIMITS.watchMaxMs / 60_000} min |
+| Offline copy | entry documents up to ${kibibytes(LIMITS.offlineCopyBytes)} are kept so the page opens read-only when its host is unreachable |`;
+
+const limitations = (site: SiteStrategy) => `## Known limitations
+
+- A page served from the offline copy is read-only: captured forms are
+  disabled and effectful capabilities answer unavailable.
+- A confirmed capability that fails on the host answers handler_error with a
+  generic message; the cause is in the plugin log (\`bb plugin logs thread-pages\`).
+- Embedding another page or site in an <iframe> is blocked (frame-src 'none').
+- \`voice.captureAndTranscribe\` is not implemented: unknown_method.${
+  site.name === "core-storage" ? `\n- fetch() of your own files from page script is refused on this host (see Files you show the reader).` : ""
+}`;

package/src/agent/instruction.ts

@@ -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

@@ -0,0 +1,69 @@
+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>
+
+  <!--
+    Write inside <main>. Plain semantic HTML is already styled: h2, p, ul,
+    table, form, fieldset/legend, a wrapping label, small, details. Three
+    class names exist: .card boxes an aside, .needs-you flags a block that is
+    blocked on the reader, .label is a small uppercase tag.
+
+    Every <form> answers this session automatically unless it carries
+    data-thread-page-manual. Blank answers are valid. A <form method="dialog">
+    you only meant as a local confirm still sends a message unless it opts out.
+
+    Files you put beside this index.html are served relatively: <img
+    src="chart.png">, <link href="page.css">, <script src="app.js">, nested
+    paths included. Ordinary <a href="https://…"> links work.
+
+    data-theme: paper | terminal | atrium | volume | bloom.
+    data-mode: system | light | dark. data-atmos: on | off.
+    Extra CSS goes in one more <style>, everything inside @scope (main),
+    colour and shape from var(--token) only.
+
+    Never use window.prompt, alert, confirm or window.open: the sandbox
+    silences them. For anything more — charts, files, live session state,
+    starting sessions, links — run: bb thread-page guide
+  -->
+  <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));
+}