@quo-systems/dock 0.2.0 → 0.2.1

package/human/tab.ts

@@ -1,23 +1,58 @@
 // 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 tab: a page on a world's web. that is a device of its own. The tab
+// boots a browser harbor on a seed minted into IndexedDB the first time,
+// and keeps one ward per world it has joined, each with one avatar, so the
+// tab is a browser of worlds: a switcher between them is a switch of ward
+// and nothing more. It dials the world's quo. route.
 //
-// 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';
+// Three ways in, all the same act, a knock that ends in a standing:
+//
+//   a link      the page with the invitation in its fragment, `#quo=...`,
+//               read and stripped before anything else runs, then joined.
+//   a guest     the world's public being, whatever class she is, rendered
+//               as a page by the same screen; a form on it whose answer is
+//               an invitation is the way in.
+//   a password  the dock's own way, when the public being shows `device`:
+//               the owner password goes to the web route for a nonce the
+//               front desk honours under the `tab` proof kind, and the
+//               guest form `device({ proof })` is submitted for the human.
+//
+// From then on there is no cookie and no token anywhere; the seed and the
+// standing are in the tab's store, and a reload asks nothing. The screen
+// is the human side in `screen.ts` over the DOM surface in `dom.ts`. This
+// file is the harbor, the worlds and the ways in, and hands the avatar over.
+import type { Invitation, JsonObject } from '@quo-systems/quo';
 import { BrowserHarbor } from '../harbor/browser.ts';
 import { Avatar, USER } from '../beings/avatar.ts';
+import { parse, strip, isInvitation } from '../beings/link.ts';
 import { screenSide } from './screen.ts';
 import { domSurface } from './dom.ts';
+import { guest } from './guest.ts';
+import { escape } from './html.ts';
+
+// What the page is told by the daemon that served it: the world's routes,
+// this ward's name on that harbor, and its pk.
+export type Config = { quo: string; web: string; ward: string; pk: string };
 
