@quo-systems/dock 0.1.0

package/human/html.ts

@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: Apache-2.0
+// A blueprint spoken as HTML, and a form heard back as arguments. Pure:
+// strings in, strings out, no document, no element, no event. This is the
+// whole vocabulary of the screen, so that a page can be proven with no
+// browser at all. Nothing here knows an avatar; the side hands in what she
+// answered and reads out what the human submitted.
+//
+//   form(ask)             the ask's input schema as fields, one per property
+//   values(ask, raw)      the submitted strings back as arguments, typed by the schema
+//   view(value, schema?)  an answer as a view, ordered by the output schema
+//   page(model)           the whole page: title, notice, forms, views, pushes
+import type { Ask, Blueprint, Json, JsonObject } from '@quo-systems/quo';
+import { SILENCE_TEXT, UNREACHED_TEXT, wordText, type Word } from '../beings/side.ts';
+
+// One property of an input schema, as the form needs it.
+export type Property = { type?: string; description?: string; enum?: Json[]; format?: string; default?: Json };
+export type Schema = { properties?: Record<string, Property>; required?: string[] };
+
+export const escape = (s: string): string => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+
+const props = (schema: JsonObject | undefined): [string, Property][] => Object.entries(((schema as Schema | undefined)?.properties ?? {}) as Record<string, Property>);
+const required = (schema: JsonObject | undefined): Set<string> => new Set(((schema as Schema | undefined)?.required ?? []) as string[]);
+
+// ---- a schema as a form
+
+// A property is one field by its type. A string is a text input, and a
+// format the browser knows, `password`, `date`, `email`, is the input's
+// type. A number is a number input. A boolean is a checkbox. An enum is a
+// select. An object or an array is a box for JSON, because a form has no
+// better face for a value the schema left open. A description is the label.
+export function field(name: string, p: Property, must: boolean): string {
+  const id = escape(name);
+  const label = `<label for="${id}">${id}${must ? ' <b>*</b>' : ''}${p.description ? ` <small>${escape(p.description)}</small>` : ''}</label>`;
+  const req = must ? ' required' : '';
+  if (Array.isArray(p.enum)) {
+    const options = p.enum.map((v) => `<option value="${escape(String(v))}">${escape(String(v))}</option>`).join('');
+    return `<p>${label}<select id="${id}" name="${id}"${req}>${must ? '' : '<option value=""></option>'}${options}</select></p>`;
+  }
+  if (p.type === 'boolean') return `<p><input type="checkbox" id="${id}" name="${id}" value="true">${label}</p>`;
+  if (p.type === 'number' || p.type === 'integer') return `<p>${label}<input type="number" id="${id}" name="${id}"${p.type === 'integer' ? ' step="1"' : ' step="any"'}${req}></p>`;
+  if (p.type === 'string' || p.type === undefined) {
+    const kind = p.format === 'password' || p.format === 'date' || p.format === 'email' || p.format === 'time' ? p.format : 'text';
+    return `<p>${label}<input type="${kind}" id="${id}" name="${id}"${req}></p>`;
+  }
+  return `<p>${label}<textarea id="${id}" name="${id}" placeholder="JSON"${req}></textarea></p>`;
+}
+
+// The ask as a form: its name is the button, its description the legend's
+// small print, and `data-ask` is how the surface says which ask was sent.
+export function form(ask: Ask): string {
+  const must = required(ask.input);
+  const fields = props(ask.input)
+    .map(([name, p]) => field(name, p, must.has(name)))
+    .join('');
+  return `<form data-ask="${escape(ask.name)}"><fieldset><legend>${escape(ask.name)}${ask.description ? ` <small>${escape(ask.description)}</small>` : ''}</legend>${fields}<p><button>${escape(ask.name)}</button></p></fieldset></form>`;
+}
+
+// ---- the form heard back
+
+// What the surface hands back: every field by name, as the string the
+// browser sends. A checkbox not ticked sends nothing.
+export type Raw = Record<string, string>;
+
+// The strings typed by the schema. An empty field that is not required is
+// left out, so the being sees what the human said and nothing else; an
+// empty required field goes as the empty string, and the being answers.
+// A JSON box that does not parse is an error the side shows before asking.
+export function values(ask: Ask, raw: Raw): { args: JsonObject } | { error: string } {
+  const args: JsonObject = {};
+  const must = required(ask.input);
+  for (const [name, p] of props(ask.input)) {
+    const s = raw[name];
+    if (p.type === 'boolean') {
+      if (s === 'true') args[name] = true;
+      else if (must.has(name)) args[name] = false;
+      continue;
+    }
+    if (s === undefined || (s === '' && !must.has(name))) continue;
+    if (p.type === 'number' || p.type === 'integer') {
+      const n = Number(s);
+      if (s === '' || Number.isNaN(n)) return { error: `${name} is a number` };
+      args[name] = n;
+    } else if (p.type === 'string' || p.type === undefined || Array.isArray(p.enum)) {
+      args[name] = s;
+    } else {
+      try {
+        args[name] = JSON.parse(s) as Json;
+      } catch {
+        return { error: `${name} is not JSON` };
+      }
+    }
+  }
+  return { args };
+}
+
+// ---- an answer as a view
+
+// A value has one face by its shape. A primitive is text. An object is a
+// table of its keys, in the output schema's order when she declared one and
+// her own order otherwise, each value viewed in turn. A list of objects is
+// one table with a column per key seen; any other list is a list. Null is
+// the word nothing, so that an answer of null is never a blank.
+export function view(value: Json, schema?: JsonObject): string {
+  if (value === null) return '<i>nothing</i>';
+  if (typeof value !== 'object') return escape(String(value));
+  if (Array.isArray(value)) {
+    if (value.length && value.every((v) => v !== null && typeof v === 'object' && !Array.isArray(v))) {
+      const rows = value as JsonObject[];
+      const keys = [...new Set(rows.flatMap((r) => Object.keys(r)))];
+      const head = keys.map((k) => `<th>${escape(k)}</th>`).join('');
+      const body = rows.map((r) => `<tr>${keys.map((k) => `<td>${k in r ? view(r[k] as Json) : ''}</td>`).join('')}</tr>`).join('');
+      return `<table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table>`;
+    }
+    return value.length ? `<ul>${value.map((v) => `<li>${view(v)}</li>`).join('')}</ul>` : '<i>none</i>';
+  }
+  const declared = props(schema).map(([k]) => k);
+  const keys = [...declared.filter((k) => k in value), ...Object.keys(value).filter((k) => !declared.includes(k))];
+  if (!keys.length) return '<i>empty</i>';
+  return `<table>${keys.map((k) => `<tr><th>${escape(k)}</th><td>${view(value[k] as Json, (props(schema).find(([n]) => n === k)?.[1] as JsonObject | undefined))}</td></tr>`).join('')}</table>`;
+}
+
+// The three words for "no object", and the object, each with a face. An
+// error object is the answer she gave, marked; silence and unreached are
+// what the side says about them, since they carry nothing themselves.
+export function face(w: Word, schema?: JsonObject): string {
+  if (w.word === 'object') return `<div class="answer">${view(w.value, schema)}</div>`;
+  if (w.word === 'error') return `<div class="answer error">${view(w.value)}</div>`;
+  if (w.word === 'silence') return `<div class="answer silence">${escape(SILENCE_TEXT)}</div>`;
+  if (w.word === 'quo') return `<div class="answer word">${escape(wordText(w.name))}</div>`;
+  return `<div class="answer unreached">${escape(UNREACHED_TEXT)}</div>`;
+}
+
+// ---- the page
+
+// Everything the screen shows, as data. The side keeps one of these and
+// hands it here after every change; the page is a function of it.
+export type Model = {
+  blueprint: Blueprint | null; // her describe for this human, or nothing yet
+  notice: string; // one line about where the human stands: in, not in, an error before an ask
+  answers: Record<string, Word>; // the last answer per ask, shown under its form
+  pushes: JsonObject[]; // every push from the world, newest last
+};
+
+// The title is the one hint the notes may carry: a string named `name`.
+// The rest of the notes is shown as a view and read as nothing else.
+export function title(bp: Blueprint | null): string {
+  const n = bp?.notes;
+  return n !== null && typeof n === 'object' && !Array.isArray(n) && typeof n.name === 'string' && n.name ? n.name : 'quo';
+}
+
+export function page(m: Model): string {
+  const bp = m.blueprint;
+  const asks = bp
+    ? bp.asks
+        .map((a) => {
+          const w = m.answers[a.name];
+          return `<section>${form(a)}${w ? face(w, a.output) : ''}</section>`;
+        })
+        .join('')
+    : '';
+  const notes = bp && bp.notes !== null && !(typeof bp.notes === 'object' && !Array.isArray(bp.notes) && !Object.keys(bp.notes).length) ? `<aside class="notes">${view(bp.notes)}</aside>` : '';
+  const pushes = m.pushes.length ? `<section class="pushes"><h2>pushes</h2><ol>${m.pushes.map((p) => `<li>${view(p)}</li>`).join('')}</ol></section>` : '';
+  return `<header><h1>${escape(title(bp))}</h1><p class="notice">${escape(m.notice)}</p></header>${notes}<main>${asks}</main>${pushes}`;
+}

