letmeknow-cli 0.3.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # LetMeKnow
 
-LetMeKnow gives an agent a temporary HTML and CSS workspace for a human. The agent renders a page, receives normalized form and button actions, and responds with HTML fragments. The browser runtime handles validation, form serialization, pending state, and targeted updates.
+LetMeKnow gives one agent and one human browser a temporary HTML and CSS workspace. The agent renders a page, receives normalized form and button actions, and responds with HTML fragments. A private browser WebSocket carries renders and actions; assets use ordinary HTTP.
 
 It is not a localhost proxy or a programmable frontend. Agents provide presentation and semantic actions, not JavaScript or HTTP handlers.
 
@@ -20,12 +20,12 @@ LETMEKNOW_URL=http://localhost:8787 npx letmeknow-cli
 
 stdin contains one compact JSON command per line. stdout contains one JSON event per line. Diagnostics go to stderr.
 
-Print the agent instructions without connecting:
-
 ```bash
 npx letmeknow-cli --skill
 ```
 
+prints the agent instructions without connecting.
+
 ## Example
 
 Open a session:
@@ -40,13 +40,13 @@ The CLI emits its temporary URL:
 {"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
 ```
 
-The URL immediately serves a styled shell with a waiting message. Send the initial HTML and optional CSS with `render`; a browser that is already open receives it without polling:
+The URL serves a trusted shell immediately. Send HTML and optional CSS with `render`:
 
 ```json
 {"type":"render","id":"render-1","body":"<h1>Search invoices</h1><form id=\"search\" action=\"search\" method=\"post\" data-lmk-target=\"results\"><label>Customer<input name=\"customer\" required></label><button>Search</button></form><section id=\"results\"><p>Enter a customer.</p></section>","css":"#results { margin-top: 2rem; }"}
 ```
 
-A successful render receives a revision:
+A connected browser receives the render immediately. The acknowledgement contains its revision:
 
 ```json
 {"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
@@ -55,16 +55,16 @@ A successful render receives a revision:
 Submitting the form produces one normalized action:
 
 ```json
-{"type":"action","id":"event-1","client_id":"8c05cc18-f503-4d1b-aad9-acde3a41c983","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","action_id":"search","form_id":"search","target_id":"results","trigger":{"id":null,"name":null,"value":null},"values":{"customer":"Acme Ltd"}}
+{"type":"action","id":"2ee81a6b-1035-40a7-a90d-c1e02f426baa","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","action_id":"search","form_id":"search","target_id":"results","trigger":{"id":null,"name":null,"value":null},"values":{"customer":"Acme Ltd"}}
 ```
 
-Respond with HTML for the target's contents:
+Respond to that ID with HTML for the target's contents:
 
 ```json
-{"type":"response","id":"response-1","request_id":"event-1","body":"<table><tr><th>Invoice</th><th>Amount</th></tr><tr><td>INV-42</td><td>$800</td></tr></table>"}
+{"type":"response","id":"response-1","request_id":"2ee81a6b-1035-40a7-a90d-c1e02f426baa","body":"<table><tr><th>Invoice</th><th>Amount</th></tr><tr><td>INV-42</td><td>$800</td></tr></table>"}
 ```
 
-The runtime assigns a new render revision and places the fragment inside `#results`. If `data-lmk-target` had been omitted, it would replace the contents of the whole workspace.
+The browser inserts the fragment into `#results`. Without `data-lmk-target`, the response replaces the whole workspace.
 
 ## HTML actions
 
@@ -74,54 +74,50 @@ Interactive forms use standard HTML:
 
 ```html
 <form id="decision" action="decide" method="post">
-  <label>
-    Comment
-    <textarea name="comment"></textarea>
-  </label>
+  <label>Comment<textarea name="comment"></textarea></label>
   <button name="decision" value="approve" formaction="approve">Approve</button>
   <button name="decision" value="reject" formaction="reject">Reject</button>
 </form>
 ```
 
-Requirements:
-
-- `method="post"`
-- A stable form `id`
-- A relative action identifier such as `search`, `approve`, or `invoice:inspect`
-- Meaningful control `name` values
-
-A submit button's standard `formaction` overrides the form's `action`. Native `required`, input types, ranges, and patterns validate locally. `FormData(form, submitter)` is captured before the form is disabled, so selected controls and the clicked submit button are included. Repeated names become string arrays. File inputs are rejected.
+Forms require `method="post"`, a stable `id`, a relative action identifier, and meaningful control names. A submit button's `formaction` overrides the form's `action`. Native validation runs locally. `FormData(form, submitter)` is captured before controls are disabled, so selected controls and the clicked button are included. Repeated names become string arrays. File inputs are rejected.
 
 ### Standalone actions
 
 A button can invoke an action without a form:
 
 ```html
-<button type="button" data-lmk-action="refresh-status" data-lmk-target="status">
-  Refresh
-</button>
+<button type="button" data-lmk-action="refresh-status" data-lmk-target="status">Refresh</button>
 ```
 
-Its event has `form_id: null`, empty `values`, and the button's optional `id`, `name`, and `value` in `trigger`.
+Its event has `form_id: null`, empty `values`, and its optional `id`, `name`, and `value` in `trigger`.
 
 ### Targeted updates
 
-`data-lmk-target` accepts one element ID without `#`:
+`data-lmk-target` accepts one bare element ID. All updates use `innerHTML`. There are no alternate swap modes or selector targets. The default target is `lmk-view`, the whole workspace.
 
-```html
-<button data-lmk-action="load-more" data-lmk-target="results">Load more</button>
-<section id="results"></section>
-```
+Typing, focusing, expanding `<details>`, validation, scrolling, and other local browser behavior produce no agent events.
 
-All updates use `innerHTML`. There are no alternate swap modes or arbitrary selector targets. The default target is the runtime-owned `lmk-view`, which means the whole workspace.
+## CSS
 
-Typing, focusing, expanding `<details>`, native validation, scrolling, and other local browser behavior produce no agent events.
+`render` accepts page CSS in its `css` field. A `response` may include `css` to replace it; omitting `css` preserves it.
 
-## CSS
+Modern CSS is supported, including grid, flexbox, media queries, variables, transitions, and print styles. External stylesheets, `@import`, scripts, inline handlers, and inline `style` attributes are blocked. Local assets work in HTML and CSS.
+
+## One browser client
 
-`render` accepts page-level CSS in its `css` field. A `response` may include `css` to replace the current page CSS; omitting it preserves the current CSS.
+At most one browser is active for a session. The first browser receives a private credential stored in that tab's `sessionStorage`.
 
-Normal modern CSS is supported, including grid, flexbox, media queries, variables, transitions, and print styles. External stylesheets, `@import`, scripts, inline event handlers, and inline `style` attributes are blocked. CSS and images may reference session assets with relative URLs.
+- Reloads and reconnects reuse the credential.
+- A competing browser triggers at most one liveness probe every five seconds.
+- If the active browser answers, the claimant sees “This session is open elsewhere.”
+- After a disconnect, the previous credential has a five-second exclusive reconnect period.
+- After five seconds, either the old browser or a new claimant may connect; first connection wins.
+- Laptop sleep does not invalidate the credential.
+
+The server sends a connecting browser one canonical snapshot of the current HTML, CSS, render ID, and pending actions. It does not replay user actions. The browser restores same-tab drafts from `sessionStorage`; drafts do not transfer to another browser.
+
+The server keeps committed page state and assets for the producer session. A full `render` replaces the page and clears old pending actions. A targeted response updates the canonical page. Browser disconnect alone does not delete state.
 
 ## Assets
 
@@ -131,45 +127,44 @@ Normal modern CSS is supported, including grid, flexbox, media queries, variable
 {"type":"put","id":"logo","path":"/assets/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
 ```
 
-Reference them relatively so local path-based sessions also work:
+Reference them relatively:
 
 ```html
 <img src="assets/logo.png" alt="Company logo">
 ```
 
-Assets answer only `GET` and `HEAD`. Each body is limited to 1 MiB. A session accepts at most 100 assets and 10 MiB of decoded asset data. Assets are removed with the session; there is no `delete` command.
+Assets answer only `GET` and `HEAD`. Each body is limited to 1 MiB. A session accepts 100 assets and 10 MiB decoded asset data. There is no `delete`; assets disappear with the session.
 
 ## Protocol
 
-### Commands
+Commands:
 
 - `open`: create the session; it must be first.
-- `render`: set the initial/current HTML and CSS for fresh clients.
+- `render`: replace the committed HTML and CSS and push it to the browser.
 - `put`: store an asset under `/assets/`.
-- `response`: answer one pending action with HTML and optional CSS.
+- `response`: resolve one pending action with HTML and optional CSS.
 - `close`: destroy the session immediately.
 
-Commands accept an optional string `id`. Successful commands emit correlated `ack` events. `render` and `response` acknowledgements also include the generated `render_id`.
-
-### Events
+Events:
 
-- `session`: the public URL and disconnect grace period.
-- `action`: a normalized form or standalone-button action.
+- `session`: public URL and producer disconnect grace.
+- `action`: normalized form or standalone-button action.
+- `cancelled`: the browser stopped waiting for an action.
 - `ack`: command completion.
 - `error`: invalid command or protocol state.
 - `closing`: explicit session destruction.
 
-One interaction per browser client, render, form, and target may be pending at a time. Conflicting submissions are rejected, while independent forms and targets can proceed concurrently. Match responses by action ID rather than event order.
+Actions remain pending for at most five minutes. One form or overlapping target can be pending at a time; independent regions may proceed concurrently. Match responses by action ID.
 
-HTML, CSS, asset, and action bodies are each limited to 1 MiB. Up to 32 independent actions may be pending. Action bodies have a 30-second read deadline, and an agent response may take up to five minutes.
+HTML, CSS, asset, and action bodies are each limited to 1 MiB. Up to 32 actions may be pending.
 
 ## Security and lifecycle
 
-HTML fragments are sanitized. Scripts, style elements, inline event handlers, HTMX attributes, frames, active metadata, external form actions, and invalid LetMeKnow attributes are removed. A strict Content Security Policy blocks arbitrary browser connections and external resources. Agent CSS is installed separately in a nonce-protected style element.
+HTML fragments are sanitized. Scripts, style elements, inline handlers, HTMX attributes, frames, active metadata, external form actions, and invalid LetMeKnow attributes are removed. CSP blocks arbitrary browser connections and external resources.
 
-The URL is a bearer secret. Share it only with the intended human.
+The URL is a bearer secret. Share it only with the intended human. Browser and producer reconnect credentials remain private and never appear in protocol output.
 
-The CLI owns the session and automatically reconnects after an unexpected disconnect. The shell, current render, and assets remain available during the ten-minute disconnect grace period, but actions fail. Browser traffic does not extend the grace period. `close` destroys everything immediately.
+If the producer disconnects, the current page remains visible, drafts are preserved, and actions are disabled. The CLI can reconnect for ten minutes. Browser traffic does not extend that grace. `close` or producer-grace expiry deletes page state, credentials, pending actions, and assets.
 
 ## Development
 

package/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: letmeknow
-description: Show a human a temporary HTML and CSS workspace and handle normalized form or button actions through the LetMeKnow NDJSON CLI.
+description: Show one human a temporary HTML and CSS workspace and handle normalized form or button actions through the LetMeKnow NDJSON CLI.
 ---
 
 # LetMeKnow
 
-Use LetMeKnow when a human needs a temporary rich document, dashboard, report, preview, form, approval, quiz, table, or status view. The agent supplies semantic HTML and CSS. The browser sends only declared actions; typing and other local state do not create events.
+Use LetMeKnow when one human needs a temporary rich document, dashboard, report, preview, form, approval, quiz, table, or status view. The agent supplies semantic HTML and CSS. The browser sends only declared actions; typing and local UI state do not create events.
 
 LetMeKnow is not a localhost proxy, persistent application, or arbitrary JavaScript environment.
 
@@ -19,8 +19,6 @@ npx letmeknow-cli
 
 Run it as a long-lived child process. Write one compact JSON object per line to stdin, keep stdin open, and read one JSON event per line from stdout. Read stderr separately.
 
-Open first:
-
 ```json
 {"type":"open","id":"open-1"}
 ```
@@ -31,25 +29,25 @@ Wait for the session URL:
 {"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
 ```
 
-The URL immediately serves a shell with a waiting message. It is safe for the human to open it before the first render.
+The URL immediately serves a shell with a waiting message. One browser may use it at a time.
 
 ## Render HTML and CSS
 
-Send an HTML fragment and optional page CSS:
-
 ```json
 {"type":"render","id":"render-1","body":"<h1>Search invoices</h1><form id=\"search\" action=\"search\" method=\"post\" data-lmk-target=\"results\"><label>Customer<input name=\"customer\" required></label><button>Search</button></form><section id=\"results\"><p>Enter a customer.</p></section>","css":"#results { margin-top: 2rem; }"}
 ```
 
-A browser already waiting at the URL receives the render. Wait for the acknowledgement:
+A connected browser receives the render immediately. Wait for its acknowledgement and retain the `render_id`:
 
 ```json
 {"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
 ```
 
-Use semantic HTML such as headings, sections, paragraphs, lists, tables, `dl`, forms, labels, controls, buttons, `details`, progress, and images. Do not include `<html>`, `<head>`, `<body>`, `<main id="lmk-view">`, scripts, style elements, inline event handlers, inline `style`, iframes, or HTMX attributes.
+Use semantic HTML: headings, sections, paragraphs, lists, tables, `dl`, forms, labels, controls, buttons, `details`, progress, and images. Do not include `<html>`, `<head>`, `<body>`, `<main id="lmk-view">`, scripts, style elements, inline handlers, inline `style`, iframes, or HTMX attributes.
+
+The optional `css` field supports modern CSS, including grid, flexbox, media queries, variables, transitions, and print styles. External stylesheets, `@import`, and remote resources do not work. Use relative session assets.
 
-The built-in stylesheet makes unstyled HTML usable. The optional `css` field supports normal modern CSS, including grid, flexbox, media queries, variables, transitions, and print styles. External stylesheets, `@import`, and remote resources do not work. Use relative asset URLs.
+A full `render` intentionally replaces the current page, resets drafts, and cancels actions from the previous render. Use `response` rather than `render` after a user action.
 
 ## Forms
 
@@ -66,29 +64,27 @@ Interactive forms use standard HTML:
 Rules:
 
 - Use `method="post"`.
-- Give every interactive form a stable, unique `id`.
+- Give each form a stable, unique `id`.
 - Give controls meaningful `name` values.
-- Use a relative action identifier containing letters, digits, `.`, `_`, `:`, or `-`.
+- Use an action identifier containing letters, digits, `.`, `_`, `:`, or `-`.
 - A submit button's standard `formaction` may override the form action.
 - Native `required`, input types, ranges, and patterns validate locally.
 
-The runtime captures `FormData(form, submitter)` before disabling the form. Selected radio buttons, checked boxes, ordinary controls, and the clicked submit button are therefore included. Repeated names become string arrays. File inputs are rejected; upload files separately as assets when needed.
+The runtime captures `FormData(form, submitter)` before disabling controls. Selected radios, checked boxes, ordinary controls, and the clicked submit button are included. Repeated names become string arrays. File inputs are rejected.
 
 ## Standalone actions
 
-Use a button when an action does not need a form:
-
 ```html
 <button type="button" data-lmk-action="refresh-status" data-lmk-target="status">
   Refresh
 </button>
 ```
 
-This is appropriate for refresh, retry, cancel, generate, inspect, load-more, and export actions. The event has `form_id: null`, empty `values`, and the button's optional `id`, `name`, and `value` in `trigger`.
+Use standalone actions for refresh, retry, cancel, generate, inspect, load-more, and export. Their events have `form_id: null`, empty `values`, and the button's optional `id`, `name`, and `value` in `trigger`.
 
 ## Whole and partial updates
 
-By default, a response replaces the contents of the whole workspace. To update a smaller region, put `data-lmk-target="element-id"` on the form or action button:
+Responses replace the whole workspace by default. To update a region, put `data-lmk-target="element-id"` on the form or action button:
 
 ```html
 <form id="search" action="search" method="post" data-lmk-target="results">
@@ -98,63 +94,62 @@ By default, a response replaces the contents of the whole workspace. To update a
 <section id="results"></section>
 ```
 
-The target is one bare element ID without `#`. Every update uses `innerHTML`; there are no other swap modes. A submit button or action button may override its form's target.
+The target is one bare element ID without `#`. Every update uses `innerHTML`. A submit button may override its form's target.
 
 ## Handle actions
 
-A completed interaction produces one normalized event:
-
 ```json
-{"type":"action","id":"event-1","client_id":"8c05cc18-f503-4d1b-aad9-acde3a41c983","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","action_id":"search","form_id":"search","target_id":"results","trigger":{"id":null,"name":null,"value":null},"values":{"query":"quarterly report"}}
+{"type":"action","id":"2ee81a6b-1035-40a7-a90d-c1e02f426baa","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","action_id":"search","form_id":"search","target_id":"results","trigger":{"id":null,"name":null,"value":null},"values":{"query":"quarterly report"}}
 ```
 
 Use:
 
-- `id` to respond to this exact pending action.
-- `client_id` to distinguish browser tabs.
-- `render_id` to identify the interface revision that produced it.
+- `id` to respond to this exact action.
+- `render_id` to identify the page revision that produced it.
 - `action_id` for user intent.
-- `form_id` and `target_id` for interaction context.
-- `trigger` to identify the clicked button.
-- `values` for the complete submitted form snapshot.
+- `form_id` and `target_id` for context.
+- `trigger` for the clicked button.
+- `values` for the submitted form snapshot.
 
-Validate action IDs and values. Treat values as untrusted human input and HTML-escape them before reflecting them.
+Validate actions and values. Treat values as untrusted and HTML-escape reflected text.
 
-Respond with HTML for the target's contents:
+Respond with HTML for the target contents:
 
 ```json
-{"type":"response","id":"response-1","request_id":"event-1","body":"<table><tr><th>Invoice</th><th>Amount</th></tr><tr><td>INV-42</td><td>$800</td></tr></table>"}
+{"type":"response","id":"response-1","request_id":"2ee81a6b-1035-40a7-a90d-c1e02f426baa","body":"<table><tr><th>Invoice</th><th>Amount</th></tr><tr><td>INV-42</td><td>$800</td></tr></table>"}
 ```
 
-A response may include `css` to replace the page CSS. Omitting `css` preserves the current CSS:
+A response may include `css` to replace the page CSS. Omitting it preserves the existing CSS:
 
 ```json
-{"type":"response","id":"response-2","request_id":"event-2","body":"<h1 class=\"success\">Approved</h1>","css":".success { color: green; text-align: center; }"}
+{"type":"response","id":"response-2","request_id":"event-2","body":"<h1 class=\"success\">Approved</h1>","css":".success { color: green; }"}
 ```
 
-Wait for the acknowledgement, which contains the new `render_id`. Do not send `render` in response to an action; use `response` with the action's `id` as `request_id`.
+Wait for the acknowledgement and its new `render_id`. Actions time out after five minutes. A `cancelled` event means the browser stopped waiting; do not respond to that action afterward. Independent regions may be pending concurrently, so always match by action ID.
 
-One action per client, render, form, and target can be pending. Conflicting actions are rejected. Independent forms and targets may proceed concurrently, so always match by action ID rather than event order.
+## One-browser behavior
 
-## Assets
+The first browser claims the session with a private credential. Reload and laptop wake reconnect automatically. A second browser cannot connect while the first is active.
 
-Store passive resources only under `/assets/`:
+Liveness is checked only when another browser tries to claim, at most once every five seconds. After a browser disconnect, its credential has five seconds of exclusive reconnect priority. After that, the first old or new browser to connect wins.
+
+A reconnect receives one canonical snapshot of committed HTML, CSS, render ID, and pending actions. It does not replay old user actions. Same-tab drafts are restored from `sessionStorage`; drafts do not transfer during takeover.
+
+## Assets
 
 ```json
 {"type":"put","id":"logo","path":"/assets/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
 ```
 
-Reference them relatively:
+Store resources only under `/assets/` and reference them relatively:
 
 ```html
 <img src="assets/logo.png" alt="Company logo">
 ```
 
-`encoding` is `utf8` by default or `base64` for binary data. Assets answer only `GET` and `HEAD`. There is no `delete`; replacement uses another `put`, and `close` removes all assets.
+`encoding` is `utf8` by default or `base64` for binary data. Assets answer only `GET` and `HEAD`. There is no `delete`; another `put` replaces an asset.
 
-## Close and limits
-
-Destroy the session when finished:
+## Close and lifecycle
 
 ```json
 {"type":"close","id":"close-1"}
@@ -162,6 +157,8 @@ Destroy the session when finished:
 
 Wait for `ack` and `closing`. Closing stdin only disconnects the producer.
 
-HTML, CSS, asset, and action bodies are each limited to 1 MiB. A session accepts 100 assets, 10 MiB decoded asset data, and 32 pending actions. Action bodies have a 30-second read deadline; the agent has five minutes to respond.
+If the producer disconnects, the page remains visible, drafts remain, and actions are disabled. The CLI has ten minutes to reconnect. Browser traffic does not extend that period. Explicit close or expiry deletes HTML, CSS, credentials, actions, and assets.
+
+Limits: 1 MiB per HTML, CSS, asset, or action body; 100 assets; 10 MiB decoded asset storage; 32 pending actions; five minutes per action.
 
-The CLI reconnects during a ten-minute disconnect grace period. The shell, current render, and assets remain readable while disconnected, but actions fail. Treat the URL as a bearer secret. Never expose the private reconnect credential.
+Treat the URL as a bearer secret. Never expose either private reconnect credential.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letmeknow-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A temporary interactive web surface for agents.",
   "files": [
     "bin",