letmeknow-cli 0.7.0 → 0.8.0

package/README.md

@@ -1,129 +1,53 @@
 # LetMeKnow
 
-LetMeKnow gives an agent a temporary public browser surface and structured human feedback. The agent authors ordinary HTML and static assets; a running CLI serves them and accepts page updates over a single ordered event stream.
+LetMeKnow gives an agent a temporary public browser surface for structured human feedback. The agent serves ordinary HTML and static assets, receives browser submissions, and can push ordered HTML replacements.
 
-## Start a session
+## Quick start
 
-Create a directory containing the public files, including an initial `index.html`, then run:
+Create a directory with an `index.html`, then run:
 
 ```bash
 npx letmeknow-cli serve ./preview
 ```
 
-`serve` reads `index.html` once as the canonical dynamic page and serves it at `/`. Other files in the directory—such as CSS, JavaScript, images, and data—are served live as static assets. The CLI prints one JSON line containing the public bearer URL:
+The CLI prints one JSON line containing the public bearer URL:
 
 ```json
 {"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/","page_event":0,"page_hash":"…"}
 ```
 
-Give the URL to the human. Anyone with the URL can view the page and submit its forms. Canonical page state and the event stream live in memory while `serve` runs; they do not survive a stopped session. The CLI connects outbound and does not listen on a network port.
+Give the URL to the human. Anyone with the URL can view the page and submit its forms.
 
-The agent’s files are never modified by `serve`.
-
-## Agent workflow
-
-Pull browser events, update the page, and push the resulting page:
-
-```bash
-batch=$(npx letmeknow-cli pull ./preview --wait 30)
-token=$(printf '%s\n' "$batch" | jq -r .token)
-# inspect events, edit index.html, then:
-npx letmeknow-cli push ./preview --batch "$token" --page index.html
-```
-
-`pull` returns an opaque batch token, current-page metadata, and the browser events not yet committed by the agent. Pulling does not consume events. Events that arrive while the agent works remain for a later pull.
-
-```json
-{"token":"…","frontier":7,"page_event":5,"page_hash":"…","events":[{"type":"submit","id":"…","event_number":7,"page_event":5,"form_id":"decision","action":"/decide","trigger":{"name":"decision","value":"approve"},"values":{"comment":"Looks good","decision":"approve"}}]}
-```
-
-An event's `page_event` identifies the page the browser displayed when it submitted. Compare it with the batch's current `page_event` when deciding whether the input still applies.
-
-A push with a page:
-
-```bash
-npx letmeknow-cli push ./preview --batch "$token" --page index.html
-```
-
-atomically commits the events represented by the token, replaces the canonical dynamic page with the complete HTML from `index.html`, appends one page-update event to the global event stream, and broadcasts that page to connected browsers. Browsers morph the page without navigating or reloading.
-
-A push without `--page` only commits the pulled browser events:
-
-```bash
-npx letmeknow-cli push ./preview --batch "$token"
-```
-
-Use `--page -` to read the complete desired page from standard input:
-
-```bash
-npx letmeknow-cli push ./preview --batch "$token" --page - < updated.html
-```
-
-The update is all-or-nothing. If the token or page input is invalid, neither the browser events nor the page update is committed.
-
-## Inspect the current page
-
-`show` writes the canonical dynamic HTML held by `serve` to standard output:
-
-```bash
-npx letmeknow-cli show ./preview > current.html
-```
-
-It is read-only and does not create or commit an event. This is different from opening the public URL: `show` returns canonical HTML, while the URL shows a particular browser’s rendered DOM, including local focus, open/closed controls, unsent values, and JavaScript state.
-
-## The event stream
-
-Browser submissions and CLI page updates share one ordered, in-memory event stream:
+## Commands
 
 ```text
-submit       browser
-submit       browser
-update_ui    CLI: complete desired HTML page
+serve <dir>
+show <dir>
+pull <dir> [--wait seconds]
+push <dir> --batch TOKEN [--updates FILE|-]
 ```
 
-Browser submission events are delivered to the agent through `pull`. Page-update events are broadcast to all connected browsers. There is no per-browser audience or dynamic view system in the initial model.
-
-The CLI assigns the event order. The number indicates acceptance order, not the physical time a person clicked. Submission IDs make retries distinguishable from new intentional submissions.
+`serve` reads `index.html` once as the canonical page. Other files are served live from the directory. `show` prints the accepted canonical HTML. `pull` returns browser events without consuming them; `push` commits a pulled batch, optionally with ordered replacements. See [`SKILL.md`](SKILL.md) for the complete workflow and protocol.
 
-## Forms
+## Page updates
 
-Use ordinary HTML forms with stable IDs and meaningful field names:
+Use stable IDs as replacement boundaries:
 
 ```html
-<form id="decision" action="/decide" method="post">
-  <label>Comment <textarea id="comment" name="comment"></textarea></label>
-  <button name="decision" value="approve">Approve</button>
-  <button name="decision" value="reject">Reject</button>
-</form>
+<output id="counter">41</output>
 ```
 