-export type Config = { quo: string; web: string };
+// The worlds this tab has joined, by pk: where each lives and what it is
+// called, kept beside the harbor so the switcher can list them. A world on
+// another origin is another page, and the switcher links to it.
+type Worlds = Record<string, { url: string; name: string }>;
+const WORLDS = 'quo-worlds';
+const worlds = (): Worlds => {
+  try {
+    return JSON.parse(localStorage.getItem(WORLDS) ?? '{}') as Worlds;
+  } catch {
+    return {};
+  }
+};
+const remember = (pk: string, url: string, name: string) => {
+  try {
+    localStorage.setItem(WORLDS, JSON.stringify({ ...worlds(), [pk]: { url, name } }));
+  } catch {
+    /* a tab with no storage still works, and forgets */
+  }
+};
 
 const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Record<string, string> = {}): HTMLElementTagNameMap[K] => {
   const e = document.createElement(tag);
@@ -27,58 +62,125 @@ const el = <K extends keyof HTMLElementTagNameMap>(tag: K, text = '', attrs: Rec
 };
 
 export async function start(cfg: Config, root: HTMLElement = document.body): Promise<void> {
+  // The link, first and once: the invitation leaves the address bar before
+  // any other code sees it.
+  const linked = parse(location.hash);
+  if (linked) history.replaceState(null, '', location.pathname + location.search + strip(location.hash));
+
+  const nav = el('nav', '', { class: 'worlds' });
   const status = el('p', 'booting');
   const screen = el('div');
-  root.append(status, screen);
+  root.append(nav, status, screen);
   const say = (s: string) => (status.textContent = s);
 
-  // The harbor in the tab: one database, one ward, one avatar, for good.
+  // The harbor in the tab: one database per origin, one ward per world.
   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;
+  const name = `w-${cfg.pk.slice(0, 16)}`;
+  const ward = harbor.wards.get(name) ?? (await harbor.create(name, 'me'));
+  if (!ward.being('me')) await ward.ask('boot', { key: 'me', class: 'Avatar' });
+  const me = ward.being('me') as Avatar;
   harbor.dial(cfg.quo);
 
-  // The screen: every call rotates her keys and a same-ward ask never
+  const switcher = () => {
+    nav.replaceChildren();
+    const known = worlds();
+    for (const [pk, w] of Object.entries(known)) {
+      const a = el('a', w.name || pk.slice(0, 8), { href: w.url });
+      if (pk === cfg.pk) a.setAttribute('aria-current', 'page');
+      nav.append(a);
+    }
+    const here = worlds()[cfg.pk];
+    if (!here) nav.append(el('span', `${cfg.ward} at ${new URL(cfg.web).host}`));
+  };
+  switcher();
+
+  // Joined: her page. 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) => {
+  const inside = async (notice: string) => {
     status.remove();
-    await screenSide(me, domSurface(screen), () => main.save(), notice);
+    screen.replaceChildren();
+    const side = await screenSide(me, domSurface(screen), { after: () => ward.save(), notice });
+    remember(cfg.pk, location.origin + location.pathname, side.model.look.name || (typeof (side.model.blueprint?.notes as JsonObject | null)?.name === 'string' ? ((side.model.blueprint!.notes as JsonObject).name as string) : cfg.ward));
+    switcher();
   };
 
-  // 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 = '';
+  // The way in, from any of the three: join, save, and be inside.
+  const admit = async (inv: Invitation, notice: string) => {
     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}`);
+    const got = await me.join(inv);
+    await ward.save(); // the knock went through her own door, which the harbor never sees
+    if (!('asks' in got)) {
+      say(`not in: ${got.error}`);
+      return;
+    }
+    await inside(notice);
   };
+
+  // Already in: reconnect, nothing minted.
+  if (me.standings[USER]) {
+    const had = await me.tools();
+    if ('asks' in had) return inside('in, as before');
+    say(`not in (${had.error})`);
+  }
+  if (linked) return admit(linked, 'in, by the link');
+
+  // A guest: the public being's describe as a page; a form whose answer is
+  // an invitation lets the guest in.
+  say(`at the door of ${cfg.ward}`);
+  const door = guest(me, cfg.pk);
+  const side = await screenSide(door, domSurface(screen), {
+    after: () => ward.save(),
+    notice: `a guest at ${cfg.ward}: what she shows strangers`,
+    admit: async (inv) => {
+      await side.close();
+      await admit(inv, `in, as a guest of ${cfg.ward}`);
+    },
+  });
+
+  // The dock's own way in, when the desk is at the door: the owner password
+  // for a nonce, and the desk's `device` form submitted with it.
+  if (side.model.blueprint?.asks.some((a) => a.name === 'device')) {
+    const form = el('form', '', { class: 'password' });
+    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 as the owner');
+    form.append(identity, password, go);
+    root.insertBefore(form, screen);
+    form.onsubmit = (ev) => {
+      ev.preventDefault();
+      void (async () => {
+        say('asking the world');
+        let res: Response;
+        try {
+          res = await fetch(`${cfg.web}/${encodeURIComponent(cfg.ward)}/login`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: password.value, identity: identity.value }) });
+        } catch (e) {
+          say(`the world did not answer: ${(e as Error).message}`);
+          return;
+        }
+        password.value = '';
+        if (!res.ok) {
+          say(`refused: ${((await res.json().catch(() => ({ error: res.status }))) as { error?: string }).error ?? res.status}`);
+          return;
+        }
+        const { nonce } = (await res.json()) as { nonce: string };
+        const inv = await door.call('device', { proof: { kind: 'tab', nonce } });
+        await ward.save();
+        if (!isInvitation(inv)) {
+          say(`not in: ${escape(JSON.stringify(inv))}`);
+          return;
+        }
+        form.remove();
+        await side.close();
+        await admit(inv, `in, as ${identity.value}`);
+      })();
+    };
+  }
 }
 
+// The page hands the config in a JSON script, which a content security
+// policy allows where an inline script is not.
+const config = document.getElementById('quo');
+if (config?.textContent) void start(JSON.parse(config.textContent) as Config);
+
 export { USER };

package/mcp/http.ts

@@ -15,9 +15,10 @@ 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 type Session = { identity: string; ward: string; transport: StreamableHTTPServerTransport; serving: Serving; touched: number };
 export const SESSION_IDLE = 60 * 60 * 1000;
-export type Resolve = (identity: string) => Promise<{ avatar?: Avatar; error?: string }>;
+// An identity in a world: one harbor holds many, and the grant names which.
+export type Resolve = (identity: string, ward: string) => Promise<{ avatar?: Avatar; error?: string }>;
 
 export class McpHttp {
   readonly sessions = new Map<string, Session>();
@@ -27,7 +28,7 @@ export class McpHttp {
   // 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 () => {};
+  gone: (identity: string, ward: string) => Promise<void> = async () => {};
   constructor(resolve: Resolve, after: () => Promise<void> = async () => {}) {
     this.resolve = resolve;
     this.after = after;
@@ -36,7 +37,7 @@ export class McpHttp {
   // `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> {
+  async handle(req: IncomingMessage, res: ServerResponse, identity: string, ward = 'main'): Promise<void> {
     const id = req.headers['mcp-session-id'];
     const sid = Array.isArray(id) ? id[0] : id;
     const json = (status: number, body: unknown) => {
@@ -47,22 +48,22 @@ export class McpHttp {
     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 });
+      if (s.identity !== identity || s.ward !== ward) 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);
+    const found = await this.resolve(identity, ward);
     // 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);
+      await this.gone(identity, ward);
+      for (const [sid, s] of this.sessions) if (s.identity === identity && s.ward === ward) 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 }));
     }
