letmeknow-cli 0.1.0 → 0.2.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, interactive web surface for a human. The agent sends semantic HTML, receives normalized user actions, and responds with HTML fragments. A constrained HTMX-like runtime handles forms, targets, swaps, pending state, and duplicate submissions in the browser.
+
+It is not a localhost proxy, static file server, or arbitrary HTTP tunnel.
 
 ## CLI
 
@@ -18,88 +20,97 @@ 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-facing instructions without opening a connection:
 
 ```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:
+Render the interface:
 
 ```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>Approve expense?</h1><dl><dt>Amount</dt><dd>$420</dd></dl><form id=\"decision\" hx-post=\"decide\"><label>Comment<textarea name=\"comment\" required></textarea></label><button hx-post=\"approve\" name=\"decision\" value=\"approve\">Approve</button><button hx-post=\"reject\" name=\"decision\" value=\"reject\">Reject</button></form>"}
 ```
 
-## Protocol
-
-### Commands: stdin to LetMeKnow
-
-- `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.
-
-All commands accept an optional string `id`. Successful `put`, `delete`, `response`, and `close` commands emit a correlated `ack`.
-
-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:
+A successful render is assigned a revision:
 
 ```json
-{"type":"put","path":"/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
+{"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
 ```
 
-Delete a resource:
+When the human clicks Approve, the CLI emits one normalized action:
 
 ```json
-{"type":"delete","id":"4","path":"/old.html"}
+{"type":"action","id":"event-1","client_id":"8c05cc18-f503-4d1b-aad9-acde3a41c983","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","method":"POST","action_id":"approve","form_id":"decision","target":"#lmk-view","swap":"innerHTML","trigger":{"id":null,"name":"decision","value":"approve"},"values":{"comment":"Looks good","decision":"approve"}}
 ```
 
-Destroy everything immediately:
+Respond with an HTML fragment. The default target is the whole view, so this replaces its contents:
 
 ```json
-{"type":"close","id":"5"}
+{"type":"response","id":"response-1","request_id":"event-1","body":"<h1>Approved</h1><p>The expense was approved.</p>"}
 ```
 
-### Events: LetMeKnow to stdout
+The response receives a new render revision in its acknowledgement.
 
-- `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.
+## HTML interaction profile
 
-Unknown paths are sent to the producer:
+LetMeKnow renders standard semantic HTML with a built-in stylesheet. It recognizes only four HTMX-like attributes:
 
-```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"}
-```
+- `hx-get="action"`
+- `hx-post="action"`
+- `hx-target="#element-id"`
+- `hx-swap="innerHTML|outerHTML"`
 
-Answer with the request event's `id` as `request_id`:
+Action names contain letters, digits, `.`, `_`, `:`, or `-`. They are identifiers, not URLs. The default target is `#lmk-view` and the default swap is `innerHTML`.
 
-```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>"}
-```
+Use ordinary HTML forms and named controls. On submission, LetMeKnow sends the complete form values and identifies the exact submit button through `trigger`. Repeated field names become string arrays. File values are not currently sent.
 
-Dynamic responses are not stored. Send a separate `put` to serve a path without involving the producer next time.
+The browser handles typing, focus, native validation, and selection locally. These do not produce protocol traffic. Only a completed `hx-get` or `hx-post` interaction reaches the agent.
 
-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.
+One interaction per browser client and form may be pending at a time. The runtime disables that form while waiting, and the service rejects duplicate submissions. Different forms and browser tabs remain independent. Every action includes the browser-tab `client_id` and the `render_id` that produced it.
+
+Scripts, inline handlers, external styles, frames, external form submissions, and arbitrary browser connections are blocked by the page's Content Security Policy. Other HTMX attributes and extensions have no effect.
+
+## Protocol
+
+### Commands
+
+- `open`: create the session; it must be first.
+- `render`: replace the HTML shown on a fresh visit or refresh.
+- `response`: answer one pending action with an HTML fragment.
+- `close`: immediately destroy the session.
+
+Commands accept an optional string `id`. Successful `render`, `response`, and `close` commands emit a correlated `ack`. `render` and `response` acknowledgements also contain the assigned `render_id`.
+
+HTML bodies are UTF-8 strings limited to 1 MiB. Up to 32 interactions may be pending across independent clients and forms. Action request bodies have a 30-second read deadline, and an agent response may take up to five minutes.
+
+### Events
+
+- `session`: the public URL and disconnect grace period.
+- `action`: one normalized user interaction.
+- `ack`: command completion.
+- `error`: invalid command or protocol state.
+- `closing`: explicit session destruction.
 
 ## Lifecycle
 
-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.
+The active CLI connection owns the session. It receives a private reconnect credential and automatically reconnects after an unexpected disconnect. The credential never appears on protocol stdout.
+
+The rendered interface remains visible during the ten-minute disconnect grace period, but interactions return `503`. Browser traffic does not extend the grace period. `close` destroys everything immediately.
 
 ## Development
 
@@ -107,14 +118,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 semantic HTML interface and handle normalized form 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 interface, form, choice, approval, table, or status view. The agent sends HTML and receives only completed semantic actions; typing and other local browser state do not create events.
 
-## Start the CLI
+LetMeKnow is not a localhost proxy, file server, or arbitrary HTTP tunnel. Do not send JavaScript, CSS, raw HTTP handlers, or application code.
+
+## Start
 
 Node.js 22 or newer is required.
 