-The runtime intercepts native form submission and turns it into a durable JSON `submit` event. It assigns an opaque UUID, stores the event in the browser’s local outbox before delivery, retries after connection failures, and reuses the UUID on retry. The CLI deduplicates repeated delivery of the same event. Distinct submissions remain distinct, including rapid repeated clicks.
-
-Form values are untrusted input and should be validated by the agent. File uploads are not supported.
-
-## Authoring the dynamic page
-
-Each page update supplies the complete desired HTML document. The browser morphs the current document toward it, so a small change such as a counter update need not recreate the whole DOM.
-
-Give elements stable unique IDs. They help the morphing runtime retain unchanged elements, including controls whose local state should survive an update:
-
-```html
-<output id="count">0</output>
+```json
+{"updates":[{"target":"counter","html":"<output id=\"counter\">42</output>"}]}
 ```
 
-Agent-authored JavaScript should be loaded by the initial page as a static asset and use delegated event listeners. Existing scripts remain active across morphs, but scripts added or changed by a pushed page are not executed in connected browsers; keep script references fixed for the session.
-
-The CLI owns rendered page content. The browser preserves focus, scrolling, dirty controls with stable IDs, and the open state of `<details id="…">`. Mark an element with a stable ID and `data-letmeknow-local` when its `hidden` state is browser-owned. Avoid having browser JavaScript and pushed HTML otherwise mutate the same state; a later morph may replace browser-created changes.
-
-A page update is shared with all browsers. Keep private or browser-specific behavior local unless a future requirement introduces targeted updates.
-
-## Static assets
+Each replacement must contain one element with the target's ID and cannot contain scripts. Replacements in one push are applied in order and atomically. Replacing `letmeknow-root` is the broad page-update case and intentionally discards browser-local state inside that root.
 
-Static assets are read live from the directory, independently of the canonical dynamic page. An agent can change CSS, JavaScript, images, and other assets without a page push. Finish an asset before pushing HTML that references it, write files atomically, and use versioned filenames or cache-busting URLs when cached assets must change with the page.
+## Session and security basics
 
-## Security
+Sessions are temporary and held in memory by the CLI and relay. The service may expire a session at any time. If the producer disconnects, reconnect is best-effort and may be available only for a limited period; clients should handle disconnects without assuming that reconnect will succeed.
 
-The URL is a bearer capability. Anyone who has it can view the page and submit forms. Keep secrets and unrelated files outside the served directory. Browser values are untrusted input; escape them before placing them in HTML.
+The public URL is a bearer capability: anyone who has it can view the page and submit forms. Treat browser values as untrusted input and escape them before placing them in HTML. Keep secrets and unrelated files outside the served directory.
 
 ## Development
 
@@ -135,4 +59,4 @@ npm run dev
 npm run deploy
 ```
 
-The browser test requires Firefox and geckodriver. `npm run dev` and `npm run deploy` operate the Cloudflare relay.
+The browser smoke test requires Firefox and geckodriver. `npm run dev` and `npm run deploy` operate the Cloudflare relay. For the detailed agent workflow, forms, event causality, reconnect behavior, and static-asset guidance, read [`SKILL.md`](SKILL.md).

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: letmeknow
-description: Serve a temporary live HTML page, collect structured human feedback, and push agent-authored page updates.
+description: Serve a temporary live HTML page, collect structured human feedback, and push ordered HTML replacements.
 ---
 
 # LetMeKnow
@@ -9,29 +9,46 @@ Use LetMeKnow when a human should inspect or interact with an agent-authored pag
 
 ## Start
 
-Create a directory containing the public files and an initial `index.html`:
+Create a directory containing the public files and an initial `index.html`, then run:
 
 ```bash
 npx letmeknow-cli serve ./preview
 ```
 
-`serve` reads `index.html` once as the canonical dynamic document and serves it at `/`. It serves the other files in the directory live as static assets. The first stdout JSON line contains the public bearer URL:
+`serve` reads `index.html` once as the initial canonical dynamic page and serves it at `/`. Other files—such as CSS, JavaScript, images, and data—are served live from the directory. The first stdout JSON line contains the public bearer URL and initial page metadata:
 
 ```json
 {"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/","page_event":0,"page_hash":"…"}
 ```
 
-Give the URL to the human. Anyone with the URL can view the page and submit its forms. The CLI connects outbound and opens no network port. Canonical page state and events are temporary in-memory session state; they end when `serve` stops. `serve` never modifies agent files.
+The initial page should have a stable shell and a dynamic root:
+
+```html
+<body>
+  <main id="letmeknow-root">
+    ...
+  </main>
+  <script type="module" src="/app.js"></script>
+</body>
+```
+
+The runtime is injected into the page separately. Keep agent-authored scripts and the runtime outside normal replacement targets.
+
+## Session lifetime and reconnect
+
+A producer must successfully send `open` shortly after connecting. Sessions are temporary and may be expired by the service at any time.
+
+If an opened producer disconnects, reconnect is best-effort and may be available only for a limited period. A reconnect uses the existing session credential, but clients must handle disconnects without assuming that reconnect will succeed. When the service expires a session, the session and its browser connections end.
 
 ## Agent loop
 