package/human/quo-human.md

@@ -0,0 +1,86 @@
+# The human side
+
+This is how a Quo world speaks to a human, and how a human speaks back. It
+is one side of the avatar described in `packages/dock/beings/quo-dock.md`, which
+owns the avatar, the front desk, the credential exchange and the shared
+invariants; this document assumes all of that and adds only what a screen
+needs. It names no transport and no model. A tab is a device with a harbor
+of its own, and where its bytes go is `packages/dock/harbor/quo-harbor.md`.
+
+The claim it will make good on: a human needs no page written for them. A
+screen is a blueprint spoken as HTML. The user being's describe for this
+asker becomes the forms the human sees, a submitted form becomes a named
+ask, an answer becomes a view, a push becomes a notification, and the three
+words for "no object" each have a face. Nothing the screen shows exists
+anywhere but in a blueprint, so every world gets a screen for free and no
+world gets a screen it did not describe.
+
+What this document decides, in its own sitting:
+
+- how a JSON Schema input becomes a form without a designer;
+- how an output schema, and an answer, become a view;
+- what the blueprint's notes may carry as rendering hints without becoming
+  state, and what they may never carry;
+- how a standing is a page, and a digest change is a refreshed page;
+- how the same screen is a guest one minute and an occupant the next, and
+  what the human sees at each of the three words;
+- how a native app shows many worlds: one screen per ward, a switcher
+  between them, and the device's own beings offered to each through gates;
+- what one avatar class, one `side` implementation and one suite look like
+  for a screen, proven on the memory harbor with no browser at all.
+
+Until that sitting, the only rule in force is the one law from the trunk:
+the human is an occupant, reached through an avatar, seeing what the gate
+shows.
+
+## The screen today, minimal on purpose
+
+The sitting above has not happened. What stands is the least screen that
+speaks a blueprint as HTML with no page written for any world, so that the
+rest of the dock is not held up by a design. Three pieces under
+`packages/dock/human/`, and the tab that holds them:
+
+- `html.ts` is pure, strings in and strings out, and is the screen's whole
+  vocabulary. An input schema is a form with one field per property by
+  type: a string is a text input, and `password`, `date`, `email` and
+  `time` are the input's type; a number is a number input; a boolean is a
+  checkbox; an enum is a select; an object or an array is a box for JSON.
+  The submitted strings come back as arguments typed by the schema, an
+  empty optional field left out. An answer is a view: a primitive is text,
+  an object a table of its keys in the output schema's order when she
+  declared one, a list of objects one table, null the word nothing. The
+  three words for "no object" each have a face, an error object marked,
+  silence and each of the ward's words saying what the side says of them.
+  The notes may carry one hint, a string `name` that titles the page; the
+  rest is shown as a view and read as nothing else.
+- `screen.ts` is the side: one avatar and one surface, where a surface can
+  only show a page and hand back a submitted form. The side keeps the
+  model, speaks it as a page after every change, calls her when a form
+  comes back, and re-asks her describe after every call, so a digest that
+  moved is a page that moved. A push is appended and shown as it lands. A
+  describe that fails leaves the last page standing and says so in the
+  notice.
+- `dom.ts` is the surface on an element, the one file that touches one.
+- `tab.ts` is the harbor in the tab and the exchange, unchanged from the
+  first screen, and hands the avatar to the side.
+
+Proven in `packages/dock/test/human.test.ts` on the memory harbor with a fake
+surface and no browser, and in `packages/dock/test/terrain/browser.test.ts` in a
+real Chromium against a daemon on loopback, behind `npm run check:terrain`.
+
+What it leaves to the sitting above, deliberately: any design, a switcher
+between worlds, the guest's page before the exchange, the native app, and
+every rendering hint beyond `name`. None of it blocks a world from having
+a screen today.
+
+## The tab
+
+The tab is a device. The page boots a browser harbor on a seed minted into
+the tab's store the first time, one ward with one avatar in it, and dials
+the world's `quo.` route. The exchange happens once: the owner password
+goes to `/tab/login`, which answers a nonce and the ward pk, and the
+avatar in the tab knocks the front desk over the socket with the nonce
+under the `tab` proof kind, is handed the invitation the user being minted,
+and joins her. From then on there is no cookie and no token anywhere, and
+a reload asks nothing: the seed and the standing are in the tab's store.
+Live on the lab at `web.lab.quo.systems/tab`.

