letmeknow-cli 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# 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.
+
+## CLI
+
+Node 22 or newer is required.
+
+```bash
+npx letmeknow-cli
+```
+
+The deployed service is used by default. Set `LETMEKNOW_URL` for local development:
+
+```bash
+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:
+
+```bash
+npx letmeknow-cli --skill > SKILL.md
+```
+
+Start a session:
+
+```json
+{"type":"open","id":"1"}
+```
+
+stdout returns the URL to share with the human:
+
+```json
+{"type":"session","id":"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:
+
+```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')"}
+```
+
+## 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:
+
+```json
+{"type":"put","path":"/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
+```
+
+Delete a resource:
+
+```json
+{"type":"delete","id":"4","path":"/old.html"}
+```
+
+Destroy everything immediately:
+
+```json
+{"type":"close","id":"5"}
+```
+
+### Events: LetMeKnow to stdout
+
+- `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.
+
+Unknown paths are sent to the producer:
+
+```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"}
+```
+
+Answer with the request event's `id` as `request_id`:
+
+```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>"}
+```
+
+Dynamic responses are not stored. Send a separate `put` to serve a path without involving the producer next time.
+
+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.
+
+## 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.
+
+## Development
+
+```bash
+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

@@ -0,0 +1,98 @@
+---
+name: letmeknow
+description: Create a temporary browser surface for a human, serve static resources, and handle interactive HTTP requests 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.
+
+## Start the CLI
+
+Node.js 22 or newer is required.
+
+```bash
+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 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.
+
+```json
+{"type":"open","id":"open-1"}
+```
+
+Wait for the `session` event and retain its 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:
+
+```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>"}
+```
+
+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:
+
+```json
+{"type":"delete","id":"delete-1","path":"/old.html"}
+```
+
+## Handle dynamic requests
+
+A browser request whose path is not stored produces a `request` event:
+
+```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"}
+```
+
+Reply using the event's `id` as `request_id`:
+
+```json
+{"type":"response","id":"response-1","request_id":"cf-request-id","status":200,"content_type":"text/html; charset=utf-8","body":"<strong>Accepted</strong>"}
+```
+
+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.
+
+The stdout event types are `session`, `request`, `ack`, `error`, and `closing`. Handle `error` rather than assuming a command succeeded.
+
+## Close and lifecycle
+
+Destroy the session and all content immediately when finished:
+
+```json
+{"type":"close","id":"close-1"}
+```
+
+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.
+
+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.
+
+## Security
+
+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.
+
+## Recommended skill output
+
+The minimal package interface should be:
+
+```bash
+npx letmeknow-cli --skill
+```
+
+It should print this exact `SKILL.md` byte-for-byte to stdout and exit successfully without opening a network connection.

package/bin/letmeknow.js

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeSync } from "node:fs";
+import readline from "node:readline";
+
+if (process.argv[2] === "--skill") {
+  if (process.argv.length !== 3) {
+    process.stderr.write("Usage: npx letmeknow-cli --skill\n");
+    process.exit(1);
+  }
+  writeSync(1, readFileSync(new URL("../SKILL.md", import.meta.url)));
+  process.exit(0);
+}
+
+const control = new URL(process.env.LETMEKNOW_URL || "https://letmeknow.dev");
+const graceSeconds = 10 * 60;
+const connectionAttemptTimeout = 10_000;
+const maxRetryDelay = 5_000;
+const subprotocolTokenPattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+let socket;
+let input;
+let credential;
+let sessionUrl;
+let retryTimer;
+let connectionTimer;
+let retryDelay = 100;
+let stdinClosed = false;
+let signalRequested = false;
+let explicitSessionClosed = false;
+let closeCommandAccepted = false;
+let closeCommandSent = false;
+let retryUntil = 0;
+let connected = false;
+let finished = false;
+const queued = [];
+
+function endpoint() {
+  const url = new URL(control);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = "/v1/connect";
+  url.search = "";
+  url.hash = "";
+  if (credential && sessionUrl) {
+    const publicUrl = new URL(sessionUrl);
+    const hostCode = publicUrl.hostname.match(/^([a-f0-9]{20})\.letmeknow\.dev$/);
+    const pathCode = publicUrl.pathname.match(/^\/s\/([a-f0-9]{20})(?:\/|$)/);
+    const code = hostCode?.[1] || pathCode?.[1];
+    if (code) {
+      url.searchParams.set("code", code);
+    }
+  }
+  return url;
+}
+
+function clearConnectionTimer() {
+  if (connectionTimer) clearTimeout(connectionTimer);
+  connectionTimer = undefined;
+}
+
+function finish(code) {
+  if (finished) return;
+  finished = true;
+  if (retryTimer) clearTimeout(retryTimer);
+  clearConnectionTimer();
+  input?.close();
+  process.exitCode = code;
+}
+
+function validCredential(value) {
+  return typeof value === "string" && subprotocolTokenPattern.test(value);
+}
+
+function validSessionUrl(value) {
+  if (typeof value !== "string") return false;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+  if (/^[a-f0-9]{20}\.letmeknow\.dev$/.test(url.hostname)) return true;
+  return /^\/s\/[a-f0-9]{20}(?:\/|$)/.test(url.pathname);
+}
+
+function isCloseCommand(line) {
+  try {
+    const packet = JSON.parse(line);
+    return packet !== null
+      && typeof packet === "object"
+      && !Array.isArray(packet)
+      && packet.type === "close"
+      && (packet.id === undefined || typeof packet.id === "string");
+  } catch {
+    return false;
+  }
+}
+
+function send(line) {
+  if (!socket || !connected || socket.readyState !== WebSocket.OPEN) return false;
+  try {
+    socket.send(line);
+    if (isCloseCommand(line)) closeCommandSent = true;
+    return true;
+  } catch {
+    try {
+      socket.close();
+    } catch {
+      // The close event still determines whether reconnect is needed.
+    }
+    return false;
+  }
+}
+
+function sendOrQueue(line) {
+  if (finished || closeCommandAccepted) return;
+  if (isCloseCommand(line)) closeCommandAccepted = true;
+  if (!send(line)) queued.push(line);
+}
+
+function flush() {
+  if (finished) return;
+  while (queued.length && !closeCommandSent) {
+    if (!send(queued[0])) break;
+    queued.shift();
+  }
+  if (closeCommandSent) queued.length = 0;
+  if (!queued.length && stdinClosed && !closeCommandSent && socket && connected) {
+    socket.close(1000, "stdin closed");
+  }
+}
+
+function protocolFailure(message) {
+  if (finished) return;
+  process.stderr.write(`letmeknow: server protocol error: ${message}\n`);
+  const current = socket;
+  if (current) {
+    try {
+      current.close(1000, "protocol error");
+    } catch {
+      // The process still exits below.
+    }
+  }
+  finish(1);
+}
+
+function handleMessage(event) {
+  if (finished) return;
+  if (typeof event.data !== "string") {
+    protocolFailure("binary WebSocket frame");
+    return;
+  }
+  const text = event.data;
+  let packet;
+  try {
+    packet = JSON.parse(text);
+  } catch {
+    protocolFailure("invalid JSON");
+    return;
+  }
+  if (!packet || typeof packet !== "object" || Array.isArray(packet)) {
+    protocolFailure("packet must be a JSON object");
+    return;
+  }
+  if (typeof packet.type !== "string") {
+    protocolFailure("packet type is required");
+    return;
+  }
+  if (packet.type === "credential") {
+    if (!validCredential(packet.credential)) {
+      protocolFailure("invalid credential");
+      return;
+    }
+    credential = packet.credential;
+    return;
+  }
+  if (packet.type === "session") {
+    if (!validSessionUrl(packet.url)) {
+      protocolFailure("invalid session URL");
+      return;
+    }
+    if (typeof packet.expires_after_disconnect !== "number"
+      || !Number.isFinite(packet.expires_after_disconnect)
+      || packet.expires_after_disconnect <= 0) {
+      protocolFailure("invalid session expiration");
+      return;
+    }
+    sessionUrl = packet.url;
+    retryDelay = 100;
+  }
+  if (packet.type === "closing") explicitSessionClosed = true;
+  process.stdout.write(`${text}\n`);
+}
+
+function retry() {
+  if (finished || signalRequested || explicitSessionClosed || closeCommandSent || (stdinClosed && !queued.length) || Date.now() >= retryUntil) {
+    finish(explicitSessionClosed || signalRequested || closeCommandSent || (stdinClosed && !queued.length) ? 0 : 1);
+    return;
+  }
+  retryTimer = setTimeout(() => {
+    retryTimer = undefined;
+    start();
+  }, retryDelay);
+  retryDelay = Math.min(retryDelay * 2, maxRetryDelay);
+}
+
+function start() {
+  if (finished || signalRequested || explicitSessionClosed || closeCommandSent) return;
+  const reconnecting = Boolean(credential && sessionUrl);
+  const current = socket = reconnecting
+    ? new WebSocket(endpoint(), credential)
+    : new WebSocket(endpoint());
+  connectionTimer = setTimeout(() => {
+    if (socket !== current || connected || finished) return;
+    clearConnectionTimer();
+    process.stderr.write("letmeknow: WebSocket connection attempt timed out\n");
+    try {
+      current.close();
+    } catch {
+      // The close event is not available when construction failed.
+    }
+    socket = undefined;
+    connected = false;
+    if (reconnecting) retry();
+    else finish(1);
+  }, connectionAttemptTimeout);
+  current.addEventListener("message", handleMessage);
+  current.addEventListener("error", () => {
+    if (!finished) process.stderr.write("letmeknow: WebSocket connection failed; retrying\n");
+  });
+  current.addEventListener("open", () => {
+    if (socket !== current || finished) return;
+    clearConnectionTimer();
+    connected = true;
+    retryDelay = 100;
+    if (reconnecting) retryUntil = 0;
+    flush();
+  });
+  current.addEventListener("close", (event) => {
+    if (socket !== current) return;
+    clearConnectionTimer();
+    connected = false;
+    if (finished) return;
+    socket = undefined;
+    if (closeCommandSent || signalRequested || explicitSessionClosed || (stdinClosed && !queued.length)) {
+      finish(0);
+      return;
+    }
+    if (!credential || !sessionUrl) {
+      process.stderr.write(`letmeknow: connection closed (${event.code}${event.reason ? `: ${event.reason}` : ""})\n`);
+      finish(1);
+      return;
+    }
+    if (!retryUntil) retryUntil = Date.now() + graceSeconds * 1_000;
+    retry();
+  });
+}
+
+input = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+input.on("line", (line) => {
+  if (!finished && line.trim() && !closeCommandAccepted) sendOrQueue(line);
+});
+input.on("close", () => {
+  if (finished) return;
+  stdinClosed = true;
+  if (!socket) {
+    if (!queued.length) finish(0);
+    return;
+  }
+  if (connected) flush();
+  else if (!queued.length) {
+    const current = socket;
+    clearConnectionTimer();
+    try {
+      current.close();
+    } catch {
+      // The process still exits below.
+    }
+    socket = undefined;
+    finish(0);
+  }
+});
+
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    signalRequested = true;
+    clearConnectionTimer();
+    if (socket) {
+      try {
+        socket.close(1000, signal);
+      } catch {
+        // The process still exits below.
+      }
+    }
+    finish(0);
+  });
+}
+
+start();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "letmeknow-cli",
+  "version": "0.1.0",
+  "description": "A temporary interactive web surface for agents.",
+  "files": ["bin", "SKILL.md"],
+  "type": "module",
+  "bin": {
+    "letmeknow": "bin/letmeknow.js"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "check": "tsc --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "test": "npm run check && vitest run && node --test tests/cli.test.js"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-plugin": "^1.1.0",
+    "@cloudflare/workers-types": "^5.20260825.1",
+    "@types/node": "^22.15.17",
+    "typescript": "^5.9.2",
+    "vitest": "^4.1.11",
+    "wrangler": "^4.126.0",
+    "ws": "^8.21.3"
+  }
+}