-Pull browser events, update the desired page, and push it:
+Pull browser events, update one or more HTML fragments, and push the replacements:
 
 ```bash
 batch=$(npx letmeknow-cli pull ./preview --wait 30)
 token=$(printf '%s\n' "$batch" | jq -r .token)
-# inspect the events and edit index.html
-npx letmeknow-cli push ./preview --batch "$token" --page index.html
+# inspect events and write fragments such as counter.html and status.html
+npx letmeknow-cli push ./preview --batch "$token" --updates updates.json
 ```
 
 Commands:
@@ -40,74 +57,149 @@ Commands:
 serve <dir>
 show <dir>
 pull <dir> [--wait seconds]
-push <dir> --batch TOKEN [--page FILE|-]
+push <dir> --batch TOKEN [--updates FILE|-]
 ```
 
-`pull` returns an opaque batch token, current-page metadata, and browser events not yet committed by the agent. Pulling does not consume events. Events arriving while the agent works remain for a later pull.
+`show` returns the current canonical page without changing the event stream:
+
+```bash
+npx letmeknow-cli show ./preview > current.html
+```
+
+The public URL is the visual preview. `show` returns canonical HTML, not a browser's local focus, open disclosures, unsent input, scroll position, or JavaScript state.
+
+## Push updates
+
+A push accepts one JSON document:
 
 ```json
-{"token":"…","frontier":7,"page_event":5,"page_hash":"…","events":[{"type":"submit","id":"…","event_number":7,"page_event":5,"form_id":"decision","action":"/decide","trigger":{"name":"decision","value":"approve"},"values":{"comment":"Looks good","decision":"approve"}}]}
+{
+  "updates": [
+    {"target": "counter", "file": "counter.html"},
+    {"target": "status", "html": "<output id=\"status\">Saved</output>"}
+  ]
+}
 ```
 
-An event's `page_event` identifies the page displayed when the browser submitted it. Compare it with the batch's current `page_event` before applying old input to the current page.
+Each update must contain exactly one of `html` or `file`. A file supplies the replacement HTML. The normal operation is direct replacement of one element identified by its unique stable `id`:
 
-`push --page FILE` atomically commits the events represented by the token, makes FILE the complete desired dynamic document, appends one page-update event to the global event stream, and broadcasts it to all connected browsers. Browsers morph the page without navigation.
+```html
+<output id="counter">41</output>
+```
 
-```bash
-npx letmeknow-cli push ./preview --batch "$token" --page index.html
+```json
+{"updates":[{"target":"counter","html":"<output id=\"counter\">42</output>"}]}
+```
+
+The replacement must contain exactly one element, and that element must have the same ID as the target. Replacement HTML cannot contain scripts. The target must exist when the replacement is applied.
+
+Use small output regions for ordinary updates. The replacement is destructive inside its target but leaves the rest of the page alone, so a counter update does not disturb a form or button elsewhere.
+
+The document root is just another target. To intentionally replace all dynamic content, target the root:
+
+```html
+<main id="letmeknow-root">
+  ...
+</main>
+```
+
+```json
+{"updates":[{"target":"letmeknow-root","file":"root.html"}]}
 ```
 
-A push without `--page` only commits the pulled browser events:
+Replacing the root intentionally discards browser-local state inside it. Use it when that is acceptable, not for every small change.
+
+A single push may contain many replacements. They are applied in the order listed. Later replacements may target elements introduced by earlier replacements in the same push, so introduce a target before updating it. Conversely, a replacement that removes a later target makes a following update invalid. The CLI validates the complete ordered batch before committing anything.
+
+Each replacement becomes its own `update_ui` event with its own global event number. The complete push is still atomic: either all replacements and the pulled browser-event batch commit, or none do. Connected browsers receive committed replacements in order.
+
+A push without `--updates` commits the pulled browser events without changing the page:
 
 ```bash
 npx letmeknow-cli push ./preview --batch "$token"
 ```
 
-Use `--page -` for standard input:
+There is no separate acknowledgement command and no `--page` mode. Replacing `letmeknow-root` provides the broad page-update case.
 
-```bash
-npx letmeknow-cli push ./preview --batch "$token" --page - < updated.html
+## Event stream and page causality
+
+Browser submissions and CLI page replacements share one ordered, in-memory event stream:
+
+```text
+submit       browser
+submit       browser
+update_ui    CLI: replace #counter
+update_ui    CLI: replace #status
 ```
 
-The page push is all-or-nothing. Invalid input or an invalid token commits nothing. The CLI assigns one global order to each browser submission and each page-update event.
+The CLI assigns event numbers in acceptance order. They do not claim to be the physical order in which people clicked. Browser submissions are delivered to the agent through `pull`; raw submissions are not broadcast to other browsers. Page replacements are broadcast to all connected browsers.
 
-`show` retrieves the canonical dynamic HTML held by `serve` without changing the event stream:
+`pull` returns an opaque batch token, current-page metadata, and browser events not yet committed by the agent. Pulling does not consume events. Events arriving while the agent works remain for a later pull.
 
-```bash
-npx letmeknow-cli show ./preview > current.html
+```json
+{
+  "token": "…",
+  "frontier": 7,
+  "page_event": 5,
+  "page_hash": "…",
+  "events": [
+    {
+      "type": "submit",
+      "id": "…",
+      "event_number": 7,
+      "page_event": 5,
+      "form_id": "decision",
+      "action": "/decide",
+      "trigger": {"name": "decision", "value": "approve"},
+      "values": {"comment": "Looks good", "decision": "approve"}
+    }
+  ]
+}
 ```
 