@@ -70,7 +71,7 @@ export class McpHttp {
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => randomUUID(),
       onsessioninitialized: (s) => {
-        this.sessions.set(s, { identity, transport, serving, touched: this.now() });
+        this.sessions.set(s, { identity, ward, transport, serving, touched: this.now() });
       },
       onsessionclosed: (s) => this.drop(s),
     });

package/mcp/oauth.ts

@@ -33,11 +33,13 @@ export const REFRESH_TTL = 30 * 24 * 60 * 60 * 1000; // a refresh token, thirty
 // is open to anyone, and what nobody allowed must not stay on disk.
 export type Client = { client_id: string; client_name: string; redirect_uris: string[]; exp: number };
 export type Pending = { client_id: string; redirect_uri: string; challenge: string; state: string | null; resource: string | null; exp: number };
-export type Grant = { identity: string; client_id: string; exp: number };
+// A grant names the world the human allowed the client into, since one
+// harbor holds many; a record from before there were worlds is `main`'s.
+export type Grant = { identity: string; ward: string; client_id: string; exp: number };
 export type Store = {
   clients: Record<string, Client>;
   pending: Record<string, Pending>;
-  codes: Record<string, Pending & { identity: string }>;
+  codes: Record<string, Pending & { identity: string; ward: string }>;
   access: Record<string, Grant>;
   refresh: Record<string, Grant>;
 };
@@ -129,13 +131,14 @@ export class OAuth {
     return client ? { ...p, client } : null;
   }
 
