@nervur-org/dock 0.3.0

package/mcp/runner.ts

@@ -0,0 +1,136 @@
+// 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 '@nervur-org/nervur';
+import type { Avatar } from '../beings/avatar.ts';
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving } from '../beings/side.ts';
+import { presentation } from '../beings/look.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. Her look, her page and
+// every carried page are presentation, for a screen, and are not functions.
+export function tools(bp: Blueprint): Tool[] {
+  const shown = presentation(bp);
+  return bp.asks
+    .filter((a) => !shown.has(a.name))
+    .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,101 @@
+// SPDX-License-Identifier: Apache-2.0
+// 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 '@nervur-org/nervur';
+import { word, wordText, SILENCE_TEXT, UNREACHED_TEXT, type Serving, type Subject } from '../beings/side.ts';
+import { hintFor, presentation, sanitise, type Look } from '../beings/look.ts';
+import { isSilence, isWord, digest } from '@nervur-org/nervur';
+
+export const NAME = 'quo';
+export const VERSION = '0.0.0';
+
+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. Her look, her page and every carried page are presentation, for a
+// screen, and are not tools.
+export function tools(bp: Blueprint, look: Look = {}): Tool[] {
+  const shown = presentation(bp);
+  const asks = bp.asks
+    .filter((a) => !shown.has(a.name))
+    .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: 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
+    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);
+      } else look = {};
+    }
+    return { tools: tools(bp as Blueprint, look) };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (req): Promise<CallToolResult> => {
+    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 } : {};
+      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/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@nervur-org/dock",
+  "version": "0.3.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",
+  "homepage": "https://nervur.org",
+  "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"
+    },
+    "./cli": "./dist/cli/quo.js",
+    "./stand": {
+      "types": "./dist/cli/stand.d.ts",
+      "default": "./dist/cli/stand.js"
+    },
+    "./harbor/browser": {
+      "types": "./dist/harbor/browser.d.ts",
+      "default": "./dist/harbor/browser.js"
+    },
+    "./harbor/capacitor": {
+      "types": "./dist/harbor/capacitor.d.ts",
+      "default": "./dist/harbor/capacitor.js"
+    },
+    "./harbor/tauri": {
+      "types": "./dist/harbor/tauri.d.ts",
+      "default": "./dist/harbor/tauri.js"
+    },
+    "./human/apps": {
+      "types": "./dist/human/apps.d.ts",
+      "default": "./dist/human/apps.js"
+    },
+    "./human/html": {
+      "types": "./dist/human/html.d.ts",
+      "default": "./dist/human/html.js"
+    },
+    "./human/app": {
+      "types": "./dist/human/app.d.ts",
+      "default": "./dist/human/app.js"
+    },
+    "./human/worlds": {
+      "types": "./dist/human/worlds.d.ts",
+      "default": "./dist/human/worlds.js"
+    },
+    "./beings/link": {
+      "types": "./dist/beings/link.d.ts",
+      "default": "./dist/beings/link.js"
+    },
+    "./human/style": {
+      "types": "./dist/human/style.d.ts",
+      "default": "./dist/human/style.js"
+    },
+    "./human/mark": {
+      "types": "./dist/human/mark.d.ts",
+      "default": "./dist/human/mark.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 && node build/bundle.ts && chmod +x dist/cli/quo.js && cp harbor/edge/platform.d.ts dist/harbor/edge/ && cp -R cli/estate dist/cli/ && cp ../../papers/quo-dock.md beings/ && cp ../../papers/quo-dock.md dock/ && cp ../../papers/quo-dock.md cli/ && cp ../../papers/quo-human.md human/ && cp ../../papers/quo-mcp.md mcp/ && cp ../../papers/quo-api.md api/ && cp ../../papers/quo-harbor.md harbor/ && cp ../../papers/quo-app-bells.md beings/ && cp ../../papers/quo-app-bells.md dock/ && cp ../../papers/GLOSSARY.md beings/ && cp ../../papers/WORLDS.md beings/ && cp ../../papers/GETTING_STARTED.md GETTING_STARTED.md",
+    "check": "node --test \"test/*.test.ts\"",
+    "deep": "node --test \"test/terrain/*.test.ts\"",
+    "prepublishOnly": "test \"$QUO_GATED\" = 1 || { echo 'publish from the root, gated once: npm run release:dock' >&2; exit 1; }"
+  },
+  "dependencies": {
+    "@aparajita/capacitor-secure-storage": "^8.0.0",
+    "@capacitor/app": "^8.1.1",
+    "@capacitor/core": "^8.5.1",
+    "@capacitor/filesystem": "^8.1.3",
+    "@capacitor/geolocation": "^8.2.2",
+    "@capacitor/local-notifications": "^8.3.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@nervur-org/nervur": "^0.3.0",
+    "@nervur-org/ui": "^0.3.0",
+    "ws": "^8.21.3"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.18.1",
+    "esbuild": "^0.28.2",
+    "wrangler": "^4.129.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "beings",
+    "dock",
+    "cli",
+    "harbor",
+    "mcp",
+    "human",
+    "api",
+    "GETTING_STARTED.md",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}