@quo-systems/dock 0.1.0

package/mcp/oauth.ts

@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: Apache-2.0
+// OAuth on the mcp route: the credential exchange for a remote MCP client.
+// An authorization server small enough to read, and nothing a client does
+// not need: metadata, dynamic registration, PKCE with S256, the code grant,
+// refresh, opaque tokens. It is a route, not Quo. Its one job is to end with
+// a client identity, which the front desk trades for an invitation and the
+// avatar knocks with; the tokens it keeps map a bearer to that identity and
+// nothing else. No secret of Quo's is ever here.
+//
+//   GET  /.well-known/oauth-authorization-server     who issues, and where
+//   GET  /.well-known/oauth-protected-resource[/mcp] which issuer guards the MCP endpoint
+//   POST /register                                    a client names itself and its redirects
+//   GET  /authorize                                   starts a request; sent to the web route to finish
+//   POST /token                                       code or refresh for an access token
+//
+// The web route finishes a request by calling `complete(request, identity)`
+// after its own login and allow pages; that returns the redirect that
+// carries the code back to the client. Step 8 builds those pages.
+import { randomBytes, createHash } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+// A token, a code, a client id: every key here is a string the far side chose,
+// and a bare lookup would find `__proto__` and hand back an object with no
+// identity. Own keys only.
+const own = <T>(rec: Record<string, T>, key: string): T | undefined => (Object.hasOwn(rec, key) ? rec[key] : undefined);
+
+export const CODE_TTL = 10 * 60 * 1000; // a code, and a pending request, live ten minutes
+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[] };
+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 };
+export type Store = {
+  clients: Record<string, Client>;
+  pending: Record<string, Pending>;
+  codes: Record<string, Pending & { identity: string }>;
+  access: Record<string, Grant>;
+  refresh: Record<string, Grant>;
+};
+export const emptyStore = (): Store => ({ clients: {}, pending: {}, codes: {}, access: {}, refresh: {} });
+
+export type Options = {
+  issuer: string; // https://mcp.lab.quo.systems
+  resource: string; // https://mcp.lab.quo.systems/mcp
+  finish: (request: string) => string; // where the web route takes a pending request
+  store: Store;
+  persist: (store: Store) => Promise<void>;
+  now?: () => number;
+};
+
+const token = () => randomBytes(32).toString('base64url');
+const s256 = (v: string) => createHash('sha256').update(v).digest('base64url');
+
+export class OAuth {
+  readonly o: Options;
+  constructor(o: Options) {
+    this.o = o;
+  }
+  get store() {
+    return this.o.store;
+  }
+  now() {
+    return this.o.now?.() ?? Date.now();
+  }
+
+  metadata() {
+    const i = this.o.issuer;
+    return {
+      issuer: i,
+      authorization_endpoint: `${i}/authorize`,
+      token_endpoint: `${i}/token`,
+      registration_endpoint: `${i}/register`,
+      response_types_supported: ['code'],
+      grant_types_supported: ['authorization_code', 'refresh_token'],
+      code_challenge_methods_supported: ['S256'],
+      token_endpoint_auth_methods_supported: ['none'],
+      scopes_supported: ['quo'],
+    };
+  }
+
+  protectedResource() {
+    return { resource: this.o.resource, authorization_servers: [this.o.issuer], bearer_methods_supported: ['header'] };
+  }
+
+  async register(body: unknown): Promise<Client | { error: string }> {
+    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 };
+    this.store.clients[client.client_id] = client;
+    await this.o.persist(this.store);
+    return client;
+  }
+
+  // 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 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') }) });
+    if (q.get('response_type') !== 'code') return back('unsupported_response_type');
+    const challenge = q.get('code_challenge');
+    if (!challenge || q.get('code_challenge_method') !== 'S256') return back('invalid_request');
+    const id = token();
+    this.store.pending[id] = { client_id: client.client_id, redirect_uri: redirect, challenge, state: q.get('state'), resource: q.get('resource'), exp: this.now() + CODE_TTL };
+    this.sweep();
+    await this.o.persist(this.store);
+    return { redirect: this.o.finish(id) };
+  }
+
+  // What the web route shows: who is asking. Null if the request is gone.
+  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);
+    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 }> {
+    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 };
+    await this.o.persist(this.store);
+    return { redirect: withQuery(p.redirect_uri, { code, state: p.state }) };
+  }
+
+  // The human refused, or the request died: the client hears that.
+  async deny(id: string): Promise<{ redirect: string } | { error: string }> {
+    const p = this.pending(id);
+    if (!p) return { error: 'expired' };
+    delete this.store.pending[id];
+    await this.o.persist(this.store);
+    return { redirect: withQuery(p.redirect_uri, { error: 'access_denied', state: p.state }) };
+  }
+
+  async token(body: URLSearchParams): Promise<Record<string, unknown>> {
+    const grant = body.get('grant_type');
+    if (grant === 'authorization_code') {
+      const c = own(this.store.codes, body.get('code') ?? '');
+      if (!c || c.exp < this.now()) return { error: 'invalid_grant' };
+      delete this.store.codes[body.get('code') ?? '']; // a code is spent the first time it is offered, right or wrong
+      const verifier = body.get('code_verifier') ?? '';
+      if (s256(verifier) !== c.challenge || (body.get('client_id') ?? c.client_id) !== c.client_id || (body.get('redirect_uri') ?? c.redirect_uri) !== c.redirect_uri) {
+        await this.o.persist(this.store);
+        return { error: 'invalid_grant' };
+      }
+      return this.issue(c.identity, 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 { error: 'unsupported_grant_type' };
+  }
+
+  async issue(identity: 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.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 {
+    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;
+  }
+
+  // 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];
+    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];
+  }
+
+  // The HTTP face. `rest` is the path under the route.
+  async handle(req: IncomingMessage, res: ServerResponse, rest: string): Promise<boolean> {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const json = (status: number, body: unknown, headers: Record<string, string> = {}) => {
+      res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store', ...headers });
+      res.end(JSON.stringify(body));
+    };
+    if (rest === '/.well-known/oauth-authorization-server' && req.method === 'GET') return json(200, this.metadata()), true;
+    if ((rest === '/.well-known/oauth-protected-resource' || rest === '/.well-known/oauth-protected-resource/mcp') && req.method === 'GET') return json(200, this.protectedResource()), true;
+    if (rest === '/register' && req.method === 'POST') {
+      const out = await this.register(await readJson(req));
+      return json('error' in out ? 400 : 201, out), true;
+    }
+    if (rest === '/authorize' && req.method === 'GET') {
+      const out = await this.authorize(url.searchParams);
+      if ('error' in out) return json(400, out), true;
+      res.writeHead(302, { location: out.redirect, 'cache-control': 'no-store' });
+      res.end();
+      return true;
+    }
+    if (rest === '/token' && req.method === 'POST') {
+      const out = await this.token(await readForm(req));
+      return json('error' in out ? 400 : 200, out), true;
+    }
+    return false;
+  }
+
+  // What an unauthenticated MCP request is told: where to go.
+  challenge(res: ServerResponse) {
+    res.writeHead(401, { 'www-authenticate': `Bearer resource_metadata="${this.o.issuer}/.well-known/oauth-protected-resource/mcp"`, 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'unauthorized' }));
+  }
+}
+
+function withQuery(base: string, params: Record<string, string | null>): string {
+  const u = new URL(base);
+  for (const [k, v] of Object.entries(params)) if (v !== null) u.searchParams.set(k, v);
+  return u.toString();
+}
+
+export async function readBody(req: IncomingMessage, limit = 64 * 1024): Promise<string> {
+  let s = '';
+  for await (const chunk of req) {
+    s += chunk;
+    if (s.length > limit) throw new Error('too large');
+  }
+  return s;
+}
+async function readJson(req: IncomingMessage): Promise<unknown> {
+  try {
+    return JSON.parse(await readBody(req));
+  } catch {
+    return {};
+  }
+}
+export async function readForm(req: IncomingMessage): Promise<URLSearchParams> {
+  const body = await readBody(req);
+  if ((req.headers['content-type'] ?? '').includes('application/json')) {
+    try {
+      const o = JSON.parse(body) as Record<string, unknown>;
+      return new URLSearchParams(Object.entries(o).map(([k, v]) => [k, String(v)]));
+    } catch {
+      return new URLSearchParams();
+    }
+  }
+  return new URLSearchParams(body);
+}