-The public URL is the visual preview. `show` returns canonical HTML, not a browser’s local DOM state such as focus, open disclosures, unsent input, scroll position, or JavaScript state.
+`page_event` is the page-update event number displayed when the browser submitted. Compare each event's `page_event` with the batch's current page before applying old input to the current HTML. `frontier` is the latest global event number, including events that are not browser submissions.
+
+The token identifies exactly the browser-event frontier the agent saw. A successful push commits that frontier and its ordered replacements together. Browser events accepted after the pull remain for the next batch.
 
 ## Forms
 
-Use native forms with stable IDs and meaningful names:
+Use ordinary same-origin forms with stable IDs and meaningful field names:
 
 ```html
-<form id="review" action="/review" method="post">
+<form id="decision" action="/decide" method="post">
   <label>Comment <textarea id="comment" name="comment"></textarea></label>
   <button name="decision" value="approve">Approve</button>
   <button name="decision" value="reject">Reject</button>
 </form>
 ```
 
-The browser runtime serializes native form submissions as JSON `submit` events. It assigns an opaque ID, stores each event in a local durable outbox before sending it, retries after connection failures, and reuses the ID on retry. The CLI deduplicates repeated delivery. Ten intentional rapid clicks should produce ten distinct events. File uploads are not supported.
+The runtime converts native form submission into a JSON `submit` event. It assigns an opaque UUID, stores each event in a durable browser outbox before delivery, retries after connection failures, and reuses the UUID on retry. The CLI deduplicates repeated delivery of the same event. Distinct intentional submissions remain distinct, including rapid repeated clicks. File uploads are not supported.
 
 Treat pulled values as untrusted input. Validate them and escape them before putting them into HTML.
 
-## Dynamic page rules
-
-Every page push supplies the complete desired dynamic document. The browser uses HTML morphing, so unchanged DOM nodes can survive while changed content is updated.
+## Browser and HTML rules
 
-Give elements stable unique IDs. Load agent-authored JavaScript from the initial page as a static asset and use delegated listeners. Existing scripts remain active across morphs, but scripts added or changed by a pushed page are not executed in connected browsers; keep script references fixed for the session.
+Normal updates are direct replacements, not DOM morphs. Stable IDs are therefore important for naming update boundaries, not for preserving DOM nodes.
 
-The CLI owns page content. The browser preserves focus, scrolling, dirty controls with stable IDs, and the open state of `<details id="…">`. Mark an element with a stable ID and `data-letmeknow-local` when its `hidden` state is browser-owned. Do not have browser JavaScript and pushed HTML otherwise mutate the same state; a later morph may replace browser-created changes.
+- The CLI owns content inside replacement targets.
+- The browser owns local focus, open/closed disclosure state, and hide/show behavior outside deliberately replaced targets.
+- A root replacement can destroy all local state inside the root.
+- Load agent-authored JavaScript from the initial page as a static asset.
+- Use delegated event listeners because replaced elements are new DOM nodes.
+- Scripts in update fragments are not executed.
+- Do not have browser JavaScript and pushed HTML independently own the same state.
 
-Page updates are shared with all connected browsers. There is no dynamic view or per-browser update system. Use ordinary static links and files when the application needs more persistent pages.
+When a session ends, the browser shows a permanent closed status and discards unsent submissions rather than retrying them.
 
 ## Static assets
 
-CSS, JavaScript, images, and other non-`index.html` files are served live. Finish writing an asset before pushing HTML that references it. Write assets atomically, and use versioned filenames or cache-busting URLs when the browser must fetch a changed asset with the new page.
+CSS, JavaScript, images, and other non-`index.html` files are served live. Finish writing an asset before pushing HTML that references it. Write assets atomically, and use versioned filenames or cache-busting URLs when the browser must fetch a changed asset with the page update.
+
+This design intentionally does not provide atomic publication of the whole directory. The dynamic page changes through ordered replacements; other files can change as soon as they are written.
+
+## Security
+
+The URL is a bearer capability. Anyone who has it can view the page and submit forms. Keep secrets and unrelated files outside the served directory. Browser values are untrusted input; escape them before placing them in HTML.
 
 ## Stop
 

package/bin/letmeknow.js

@@ -1,17 +1,22 @@
 #!/usr/bin/env node
 
-import { constants, existsSync, readFileSync, statSync, writeSync } from "node:fs";
+import { constants, createReadStream, existsSync, readFileSync, statSync, writeSync } from "node:fs";
 import { chmod, open, readFile, realpath, stat, unlink } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import net from "node:net";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { tmpdir } from "node:os";
 import { parseArgs } from "node:util";
+import { parse, parseFragment, serialize } from "parse5";
 import { lookup } from "mrmime";
 
 const MAX_BODY_BYTES = 1024 * 1024;
