letmeknow-cli 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,8 @@
 # LetMeKnow
 
-LetMeKnow gives an agent a temporary interactive web surface for a human. It is not a localhost proxy and does not read directories. A Node CLI carries newline-delimited JSON between stdin/stdout and a Cloudflare Durable Object over one persistent WebSocket.
+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.
+
+It is not a localhost proxy or a programmable frontend. Agents provide presentation and semantic actions, not JavaScript or HTTP handlers.
 
 ## CLI
 
@@ -18,88 +20,156 @@ 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-facing skill file without opening a network connection:
+Print the agent instructions without connecting:
 
 ```bash
-npx letmeknow-cli --skill > SKILL.md
+npx letmeknow-cli --skill
 ```
 
-Start a session:
+## Example
+
+Open a session:
 
 ```json
-{"type":"open","id":"1"}
+{"type":"open","id":"open-1"}
 ```
 
-stdout returns the URL to share with the human:
+The CLI emits its temporary URL:
 
 ```json
-{"type":"session","id":"1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
+{"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
 ```
 
-There is no initial bundle. Initial resources and later updates are the same `put` command:
+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:
 
 ```json
-{"type":"put","id":"2","path":"/","content_type":"text/html; charset=utf-8","body":"<h1>Hello</h1>"}
-{"type":"put","id":"3","path":"/app.js","content_type":"text/javascript","body":"document.body.append(' ready')"}
+{"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; }"}
 ```
 
-## Protocol
+A successful render receives a revision:
 
-### Commands: stdin to LetMeKnow
+```json
+{"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
+```
 
-- `open` creates the session and emits `session`.
-- `put` stores or replaces an exact pathname.
-- `delete` removes a stored pathname.
-- `response` answers one pending browser request.
-- `close` immediately destroys the session.
+Submitting the form produces one normalized action:
 
-All commands accept an optional string `id`. Successful `put`, `delete`, `response`, and `close` commands emit a correlated `ack`.
+```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"}}
+```
 
-A resource supports `status`, `headers`, `content_type`, `encoding`, and `body`. `status` defaults to `200`, `encoding` to `utf8`, and `body` to an empty string. Header values may be strings or string arrays; arrays preserve repeated headers such as `Set-Cookie`. `content_type` overrides any `Content-Type` header. Binary bodies use base64:
+Respond with HTML for the target's contents:
 
 ```json
-{"type":"put","path":"/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
+{"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>"}
 ```
 
-Delete a resource:
+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.
 
-```json
-{"type":"delete","id":"4","path":"/old.html"}
+## HTML actions
+
+### Forms
+
+Interactive forms use standard HTML:
+
+```html
+<form id="decision" action="decide" method="post">
+  <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>
 ```
 
-Destroy everything immediately:
+Requirements:
 
-```json
-{"type":"close","id":"5"}
+- `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.
+
+### 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>
 ```
 
-### Events: LetMeKnow to stdout
+Its event has `form_id: null`, empty `values`, and the button's optional `id`, `name`, and `value` in `trigger`.
 
-- `session` contains the public URL and disconnect grace period.
-- `request` describes a browser request that did not match a stored resource.
-- `ack` confirms a command.
-- `error` reports a command or protocol error.
-- `closing` reports explicit destruction.
+### Targeted updates
 
-Unknown paths are sent to the producer:
+`data-lmk-target` accepts one element ID without `#`:
 
