@quo-systems/dock 0.1.0 → 0.2.1

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

@@ -28,13 +28,18 @@ export const CODE_TTL = 10 * 60 * 1000; // a code, and a pending request, live t
 export const ACCESS_TTL = 60 * 60 * 1000; // an access token, one hour
 export const REFRESH_TTL = 30 * 24 * 60 * 60 * 1000; // a refresh token, thirty days
 
-export type Client = { client_id: string; client_name: string; redirect_uris: string[] };
+// A client lives ten minutes from registration, the life of a request, and
+// as long as its refresh token once the human allowed it: the register door
+// 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>;
 };
@@ -87,16 +92,24 @@ export class OAuth {
     const b = body as { client_name?: unknown; redirect_uris?: unknown };
     const uris = Array.isArray(b.redirect_uris) ? b.redirect_uris.filter((u): u is string => typeof u === 'string' && /^https?:\/\//.test(u)) : [];
     if (uris.length === 0) return { error: 'invalid_redirect_uri' };
-    const client: Client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris };
+    const client: Client = { client_id: token(), client_name: typeof b.client_name === 'string' ? b.client_name.slice(0, 80) : 'client', redirect_uris: uris, exp: this.now() + CODE_TTL };
     this.store.clients[client.client_id] = client;
+    this.sweep();
     await this.o.persist(this.store);
-    return client;
+    const { exp: _, ...shown } = client;
+    return shown as Client;
+  }
+
+  // A client still alive, by id.
+  client(id: string): Client | undefined {
+    const c = own(this.store.clients, id);
+    return c && c.exp >= this.now() ? c : undefined;
   }
 
   // Start a request. What comes back is where to send the browser: the web
   // route with the request id, or the client's redirect with an error.
   async authorize(q: URLSearchParams): Promise<{ redirect: string } | { error: string }> {
-    const client = own(this.store.clients, q.get('client_id') ?? '');
+    const client = this.client(q.get('client_id') ?? '');
     const redirect = q.get('redirect_uri') ?? client?.redirect_uris[0] ?? null;
     if (!client || redirect === null || !client.redirect_uris.includes(redirect)) return { error: 'invalid_client' };
     const back = (error: string) => ({ redirect: withQuery(redirect, { error, state: q.get('state') }) });
@@ -114,17 +127,18 @@ export class OAuth {
   pending(id: string): (Pending & { client: Client }) | null {
     const p = own(this.store.pending, id);
     if (!p || p.exp < this.now()) return null;
-    const client = own(this.store.clients, p.client_id);
+    const client = this.client(p.client_id);
     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 }) };
   }
@@ -149,46 +163,48 @@ 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();
     await this.o.persist(this.store);
     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);
   }
 
   sweep() {
     const now = this.now();
-    for (const k of ['pending', 'codes', 'access', 'refresh'] as const) for (const [t, g] of Object.entries(this.store[k])) if (g.exp < now) delete this.store[k][t];
+    for (const k of ['clients', 'pending', 'codes', 'access', 'refresh'] as const) for (const [t, g] of Object.entries(this.store[k])) if (!(g.exp >= now)) delete this.store[k][t]; // a record with no exp is from before there was one, and goes too
   }
 
   // The HTTP face. `rest` is the path under the route.

package/mcp/pilot.ts

@@ -1,73 +1,34 @@
 // SPDX-License-Identifier: Apache-2.0
-// The owner pilot: `quo pilot`. An MCP server over stdio that reaches a
-// ward's owner asks through the daemon's root socket, and exposes four tools
-// and no more, plus the one read. Whoever runs this process is the owner, by
-// the device's own rules: the root of the ward here, or, with `via`, an
-// owner at another ward's door, on a standing the user being here holds
-// there. Every call is logged with what it made. The owner creates and
-// places; the work goes through `quo side`, under a gate.
-import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+// The owner pilot: `quo pilot`. The model side pointed at a ward instead of
+// an avatar. The ward is a being to her owner, so her describe is the tool
+// list and a tool call is an owner ask, exactly as for anyone; nothing here
+// names an ask. Whoever runs this process is the owner, by the device's own
+// rules: the root of the ward here, through the daemon's socket, or, with
+// `via`, an owner at another ward's door, on a standing the user being here
+// holds there. The owner creates and places; the work goes through
+// `quo side`, under a gate.
 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 { ask } from '../cli/client.ts';
 import type { Serving } from '../beings/side.ts';
