@quo-systems/dock 0.1.0

package/mcp/runner.ts

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+// The model side as a runner: an MCP client written inline, for a model that
+// speaks function calling and not MCP. The avatar is the one in server.ts and
+// the mapping is the same envelope; what moved in-process is the host that
+// drives the loop, because a completions API cannot. The runner holds one
+// conversation for as long as it serves. Two things start a turn in it: a
+// line from the human, and a push from the user being, which is the world
+// asking. A turn posts the conversation with her describe as tools, turns
+// each tool call into a named ask on her standing, hands the result back as
+// a tool message, and ends when the model answers with no tool call, or at
+// the ceiling. Nothing here names a vendor: the endpoint is a base URL and a
+// model name, which is LM Studio, OpenRouter, or a scripted fake alike.
+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';
+
+// Where the model is. `key` is a bearer for endpoints that want one, read
+// from the device and never from cells. `turns` is the ceiling of model
+// calls in one turn of the conversation; ten by default.
+export type Model = { url: string; model: string; key?: string; turns?: number };
+export const TURNS = 10;
+
+// The wire shapes, only as much as the loop reads and writes.
+export type Tool = { type: 'function'; function: { name: string; description?: string; parameters: JsonObject } };
+export type ToolCall = { id: string; type: 'function'; function: { name: string; arguments: string } };
+export type Message =
+  | { role: 'system' | 'user'; content: string }
+  | { role: 'assistant'; content: string | null; tool_calls?: ToolCall[] }
+  | { role: 'tool'; tool_call_id: string; content: string };
+type Completion = { choices: { message: { role: 'assistant'; content: string | null; tool_calls?: ToolCall[] } }[]; error?: unknown };
+
+// Her describe, spoken as a tools array. Name, description and input are
+// verbatim, with the one narrowing an endpoint has asked for: an ask that
+// declares no properties is sent with an empty `properties`, because
+// LM Studio refuses a parameters schema without one.
+export function tools(bp: Blueprint): Tool[] {
+  return bp.asks.map((a) => {
+    const t: Tool = { type: 'function', function: { name: a.name, parameters: { properties: {}, ...a.input, type: 'object' } } };
+    if (a.description !== undefined) t.function.description = a.description;
+    return t;
+  });
+}
+
+// One tool call, one ask, one tool message: the three words cross as the
+// table in quo-mcp.md says, and a tool message is text, so the two words
+// that carry nothing cross as the text the trunk gives them.
+export async function result(avatar: Avatar, call: ToolCall): Promise<string> {
+  let args: JsonObject = {};
+  try {
+    const parsed: unknown = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) args = parsed as JsonObject;
+  } catch {
+    return JSON.stringify({ error: 'arguments are not JSON' });
+  }
+  const w = word(await avatar.call(call.function.name, args));
+  if (w.word === 'object' || w.word === 'error') return JSON.stringify(w.value);
+  return w.word === 'silence' ? SILENCE_TEXT : w.word === 'quo' ? wordText(w.name) : UNREACHED_TEXT;
+}
+
+export type Runner = Serving & {
+  // A line from the human; resolves with the model's final text, or null
+  // when the turn ended at the ceiling.
+  say(text: string): Promise<string | null>;
+  // The conversation so far, for whoever renders it.
+  readonly messages: readonly Message[];
+};
+
+// `hear` gets every final text the model says, whoever started the turn.
+// `after` runs when an ask is done, as in the MCP server: a harbor that must
+// write what the ward changed hooks it.
+export function runnerSide(avatar: Avatar, model: Model, hear: (text: string) => void = () => {}, after: () => Promise<void> = async () => {}): Runner {
+  const messages: Message[] = [];
+  const ceiling = model.turns ?? TURNS;
+  let busy: Promise<unknown> = Promise.resolve();
+
+  async function complete(t: Tool[]): Promise<Completion['choices'][0]['message']> {
+    const headers: Record<string, string> = { 'content-type': 'application/json' };
+    if (model.key !== undefined) headers.authorization = `Bearer ${model.key}`;
+    const res = await fetch(`${model.url.replace(/\/$/, '')}/chat/completions`, { method: 'POST', headers, body: JSON.stringify({ model: model.model, messages, tools: t }) });
+    const body = (await res.json()) as Completion;
+    const m = body.choices?.[0]?.message;
+    if (!res.ok || !m) throw new Error(`model: ${res.status} ${JSON.stringify(body.error ?? body)}`);
+    return m;
+  }
+
+  // One turn: from the last appended message to the model's final text.
+  async function turn(): Promise<string | null> {
+    const bp = await avatar.tools();
+    const t = 'asks' in bp ? tools(bp) : [];
+    for (let i = 0; i < ceiling; i++) {
+      const m = await complete(t);
+      const reply: Message = { role: 'assistant', content: m.content };
+      if (m.tool_calls?.length) reply.tool_calls = m.tool_calls;
+      messages.push(reply);
+      if (!m.tool_calls?.length) {
+        const text = m.content ?? '';
+        hear(text);
+        return text;
+      }
+      for (const call of m.tool_calls) {
+        messages.push({ role: 'tool', tool_call_id: call.id, content: await result(avatar, call) });
+        await after();
+      }
+    }
+    return null;
+  }
+
+  // Turns never overlap: one conversation, one train of thought.
+  function start(message: Message): Promise<string | null> {
+    const next = busy.then(async () => {
+      messages.push(message);
+      return turn();
+    });
+    busy = next.catch(() => {});
+    return next;
+  }
+
+  const ear = (object: JsonObject) => {
+    void start({ role: 'user', content: JSON.stringify(object) }).catch(() => {});
+  };
+  avatar.ears.add(ear);
+
+  return {
+    messages,
+    say: (text) => start({ role: 'user', content: text }),
+    close: async () => {
+      avatar.ears.delete(ear);
+      await busy;
+    },
+  };
+}