-  // The web route's last step: the human allowed this client as this identity.
-  async complete(id: string, identity: string): Promise<{ redirect: string } | { error: string }> {
+  // The web route's last step: the human allowed this client as this
+  // identity, into this world.
+  async complete(id: string, identity: string, ward = 'main'): Promise<{ redirect: string } | { error: string }> {
     const p = this.pending(id);
     if (!p) return { error: 'expired' };
     delete this.store.pending[id];
     const code = token();
-    this.store.codes[code] = { ...p, identity, exp: this.now() + CODE_TTL };
+    this.store.codes[code] = { ...p, identity, ward, exp: this.now() + CODE_TTL };
     await this.o.persist(this.store);
     return { redirect: withQuery(p.redirect_uri, { code, state: p.state }) };
   }
@@ -160,23 +163,23 @@ export class OAuth {
         await this.o.persist(this.store);
         return { error: 'invalid_grant' };
       }
-      return this.issue(c.identity, c.client_id);
+      return this.issue(c.identity, c.ward ?? 'main', c.client_id);
     }
     if (grant === 'refresh_token') {
       const rt = body.get('refresh_token') ?? '';
       const r = own(this.store.refresh, rt);
       if (!r || r.exp < this.now()) return { error: 'invalid_grant' };
       delete this.store.refresh[rt]; // rotated: the old one is gone with the new one's birth
-      return this.issue(r.identity, r.client_id);
+      return this.issue(r.identity, r.ward ?? 'main', r.client_id);
     }
     return { error: 'unsupported_grant_type' };
   }
 