package/mcp/pilot.ts

@@ -0,0 +1,73 @@
+// 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';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, type CallToolResult, type Tool } from '@modelcontextprotocol/sdk/types.js';
+import { ask } from '../cli/client.ts';
+import type { Serving } from '../beings/side.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() };
+}

package/mcp/quo-mcp.md

@@ -0,0 +1,262 @@
+# The model side
+
+This is the one way a model meets a Quo world. 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, the roles and the shared invariants; this
+document assumes all of that and adds only what a model needs. It is
+model-agnostic on purpose. Claude, GPT, Kimi, a model in LM Studio, a model
+behind OpenRouter: capable or not, local or hosted, speaking MCP or plain
+function calling, every one meets a world in exactly one shape.
+
+A remote model, claude.ai or an API behind a vendor, is an occupant and
+nothing else. A local agent, Claude Code, `claude -p`, or any CLI agent on
+the Mac or the droplet, may also be the owner and the developer, and keeps
+the three apart.
+
+## What MCP is, in Quo words
+
+MCP is the description and value layer and nothing more. The mapping is total
+and needs no translation code beyond an envelope:
+
+| MCP                      | Quo                                                          |
+| ------------------------ | ------------------------------------------------------------ |
+| 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      |
+| 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.          |
+
+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.
+
+The three words for "no object" cross the envelope like this:
+
+| the avatar heard | the client gets                                                     |
+| ---------------- | ------------------------------------------------------------------- |
+| an object        | a tool result with that JSON                                        |
+| `{ error }`      | a tool result marked as error, with that JSON                       |
+| silence          | an error result, `{ error: 'silence' }`: the work may have happened |
+| unreached        | an error result, `{ error: 'unreached' }`: nothing was delivered    |
+| another word     | an error result, `{ error: word }`, with what the side says of it   |
+| `removed`        | at session open: 401, the token forgotten, the exchange again       |
+
+Silence is never turned into a retry by the envelope. The model decides, and
+the two words give it what it needs to decide.
+
+## Flows
+
+### A remote MCP client connects
+
+```
+client            mcp. route          front desk         user being        avatar
+  |-- OAuth ------->|                     |                  |                |
+  |                 |-- device(proof) --->|                  |                |
+  |                 |                     |-- invite ------->|                |
+  |                 |                     |<-- invitation ---|                |
+  |                 |<-- invitation ------|                  |                |
+  |                 |-- boot or find avatar for (human, client) ------------>|
+  |                 |-- knock(invitation) --------------------------------->|
+  |                 |                     |                  |<-- knock ------|
+  |                 |                     |                  |--- answer ---->|
+  |                 |                                                  take   |
+  |<-- initialize --|                                                          |
+  |-- tools/list -->|-- ask() ------------------------------------------------>|--> user being
+  |<-- tool list ---|<-- describe for this asker --------------------------------|
+  |-- tools/call -->|-- ask(name, args, { time }) ---------------------------->|--> user being
+  |<-- result ------|<-- object | error | silence | unreached ------------------|
+```
+
+### A local client connects over stdio
+
+Identical, with the differences that there is no OAuth, the proof is that the
+process runs as the human on the device, and the avatar lives in the laptop
+harbor. No droplet is needed for this. A dialer harbor is enough, because the
+model is on the same machine as the ward it talks to.
+
+### Two ways a model is driven
+
+Every model is driven in one of two ways, and the avatar is the same in
+both. What differs is who starts the loop.
+
+**The human is the loop.** You are in a chat and the model is your hands.
+You say "book the visit", it chains availability, calendar and book, each
+one an ask through your gate under the id you minted for it, and acme sees
+your id. Without the model you would press the buttons yourself, and that
+sentence is literally true: the screen is the user being's describe spoken
+as forms, the tool list is the same describe spoken as tools. Two sides onto
+one gate, and neither can do a thing the other cannot.
+
+**The world is the loop.** An agent lives alone in a folder with its own
+constitution, a `CLAUDE.md` or the equivalent for any other model, and is
+woken by events. The flow:
+
+1. **The trigger is a reverse ask.** The user being holds a standing to the
+   agent's avatar and asks it when something happens. The avatar's `answer`
+   is the side: it starts a run, `claude -p` or any CLI agent, in the
+   agent's folder with the event as the prompt.
+2. **Ack now, report later.** A run takes minutes; an ask waits thirty
+   seconds by default and five at the ceiling, and a late reply is not read.
+   So the avatar answers at once with an acknowledgement, and when the run
+   ends it asks the user being back on its own standing with the result.
+   A run never holds an ask open.
+3. **One run at a time.** Asks are concurrent by design, so two events would
+   start two runs in one folder. The avatar serializes runs per agent: one
+   constitution, one train of thought. A queue in her cells is enough.
+4. **Roles stay apart in one agent.** The run that does chores goes through
+   the gate as an occupant. If the same agent also boots beings, it holds the
+   owner pilot, and that is the estate: a separate run, through the pilot,
+   never the one doing the work.
+
+Two layers of permission exist here, and only one is real. The gate on the
+user being decides what the agent may ask, in hard terms. The constitution
+decides how it behaves, in soft terms. A permission never lives in the soft
+layer: a run gone wrong can do exactly what the gate shows the asker
+"agent", so that list is the narrowest that still gets the job done.
+
+The conventions this side pins, in `packages/dock/mcp/agent.ts`:
+
+| the agent side does   | as                                                              |
+| --------------------- | --------------------------------------------------------------- |
+| the event             | the object the user being pushed; `notify` answers at once      |
+| the queue             | her inbox, in her cells, so it survives the side and a reboot   |
+| a run                 | a function of the event, or a process in the agent's folder     |
+| the process           | the command, then the event as JSON as its last argument        |
+| its result            | `{ output }` from stdout, or `{ error, stderr }` on a bad exit  |
+| a run that throws     | `{ error }` with what it said                                   |
+| the callback          | `report({ event, result })` on the user being, gated to devices |
+| a report unanswered   | dropped, never retried, never held                              |
+| two events            | one after the other, first in first out                         |
+| on a device           | `<dir>/agents.json`: identity to command, args and folder       |
+| who wakes her         | the desk, or a device the human allowed to wake at the exchange |
+
+An event leaves the queue before its run starts, so a crash mid-run loses that
+event and never runs it twice. A run costs the human's quota, so the agent side
+never starts one on its own: only a push starts a run, one per event, never
+retried, and the command in `agents.json` names the model and the tools it may
+have; on the lab that is Haiku and no tools. `report` is the one ask this step
+added to the user being: every device may say what a run of its found, and she
+keeps it in her cells for whoever renders her. The proof is
+`packages/dock/test/agent.test.ts` with a fake run and a fake process.
+
+### A model that does not speak MCP
+
+OpenAI-style function calling, Kimi, LM Studio, OpenRouter, anything with a
+tools array. The side is a **runner**: a loop you own that holds the avatar's
+standing on one side and the model's API on the other.
+
+- The runner calls the empty ask and hands the model `asks[]` as its tool
+  definitions. The schema is already JSON Schema 2020-12; most APIs take it
+  verbatim, and the runner narrows it where one does not.
+- Each tool call from the model becomes a named ask on the avatar's standing.
+- Each answer, error, silence or word goes back as the tool result, in the
+  same mapping as above.
+
+The runner is not a second architecture. It is an MCP client written inline,
+and it uses the same avatar, the same invitation, the same gate. A model's
+capability changes how well it uses the tools and nothing about what it can
+reach: a weak model calls the wrong ask and gets an error object.
+
+What moved in-process is the host. An MCP client drives the loop from
+outside; a completions API cannot, so the runner drives it. It holds one
+conversation for as long as it serves, and two things start a turn in it:
+a line from the human, which is the human being the loop, and a push from
+the user being, which is the world being the loop. The conventions the
+runner pins, in `packages/dock/mcp/runner.ts`:
+
+| the runner does                | as                                                           |
+| ------------------------------ | ------------------------------------------------------------ |
+| the model                      | a base URL, a model name, a bearer from the device if wanted |
+| her describe                   | `tools[]` of `type: function`, name, description, parameters |
+| an ask with no properties      | sent with `properties: {}`; LM Studio refuses it bare        |
+| a tool call                    | a named ask; arguments that are not JSON are an error object |
+| a tool result                  | one `tool` message: JSON, or the text of the two words       |
+| a push                         | a `user` message holding the object; it starts a turn        |
+| a turn                         | until the model answers with no tool call, or ten calls      |
+| two turns                      | never at once: the second waits, one train of thought        |
+
+Ten is a ceiling, not a permission: a turn that ends there has no final
+text, and the gate decided everything the model reached. The proof is
+`packages/dock/test/runner.test.ts` over a scripted endpoint on loopback, and the
+same suite runs one live turn when `QUO_MODEL_URL` names a real endpoint.
+
+From a terminal the runner is `quo run --as NAME --url URL --model NAME`:
+the same pipe as `quo side`, with the model named in the hello line, so
+the daemon runs the runner beside the avatar it boots for the name. A line
+typed is a turn; the model's final text is a line back; a push from the
+user being starts a turn of its own and its text comes back the same way.
+A turn that ends at the ceiling, `--turns`, has no final text and comes
+back as an empty line; a model that fails comes back as one line holding
+an error object. The bearer, `QUO_MODEL_KEY`, is read by the command from
+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
+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.
+
+The owner does not do the work. A Claude Code session that boots a being and
+wants to try it connects to an avatar like anyone else and asks through the
+gate. If it could act as the owner, the arrival would be unnamed and no gate
+would have judged it.
+
+### The estate agent
+
+The spec has no estate on purpose. On the droplet it is `claude -p`, or any
+CLI agent, under cron, holding the owner pilot and one avatar:
+
+- through the pilot: read the census, boot again a being whose digest is
+  null this run, report a class the harbor no longer holds.
+- through the avatar: run the chores the human gated to it.
+
+Nothing about the estate agent is inside a ward. Lose the cron and the world
+keeps running; it just stops being looked after.
+
+### A model as the developer
+
+A local agent writes a being class to disk. The harbor holds class bodies, so
+a new class is a file the harbor loads and a name the owner boots. The
+developer role is a file system and an editor, plus the owner pilot to boot.
+Nothing crosses the wire.
+
+## Invariants of this side
+
+On top of the shared ones in the trunk:
+
+1. A run never holds an ask open: it acknowledges, and asks back with the
+   result.
+2. A permission lives in a gate, never in a constitution.
+3. The runner and the MCP server are two envelopes over one avatar; no
+   behaviour lives in either that the other lacks.
+
+## Glossary of this side
+
+- **constitution**: the folder and instructions an autonomous agent runs
+  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.