+import { mcpSide, type Subject } from './server.ts';
 
-export const PILOT_TOOLS: Tool[] = [
-  {
-    name: 'census',
-    description: 'the empty ask: the ward pk and every being, with class, public and digest',
-    inputSchema: { type: 'object', properties: {} },
-  },
-  {
-    name: 'boot',
-    description: 'boot a being by class name under a key; public marks the one public being',
-    inputSchema: { type: 'object', properties: { key: { type: 'string' }, class: { type: 'string' }, public: { type: 'boolean' } }, required: ['key', 'class'] },
-  },
-  {
-    name: 'invite',
-    description: 'mint an invitation on a being of the ward, under an id she will know the occupant by',
-    inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
-  },
-  {
-    name: 'knock',
-    description: 'knock for a being of the ward with an invitation, and take the standing under id if answered',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        being: { description: 'a key already booted, or { boot: class, key } to boot her first' },
-        id: { type: 'string' },
-        invitation: { type: 'object' },
-        method: { type: 'string' },
-        args: { type: 'object' },
-        wanted: { type: 'object', properties: { time: { type: 'number' } } },
-      },
-      required: ['being', 'id', 'invitation'],
-    },
-  },
-  {
-    name: 'remove',
-    description: 'take a relation out of a being of the ward by id, occupant or standing; on the ward pk, an owner, by the root alone',
-    inputSchema: { type: 'object', properties: { being: { type: 'string' }, id: { type: 'string' } }, required: ['being', 'id'] },
-  },
-];
-
-export type Log = (line: string) => void;
 const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 
-export async function pilotSide(dir: string, ward: string, transport: Transport, log: Log = () => {}, via?: string): Promise<Serving> {
-  const server = new Server({ name: 'quo-pilot', version: '0.0.0' }, { capabilities: { tools: {} } });
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: PILOT_TOOLS }));
-  server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
-    const name = req.params.name;
-    const args: Record<string, unknown> = req.params.arguments ?? {};
-    if (!PILOT_TOOLS.some((t) => t.name === name)) return { content: [{ type: 'text', text: JSON.stringify({ error: 'unknown ask' }) }], structuredContent: { error: 'unknown ask' }, isError: true };
-    const out = await ask(dir, name === 'census' ? undefined : name, args, ward, via);
-    const value = 'error' in out ? { error: out.error } : out.result;
-    const failed = 'error' in out || (typeof value === 'object' && value !== null && 'error' in value);
-    log(`${via === undefined ? ward : `${ward} via ${via}`} ${name} ${JSON.stringify(args)} -> ${JSON.stringify(value)}`);
-    const structured = isRecord(value) ? { structuredContent: value } : {};
-    return { content: [{ type: 'text', text: JSON.stringify(value) }], ...structured, ...(failed ? { isError: true } : {}) };
-  });
-  await server.connect(transport);
-  return { close: () => server.close() };
+// The owner hears objects: the socket's own failure, a silence and a word
+// each come back as an error object named for what it was.
+export function owner(dir: string, ward: string, via?: string): Subject {
+  const one = async (method: string | undefined, args: JsonObject): Promise<Answer> => {
+    const out = await ask(dir, method, args, ward, via);
+    if ('error' in out) return { error: out.error };
+    const r = out.result;
+    if (isRecord(r) && r.silence === true) return { error: 'silence' };
+    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() };
+}
+
+export function pilotSide(dir: string, ward: string, transport: Transport, via?: string): Promise<Serving> {
+  return mcpSide(owner(dir, ward, via), transport);
 }

package/mcp/quo-mcp.md

@@ -23,19 +23,32 @@ and needs no translation code beyond an envelope:
 | server                   | an avatar's side                                             |
 | session                  | a standing the avatar holds, persistent across sessions      |
 | tools/list               | the empty ask on that standing: describe for this asker      |
+| the `describe` tool      | the empty ask itself, first in the list, so the notes of the |
+|                          | describe are readable and not only its asks                  |
 | tool name, inputSchema   | `asks[].name`, `asks[].input`, verbatim                      |
 | tools/call               | a named ask with args                                        |
 | result content           | the answer object, as JSON                                   |
 | 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                                                     |
@@ -54,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 ------->|                     |                  |                |
@@ -198,23 +216,20 @@ the device and crosses only the local socket.
 
 ### A model as the owner
 
