@quo-systems/dock 0.1.0

package/beings/setup.ts

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+// The root's setup of a fresh ward, as every terrain does it: the front desk
+// booted public, one user being, and the desk holding a standing to her
+// under `user:<name>`, placed by the root's knock. She names it `desk`, and
+// that id is the only thing that makes it the desk. A disk harbor does this
+// at `quo init`, the edge at its root route's init; the memory harbor's
+// test world does the same by hand.
+import type { Invitation } from '@quo-systems/quo';
+import type { Hosted } from '@quo-systems/quo/harbor';
+import { DESK } from './user.ts';
+
+export async function setup(hosted: Hosted, user: string): Promise<void> {
+  if (!/^[\w.-]+$/.test(user) || user === 'desk') throw new Error(`a user is a word, and not desk: ${user}`);
+  const boot = async (args: Record<string, unknown>) => {
+    const out = (await hosted.ask('boot', args)) as { booted?: string; error?: string };
+    if (out.error) throw new Error(`init: ${out.error}`);
+  };
+  await boot({ key: 'desk', class: 'Desk', public: true });
+  await boot({ key: user, class: 'User' });
+  const inv = (await hosted.ask('invite', { being: user, id: DESK })) as Invitation;
+  const placed = (await hosted.ask('knock', { being: 'desk', id: `user:${user}`, invitation: inv, method: 'hello' })) as { taken?: string };
+  if (placed.taken !== `user:${user}`) throw new Error('init: the desk could not reach the user being');
+}

package/beings/side.ts

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: Apache-2.0
+// The side: the one interface an avatar speaks through to someone outside
+// Quo. A side takes the avatar object, in-process, and renders three things
+// its own way: her describe as what that someone reads, a call as an ask on
+// her one standing, and a push as a notification. Sides in this repository:
+// a screen, an MCP server, a runner, an event-driven agent. None knows
+// another exists, and none of this file names a platform.
+import { isSilence, isUnreached, isWord, wordOf } from '@quo-systems/quo';
+import type { Answer, Json, JsonObject, WordName } from '@quo-systems/quo';
+import type { Avatar } from './avatar.ts';
+
+// A side, running: it holds the avatar until closed.
+export type Serving = { close(): Promise<void> };
+export type Side = (avatar: Avatar) => Promise<Serving>;
+
+// The three words for "no object", and the object itself, as every side must
+// tell them apart before rendering. An error object is an ordinary answer
+// that the side may mark; silence and unreached are not objects at all.
+export type Word =
+  | { word: 'object'; value: Json }
+  | { word: 'error'; value: JsonObject }
+  | { word: 'silence' }
+  | { word: 'unreached' }
+  | { word: 'quo'; name: WordName }; // the ward's word, named: why no object came
+
+export function word(answer: Answer): Word {
+  if (isSilence(answer)) return { word: 'silence' };
+  if (isUnreached(answer)) return { word: 'unreached' };
+  if (isWord(answer)) return { word: 'quo', name: wordOf(answer) };
+  if (answer !== null && typeof answer === 'object' && !Array.isArray(answer) && 'error' in answer) return { word: 'error', value: answer };
+  return { word: 'object', value: answer };
+}
+
+// What a side says about the two words that carry nothing, so that whoever
+// reads them can decide: silence promises nothing, unreached promises that
+// nothing was delivered.
+export const SILENCE_TEXT = 'silence: the work may have happened, and no answer came back';
+export const UNREACHED_TEXT = 'unreached: nothing was delivered; asking again is safe';
+// And the ward's other words, each with what a side says of it.
+export const WORD_TEXT: Record<WordName, string> = {
+  unreached: UNREACHED_TEXT,
+  late: 'late: the wait ran out; the work may have happened',
+  invitation: 'invitation: that is not an invitation',
+  dropped: 'dropped: the standing is gone',
+  removed: 'removed: the far being removed you',
+  absent: 'absent: the far being did not come back this run',
+  unannounced: 'unannounced: the knock announced no key of its own',
+  repeated: 'repeated: that number was already honoured',
+  threw: 'threw: the far being threw',
+};
+export const wordText = (name: WordName): string => WORD_TEXT[name];