-```json
-{"type":"request","id":"cf-request-id","method":"POST","path":"/answer","query":"step=2","headers":{"content-type":"application/x-www-form-urlencoded","hx-request":"true"},"encoding":"utf8","body":"answer=yes"}
+```html
+<button data-lmk-action="load-more" data-lmk-target="results">Load more</button>
+<section id="results"></section>
 ```
 
-Answer with the request event's `id` as `request_id`:
+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.
+
+Typing, focusing, expanding `<details>`, native validation, scrolling, and other local browser behavior produce no agent events.
+
+## CSS
+
+`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.
+
+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.
+
+## Assets
+
+`put` stores or replaces passive resources only under `/assets/`:
 
 ```json
-{"type":"response","id":"6","request_id":"cf-request-id","status":200,"headers":{"content-type":"text/html; charset=utf-8","hx-trigger":"answered"},"body":"<strong>Accepted</strong>"}
+{"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:
+
+```html
+<img src="assets/logo.png" alt="Company logo">
 ```
 
-Dynamic responses are not stored. Send a separate `put` to serve a path without involving the producer next time.
+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.
+
+## Protocol
+
+### Commands
+
+- `open`: create the session; it must be first.
+- `render`: set the initial/current HTML and CSS for fresh clients.
+- `put`: store an asset under `/assets/`.
+- `response`: answer 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
 
-Production sessions use isolated `*.letmeknow.dev` origins, so root-relative links, forms, and asset URLs work normally. Local sessions use `/s/<code>/`; use relative URLs there. Stored paths ignore the URL query when matching. Dynamic events contain pathname and query separately. Methods, forms, cookies, HTMX headers, SPA API requests, status, response headers, and text or binary bodies pass through generically. Browser request bodies use UTF-8 only for recognized textual media types; absent, unrecognized, or invalid UTF-8 bodies use base64. Request, response, and stored-resource bodies are bounded to 1 MiB and are non-streaming; a stalled dynamic browser request body times out after 30 seconds, and a producer response may take up to 5 minutes. Stored and dynamic responses default to `Cache-Control: no-store`; an explicit producer header overrides that default. A session accepts at most 100 stored resources (10 MiB decoded total) and 32 simultaneous dynamic requests.
+- `session`: the public URL and disconnect grace period.
+- `action`: a normalized form or standalone-button action.
+- `ack`: command completion.
+- `error`: invalid command or protocol state.
+- `closing`: explicit session destruction.
 
-## Lifecycle
+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.
 
-The active CLI connection owns the session. The CLI receives an unguessable private reconnect credential in a private WebSocket message, keeps it off protocol stdout, and sends it as the WebSocket subprotocol on reconnect. The reconnect URL contains only the public session code. If the connection drops unexpectedly, it reconnects with that credential during the ten-minute grace period without requiring another `open` command; each connection attempt has a ten-second deadline, and a failed initial attempt exits nonzero while reconnect attempts continue within the grace period. Stored resources remain available for ten minutes, while unknown paths return `503`. Browser traffic does not extend the grace period. After the alarm fires all resources are deleted. A producer connection that never sends `open` is cleaned up after a short deadline. `close` deletes everything immediately.
+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.
+
+## 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.
+
+The URL is a bearer secret. Share it only with the intended human.
+
+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.
 
 ## Development
 
@@ -107,14 +177,5 @@ The active CLI connection owns the session. The CLI receives an unguessable priv
 npm install
 npm run dev
 npm test
-```
-
-The Worker uses one Durable Object per session. The object owns the producer WebSocket, stored resources, pending browser requests, and disconnect alarm. No D1 or R2 binding is required.
-
-Deploy with:
-
-```bash
 npm run deploy
 ```
-
-Production subdomain URLs require a proxied `*.letmeknow.dev` DNS record and a Worker route for `*.letmeknow.dev/*` in Cloudflare. The apex `letmeknow.dev` remains the control endpoint.

package/SKILL.md

@@ -1,13 +1,15 @@
 ---
 name: letmeknow
-description: Create a temporary browser surface for a human, serve static resources, and handle interactive HTTP requests through the LetMeKnow NDJSON CLI.
+description: Show a 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 web page or interactive UI from an agent. It is not a localhost proxy and does not read files or directories.
+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.
 
-## Start the CLI
+LetMeKnow is not a localhost proxy, persistent application, or arbitrary JavaScript environment.
+
+## Start
 
 Node.js 22 or newer is required.
 
@@ -15,84 +17,151 @@ Node.js 22 or newer is required.
 npx letmeknow-cli
 ```
 
-This connects to `https://letmeknow.dev` by default. To use another trusted deployment:
+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.
 