package/mcp/server.ts

@@ -0,0 +1,67 @@
+// 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
+// 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';
+
+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;
+  });
+}
+
+// `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> {
+  const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: { listChanged: true }, logging: {} } });
+
+  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) };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
+    const w = word(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 } : {};
+      return { content: [{ type: 'text', text: JSON.stringify(w.value) }], ...structured };
+    }
+    if (w.word === 'error') return { content: [{ type: 'text', text: JSON.stringify(w.value) }], structuredContent: w.value, isError: true };
+    if (w.word === 'silence') return { content: [{ type: 'text', text: SILENCE_TEXT }], structuredContent: { error: 'silence' }, isError: true };
+    if (w.word === 'quo') return { content: [{ type: 'text', text: wordText(w.name) }], structuredContent: { error: w.name }, isError: true };
+    return { content: [{ type: 'text', text: UNREACHED_TEXT }], structuredContent: { error: 'unreached' }, isError: true };
+  });
+
+  // A push from the user being is a notification to the client. If the
+  // transport is gone, the push is dropped, as the side says it is.
+  const ear = (object: JsonObject) => {
+    void server.sendLoggingMessage({ level: 'info', logger: NAME, data: object }).catch(() => {});
+  };
+  avatar.ears.add(ear);
+
+  await server.connect(transport);
+  return {
+    close: async () => {
+      avatar.ears.delete(ear);
+      await server.close();
+    },
+  };
+}