package/beings/user.ts

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+// The user being. One per human, running wherever the human's world runs.
+// She holds the human's standings, and everyone who acts for the human is
+// her occupant, seeing what her gate shows. Two of her occupants are
+// special only by the id the root chose for them: `desk`, the front desk,
+// who may ask her to invite a device; and each device, whose id is the
+// client identity the desk established.
+import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+import type { Asker, Invitation, JsonObject, OccupantRecord } from '@quo-systems/quo';
+
+export const DESK = 'desk';
+const isDesk = (occ: OccupantRecord | undefined) => occ?.id === DESK;
+const isDevice = (occ: OccupantRecord | undefined) => occ !== undefined && occ.id !== DESK;
+const client = (occ: OccupantRecord | undefined) => (typeof occ?.notes.client === 'string' ? occ.notes.client : null);
+// A device the human allowed to wake her other devices: the note says so.
+const mayWake = (occ: OccupantRecord | undefined) => isDesk(occ) || occ?.notes.wake === true;
+
+export class User extends Being {
+  static override cells = { name: '', reports: [] as JsonObject[] };
+  static override asks = {
+    hello: { description: 'say hello, and hand back an invitation so she can reach you', input: { type: 'object', properties: { invitation: { type: 'object' } } } },
+    whoami: { description: 'who she thinks you are', input: { type: 'object' }, for: isDevice },
+    device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
+    push: { description: 'push an object to a device: wake it with an event', input: { type: 'object', properties: { client: { type: 'string' }, object: { type: 'object' } }, required: ['client', 'object'] }, for: mayWake },
+    chores: { description: 'what the agent may run', input: { type: 'object' }, for: (occ: OccupantRecord | undefined) => client(occ) === 'agent' },
+    report: { description: 'what a run of yours found', input: { type: 'object', properties: { event: { type: 'object' }, result: {} }, required: ['event', 'result'] }, for: isDevice },
+  };
+
+  // Anyone may say hello. A device that hands her an invitation in the args
+  // is taken as a standing under its own id, so she can push to it later.
+  async hello(args: JsonObject, asker: Asker) {
+    if (asker.id !== undefined && args.invitation && typeof args.invitation === 'object' && !Array.isArray(args.invitation)) {
+      const inv = args.invitation as Invitation;
+      const back = await this.knock(inv);
+      if (!isSilence(back) && !isWord(back)) await this.take(`to:${asker.id}`, inv);
+    }
+    return { welcome: asker.id ?? null, name: this.cells.name };
+  }
+
+  whoami(_args: JsonObject, asker: Asker) {
+    return { id: asker.id ?? null, client: client(this.occupant(asker)) };
+  }
+
+  // The front desk asks; she mints. The client identity goes into the
+  // occupant's notes, and that is what every gate reads. `wake` is the
+  // human's word at the exchange that this device may wake her others.
+  async device(args: JsonObject) {
+    const c = typeof args.client === 'string' ? args.client : null;
+    if (c === null) return { error: 'client is a string' };
+    const inv = await this.invite(c);
+    if (inv === null) return { error: 'id taken' };
+    const rec = this.cells.occupants[c];
+    if (rec) {
+      rec.notes.client = c;
+      if (args.wake === true) rec.notes.wake = true;
+    }
+    return inv as unknown as JsonObject;
+  }
+
+  async push(args: JsonObject) {
+    const c = typeof args.client === 'string' ? args.client : null;
+    const st = c === null ? undefined : this.standings[`to:${c}`];
+    if (!st) return { error: 'no such device, or it gave no way back' };
+    const out = await st.ask('notify', (args.object as JsonObject) ?? {});
+    return isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: wordOf(out) } : { pushed: out };
+  }
+
+  chores() {
+    return { chores: ['census', 'report'] };
+  }
+
+  // A device that ran something for her says what it found. Kept, so that
+  // whoever renders her can show it; the ask itself is the callback.
+  report(args: JsonObject, asker: Asker) {
+    (this.cells.reports as JsonObject[]).push({ from: asker.id ?? null, event: args.event ?? null, result: args.result ?? null });
+    return { reported: true };
+  }
+}

package/cli/client.ts

@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: Apache-2.0
+// A client of the daemon's socket. One ask, one line, one reply. This is
+// what every subcommand but init and serve is: connect, ask, print, exit.
+import { connect } from 'node:net';
+import { createInterface } from 'node:readline';
+import { sockPath, sidePath } from './daemon.ts';
+
+export type Answer = { result: unknown } | { error: string };
+
+// `via` names a standing the ward's user being holds at another ward: the
+// ask is then an owner's ask at that ward's door, sealed, and the answer is
+// the far ward's. Without it the ask is the root's, on the pointer.
+export function ask(dir: string, method: string | undefined, args: Record<string, unknown> = {}, ward = 'main', via?: string): Promise<Answer> {
+  return line(dir, via === undefined ? { ward, method, args } : { ward, method, args, via });
+}
+
+// `quo reach`: a hint for the harbor's directory, which is the harbor's and
+// not a ward's, so it crosses the root socket as its own line.
+export function reach(dir: string, pk: string, url: string): Promise<Answer> {
+  return line(dir, { reach: { pk, url } });
+}
+
+function line(dir: string, body: Record<string, unknown>): Promise<Answer> {
+  return new Promise((ok, no) => {
+    const c = connect(sockPath(dir));
+    const id = Math.random().toString(36).slice(2);
+    c.once('error', (e: NodeJS.ErrnoException) => no(e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? new Error(`no daemon at ${dir}: run \`quo serve\``) : e));
+    c.once('connect', () => {
+      c.write(JSON.stringify({ id, ...body }) + '\n');
+      createInterface({ input: c }).once('line', (line) => {
+        c.end();
+        const r = JSON.parse(line) as { id: string; result?: unknown; error?: string };
+        ok(r.error !== undefined ? { error: r.error } : { result: r.result });
+      });
+    });
+  });
+}
+
+// `quo side`: a pipe. Hello to the daemon's side socket, then stdin to the
+// socket and the socket to stdout, line for line, until either end closes.
+// The MCP server runs in the daemon, beside the avatar; this process knows
+// nothing of MCP but its newlines.
+//
+// `quo run` is the same pipe with a model named in the hello: the daemon
+// runs the runner beside the avatar, each line typed is a turn, and each
+// final text comes back as a line.
+export type Run = { url: string; model: string; key?: string; turns?: number };
+export function side(dir: string, as: string, ward = 'main', run?: Run): Promise<void> {
+  return new Promise((ok, no) => {
+    const c = connect(sidePath(dir));
+    c.once('error', (e: NodeJS.ErrnoException) => no(e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? new Error(`no daemon at ${dir}: run \`quo serve\``) : e));
+    c.once('connect', () => {
+      c.write(JSON.stringify(run ? { as, ward, run } : { as, ward }) + '\n');
+      const lines = createInterface({ input: c });
+      lines.once('line', (hello) => {
+        const h = JSON.parse(hello) as { ok?: string; error?: string };
+        if (h.error !== undefined) return no(new Error(h.error));
+        lines.on('line', (line) => process.stdout.write(line + '\n'));
+        createInterface({ input: process.stdin }).on('line', (line) => c.write(line + '\n'));
+        process.stdin.once('end', () => c.end());
+      });
+      c.once('close', () => ok());
+    });
+  });
+}