-```bash
-LETMEKNOW_URL=http://localhost:8787 npx letmeknow-cli
+Open first:
+
+```json
+{"type":"open","id":"open-1"}
+```
+
+Wait for the session URL:
+
+```json
+{"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
 ```
 
-Run the CLI as a long-lived child process. Write one compact JSON object per line to stdin, keep stdin open while the session is active, and read one JSON event per line from stdout. Read diagnostics from stderr separately. Do not mix stderr into the NDJSON stream.
+The URL immediately serves a shell with a waiting message. It is safe for the human to open it before the first render.
 
-## Open and publish static content
+## Render HTML and CSS
 
-`open` must be the first command. String `id` values are optional; use them to correlate results.
+Send an HTML fragment and optional page CSS:
 
 ```json
-{"type":"open","id":"open-1"}
+{"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; }"}
 ```
 
-Wait for the `session` event and retain its URL:
+A browser already waiting at the URL receives the render. Wait for the acknowledgement:
 
 ```json
-{"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
+{"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
 ```
 
-Store or replace exact pathnames with `put`. The following page submits to an unstored path so the agent can handle it dynamically:
+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.
 
-```json
-{"type":"put","id":"put-1","path":"/","content_type":"text/html; charset=utf-8","body":"<!doctype html><form method=\"post\" action=\"answer\"><label>Answer <input name=\"answer\"></label><button>Send</button></form>"}
+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.
+
+## Forms
+
+Interactive forms use standard HTML:
+
+```html
+<form id="decision" action="decide" method="post">
+  <label>Reason<textarea name="reason" required></textarea></label>
+  <button name="decision" value="approve" formaction="approve">Approve</button>
+  <button name="decision" value="reject" formaction="reject">Reject</button>
+</form>
+```
+
+Rules:
+
+- Use `method="post"`.
+- Give every interactive form a stable, unique `id`.
+- Give controls meaningful `name` values.
+- Use a relative 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 values are not currently sent.
+
+## 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`.
+
+## 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:
+
+```html
+<form id="search" action="search" method="post" data-lmk-target="results">
+  <input name="query">
+  <button>Search</button>
+</form>
+<section id="results"></section>
 ```
 
-Use relative links, form actions, and asset URLs so pages also work on local deployments, whose session URL includes a path prefix. Wait for `{"type":"ack","id":"put-1"}` before relying on the update. `status` defaults to `200`, `encoding` to `utf8`, and `body` to an empty string. `headers` accepts string values or string arrays; `content_type` overrides `Content-Type`. For binary content, set `encoding` to `base64`. Paths must start with `/` and must not contain a query. Query strings do not affect stored-path matching.
+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.
+
+## Handle actions
 
-Remove static content with:
+A completed interaction produces one normalized event:
 
 ```json
-{"type":"delete","id":"delete-1","path":"/old.html"}
+{"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"}}
 ```
 
-## Handle dynamic requests
+Use:
 
-A browser request whose path is not stored produces a `request` event:
+- `id` to respond to this exact pending action.
+- `client_id` to distinguish browser tabs.
+- `render_id` to identify the interface 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.
+
+Validate action IDs and values. Treat values as untrusted human input and HTML-escape them before reflecting them.
+
+Respond with HTML for the target's contents:
 
 ```json
-{"type":"request","id":"cf-request-id","method":"POST","path":"/answer","query":"step=2","headers":{"content-type":"application/x-www-form-urlencoded"},"encoding":"utf8","body":"answer=yes"}
+{"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>"}
 ```
 
-Reply using the event's `id` as `request_id`:
+A response may include `css` to replace the page CSS. Omitting `css` preserves the current CSS:
 
 ```json
-{"type":"response","id":"response-1","request_id":"cf-request-id","status":200,"content_type":"text/html; charset=utf-8","body":"<strong>Accepted</strong>"}
+{"type":"response","id":"response-2","request_id":"event-2","body":"<h1 class=\"success\">Approved</h1>","css":".success { color: green; text-align: center; }"}
 ```
 
-Wait for the correlated `ack`. Dynamic responses are not stored; use `put` if later requests should receive the same response without involving the agent. Treat request bodies and headers as untrusted input, and escape or validate values before placing them in HTML, headers, or commands.
+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`.
 
-The stdout event types are `session`, `request`, `ack`, `error`, and `closing`. Handle `error` rather than assuming a command succeeded.
+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.
 
-## Close and lifecycle
+## Assets
 
-Destroy the session and all content immediately when finished:
+Store passive resources only under `/assets/`:
 
 ```json
-{"type":"close","id":"close-1"}
+{"type":"put","id":"logo","path":"/assets/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
 ```
 
-Wait for `ack` and `closing`, then let the process exit. Closing stdin or terminating the CLI only disconnects the producer; it does not replace an explicit `close`.
+Reference them relatively:
 
-The CLI owns the session and automatically reconnects after an unexpected disconnect. Each connection attempt has a 10-second deadline. Reconnection is possible only during the 10-minute disconnect grace period; stored resources remain available then, but unstored paths return `503`, and browser traffic does not extend the grace period. An initial producer connection must send `open` within 30 seconds. Dynamic request bodies have a 30-second read deadline, and a `response` may take at most 5 minutes.
+```html
+<img src="assets/logo.png" alt="Company logo">
+```
 
-Limits per session: 1 MiB per stored, request, or response body; 100 stored resources; 10 MiB decoded stored content in total; and 32 simultaneous dynamic requests. Bodies are non-streaming. Default responses include `Cache-Control: no-store` unless explicitly overridden.
+`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.
 
-## Security
+## Close and limits
 
-Treat the session URL as a bearer secret: anyone who has it can access the surface and submit requests. Share it only with the intended human, and do not put it in source control, public logs, issue trackers, or unrelated output. The CLI also receives a separate private reconnect credential over the WebSocket, keeps it off protocol stdout, and uses it automatically. Never expose, persist, or ask the human for that credential. Use only a trusted `LETMEKNOW_URL`, because the deployment receives all page content and browser traffic.
+Destroy the session when finished:
 
-## Recommended skill output
+```json
+{"type":"close","id":"close-1"}
+```
 
-The minimal package interface should be:
+Wait for `ack` and `closing`. Closing stdin only disconnects the producer.
 
-```bash
-npx letmeknow-cli --skill
-```
+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.
 
-It should print this exact `SKILL.md` byte-for-byte to stdout and exit successfully without opening a network connection.
+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.

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "letmeknow-cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A temporary interactive web surface for agents.",
-  "files": ["bin", "SKILL.md"],
+  "files": [
+    "bin",
+    "SKILL.md"
+  ],
   "type": "module",
   "bin": {
     "letmeknow": "bin/letmeknow.js"