package/mcp/web/exchange.ts

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+// The exchange pages on the web route. Two static pages, hand-written, and
+// explicitly not the human side: they render no blueprint. They end the
+// credential exchange the way the trunk says every route does: a proof is
+// made, the front desk trades it for an invitation, the avatar knocks, and
+// the OAuth request completes with the client identity the human chose.
+//
+//   GET  /login?request=ID     the owner password, from QUO_OWNER_PASSWORD
+//   POST /login                sets a short session cookie, goes to /allow
+//   GET  /allow?request=ID     who is asking, and the identity they will be
+//   POST /allow                allow as that identity, or deny
+//
+// The password is the device's, read from the environment the way an envoy
+// reads a secret, never through cells. With none set, the exchange is closed.
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { OAuth } from '../oauth.ts';
+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 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
+  now?: () => number;
+};
+
+const esc = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c);
+const word = (s: unknown) => (typeof s === 'string' && /^[\w.-]{1,40}$/.test(s) ? s : null);
+// A client's name as an identity: lowercase words joined by dashes.
+export const suggest = (name: string) =>
+  name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 40) || 'client';
+
+export class Exchange {
+  readonly o: Options;
+  readonly secret = randomBytes(32); // sessions die with the daemon, and that is fine: they live ten minutes
+  constructor(o: Options) {
+    this.o = o;
+  }
+  now() {
+    return this.o.now?.() ?? Date.now();
+  }
+
+  // ---- the session cookie: an expiry, signed
+
+  mint(): string {
+    const exp = String(this.now() + SESSION_TTL);
+    return `${exp}.${createHmac('sha256', this.secret).update(exp).digest('base64url')}`;
+  }
+  valid(req: IncomingMessage): boolean {
+    const m = /(?:^|;\s*)quo_exchange=([^;]+)/.exec(req.headers.cookie ?? '');
+    const [exp, sig] = (m?.[1] ?? '').split('.');
+    if (!exp || !sig) return false;
+    const want = createHmac('sha256', this.secret).update(exp).digest('base64url');
+    return sig.length === want.length && timingSafeEqual(Buffer.from(sig), Buffer.from(want)) && Number(exp) > this.now();
+  }
+
+  async handle(req: IncomingMessage, res: ServerResponse, rest: string): Promise<boolean> {
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const page = (status: number, body: string, headers: Record<string, string> = {}) => {
+      res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', ...headers });
+      res.end(shell(body));
+    };
+    const go = (to: string, headers: Record<string, string> = {}) => {
+      res.writeHead(302, { location: to, 'cache-control': 'no-store', ...headers });
+      res.end();
+    };
+
+    if (rest === '/login' && req.method === 'GET') {
+      const request = url.searchParams.get('request') ?? '';
+      const p = this.o.oauth.pending(request);
+      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone. Start again from the app that sent you here.</p>`), true;
+      if (this.o.password() === undefined) return page(503, `<h1>Closed</h1><p>This world takes no logins: no owner password is set.</p>`), true;
+      if (this.valid(req)) return go(`/allow?request=${encodeURIComponent(request)}`), true;
+      return page(200, loginForm(request, p.client.client_name)), true;
+    }
+    if (rest === '/login' && req.method === 'POST') {
+      const f = await readForm(req);
+      const request = f.get('request') ?? '';
+      const p = this.o.oauth.pending(request);
+      if (!p) return page(400, `<h1>Nothing to allow</h1><p>This request is gone.</p>`), true;
+      const want = this.o.password();
+      const got = f.get('password') ?? '';
+      if (want === undefined) return page(503, `<h1>Closed</h1>`), true;
+      if (got.length !== want.length || !timingSafeEqual(Buffer.from(got), Buffer.from(want))) {
+        await new Promise((ok) => setTimeout(ok, 300));
+        return page(401, loginForm(request, p.client.client_name, 'That is not the password.')), true;
+      }
+      return go(`/allow?request=${encodeURIComponent(request)}`, { 'set-cookie': `${COOKIE}=${this.mint()}; Path=/; HttpOnly; Secure; SameSite=Strict; Max-Age=${SESSION_TTL / 1000}` }), true;
+    }
+    if (rest === '/allow' && req.method === 'GET') {
+      const request = url.searchParams.get('request') ?? '';
+      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;
+    }
+    if (rest === '/allow' && req.method === 'POST') {
+      const f = await readForm(req);
+      const request = f.get('request') ?? '';
+      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;
+      if (f.get('decision') !== 'allow') {
+        const out = await this.o.oauth.deny(request);
+        return 'redirect' in out ? go(out.redirect) : page(400, `<h1>Gone</h1>`), 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 (admitted.error) return page(500, `<h1>Not admitted</h1><p>${esc(admitted.error)}</p>`), true;
+      const out = await this.o.oauth.complete(request, identity);
+      return 'redirect' in out ? go(out.redirect, { 'set-cookie': `${COOKIE}=; Path=/; Max-Age=0` }) : page(400, `<h1>Gone</h1>`), true;
+    }
+    return false;
+  }
+}
+
+const shell = (body: string) => `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>quo</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:4rem auto;padding:0 1rem;color:#222}h1{font-size:1.4rem}label{display:block;margin:1rem 0 .25rem}input{font:inherit;padding:.5rem;width:100%;box-sizing:border-box}button{font:inherit;padding:.5rem 1rem;margin:1rem .5rem 0 0}.err{color:#b00}.who{background:#f4f4f4;padding:.75rem 1rem;border-radius:.5rem}code{word-break:break-all}</style>
+</head><body>${body}</body></html>`;
+
+const loginForm = (request: string, client: string, err = '') => `<h1>${esc(client)} wants in</h1>
+<p>Log in as the owner of this world to decide.</p>
+${err ? `<p class="err">${esc(err)}</p>` : ''}
+<form method="post" action="/login"><input type="hidden" name="request" value="${esc(request)}">
+<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>
+<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)}">
+<label for="i">Identity</label><input id="i" name="identity" value="${esc(identity)}" pattern="[\\w.-]{1,40}" required>
+<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

@@ -0,0 +1,89 @@
+{
+  "name": "@quo-systems/dock",
+  "version": "0.1.0",
+  "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",
+    "estate",
+    "harbor",
+    "mcp",
+    "daemon"
+  ],
+  "author": "Razvan Gherghina",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "bin": {
+    "quo": "./dist/cli/quo.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/beings/index.d.ts",
+      "default": "./dist/beings/index.js"
+    },
+    "./harbor/disk": {
+      "types": "./dist/harbor/disk.d.ts",
+      "default": "./dist/harbor/disk.js"
+    },
+    "./harbor/browser": {
+      "types": "./dist/harbor/browser.d.ts",
+      "default": "./dist/harbor/browser.js"
+    },
+    "./cli/daemon": {
+      "types": "./dist/cli/daemon.d.ts",
+      "default": "./dist/cli/daemon.js"
+    },
+    "./mcp/server": {
+      "types": "./dist/mcp/server.d.ts",
+      "default": "./dist/mcp/server.js"
+    },
+    "./mcp/runner": {
+      "types": "./dist/mcp/runner.d.ts",
+      "default": "./dist/mcp/runner.js"
+    },
+    "./mcp/agent": {
+      "types": "./dist/mcp/agent.d.ts",
+      "default": "./dist/mcp/agent.js"
+    },
+    "./human/screen": {
+      "types": "./dist/human/screen.d.ts",
+      "default": "./dist/human/screen.js"
+    },
+    "./human/html": {
+      "types": "./dist/human/html.d.ts",
+      "default": "./dist/human/html.js"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "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",
+    "esbuild": "^0.28.2",
+    "ws": "^8.21.3"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "wrangler": "^4.129.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "beings",
+    "cli",
+    "harbor",
+    "mcp",
+    "human",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}