package/human/screen.ts

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: Apache-2.0
+// The human side: one avatar, one surface. The surface is the least a
+// screen can be: it shows a page and hands back a submitted form, and that
+// is all this side asks of a terrain. A DOM is one surface; a test is
+// another. The side keeps the model, speaks it as a page after every change
+// through `html.ts`, calls the avatar when a form comes back, and re-asks
+// her describe after each call, so a digest that moved is a page that
+// moved. A push is appended and shown the moment it lands.
+import { digest } from '@quo-systems/quo';
+import type { Blueprint, JsonObject } from '@quo-systems/quo';
+import type { Avatar } from '../beings/avatar.ts';
+import { word, type Serving } from '../beings/side.ts';
+import { page, values, type Model, type Raw } from './html.ts';
+
+export type Surface = {
+  show(html: string): void;
+  // The surface calls this when a form is submitted: the ask's name and
+  // the fields as strings. Set once by the side.
+  onSubmit: ((ask: string, raw: Raw) => void) | undefined;
+};
+
+// `after` runs when a call is done, as it does for the model side: a harbor
+// that must write what the ward changed hooks it.
+export async function screenSide(avatar: Avatar, surface: Surface, after: () => Promise<void> = async () => {}, notice = ''): Promise<Serving & { model: Model; refresh(): Promise<void> }> {
+  const model: Model = { blueprint: null, notice, answers: {}, pushes: [] };
+  let seen: string | null = null;
+  const show = () => surface.show(page(model));
+
+  // Her describe, again: the page follows the digest.
+  const refresh = async () => {
+    const bp = await avatar.tools();
+    if ('error' in bp && !('asks' in bp)) {
+      // the last page she gave stays, with the answers under it, and the
+      // notice says where the human stands now
+      model.notice = `not in: ${bp.error}`;
+    } else {
+      const d = await digest(bp as Blueprint);
+      if (d !== seen) {
+        seen = d;
+        model.blueprint = bp as Blueprint;
+        for (const k of Object.keys(model.answers)) if (!(bp as Blueprint).asks.some((a) => a.name === k)) delete model.answers[k];
+      }
+    }
+    show();
+  };
+
+  surface.onSubmit = (name, raw) => void submit(name, raw);
+  const submit = async (name: string, raw: Raw) => {
+    const ask = model.blueprint?.asks.find((a) => a.name === name);
+    if (!ask) return;
+    const v = values(ask, raw);
+    if ('error' in v) {
+      model.answers[name] = { word: 'error', value: { error: v.error } };
+      return show();
+    }
+    model.answers[name] = word(await avatar.call(name, v.args));
+    await after();
+    await refresh();
+  };
+
+  const ear = (object: JsonObject) => {
+    model.pushes.push(object);
+    show();
+  };
+  avatar.ears.add(ear);
+
+  await refresh();
+  return {
+    model,
+    refresh,
+    close: async () => {
+      avatar.ears.delete(ear);
+      surface.onSubmit = undefined;
+    },
+  };
+}