-const CONTROL_MAX_BYTES = MAX_BODY_BYTES * 2 + 16 * 1024;
-const GRACE_SECONDS = 10 * 60;
+const UPDATE_BATCH_MAX_BYTES = 16 * MAX_BODY_BYTES;
+const MAX_BATCH_TOKENS = 100_000;
+const MAX_UNIQUE_SUBMISSIONS = 100_000;
+const MAX_RETAINED_SUBMISSION_BYTES = 256 * 1024 * 1024;
+const CONTROL_MAX_BYTES = UPDATE_BATCH_MAX_BYTES * 2;
+const RECONNECT_RETRY_SECONDS = 10 * 60;
 const CONNECTION_TIMEOUT = 10_000;
 const CONTROL_TIMEOUT = 35_000;
 const CONTROL_PREFIX = "letmeknow-control-";
@@ -20,6 +25,7 @@ const credentialPattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const privateNames = new Set([".env", ".git", ".ssh", "id_rsa", "id_ed25519", "id_ecdsa", "id_dsa"]);
 const privateFilePattern = /^\.env\.|\.(?:key|pem|p12|ppk|p8|sqlite|sqlite3|db|db3)$|-(?:wal|shm|journal)$/i;
 const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const forbiddenUpdateTargets = new Set(["html", "head", "body", "script"]);
 
 function getMimeType(filename) {
   const type = lookup(filename);
@@ -153,6 +159,119 @@ async function readInitialPage(root) {
   return (await readFile(target)).toString("utf8");
 }
 
+function nodeId(node) {
+  return node.attrs?.find(attribute => attribute.name === "id")?.value;
+}
+
+function elementsWithId(node, id, matches = []) {
+  if (node.nodeName !== "#text" && node.nodeName !== "#comment" && nodeId(node) === id) matches.push(node);
+  for (const child of node.childNodes || []) elementsWithId(child, id, matches);
+  return matches;
+}
+
+function containsScript(node) {
+  if (node.nodeName === "script") return true;
+  if (node.content && containsScript(node.content)) return true;
+  return (node.childNodes || []).some(containsScript);
+}
+
+function updateFragment(target, html, context) {
+  const fragment = parseFragment(context, html);
+  const meaningful = (fragment.childNodes || []).filter(node => node.nodeName !== "#text" || node.value.trim() !== "");
+  if (meaningful.length !== 1 || meaningful[0].nodeName === "#comment" || meaningful[0].nodeName?.startsWith("#")) throw new Error(`update for ${target} must contain exactly one root element`);
+  const root = meaningful[0];
+  if (containsScript(root)) throw new Error(`update for ${target} cannot contain script elements`);
+  if (nodeId(root) !== target) throw new Error(`update root ID must be ${target}`);
+  return root;
+}
+
+function replaceElement(document, target, html) {
+  if (forbiddenUpdateTargets.has(target.nodeName)) throw new Error(`cannot update ${target.nodeName} element`);
+  const parent = target.parentNode;
+  const index = parent?.childNodes.indexOf(target);
+  if (!parent || index === undefined || index < 0) throw new Error("update target has no parent");
+  const replacement = updateFragment(nodeId(target), html, parent);
+  parent.childNodes[index] = replacement;
+  replacement.parentNode = parent;
+  target.parentNode = null;
+}
+
+function validateUpdates(updates) {
+  if (!Array.isArray(updates)) throw new Error("updates must be an array");
+  let bytes = 0;
+  for (const update of updates) {
+    if (!update || typeof update !== "object" || Array.isArray(update)) throw new Error("each update must be an object");
+    if (typeof update.target !== "string" || update.target.trim() === "") throw new Error("update target must be a non-empty ID");
+    if (typeof update.html !== "string") throw new Error("update html must be text");
+    bytes += Buffer.byteLength(update.html, "utf8");
+    if (bytes > UPDATE_BATCH_MAX_BYTES) throw new Error("updates are too large");
+  }
+  return updates;
+}
+
+function applyUpdates(page, updates) {
+  validateUpdates(updates);
+  const document = parse(page);
+  for (const update of updates) {
+    const matches = elementsWithId(document, update.target);
+    if (matches.length !== 1) throw new Error(`update target ${update.target} must match exactly one element`);
+    replaceElement(document, matches[0], update.html);
+  }
+  const result = serialize(document);
+  if (Buffer.byteLength(result, "utf8") > MAX_BODY_BYTES) throw new Error("updated page is too large");
+  return result;
+}
+
+async function readInput(filename) {
+  const chunks = [];
+  let length = 0;
+  const input = filename === "-" ? process.stdin : createReadStream(filename);
+  for await (const chunk of input) {
+    const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    length += value.byteLength;
+    if (length > UPDATE_BATCH_MAX_BYTES) throw new Error("updates are too large");
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function readUpdatesInput(filename) {
+  const manifest = await readInput(filename);
+  let value;
+  try { value = JSON.parse(manifest); } catch { throw new Error("invalid updates JSON"); }
+  if (!value || typeof value !== "object" || Array.isArray(value) || !Array.isArray(value.updates)) throw new Error("updates must be an object with an updates array");
+  const base = filename === "-" ? process.cwd() : dirname(resolve(filename));
+  const updates = [];
+  let bytes = 0;
+  for (const item of value.updates) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("each update must be an object");
+    if (typeof item.target !== "string" || item.target.trim() === "") throw new Error("update target must be a non-empty ID");
+    const hasHtml = Object.prototype.hasOwnProperty.call(item, "html");
+    const hasFile = Object.prototype.hasOwnProperty.call(item, "file");
+    if (hasHtml === hasFile) throw new Error(`update for ${item.target} must have exactly one of html or file`);
+    let html;
+    if (hasHtml) {
+      if (typeof item.html !== "string") throw new Error(`update html for ${item.target} must be text`);
+      html = item.html;
+    } else {
+      if (typeof item.file !== "string" || item.file === "") throw new Error(`update file for ${item.target} must be a path`);
+      const file = resolve(base, item.file);
+      const info = await stat(file);
+      if (!info.isFile()) throw new Error(`update file for ${item.target} must be a regular file`);
+      if (info.size > UPDATE_BATCH_MAX_BYTES - bytes) throw new Error("updates are too large");
+      html = (await readFile(file)).toString("utf8");
+    }
+    bytes += Buffer.byteLength(html, "utf8");
+    if (bytes > UPDATE_BATCH_MAX_BYTES) throw new Error("updates are too large");
+    updates.push({ target: item.target, html });
+  }
+  return updates;
+}
+
+function updatesHash(updates) {
+  return createHash("sha256").update(JSON.stringify(updates)).digest("hex");
+}
+
 async function submission(packet, recordInteraction) {
   const request = requestUrl(packet);
   const method = typeof packet.method === "string" ? packet.method.toUpperCase() : "";
@@ -170,7 +289,7 @@ async function submission(packet, recordInteraction) {
   if (typeof value.action !== "string") throw new Error("action is required");
   if (value.trigger !== null && (typeof value.trigger !== "object" || Array.isArray(value.trigger))) throw new Error("trigger must be an object or null");
   if (!value.values || typeof value.values !== "object" || Array.isArray(value.values)) throw new Error("values are required");
-  await recordInteraction({ type: "submit", id: value.id, page_event: value.page_event, form_id: value.form_id, action: value.action, trigger: value.trigger, values: value.values });
+  await recordInteraction({ type: "submit", id: value.id, page_event: value.page_event, form_id: value.form_id, action: value.action, trigger: value.trigger, values: value.values }, body.byteLength);
   return response(packet, 202);
 }
 
@@ -245,8 +364,9 @@ async function start(directory) {
   let pageEvent = 0;
   let eventNumber = 0;
   const currentPageHash = () => pageHash(page);
-  const eventLog = [];
   const browserEvents = [];
+  const browserEventBytes = [];
+  let retainedSubmissionBytes = 0;
   let committedBrowserCursor = 0;
   const seenEvents = new Set();
   const tokens = new Map();
@@ -264,24 +384,28 @@ async function start(directory) {
   let retryUntil = 0;
   let stopped = false;
   let ready = false;
+  let stopSession = () => {};
 
   const batch = () => {
     const start = committedBrowserCursor;
-    const end = browserEvents.length;
+    const end = start + browserEvents.length;
     const key = `${pageEvent}:${start}:${end}`;
-    const existing = pendingTokens.get(key);
-    if (existing) return existing;
-    const token = randomUUID();
-    const events = browserEvents.slice(start, end);
-    tokens.set(token, { start, end, page_event: pageEvent, status: "pending", key, page_hash: currentPageHash(), has_page: null, requested_page_hash: null });
-    const result = { ok: true, type: "batch", token, frontier: eventNumber, page_event: pageEvent, page_hash: currentPageHash(), events };
-    pendingTokens.set(key, result);
-    return result;
+    let token = pendingTokens.get(key)?.token;
+    if (!token) {
+      if (tokens.size >= MAX_BATCH_TOKENS) {
+        stopSession();
+        throw new Error("session batch token limit exceeded");
+      }
+      token = randomUUID();
+      tokens.set(token, { start, end, page_event: pageEvent, status: "pending", key, updates_hash: null });
+      pendingTokens.set(key, { token });
+    }
+    return { ok: true, type: "batch", token, frontier: eventNumber, page_event: pageEvent, page_hash: currentPageHash(), events: browserEvents.slice() };
   };
 
   const notifyPullWaiters = () => {
     for (const waiter of [...pullWaiters]) {
-      if (browserEvents.length === committedBrowserCursor) continue;
+      if (browserEvents.length === 0) continue;
       pullWaiters.delete(waiter);
       clearTimeout(waiter.timer);
       waiter.resolve(batch());
@@ -289,45 +413,60 @@ async function start(directory) {
   };
 
   const pull = waitSeconds => {
-    if (browserEvents.length > committedBrowserCursor || waitSeconds <= 0) return Promise.resolve(batch());
+    if (browserEvents.length > 0 || waitSeconds <= 0) return Promise.resolve(batch());
     return new Promise(resolve => {
       const waiter = { resolve, timer: setTimeout(() => { pullWaiters.delete(waiter); resolve(batch()); }, waitSeconds * 1_000) };
       pullWaiters.add(waiter);
     });
   };
 
-  const commit = async (token, requestedPage) => {
+  const commit = async (token, requestedUpdates) => {
     const record = tokens.get(token);
     if (!record) return { ok: false, error: "unknown batch token" };
-    const hasPage = requestedPage !== undefined;
-    const requestedPageHash = hasPage ? pageHash(requestedPage) : null;
+    const updates = validateUpdates(requestedUpdates);
+    const requestedUpdatesHash = updatesHash(updates);
     if (record.status !== "pending") {
-      if (record.has_page === hasPage && record.requested_page_hash === requestedPageHash) return record.result;
-      return { ok: false, error: "batch was already committed with a different page payload" };
+      if (record.updates_hash === requestedUpdatesHash) return record.result;
+      return { ok: false, error: "batch was already committed with a different updates payload" };
     }
-    record.has_page = hasPage;
-    record.requested_page_hash = requestedPageHash;
     if (record.page_event !== pageEvent || record.start !== committedBrowserCursor) {
+      record.updates_hash = requestedUpdatesHash;
       pendingTokens.delete(record.key);
       record.status = "failed";
       record.result = { ok: false, error: "batch is based on an old page or browser cursor", frontier: eventNumber, page_event: pageEvent, page_hash: currentPageHash() };
       return record.result;
     }
-    if (hasPage && Buffer.byteLength(requestedPage, "utf8") > MAX_BODY_BYTES) return { ok: false, error: "page is too large" };
-    const committedEvents = browserEvents.slice(record.start, record.end).map(event => event.id);
-    let update;
-    if (hasPage) {
-      page = requestedPage;
+    let nextPage = page;
+    try { if (updates.length) nextPage = applyUpdates(page, updates); } catch (cause) {
+      throw new Error(cause instanceof Error ? cause.message : "invalid page updates");
+    }
+    const committedCount = record.end - record.start;
+    const committedEvents = browserEvents.slice(0, committedCount).map(event => event.id);
+    retainedSubmissionBytes -= browserEventBytes.slice(0, committedCount).reduce((total, bytes) => total + bytes, 0);
+    const updateEvents = [];
+    for (const update of updates) {
       eventNumber += 1;
-      pageEvent = eventNumber;
-      update = { type: "update_ui", event_number: pageEvent, html: page };
-      eventLog.push(update);
+      updateEvents.push({ type: "update_ui", event_number: eventNumber, target: update.target, html: update.html });
     }
+    page = nextPage;
+    pageEvent = updateEvents.at(-1)?.event_number ?? pageEvent;
+    browserEvents.splice(0, committedCount);
+    browserEventBytes.splice(0, committedCount);
     committedBrowserCursor = record.end;
     pendingTokens.delete(record.key);
     record.status = "committed";
-    record.result = { ok: true, type: "committed", token, frontier: eventNumber, page_event: pageEvent, page_hash: currentPageHash(), events: committedEvents };
-    if (update) send(update);
+    record.updates_hash = requestedUpdatesHash;
+    record.result = {
+      ok: true,
+      type: "committed",
+      token,
+      frontier: eventNumber,
+      page_event: pageEvent,
+      page_hash: currentPageHash(),
+      events: committedEvents,
+      updates: updateEvents.map(({ event_number, target }) => ({ event_number, target }))
+    };
+    for (const update of updateEvents) send(update);
     return record.result;
   };
 
@@ -337,8 +476,7 @@ async function start(directory) {
     if (request.type === "show") return { ok: true, type: "page", page_event: pageEvent, page_hash: currentPageHash(), html: page };
     if (request.type === "push") {
       if (typeof request.token !== "string") return { ok: false, error: "batch token is required" };
-      if (request.page !== undefined && typeof request.page !== "string") return { ok: false, error: "page must be text" };
-      return commit(request.token, request.page);
+      return commit(request.token, request.updates === undefined ? [] : request.updates);
     }
     return { ok: false, error: "unknown control request" };
   };
@@ -351,7 +489,7 @@ async function start(directory) {
     let handled = false;
     connection.on("data", async chunk => {
       input += chunk;
-      if (input.length > CONTROL_MAX_BYTES || handled) return;
+      if (Buffer.byteLength(input, "utf8") > CONTROL_MAX_BYTES || handled) return;
       const newline = input.indexOf("\n");
       if (newline < 0) return;
       handled = true;
@@ -374,13 +512,18 @@ async function start(directory) {
     });
   }).catch(cause => { throw new Error(`cannot start local control channel: ${cause.message}`); });
 
-  const recordInteraction = event => mutate(async () => {
+  const recordInteraction = (event, bytes) => mutate(async () => {
     if (seenEvents.has(event.id)) return;
+    if (seenEvents.size >= MAX_UNIQUE_SUBMISSIONS || retainedSubmissionBytes + bytes > MAX_RETAINED_SUBMISSION_BYTES) {
+      stopSession();
+      throw new Error("session submission limit exceeded");
+    }
     seenEvents.add(event.id);
+    retainedSubmissionBytes += bytes;
     eventNumber += 1;
     const numbered = { ...event, event_number: eventNumber };
-    eventLog.push(numbered);
     browserEvents.push(numbered);
+    browserEventBytes.push(bytes);
     notifyPullWaiters();
   });
 
@@ -396,6 +539,7 @@ async function start(directory) {
     await unlink(controlPath(root)).catch(() => {});
     process.exit(code);
   };
+  stopSession = () => { void stop(1); };
   process.once("SIGINT", () => void stop(0));
   process.once("SIGTERM", () => void stop(0));
 
@@ -453,7 +597,7 @@ async function start(directory) {
       send = () => false;
       socket = undefined;
       if (!credential || !sessionUrl) return void stop(1);
-      if (!retryUntil) retryUntil = Date.now() + GRACE_SECONDS * 1_000;
+      if (!retryUntil) retryUntil = Date.now() + RECONNECT_RETRY_SECONDS * 1_000;
       retry();
     });
   };
@@ -483,7 +627,7 @@ function validSessionUrl(value) {
 }
 
 function usage() {
-  return "Usage:\n  npx letmeknow-cli serve <directory>\n  npx letmeknow-cli show <directory>\n  npx letmeknow-cli pull <directory> [--wait <seconds>]\n  npx letmeknow-cli push <directory> --batch <token> [--page <file|->]\n";
+  return "Usage:\n  npx letmeknow-cli serve <directory>\n  npx letmeknow-cli show <directory>\n  npx letmeknow-cli pull <directory> [--wait <seconds>]\n  npx letmeknow-cli push <directory> --batch <token> [--updates <file|->]\n";
 }
 
 function commandArgs() {
@@ -496,7 +640,7 @@ function commandArgs() {
         help: { type: "boolean", short: "h" },
         wait: { type: "string" },
         batch: { type: "string" },
-        page: { type: "string" }
+        updates: { type: "string" }
       },
       allowPositionals: true,
       strict: true
@@ -505,14 +649,14 @@ function commandArgs() {
     throw new Error(cause instanceof Error ? cause.message : "invalid arguments");
   }
   if (parsed.values.skill || parsed.values.help) {
-    if (parsed.positionals.length || parsed.values.wait !== undefined || parsed.values.batch !== undefined || parsed.values.page !== undefined) throw new Error(usage());
+    if (parsed.positionals.length || parsed.values.wait !== undefined || parsed.values.batch !== undefined || parsed.values.updates !== undefined) throw new Error(usage());
     return { command: parsed.values.skill ? "skill" : "help" };
   }
   const [command, directory, ...extra] = parsed.positionals;
   if (!command || !directory || extra.length) throw new Error(usage());
   if (!["serve", "show", "pull", "push"].includes(command)) throw new Error(usage());
-  if ((command === "serve" || command === "show") && (parsed.values.wait !== undefined || parsed.values.batch !== undefined || parsed.values.page !== undefined)) throw new Error(usage());
-  if (command === "pull" && (parsed.values.batch !== undefined || parsed.values.page !== undefined)) throw new Error(usage());
+  if ((command === "serve" || command === "show") && (parsed.values.wait !== undefined || parsed.values.batch !== undefined || parsed.values.updates !== undefined)) throw new Error(usage());
+  if (command === "pull" && (parsed.values.batch !== undefined || parsed.values.updates !== undefined)) throw new Error(usage());
   if (command === "push" && parsed.values.wait !== undefined) throw new Error(usage());
   let wait = 0;
   if (parsed.values.wait !== undefined) {
@@ -520,26 +664,9 @@ function commandArgs() {
     if (!Number.isFinite(wait) || wait < 0) throw new Error("--wait must be a non-negative number");
   }
   if (command === "push" && typeof parsed.values.batch !== "string") throw new Error("--batch is required");
-  return { command, directory, wait, token: parsed.values.batch, page: parsed.values.page };
+  return { command, directory, wait, token: parsed.values.batch, updates: parsed.values.updates };
 }
 
-async function readPageInput(filename) {
-  const chunks = [];
-  let length = 0;
-  if (filename === "-") {
-    for await (const chunk of process.stdin) {
-      const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-      length += value.byteLength;
-      if (length > MAX_BODY_BYTES) throw new Error("page is too large");
-      chunks.push(value);
-    }
-  } else {
-    const body = await readFile(resolve(filename));
-    if (body.byteLength > MAX_BODY_BYTES) throw new Error("page is too large");
-    chunks.push(body);
-  }
-  return Buffer.concat(chunks).toString("utf8");
-}
 
 let command;
 try {
@@ -553,8 +680,7 @@ try {
     if (command.command === "pull") packet = { type: "pull", wait_seconds: command.wait };
     else if (command.command === "show") packet = { type: "show" };
     else {
-      packet = { type: "push", token: command.token };
-      if (command.page !== undefined) packet.page = await readPageInput(command.page);
+      packet = { type: "push", token: command.token, updates: command.updates === undefined ? [] : await readUpdatesInput(command.updates) };
     }
     const result = await connectControl(root, packet);
     if (command.command === "show" && result.ok) process.stdout.write(result.html);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letmeknow-cli",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "A live agent-authored page with structured browser feedback.",
   "files": [
     "bin",
@@ -24,13 +24,13 @@
     "@cloudflare/vitest-plugin": "^1.1.0",
     "@cloudflare/workers-types": "^5.20260825.1",
     "@types/node": "^22.15.17",
-    "idiomorph": "0.7.4",
     "typescript": "^5.9.2",
     "vitest": "^4.1.11",
     "wrangler": "^4.126.0",
     "ws": "^8.21.3"
   },
   "dependencies": {
-    "mrmime": "^2.0.1"
+    "mrmime": "^2.0.1",
+    "parse5": "^8.0.1"
   }
 }