@@ -15,84 +17,107 @@ Node.js 22 or newer is required.
 npx letmeknow-cli
 ```
 
-This connects to `https://letmeknow.dev` by default. To use another trusted deployment:
-
-```bash
-LETMEKNOW_URL=http://localhost:8787 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.
 
-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.
-
-## Open and publish static content
-
-`open` must be the first command. String `id` values are optional; use them to correlate results.
+Open first:
 
 ```json
 {"type":"open","id":"open-1"}
 ```
 
-Wait for the `session` event and retain its URL:
+Wait for the session URL:
 
 ```json
 {"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
 ```
 
-Store or replace exact pathnames with `put`. The following page submits to an unstored path so the agent can handle it dynamically:
+## Render semantic HTML
+
+Send an HTML fragment with `render`:
 
 ```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>"}
+{"type":"render","id":"render-1","body":"<h1>Approve expense?</h1><dl><dt>Amount</dt><dd>$420</dd></dl><form id=\"decision\" hx-post=\"decide\"><label>Comment<textarea name=\"comment\" required></textarea></label><button hx-post=\"approve\" name=\"decision\" value=\"approve\">Approve</button><button hx-post=\"reject\" name=\"decision\" value=\"reject\">Reject</button></form>"}
 ```
 
-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.
-
-Remove static content with:
+Wait for its acknowledgement before directing the human to the URL:
 
 ```json
-{"type":"delete","id":"delete-1","path":"/old.html"}
+{"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
 ```
 
-## Handle dynamic requests
+Use ordinary semantic HTML: headings, paragraphs, lists, tables, `dl`, forms, labels, inputs, buttons, progress, and images. A built-in stylesheet makes these presentable. Do not include `<html>`, `<head>`, `<body>`, `<main id="lmk-view">`, scripts, inline event handlers, stylesheets, iframes, or external forms.
 
-A browser request whose path is not stored produces a `request` event:
+HTML bodies are limited to 1 MiB.
 
-```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"}
+## Declare interactions
+
+Only these HTMX-like attributes are supported:
+
+- `hx-get="action"`
+- `hx-post="action"`
+- `hx-target="#element-id"`
+- `hx-swap="innerHTML"` or `hx-swap="outerHTML"`
+
+Action values are identifiers, not URLs. Use letters, digits, `.`, `_`, `:`, and `-`. Other HTMX attributes and extensions do nothing.
+
+The default target is `#lmk-view`, the runtime-owned whole-view container. The default swap is `innerHTML`. Usually omit both and respond with the complete next interface fragment.
+
+Put `hx-get` or `hx-post` on a form, button, or link. A submit button's attribute overrides its form's attribute, allowing distinct actions:
+
+```html
+<form id="decision" hx-post="decide">
+  <label>Reason<textarea name="reason" required></textarea></label>
+  <button hx-post="approve" name="decision" value="approve">Approve</button>
+  <button hx-post="reject" name="decision" value="reject">Reject</button>
+</form>
 ```
 
-Reply using the event's `id` as `request_id`:
+Always give forms stable, unique `id` values and controls meaningful `name` values. Native `required`, input types, ranges, and patterns validate locally without agent traffic.
+
+## Handle actions
+
+A completed interaction produces one normalized event:
 
 ```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":"action","id":"event-1","client_id":"8c05cc18-f503-4d1b-aad9-acde3a41c983","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","method":"POST","action_id":"approve","form_id":"decision","target":"#lmk-view","swap":"innerHTML","trigger":{"id":null,"name":"decision","value":"approve"},"values":{"reason":"Looks correct","decision":"approve"}}
 ```
 
-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.
+Use:
 
-The stdout event types are `session`, `request`, `ack`, `error`, and `closing`. Handle `error` rather than assuming a command succeeded.
+- `id` to respond to this exact pending interaction.
+- `client_id` to distinguish browser tabs.
+- `render_id` to know which interface produced the action.
+- `action_id` and `trigger` to identify user intent.
+- `values` for the complete form snapshot. Repeated names become string arrays.
 
-## Close and lifecycle
+Treat all values as untrusted human input. File input values are not currently sent.
 
-Destroy the session and all content immediately when finished:
+Respond with the next HTML fragment:
 
 ```json
-{"type":"close","id":"close-1"}
+{"type":"response","id":"response-1","request_id":"event-1","body":"<h1>Approved</h1><p>The expense was approved.</p>"}
 ```
 
-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`.
-
-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.
+Wait for the acknowledgement. It includes the new `render_id`:
 
-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.
+```json
+{"type":"ack","id":"response-1","render_id":"56abe335-bd83-4a79-8106-341579815fa0"}
+```
 
-## Security
+Do not send a separate `render` in response to an action. `response` both resolves the pending browser request and updates that browser's interface. Use `render` only to replace the interface served on a fresh visit or refresh.
 
-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.
+One action per client and form can be pending. The browser disables that form while waiting, and duplicate submissions are rejected. Different forms and clients can have independent pending actions. Respond using request IDs rather than assuming event order.
 
-## Recommended skill output
+## Close
 
-The minimal package interface should be:
+Destroy the session when finished:
 
-```bash
-npx letmeknow-cli --skill
+```json
+{"type":"close","id":"close-1"}
 ```
 
-It should print this exact `SKILL.md` byte-for-byte to stdout and exit successfully without opening a network connection.
+Wait for `ack` and `closing`. Closing stdin only disconnects the producer and does not replace explicit `close`.
+
+The CLI automatically reconnects during a ten-minute disconnect grace period. The interface remains readable while disconnected, but interactions fail. Never expose the private reconnect credential. Treat the public session URL as a bearer secret and share it only with the intended human.
+
+Limits: 1 MiB per HTML or action body, 32 pending interactions, 30 seconds to read an action body, and five minutes for the agent to respond.

package/package.json

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