-  async issue(identity: string, client_id: string) {
+  async issue(identity: string, ward: string, client_id: string) {
     const access_token = token(),
       refresh_token = token();
-    this.store.access[access_token] = { identity, client_id, exp: this.now() + ACCESS_TTL };
-    this.store.refresh[refresh_token] = { identity, client_id, exp: this.now() + REFRESH_TTL };
+    this.store.access[access_token] = { identity, ward, client_id, exp: this.now() + ACCESS_TTL };
+    this.store.refresh[refresh_token] = { identity, ward, client_id, exp: this.now() + REFRESH_TTL };
     const c = own(this.store.clients, client_id);
     if (c) c.exp = this.now() + REFRESH_TTL; // allowed: the client lives as long as what it was granted
     this.sweep();
@@ -184,18 +187,18 @@ export class OAuth {
     return { access_token, token_type: 'Bearer', expires_in: ACCESS_TTL / 1000, refresh_token, scope: 'quo' };
   }
 
-  // The bearer on an MCP request, to a client identity. Null is 401.
-  bearer(req: IncomingMessage): string | null {
+  // The bearer on an MCP request, to a client identity in a world. Null is 401.
+  bearer(req: IncomingMessage): { identity: string; ward: string } | null {
     const h = req.headers.authorization ?? '';
     const t = h.startsWith('Bearer ') ? h.slice(7) : '';
     const g = own(this.store.access, t);
-    return g && g.exp >= this.now() && typeof g.identity === 'string' ? g.identity : null;
+    return g && g.exp >= this.now() && typeof g.identity === 'string' ? { identity: g.identity, ward: g.ward ?? 'main' } : null;
   }
 
-  // Every grant an identity holds, gone: the route's half of revocation.
-  // The other half is the user being removing the occupant.
-  async revoke(identity: string): Promise<void> {
-    for (const k of ['access', 'refresh'] as const) for (const [t, g] of Object.entries(this.store[k])) if (g.identity === identity) delete this.store[k][t];
+  // Every grant an identity holds in a world, gone: the route's half of
+  // revocation. The other half is the user being removing the occupant.
+  async revoke(identity: string, ward = 'main'): Promise<void> {
+    for (const k of ['access', 'refresh'] as const) for (const [t, g] of Object.entries(this.store[k])) if (g.identity === identity && (g.ward ?? 'main') === ward) delete this.store[k][t];
     await this.o.persist(this.store);
   }
 

package/mcp/pilot.ts

@@ -26,7 +26,7 @@ export function owner(dir: string, ward: string, via?: string): Subject {
     if (isRecord(r) && typeof r.word === 'string') return { error: r.word };
     return r as Answer;
   };
-  return { tools: () => one(undefined, {}) as Promise<Blueprint | { error: string }>, call: (name, args) => one(name, args), ears: new Set() };
+  return { tools: () => one(undefined, {}) as Promise<Blueprint | { error: string }>, call: (name, args) => one(name, args ?? {}), ears: new Set() };
 }
 
 export function pilotSide(dir: string, ward: string, transport: Transport, via?: string): Promise<Serving> {

package/mcp/quo-mcp.md

@@ -31,13 +31,24 @@ and needs no translation code beyond an envelope:
 | tool error result        | an error object she answered, `{ error }`, as JSON           |
 | protocol error           | silence and the ward's words, see the table below            |
 | auth token               | an invitation, used once, then keys                          |
-| resources, prompts       | not mapped. Notes in the blueprint may carry hints.          |
+| tool title, annotations  | her `look`: a title and the hints per ask, see below         |
+| resources, prompts       | not mapped.                                                  |
 
 A tool list is a describe. Because a being describes per asker, two models
 connected to the same user being see two different tool lists, and neither
 can call what it cannot see: the gate is one decision for describe and for
 dispatch.
 
+A being who answers `look`, the trunk's one optional ask, is listed with
+what it says: `asks.NAME.title` is the tool's title, and `readOnly`,
+`destructive` and `idempotent` are the annotations of the same names with
+`Hint` after them. The `look` ask itself is not a tool. A carried standing's
+asks, `acme-book` on the user being for a model the human let reach, carry
+the far being's hints the same way, read from the notes the carrier writes.
+The side asks `look` once per digest of the describe. Nothing else changes:
+a model sees a flat list with a dash, exactly as a screen sees a section
+per standing, and neither can do a thing the other cannot.
+
 The three words for "no object" cross the envelope like this:
 
 | the avatar heard | the client gets                                                     |
@@ -56,6 +67,11 @@ the two words give it what it needs to decide.
 
 ### A remote MCP client connects
 
+One harbor holds many worlds, and the allow page names the one the client
+is let into; the grant remembers it, so a bearer is an identity in a world
+and a session is that identity's there. `/mcp` stays one endpoint per
+harbor.
+
 ```
 client            mcp. route          front desk         user being        avatar
   |-- OAuth ------->|                     |                  |                |
@@ -205,7 +221,7 @@ avatar. The ward is a being to her owner, and `packages/quo/SPEC.md` says her
 describe carries her asks with a description and an input each, so the
 pilot holds no list of its own: tools/list is the ward's describe, the
 `describe` tool is the census, and a tool call is an owner ask, boot,
-public, invite, knock or remove, in the ward's own words. It reaches those
+public, invite, knock, remove or unboot, in the ward's own words. It reaches those
 asks either as the root through the daemon's socket on the device, or as an
 owner the root invited, through a standing over the sealed door. It keeps
 nothing and logs nothing: what a model did with it is in the host's own

package/mcp/server.ts

@@ -11,32 +11,40 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, type CallToolResult, type Tool } from '@modelcontextprotocol/sdk/types.js';
-import type { Answer, Blueprint, JsonObject } from '@quo-systems/quo';
-import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving } from '../beings/side.ts';
+import type { Blueprint, JsonObject } from '@quo-systems/quo';
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving, type Subject } from '../beings/side.ts';
+import { hintFor, sanitise, type Look } from '../beings/look.ts';
+import { isSilence, isWord, digest } from '@quo-systems/quo';
+import type { Json } from '@quo-systems/quo';
 
 export const NAME = 'quo';
 export const VERSION = '0.0.0';
 
-// What a side speaks for: the empty ask and a named one, and the ears a
-// push reaches. An avatar is one; the owner's asks on a ward are another.
-export type Subject = {
-  tools(): Promise<Blueprint | { error: string }>;
-  call(name: string, args: JsonObject): Promise<Answer>;
-  ears: Set<(object: JsonObject) => void>;
-};
+export type { Subject } from '../beings/side.ts';
 
 // The empty ask as a tool: her describe whole, asks and notes.
 export const DESCRIBE: Tool = { name: 'describe', description: 'the empty ask: her describe, the asks and the notes', inputSchema: { type: 'object' } };
 
 // Her describe, spoken as tools, the empty ask first. Name, description and
-// input are verbatim; an output schema crosses when she declared one.
-export function tools(bp: Blueprint): Tool[] {
-  const asks = bp.asks.map((a) => {
-    const t: Tool = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
-    if (a.description !== undefined) t.description = a.description;
-    if (a.output !== undefined) t.outputSchema = { ...a.output, type: 'object' };
-    return t;
-  });
+// input are verbatim; an output schema crosses when she declared one. Her
+// look, when she has one, is the hints: a title, and the annotations a host
+// reads. The `look` ask itself is presentation, and is not a tool.
+export function tools(bp: Blueprint, look: Look = {}): Tool[] {
+  const asks = bp.asks
+    .filter((a) => a.name !== 'look')
+    .map((a) => {
+      const t: Tool = { name: a.name, inputSchema: { ...a.input, type: 'object' } };
+      if (a.description !== undefined) t.description = a.description;
+      if (a.output !== undefined) t.outputSchema = { ...a.output, type: 'object' };
+      const h = hintFor(bp, look, a.name);
+      if (h.title !== undefined) t.title = h.title;
+      const notes: Record<string, boolean> = {};
+      if (h.readOnly !== undefined) notes.readOnlyHint = h.readOnly;
+      if (h.destructive !== undefined) notes.destructiveHint = h.destructive;
+      if (h.idempotent !== undefined) notes.idempotentHint = h.idempotent;
+      if (Object.keys(notes).length) t.annotations = notes;
+      return t;
+    });
   return [DESCRIBE, ...asks];
 }
 
@@ -45,10 +53,21 @@ export function tools(bp: Blueprint): Tool[] {
 export async function mcpSide(avatar: Subject, transport: Transport, after: () => Promise<void> = async () => {}): Promise<Serving> {
   const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: { listChanged: true }, logging: {} } });
 
+  // Her look, asked once per digest of her describe.
+  let seen: string | null = null;
+  let look: Look = {};
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     const bp = await avatar.tools();
     if ('error' in bp && !('asks' in bp)) return { tools: [] }; // not joined: nothing to show, and nothing to call
-    return { tools: tools(bp as Blueprint) };
+    const d = await digest(bp as Blueprint);
+    if (d !== seen) {
+      seen = d;
+      if ((bp as Blueprint).asks.some((a) => a.name === 'look')) {
+        const l = await avatar.call('look', {});
+        look = isSilence(l) || isWord(l) ? {} : sanitise(l as Json);
+      } else look = {};
+    }
+    return { tools: tools(bp as Blueprint, look) };
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {

package/mcp/web/exchange.ts

@@ -20,12 +20,12 @@ import { readForm } from '../oauth.ts';
 export const SESSION_TTL = 10 * 60 * 1000; // a login lives as long as a request: ten minutes
 const COOKIE = 'quo_exchange';
 
-export type Admit = (identity: string, wake: boolean) => Promise<{ error?: string }>;
+export type Admit = (identity: string, wake: boolean, reach: boolean, ward: string) => Promise<{ error?: string }>;
 export type Options = {
   oauth: OAuth;
   password: () => string | undefined; // QUO_OWNER_PASSWORD, read at every login
-  admit: Admit; // the daemon: boot or find the avatar for this identity, and enter her
-  user: string; // the user being's name, for the page
+  admit: Admit; // the daemon: boot or find the avatar for this identity in that world, and enter her
+  worlds: () => { ward: string; user: string }[]; // the worlds of this harbor, the first the default: a ward with a public being, and its user being's name
   now?: () => number;
 };
 
@@ -101,7 +101,7 @@ export class Exchange {
       const p = this.o.oauth.pending(request);
       if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
       if (!this.valid(req)) return go(`/login?request=${encodeURIComponent(request)}`), true;
-      return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user)), true;
+      return page(200, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.worlds())), true;
     }
     if (rest === '/allow' && req.method === 'POST') {
       const f = await readForm(req);
@@ -113,11 +113,14 @@ export class Exchange {
         const out = await this.o.oauth.deny(request);
         return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`), true;
       }
+      const worlds = this.o.worlds();
+      const world = worlds.find((w) => w.ward === (f.get('ward') ?? worlds[0]?.ward));
+      if (!world) return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'That is not a world of this harbor.')), true;
       const identity = word(f.get('identity'));