-An **owner pilot** is an MCP server over stdio that reaches a ward's owner
-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, and exposes
-four tools and no more:
-
-```
-boot({ key, class, public? })
-invite({ being, id })
-knock({ being | { boot, key }, id, invitation, method?, args? })
-remove({ being, id })
-```
-
-Plus one read, `census()`, which is the empty ask. Every call is logged
-with what it made. The pilot is handed to one local agent by the device's
-own rules. A remote pilot is a standing at the ward, and still not a route:
-a model without a ward of its own cannot be an owner anywhere. `quo pilot
---via S` is that pilot: S is a standing the user being here holds at the
+An **owner pilot** is the model side above, pointed at a ward instead of an
+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, 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
+transcript, and an invitation it was handed is in no file of the dock's.
+The pilot is handed to one local agent by the device's own rules. A remote
+pilot is a standing at the ward, and still not a route: a model without a
+ward of its own cannot be an owner anywhere. `quo pilot --via S` is that
+pilot: S is a standing the user being here holds at the
 far ward, taken when the root here knocked for her with an invitation the
 far root minted on its ward's pk, and every tool call is a sealed ask
 there, answered as the far ward answers an owner at its door.
@@ -259,4 +274,4 @@ On top of the shared ones in the trunk:
   under; governance, never permission.
 - **runner**: an inline MCP client for a model that speaks function calling;
   it drives the loop the MCP client would, over one conversation.
-- **owner pilot**: an MCP server over stdio exposing the four owner asks.
+- **owner pilot**: the model side over a ward's owner asks, over stdio.

package/mcp/server.ts

@@ -1,44 +1,77 @@
 // SPDX-License-Identifier: Apache-2.0
-// The model side as an MCP server: one avatar, one transport. The mapping is
-// total and needs nothing beyond this envelope. tools/list is her describe,
-// tools/call is a named ask on her one standing, a push is a logging
-// notification, and the three words for "no object" each cross as the table
-// in quo-mcp.md says. The transport is whatever the caller connected: the
+// The model side as an MCP server: one subject, one transport. The subject
+// is whoever answers the empty ask and a named one: an avatar on her one
+// standing, or a ward's owner asks through the pilot. The mapping is total
+// and needs nothing beyond this envelope. tools/list is her describe, and
+// the empty ask itself is the first tool, so the notes of the describe are
+// readable; tools/call is a named ask, a push is a logging notification,
+// and the three words for "no object" each cross as the table in
+// quo-mcp.md says. The transport is whatever the caller connected: the
 // SDK's in-memory pair in a test, stdio for a local client, HTTP on a route.
 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 { Blueprint, 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';
+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';
 
-// Her describe, spoken as tools. Name, description and input are verbatim;
-// an output schema crosses when she declared one.
-export function tools(bp: Blueprint): Tool[] {
-  return 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;
-  });
+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. 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];
 }
 
 // `after` runs when a call is done: a harbor that must write what the ward
 // changed hooks it, since a same-ward ask never crosses the harbor.
-export async function mcpSide(avatar: Avatar, transport: Transport, after: () => Promise<void> = async () => {}): Promise<Serving> {
+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> => {
-    const w = word(await avatar.call(req.params.name, (req.params.arguments ?? {}) as JsonObject));
+    const w = word(req.params.name === DESCRIBE.name ? await avatar.tools() : await avatar.call(req.params.name, (req.params.arguments ?? {}) as JsonObject));
     await after();
     if (w.word === 'object') {
       const structured = w.value !== null && typeof w.value === 'object' && !Array.isArray(w.value) ? { structuredContent: w.value } : {};

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.1.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",
@@ -54,17 +54,21 @@
     "./human/html": {
       "types": "./dist/human/html.d.ts",
       "default": "./dist/human/html.js"
+    },
+    "./harbor/edge/worker": {
+      "types": "./dist/harbor/edge/worker.d.ts",
+      "default": "./dist/harbor/edge/worker.js"
     }
   },
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp harbor/edge/platform.d.ts dist/harbor/edge/ && cp -R cli/estate dist/cli/",
     "test": "node --test \"test/*.test.ts\"",
     "check:terrain": "node --test \"test/terrain/*.test.ts\"",
     "prepublishOnly": "cd ../.. && npm run check && npm run check:terrain"
   },
   "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"
   },