package/human/tab.ts

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+// The tab: a page in a tab that is a world. The tab boots a browser harbor
+// on a seed minted into IndexedDB the first time, a ward with one avatar in
+// it, and dials the world's quo. route. The exchange, once: the owner
+// password goes to the web route, which mints a nonce the desk honours
+// under the `tab` proof kind; the avatar in the tab knocks the desk over the
+// socket with it, joins the user being, and from then on there is no cookie
+// and no token anywhere. The second time the page opens, she already holds
+// `user` and nothing is asked.
+//
+// The screen itself is the human side in `screen.ts` over the DOM surface
+// in `dom.ts`: her describe as forms, an answer as a view, a push on the
+// page. This file is the harbor and the exchange, and hands her over.
+import type { Invitation } from '@quo-systems/quo';
+import { BrowserHarbor } from '../harbor/browser.ts';
+import { Avatar, USER } from '../beings/avatar.ts';
+import { screenSide } from './screen.ts';
+import { domSurface } from './dom.ts';
+
+export type Config = { quo: string; web: string };
+
+const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Record<string, string> = {}): HTMLElementTagNameMap[K] => {
+  const e = document.createElement(tag);
+  if (text) e.textContent = text;
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, v);
+  return e;
+};
+
+export async function start(cfg: Config, root: HTMLElement = document.body): Promise<void> {
+  const status = el('p', 'booting');
+  const screen = el('div');
+  root.append(status, screen);
+  const say = (s: string) => (status.textContent = s);
+
+  // The harbor in the tab: one database, one ward, one avatar, for good.
+  const harbor = new BrowserHarbor('quo');
+  await harbor.boot();
+  const main = harbor.wards.get('main') ?? (await harbor.create('main', 'me'));
+  if (!main.being('me')) await main.ask('boot', { key: 'me', class: 'Avatar' });
+  const me = main.being('me') as Avatar;
+  harbor.dial(cfg.quo);
+
+  // The screen: every call rotates her keys and a same-ward ask never
+  // crosses the harbor, so the side saves after each one.
+  const show = async (notice: string) => {
+    status.remove();
+    await screenSide(me, domSurface(screen), () => main.save(), notice);
+  };
+
+  // Already in: reconnect, nothing minted.
+  const had = await me.tools();
+  if ('asks' in had) return show('in, as before');
+
+  // The exchange, once: the owner password for a nonce, the nonce for an
+  // invitation the user being mints, the invitation for a standing.
+  const form = el('form');
+  const identity = el('input', '', { name: 'identity', value: 'tab', placeholder: 'identity' });
+  const password = el('input', '', { name: 'password', type: 'password', placeholder: 'owner password' });
+  const go = el('button', 'enter');
+  form.append(identity, password, go);
+  root.insertBefore(form, screen);
+  say(`not in (${had.error}): the owner password opens the world`);
+  form.onsubmit = async (ev) => {
+    ev.preventDefault();
+    say('asking the world');
+    let res: Response;
+    try {
+      res = await fetch(`${cfg.web}/tab/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: password.value, identity: identity.value }) });
+    } catch (e) {
+      return say(`the world did not answer: ${(e as Error).message}`);
+    }
+    if (!res.ok) return say(`refused: ${(await res.json().catch(() => ({ error: res.status })) as { error?: string }).error ?? res.status}`);
+    const { nonce, ward } = (await res.json()) as { nonce: string; ward: string };
+    password.value = '';
+    say('knocking');
+    const got = await me.enter({ ward } as Invitation, { kind: 'tab', nonce });
+    await main.save(); // the knock went through her own door, which the harbor never sees
+    if (!('asks' in got)) return say(`not in: ${got.error}`);
+    form.remove();
+    await show(`in, as ${identity.value}`);
+  };
+}
+
+export { USER };

package/mcp/agent.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: Apache-2.0
+// The model side as an event-driven agent: the world is the loop. The user
+// being holds a standing to the agent's avatar and asks her when something
+// happens; that ask is a push, and her `notify` answers at once, so the ask
+// is never held open. The push lands in her inbox, which is the queue, in
+// her cells. This side drains the inbox one event at a time: it starts a
+// run with the event, and when the run ends she asks the user being back on
+// her own standing with the result. One run at a time, in the order the
+// events came, across a restart too, because the queue is in the partition
+// and not in this process. What a run may do is the gate; how it behaves
+// is its constitution, the folder it runs in.
+import { spawn } from 'node:child_process';
+import type { Json, JsonObject } from '@quo-systems/quo';
+import type { Avatar } from '../beings/avatar.ts';
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving } from '../beings/side.ts';
+
+// A run: the event in, a result out. Two exist here: any function, and a
+// process in a folder. The runner of runner.ts is a third when handed as a
+// function.
+export type Run = (event: JsonObject) => Promise<Json>;
+
+// The ask on the user being that takes the result. Gated to devices; the
+// agent's client identity is what the gate reads.
+export const REPORT = 'report';
+
+// `claude -p` or any CLI agent: the command runs in the agent's folder with
+// the event, as JSON, as its last argument. The result is what it printed.
+// A non-zero exit is an error object with what it said on stderr.
+export function processRun(command: string, args: string[], dir: string): Run {
+  return (event) =>
+    new Promise((ok) => {
+      const child = spawn(command, [...args, JSON.stringify(event)], { cwd: dir, stdio: ['ignore', 'pipe', 'pipe'] });
+      let out = '';
+      let err = '';
+      child.stdout.on('data', (c: Buffer) => (out += c.toString()));
+      child.stderr.on('data', (c: Buffer) => (err += c.toString()));
+      child.on('error', (e) => ok({ error: e.message }));
+      child.on('close', (code) => ok(code === 0 ? { output: out.trim() } : { error: `exit ${code}`, stderr: err.trim() }));
+    });
+}
+
+export type Agent = Serving & {
+  // Resolves when the queue is empty and no run is in flight.
+  idle(): Promise<void>;
+};
+
+// `after` runs when her cells changed and when an ask is done, as in the
+// other sides: a harbor that must write what the ward changed hooks it.
+export function agentSide(avatar: Avatar, run: Run, after: () => Promise<void> = async () => {}): Agent {
+  let draining: Promise<void> = Promise.resolve();
+  let open = true;
+  const inbox = () => avatar.cells.inbox as JsonObject[];
+
+  async function one(event: JsonObject): Promise<void> {
+    let result: Json;
+    try {
+      result = await run(event);
+    } catch (e) {
+      result = { error: e instanceof Error ? e.message : String(e) };
+    }
+    // The report is an ask like any other. Silence and unreached are told
+    // apart and dropped: a report is never retried, and never held.
+    const w = word(await avatar.call(REPORT, { event, result }));
+    if (w.word === 'silence' || w.word === 'unreached' || w.word === 'quo') say({ dropped: w.word === 'silence' ? SILENCE_TEXT : w.word === 'quo' ? wordText(w.name) : UNREACHED_TEXT });
+    await after();
+  }
+
+  // One at a time, first in first out, until the inbox is empty.
+  function drain(): Promise<void> {
+    draining = draining.then(async () => {
+      while (open && inbox().length > 0) {
+        const event = inbox().shift()!;
+        await after(); // the event left the queue before the run starts: a crash mid-run loses it, and never runs it twice
+        await one(event);
+      }
+    });
+    return draining;
+  }
+
+  // A dropped report is told to her other sides, if any: the agent itself has no ear for it.
+  const say = (object: JsonObject) => { for (const ear of avatar.ears) if (ear !== ear0) ear(object); };
+  const ear0 = () => void drain();
+  avatar.ears.add(ear0);
+  void drain(); // whatever waited while no side was up
+
+  return {
+    idle: () => draining,
+    close: async () => {
+      open = false;
+      avatar.ears.delete(ear0);
+      await draining;
+    },
+  };
+}

package/mcp/http.ts

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: Apache-2.0
+// The MCP endpoint on the mcp route: streamable HTTP, one session per
+// client connection, one avatar per client identity. A bearer names the
+// identity, the identity names the avatar, and the side from `server.ts`
+// runs beside her exactly as it does over stdio. A session belongs to the
+// identity that opened it; a bearer of another identity on the same session
+// is refused. Sessions live in memory and die with the daemon, which is
+// what a reconnect is for: the standing is the state, and it is on disk. A
+// client that goes away without a DELETE leaves a session behind; one idle
+// for an hour is dropped, since HTTP tells the server nothing else.
+import { randomUUID } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import type { Avatar } from '../beings/avatar.ts';
+import type { Serving } from '../beings/side.ts';
+import { mcpSide } from './server.ts';
+
+export type Session = { identity: string; transport: StreamableHTTPServerTransport; serving: Serving; touched: number };
+export const SESSION_IDLE = 60 * 60 * 1000;
+export type Resolve = (identity: string) => Promise<{ avatar?: Avatar; error?: string }>;
+
+export class McpHttp {
+  readonly sessions = new Map<string, Session>();
+  readonly resolve: Resolve;
+  readonly after: () => Promise<void>;
+  now: () => number = () => Date.now();
+  // What to do with an identity the user being has removed: the route's
+  // revoke, so the client's tokens go with the occupant. Set by whoever
+  // mounts the route beside the credential exchange.
+  gone: (identity: string) => Promise<void> = async () => {};
+  constructor(resolve: Resolve, after: () => Promise<void> = async () => {}) {
+    this.resolve = resolve;
+    this.after = after;
+  }
+
+  // `identity` is what the bearer named; the caller has already turned a
+  // stranger away. A request on a known session goes to it. A request with
+  // no session opens one, if it is an initialize; anything else is 400.
+  async handle(req: IncomingMessage, res: ServerResponse, identity: string): Promise<void> {
+    const id = req.headers['mcp-session-id'];
+    const sid = Array.isArray(id) ? id[0] : id;
+    const json = (status: number, body: unknown) => {
+      res.writeHead(status, { 'content-type': 'application/json' });
+      res.end(JSON.stringify(body));
+    };
+    this.sweep();
+    if (sid !== undefined) {
+      const s = this.sessions.get(sid);
+      if (!s) return json(404, { jsonrpc: '2.0', error: { code: -32001, message: 'no such session' }, id: null });
+      if (s.identity !== identity) return json(403, { jsonrpc: '2.0', error: { code: -32003, message: 'not your session' }, id: null });
+      s.touched = this.now();
+      await s.transport.handleRequest(req, res);
+      if (req.method === 'DELETE') this.drop(sid);
+      return;
+    }
+    if (req.method !== 'POST') return json(400, { jsonrpc: '2.0', error: { code: -32000, message: 'no session' }, id: null });
+    const found = await this.resolve(identity);
+    // A session opens on her describe, and admit already asked it. The one
+    // word the door says for an identity the user being removed is
+    // `removed`, under the key it bound for her avatar: in MCP's vocabulary
+    // that is 401, the client drops its token and starts the exchange again,
+    // and the route forgets the grant.
+    if (found.error === 'removed') {
+      await this.gone(identity);
+      for (const [sid, s] of this.sessions) if (s.identity === identity) this.drop(sid);
+      res.writeHead(401, { 'content-type': 'application/json' });
+      return void res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32001, message: 'removed: the user being removed this identity' }, id: null }));
+    }
+    if (!found.avatar) return json(500, { jsonrpc: '2.0', error: { code: -32002, message: found.error ?? 'no avatar' }, id: null });
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (s) => {
+        this.sessions.set(s, { identity, transport, serving, touched: this.now() });
+      },
+      onsessionclosed: (s) => this.drop(s),
+    });
+    const serving = await mcpSide(found.avatar, transport, this.after);
+    await transport.handleRequest(req, res);
+  }
+
+  sweep() {
+    const now = this.now();
+    for (const [sid, s] of this.sessions) if (now - s.touched > SESSION_IDLE) this.drop(sid);
+  }
+
+  drop(sid: string) {
+    const s = this.sessions.get(sid);
+    if (!s) return;
+    this.sessions.delete(sid);
+    void s.serving.close().catch(() => {});
+  }
+
+  async close() {
+    for (const sid of [...this.sessions.keys()]) this.drop(sid);
+  }
+}