-      if (identity === null || identity === this.o.user || identity === 'desk') return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), this.o.user, 'An identity is one word, and not the user or the desk.')), true;
-      const admitted = await this.o.admit(identity, f.get('wake') === 'on');
+      if (identity === null || identity === world.user || identity === 'desk') return page(400, allowForm(request, p.client.client_name, p.redirect_uri, suggest(p.client.client_name), worlds, 'An identity is one word, and not the user or the desk.')), true;
+      const admitted = await this.o.admit(identity, f.get('wake') === 'on', f.get('reach') === 'on', world.ward);
       if (admitted.error) return page(500, `<h1>Not admitted</h1><p>${esc(admitted.error)}</p>`), true;
-      const out = await this.o.oauth.complete(request, identity);
+      const out = await this.o.oauth.complete(request, identity, world.ward);
       return 'redirect' in out ? go(out.redirect, { 'set-cookie': `${COOKIE}=; Path=/; Max-Age=0` }) : page(400, `<h1>Gone</h1>`), true;
     }
     return false;
@@ -135,12 +138,23 @@ ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <label for="p">Owner password</label><input id="p" name="password" type="password" autocomplete="current-password" autofocus required>
 <button type="submit">Log in</button></form>`;
 
-const allowForm = (request: string, client: string, redirect: string, identity: string, user: string, err = '') => `<h1>Allow ${esc(client)}?</h1>
-<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>.</p>
+// The world is a choice when the harbor has more than one; the user named
+// is the first world's, and the page says which world each identity lands in.
+const allowForm = (request: string, client: string, redirect: string, identity: string, worlds: { ward: string; user: string }[], err = '') => {
+  const user = worlds[0]?.user ?? '';
+  const pick =
+    worlds.length > 1
+      ? `<label for="wd">World</label><select id="wd" name="ward">${worlds.map((w) => `<option value="${esc(w.ward)}">${esc(w.ward)}, ${esc(w.user)}'s</option>`).join('')}</select>`
+      : `<input type="hidden" name="ward" value="${esc(worlds[0]?.ward ?? 'main')}">`;
+  return `<h1>Allow ${esc(client)}?</h1>
+<div class="who"><p><strong>${esc(client)}</strong> asks to be an occupant of <strong>${esc(user)}</strong>${worlds.length > 1 ? ', or of another world below' : ''}.</p>
 <p>It will see exactly what ${esc(user)} shows the identity below, and nothing else. You can remove it any time.</p>
 <p>It returns to <code>${esc(redirect)}</code>.</p></div>
 ${err ? `<p class="err">${esc(err)}</p>` : ''}
 <form method="post" action="/allow"><input type="hidden" name="request" value="${esc(request)}">
+${pick}
 <label for="i">Identity</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required>
+<label for="r"><input id="r" name="reach" type="checkbox" style="width:auto"> May reach what ${esc(user)} holds: her standings, acme and the rest, as asks of hers</label>
 <label for="w"><input id="w" name="wake" type="checkbox" style="width:auto"> May wake your other devices: hand an agent an event through ${esc(user)}</label>
 <button type="submit" name="decision" value="allow">Allow</button><button type="submit" name="decision" value="deny">Deny</button></form>`;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quo-systems/dock",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "The dock: what every estate on Quo needs and nobody writes twice. A daemon and the quo command, the front desk, the user being and the avatar, harbors on disk, in a tab and on the edge, the model sides and the screen.",
   "keywords": [
     "quo",
@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@quo-systems/quo": "^0.2.0",
+    "@quo-systems/quo": "^0.2.1",
     "esbuild": "^0.28.2",
     "ws": "^8.21.3"
   },