clavarium 0.2.367-next.1 → 0.2.369-next.1

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "clavarium",
-  "version": "0.2.367-next.1",
+  "version": "0.2.369-next.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "clavarium",
-      "version": "0.2.367-next.1",
+      "version": "0.2.369-next.1",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavarium",
-  "version": "0.2.367-next.1",
+  "version": "0.2.369-next.1",
   "license": "MIT",
   "type": "module",
   "description": "A conversation is a VM with a terminal in it. Everything else is a folder.",

package/server/api.mjs

@@ -700,6 +700,8 @@ export async function handleApi(request, response, conversations, headers, resou
             if (access !== 'write') gitKeeper?.forgetAttachment(name, conversation);
             await resources.attach(conversation, name, access);
             retell(conversation);
+            /* Newly attached: its links looked at (and its mounts), not waited for. */
+            if (access !== 'none') void health?.check?.(conversation, { asked: true })?.catch?.(() => {});
         };
         const handSecret = async (conversation, name, attached) => {
             if (!conversations.list().some((c) => c.name === conversation)) throw new Refusal(404, 'No such conversation.');
@@ -868,6 +870,13 @@ export async function handleApi(request, response, conversations, headers, resou
             if (!conversations.list().some((c) => c.name === conversation)) throw new Refusal(404, 'No such conversation.');
             return send(200, health.markSeen(conversation)), true;
         }
+        /* "Check shared folders": each mounted and readable (put back when loose), each link the share cannot serve (health.mjs). */
+        const foldersOf = /^\/api\/conversations\/([^/]+)\/folders\/check$/.exec(pathname);
+        if (foldersOf && health) {
+            const conversation = decodeURIComponent(foldersOf[1]);
+            if (!conversations.list().some((c) => c.name === conversation)) throw new Refusal(404, 'No such conversation.');
+            return send(200, await health.checkFolders(conversation)), true;
+        }
         const machine = /^\/api\/conversations\/([^/]+)\/(restart|machine|health)$/.exec(pathname);
         if (machine) {
             const conversation = decodeURIComponent(machine[1]);

package/server/apikeys.mjs

@@ -17,6 +17,20 @@
  *   A conversation archived takes its lines with it (devices.forget). Its
  *   terminal ("x") is never given to a key.
  *
+ *   a room, given ONE BY ONE the same way:
+ *     read    read its thread, as the page reads it (names, never ids;
+ *             secrets masked)                                 room:<id> r
+ *     talk    and post in it as the person does -- to its host, or to the AIs
+ *             named -- signed with the key's name and look    room:<id> rw
+ *
+ *   a voice box, given ONE BY ONE:
+ *     state   online, where it speaks, when it last heard, its volume --
+ *             nothing it heard, never audio                   box:<id> r
+ *     speak   and make it say a short text aloud (SPEAK_MAX characters,
+ *             SPEAK_PER_MIN a minute per key and box): never listen, record,
+ *             change its settings nor update it               box:<id> rw
+ *   A room removed, a box withdrawn, takes its lines with it (main.mjs).
+ *
  * THE SECRET IS SHOWN ONCE. It is made here (32 random bytes, "clv_" before
  * them), given back by `create` and never again: only its sha256 is kept, as
  * a pairing's session is (devices.mjs). A 256-bit random secret needs no salt
@@ -40,6 +54,9 @@
  *   POST /api/apikeys                   {label, scopes, conversations: {name: 'read'|'talk'}, days|null}
  *                                       -> {key, secret}: the secret this once
  *   POST /api/apikeys/<id>/conversations {conversation, level: 'read'|'talk'|null}: one given, changed, taken back
+ *   POST /api/apikeys/<id>/rooms        {room, level: 'read'|'talk'|null}
+ *   POST /api/apikeys/<id>/boxes        {box, level: 'state'|'speak'|null}
+ *   (and on creation: rooms: {id: level}, boxes: {id: level})
  *   POST /api/apikeys/<id>/revoke
  *   GET  /api/apikeys/<id>/journal      its last uses
  *
@@ -48,9 +65,15 @@
  *   GET  /api/ext/v1/conversations                       those it may read: {conversations: [{id, name, level, chat}]}
  *   GET  /api/ext/v1/conversations/<name>/messages       ?last=1..200 (50) | ?since=<cursor>: {chat, messages, cursor}
  *   POST /api/ext/v1/conversations/<name>/messages       {text}: posted in its chat, signed with the key's name
+ *   GET  /api/ext/v1/rooms                               those it may read: {rooms: [{id, name, level, host, members}]}
+ *   GET  /api/ext/v1/rooms/<id>/messages                 as a conversation's: {messages, cursor}
+ *   POST /api/ext/v1/rooms/<id>/messages                 {text, to?: [names of its AIs]}: posted in the room, signed with the key
+ *   GET  /api/ext/v1/boxes                               {boxes: [{id, name, level, online, where, heardAt, volume}]}
+ *   POST /api/ext/v1/boxes/<id>/say                      {text}: said aloud by the box
  *   POST /api/ext/mcp                   the same as MCP tools (clavarium_status, clavarium_conversations,
- *                                       clavarium_read, clavarium_say), JSON-RPC over HTTP
- *   A conversation not given, or not there, is the same 403: a key learns nothing of what it was not given.
+ *                                       clavarium_read, clavarium_say, clavarium_rooms, clavarium_room_read,
+ *                                       clavarium_room_say, clavarium_boxes, clavarium_box_say), JSON-RPC over HTTP
+ *   A conversation, room or box not given, or not there, is the same 403: a key learns nothing of what it was not given.
  *
  * The front lets /api/ext/ through without sign-on, as it does /c/
  * (deploy/install.sh, skip_auth_routes; deploy/updater.mjs for installs made
@@ -62,6 +85,7 @@ import { appendFileSync, readFileSync, writeFileSync, renameSync, statSync } fro
 import { Refusal } from './conversations.mjs';
 import { Grants, apiKeySubject } from './grants.mjs';
 import { isConversationName } from './names.mjs';
+import { masked, lookOf } from './rooms.mjs';
 
 export const KEY_PREFIX = 'clv_';
 export const DEFAULT_DAYS = 90;
@@ -86,6 +110,14 @@ export const levelOf = (rights) => (String(rights).includes('w') ? 'talk' : Stri
 export const READ_DEFAULT = 50;
 export const READ_MAX = 200;
 export const SAY_MAX = 8000;
+/* What a room and a voice box may be given: [rights in the table]. */
+export const ROOM_LEVELS = Object.freeze({ read: 'r', talk: 'rw' });
+export const BOX_LEVELS = Object.freeze({ state: 'r', speak: 'rw' });
+export const boxLevelOf = (rights) => (String(rights).includes('w') ? 'speak' : String(rights).includes('r') ? 'state' : null);
+/* Said aloud in the home: short, and a few a minute (per key and box). */
+export const SPEAK_MAX = 300;
+export const SPEAK_PER_MIN = 3;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 const digest = (text) => createHash('sha256').update(text).digest();
 const oneLine = (value) => typeof value === 'string' && value.trim() !== '' && value.trim().length <= LABEL_MAX
@@ -93,19 +125,25 @@ const oneLine = (value) => typeof value === 'string' && value.trim() !== '' && v
 const SECRET = /^clv_[A-Za-z0-9_-]{43}$/;
 
 export class ApiKeys {
-    #store; #grants; #now; #journal; #exists;
+    #store; #grants; #now; #journal; #exists; #kinds;
     #used = new Map();       /* id -> { at, savedAt } */
     #calls = new Map();      /* id ('' for unknown keys) -> [times of the last minute] */
 
-    /* `exists(name)`: whether a conversation is there (one is given only then). */
-    constructor({ store, grants = new Grants(), journal = null, now = () => Date.now(), exists = () => true }) {
+    /* `exists(name)`: whether a conversation is there (one is given only then); `roomExists(id)`,
+       `boxExists(id)`: the same for a room, a voice box (none, without them). */
+    constructor({ store, grants = new Grants(), journal = null, now = () => Date.now(), exists = () => true, roomExists = () => false, boxExists = () => false }) {
         this.#store = store; this.#grants = grants; this.#journal = journal; this.#now = now; this.#exists = exists;
+        /* What is given one by one: its asset type, its levels, a valid name, whether it is there, its words. */
+        this.#kinds = {
+            room: { levels: ROOM_LEVELS, of: levelOf, valid: (v) => typeof v === 'string' && UUID.test(v), exists: roomExists, what: 'room', the: 'a room' },
+            box: { levels: BOX_LEVELS, of: boxLevelOf, valid: (v) => typeof v === 'string' && UUID.test(v), exists: boxExists, what: 'voice box', the: 'a voice box' },
+        };
     }
 
     #scopesOf(id) { return Object.entries(SCOPES).filter(([, s]) => this.#grants.can(apiKeySubject(id), s.asset, s.rights)).map(([name]) => name); }
     #shown(k) {
         const used = this.#used.get(k.name)?.at ?? k.usedAt ?? null;
-        return { id: k.name, label: k.label, scopes: this.#scopesOf(k.name), conversations: this.conversationsOf(k.name), createdBy: k.createdBy ?? null, createdAt: k.createdAt, expiresAt: k.expiresAt ?? null,
+        return { id: k.name, label: k.label, scopes: this.#scopesOf(k.name), conversations: this.conversationsOf(k.name), rooms: this.roomsOf(k.name), boxes: this.boxesOf(k.name), createdBy: k.createdBy ?? null, createdAt: k.createdAt, expiresAt: k.expiresAt ?? null,
             usedAt: used, expired: Boolean(k.expiresAt && Date.parse(k.expiresAt) <= this.#now()) };
     }
 
@@ -119,6 +157,34 @@ export class ApiKeys {
             .sort((a, b) => a.name.localeCompare(b.name));
     }
 
+    /* The rooms, the voice boxes a key was given, each with its level: [{ id, level }] -- only those still there. */
+    #givenOf(id, type) {
+        const k = this.#kinds[type];
+        return this.#grants.of(apiKeySubject(id), type).map((g) => ({ id: g.name, level: k.of(g.rights) })).filter((x) => x.level && k.exists(x.id))
+            .sort((a, b) => a.id.localeCompare(b.id));
+    }
+    roomsOf(id) { return this.#givenOf(id, 'room'); }
+    boxesOf(id) { return this.#givenOf(id, 'box'); }
+    #oneAsked(type, ref, level) {
+        const k = this.#kinds[type];
+        if (!k.valid(ref) || !k.exists(ref)) throw new Refusal(404, `No such ${k.what}.`);
+        if (level !== null && !Object.hasOwn(k.levels, level)) throw new Refusal(400, `${k.the[0].toUpperCase()}${k.the.slice(1)} is given at one of: ${Object.keys(k.levels).join(', ')}.`);
+    }
+    #givenAll(type, given) {
+        if (!given || typeof given !== 'object' || Array.isArray(given)) throw new Refusal(400, `${type === 'room' ? 'Rooms' : 'Voice boxes'} are given by id: {id: level}.`);
+        for (const [ref, level] of Object.entries(given)) this.#oneAsked(type, ref, level);
+    }
+    /* One room or voice box given to a key, its level changed, or taken back (level null). */
+    #setOne(type, id, ref, level) {
+        if (typeof id !== 'string' || !this.#store.get(id)) throw new Refusal(404, 'No such key.');
+        this.#oneAsked(type, ref, level);
+        if (level === null) this.#grants.take(apiKeySubject(id), `${type}:${ref}`);
+        else this.#grants.give(apiKeySubject(id), `${type}:${ref}`, this.#kinds[type].levels[level]);
+        return this.get(id);
+    }
+    setRoom(id, room, level) { return this.#setOne('room', id, room, level); }
+    setBox(id, box, level) { return this.#setOne('box', id, box, level); }
+
     #conversationAsked(name, level) {
         if (!isConversationName(name) || !this.#exists(name)) throw new Refusal(404, 'No such conversation.');
         if (level !== null && !Object.hasOwn(LEVELS, level)) throw new Refusal(400, `A conversation is given to read or to talk: ${Object.keys(LEVELS).join(', ')}.`);
@@ -135,11 +201,12 @@ export class ApiKeys {
 
     /* A new key: its secret is in the answer, this once. `days`: its life (null: it does not expire).
        `conversations`: { name: 'read' | 'talk' }, each named -- there is no "all". */
-    create({ label, scopes = [], conversations = {}, days = DEFAULT_DAYS } = {}, who = '') {
+    create({ label, scopes = [], conversations = {}, rooms = {}, boxes = {}, days = DEFAULT_DAYS } = {}, who = '') {
         if (!oneLine(label)) throw new Refusal(400, `A key has a name: one line, ${LABEL_MAX} characters at most.`);
         if (!Array.isArray(scopes) || scopes.some((s) => !Object.hasOwn(SCOPES, s))) throw new Refusal(400, `Scopes are among: ${Object.keys(SCOPES).join(', ')}.`);
         if (!conversations || typeof conversations !== 'object' || Array.isArray(conversations)) throw new Refusal(400, 'Conversations are given by name: {name: "read" | "talk"}.');
         for (const [name, level] of Object.entries(conversations)) this.#conversationAsked(name, level);
+        this.#givenAll('room', rooms); this.#givenAll('box', boxes);
         if (days !== null && !(Number.isInteger(days) && days >= 1 && days <= DAYS_MAX)) throw new Refusal(400, `A key lasts 1 to ${DAYS_MAX} days, or does not expire.`);
         if (this.#store.all().length >= KEYS_MAX) throw new Refusal(409, `At most ${KEYS_MAX} keys: revoke one first.`);
         const name = label.trim();
@@ -152,6 +219,8 @@ export class ApiKeys {
         this.#store.put(record);
         for (const s of new Set(scopes)) this.#grants.give(apiKeySubject(id), SCOPES[s].asset, SCOPES[s].rights);
         for (const [name, level] of Object.entries(conversations)) if (level !== null) this.#grants.give(apiKeySubject(id), `conversation:${name}`, LEVELS[level]);
+        for (const [ref, level] of Object.entries(rooms)) if (level !== null) this.#grants.give(apiKeySubject(id), `room:${ref}`, ROOM_LEVELS[level]);
+        for (const [ref, level] of Object.entries(boxes)) if (level !== null) this.#grants.give(apiKeySubject(id), `box:${ref}`, BOX_LEVELS[level]);
         return { key: this.#shown(record), secret };
     }
 
@@ -161,6 +230,7 @@ export class ApiKeys {
         this.#store.remove(id);
         this.#grants.forgetSubject(apiKeySubject(id));
         this.#used.delete(id); this.#calls.delete(id);
+        for (const c of [...this.#calls.keys()]) if (c.startsWith(`speak:${id}:`)) this.#calls.delete(c);
     }
 
     get(id) { const k = this.#store.get(id); return k ? this.#shown(k) : undefined; }
@@ -215,8 +285,31 @@ export class ApiKeys {
         return levelOf(rights);
     }
 
+    /* Whether a key (already checked) may read ('read') or post in ('talk') one room; 403 if not, the same for one
+       not given and one not there. */
+    mayRoom(id, room, level = 'read') {
+        const rights = typeof room === 'string' && UUID.test(room) && this.#kinds.room.exists(room) ? this.#grants.rightsOf(apiKeySubject(id), `room:${room}`) : '';
+        if (!rights.includes('r')) throw Object.assign(new Refusal(403, 'This key was not given this room.'), { key: id });
+        if (level === 'talk' && !rights.includes('w')) throw Object.assign(new Refusal(403, 'This key may read this room, not talk in it.'), { key: id });
+        return levelOf(rights);
+    }
+    /* Whether a key may see the state of ('state') or make speak ('speak') one voice box; 403 if not. */
+    mayBox(id, box, level = 'state') {
+        const rights = typeof box === 'string' && UUID.test(box) && this.#kinds.box.exists(box) ? this.#grants.rightsOf(apiKeySubject(id), `box:${box}`) : '';
+        if (!rights.includes('r')) throw Object.assign(new Refusal(403, 'This key was not given this voice box.'), { key: id });
+        if (level === 'speak' && !rights.includes('w')) throw Object.assign(new Refusal(403, 'This key may see this voice box, not make it speak.'), { key: id });
+        return boxLevelOf(rights);
+    }
+    /* One sentence said aloud, counted: SPEAK_PER_MIN a minute for this key and box, then 429. */
+    speakCounted(id, box) {
+        const wait = this.#counted(`speak:${id}:${box}`, SPEAK_PER_MIN);
+        if (wait) throw Object.assign(new Refusal(429, `Too many: ${SPEAK_PER_MIN} sentences a minute per voice box.`), { key: id, retry: wait });
+    }
+
     /* Its name, as its messages are signed in a chat (Parley's "by"). */
     signature(id) { const k = this.#store.get(id); return k ? { id: apiKeySubject(id), name: k.label, kind: 'ai', place: 'API key' } : null; }
+    /* In a room: its name and its look (the letter and colour the page draws it with). */
+    roomSignature(id) { const s = this.signature(id); return s ? { ...s, look: lookOf(s.name) } : null; }
 
     #seen(id) {
         const now = this.#now();
@@ -305,6 +398,23 @@ export function threadOf(read) {
     return { chat: true, messages, cursor: typeof read.cursor === 'string' ? read.cursor : null };
 }
 
+/* A ROOM'S THREAD as a key reads it, as the page reads it: who said it by NAME (the person, an AI, a box, a key),
+   whom it is for by name, its words with any secret masked, a file by its name only. Never a member's id, a path,
+   nor what the page keeps for itself. `read`: what rooms.read gives. */
+export function roomThreadOf(read) {
+    const messages = (Array.isArray(read?.messages) ? read.messages : []).filter((m) => m && (m.from === 'person' || m.from === 'agent')).map((m) => {
+        const files = [...(Array.isArray(m.files) ? m.files.map((f) => fileName(f?.name || f?.path)) : []), ...(m.kind === 'show' && m.path ? [fileName(m.path)] : [])].filter(Boolean).slice(0, 12);
+        const choices = Array.isArray(m.choices) ? m.choices.filter((c) => typeof c === 'string').slice(0, 8).map((c) => masked(c).slice(0, 200)) : [];
+        const to = Array.isArray(m.toNames) ? m.toNames.filter((x) => typeof x === 'string' && !UUID.test(x)).slice(0, 20).map((x) => x.slice(0, 80)) : [];
+        /* No name: the person (the room's own side), as in a conversation's thread. */
+        const by = typeof m.by?.name === 'string' && m.by.name ? m.by.name.slice(0, 80) : '';
+        return { id: String(m.id ?? '').slice(0, 80), at: String(m.at ?? '').slice(0, 40), from: m.from, kind: String(m.kind ?? 'say').slice(0, 20),
+            text: typeof m.text === 'string' ? masked(m.text).slice(0, TEXT_MAX) : '', ...(by ? { by } : {}),
+            ...(to.length ? { to } : {}), ...(m.toYou ? { toPerson: true } : {}), ...(choices.length ? { choices } : {}), ...(files.length ? { files } : {}) };
+    });
+    return { messages, cursor: typeof read?.cursor === 'string' ? read.cursor : null };
+}
+
 /* What a read asks for: the newest `last` (READ_DEFAULT; READ_MAX at most), or what came `since` a cursor. */
 export function readPart(get) {
     const last = Number(get('last') ?? READ_DEFAULT);
@@ -345,13 +455,52 @@ export const SAY_TOOL = {
     inputSchema: { type: 'object', properties: { conversation: CONVERSATION_ARG, text: { type: 'string', minLength: 1, maxLength: SAY_MAX } }, required: ['conversation', 'text'], additionalProperties: false },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
 };
-export const TOOLS = [STATUS_TOOL, CONVERSATIONS_TOOL, READ_TOOL, SAY_TOOL];
+const ROOM_ARG = { type: 'string', description: 'The room\'s id, as clavarium_rooms gives it.' };
+const BOX_ARG = { type: 'string', description: 'The voice box\'s id, as clavarium_boxes gives it.' };
+export const ROOMS_TOOL = {
+    name: 'clavarium_rooms',
+    title: 'Rooms of this key',
+    description: 'The rooms this key was given, each with its id, name, level (read or talk), its host and its members by name.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export const ROOM_READ_TOOL = {
+    name: 'clavarium_room_read',
+    title: 'Read a room',
+    description: `The newest messages of one room's thread (the person, its AIs, its voice boxes, keys), oldest first, by names; secrets masked. A cursor as for clavarium_read. ${READ_DEFAULT} by default, ${READ_MAX} at most.`,
+    inputSchema: { type: 'object', properties: { room: ROOM_ARG, last: { type: 'integer', minimum: 1, maximum: READ_MAX }, since: { type: 'string' } }, required: ['room'], additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export const ROOM_SAY_TOOL = {
+    name: 'clavarium_room_say',
+    title: 'Post a message in a room',
+    description: 'Post a message in one room, as the person would: it goes to the room\'s host, or to the AIs named in "to" (their names, as clavarium_rooms gives them). Shown signed with this key\'s name. The room must have been given to this key to talk.',
+    inputSchema: { type: 'object', properties: { room: ROOM_ARG, text: { type: 'string', minLength: 1, maxLength: SAY_MAX }, to: { type: 'array', items: { type: 'string' }, maxItems: 20 } }, required: ['room', 'text'], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+};
+export const BOXES_TOOL = {
+    name: 'clavarium_boxes',
+    title: 'Voice boxes of this key',
+    description: 'The voice boxes this key was given, each with its id, name, level (state or speak), whether it is online, where it speaks, when it last heard someone, and its volume. Nothing it heard.',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export const BOX_SAY_TOOL = {
+    name: 'clavarium_box_say',
+    title: 'Say a short text aloud on a voice box',
+    description: `Make one voice box say a short text aloud, in the home: ${SPEAK_MAX} characters at most, ${SPEAK_PER_MIN} a minute. It does not listen after. The box must have been given to this key to speak.`,
+    inputSchema: { type: 'object', properties: { box: BOX_ARG, text: { type: 'string', minLength: 1, maxLength: SPEAK_MAX } }, required: ['box', 'text'], additionalProperties: false },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+};
+export const TOOLS = [STATUS_TOOL, CONVERSATIONS_TOOL, READ_TOOL, SAY_TOOL, ROOMS_TOOL, ROOM_READ_TOOL, ROOM_SAY_TOOL, BOXES_TOOL, BOX_SAY_TOOL];
 
 /* Returns true when the request was under /api/ext/ (answered here). `status()`: the state, as statusOf
    makes it. `chats`: { list() -> [{ id, name }], read(name, part) -> talk.of's answer, chatOn(name),
-   say(name, text, by) -> { told } }. `originOk(headers)`: whether an Origin is this site's (gate.mjs); a
+   say(name, text, by) -> { told } }. `rooms`: { list() -> [{ id, name, host, members: [{ name, kind }] }],
+   read(id, part) -> rooms.read's answer, say(id, text, { as, to }) }. `boxes`: { list() -> [{ id, name, online, where,
+   heardAt, volume }], say(id, text, by) -> { seconds? } }. `originOk(headers)`: whether an Origin is this site's (gate.mjs); a
    call from a page of another site is refused. */
-export async function handleExternal(request, response, { keys, status, chats = null, headers = {}, originOk = () => false, version = null }) {
+export async function handleExternal(request, response, { keys, status, chats = null, rooms = null, boxes = null, headers = {}, originOk = () => false, version = null }) {
     const url = new URL(request.url ?? '/', 'http://local');
     const { pathname } = url;
     if (!pathname.startsWith(EXT_PREFIX) && pathname !== EXT_PREFIX.slice(0, -1)) return false;
@@ -394,6 +543,39 @@ export async function handleExternal(request, response, { keys, status, chats =
         const said = await chats.say(name, text, keys.signature(id));
         return { ok: true, told: typeof said?.told === 'string' ? said.told : null };
     };
+    /* The same for rooms and voice boxes. */
+    const roomsListed = (id) => {
+        const there = new Map((rooms?.list() ?? []).map((r) => [r.id, r]));
+        return { rooms: keys.roomsOf(id).filter((g) => there.has(g.id)).map((g) => { const r = there.get(g.id);
+            return { id: g.id, name: String(r.name ?? ''), level: g.level, host: r.host ?? null, members: (Array.isArray(r.members) ? r.members : []).map((m) => ({ name: String(m.name ?? ''), kind: String(m.kind ?? '') })) }; }) };
+    };
+    const roomKnown = (room) => { if (!(rooms?.list() ?? []).some((r) => r.id === room)) throw new Refusal(403, 'This key was not given this room.'); };
+    const roomReading = (id, room, part) => {
+        keys.mayRoom(id, room, 'read'); roomKnown(room);
+        return roomThreadOf(rooms.read(room, part));
+    };
+    const roomSaying = async (id, room, text, to) => {
+        keys.mayRoom(id, room, 'talk'); roomKnown(room);
+        if (typeof text !== 'string' || !text.trim()) throw new Refusal(400, 'Say something: text.');
+        if (text.length > SAY_MAX) throw new Refusal(400, `${SAY_MAX} characters at most.`);
+        if (to !== undefined && to !== null && (!Array.isArray(to) || to.length > 20 || to.some((x) => typeof x !== 'string'))) throw new Refusal(400, 'to: the names of AIs of this room.');
+        await rooms.say(room, text, { as: keys.roomSignature(id), to: Array.isArray(to) ? to : [] });
+        return { ok: true };
+    };
+    const boxesListed = (id) => {
+        const there = new Map((boxes?.list() ?? []).map((b) => [b.id, b]));
+        return { boxes: keys.boxesOf(id).filter((g) => there.has(g.id)).map((g) => { const b = there.get(g.id);
+            return { id: g.id, name: String(b.name ?? ''), level: g.level, online: Boolean(b.online), where: b.where ?? null, heardAt: b.heardAt ?? null, volume: Number.isFinite(b.volume) ? b.volume : null }; }) };
+    };
+    const boxSaying = async (id, box, text) => {
+        keys.mayBox(id, box, 'speak');
+        if (!(boxes?.list() ?? []).some((b) => b.id === box)) throw new Refusal(403, 'This key was not given this voice box.');
+        if (typeof text !== 'string' || !text.trim()) throw new Refusal(400, 'Say something: text.');
+        if (text.length > SPEAK_MAX) throw new Refusal(400, `${SPEAK_MAX} characters at most, said aloud.`);
+        keys.speakCounted(id, box);
+        const done = await boxes.say(box, text, keys.signature(id));
+        return { ok: true, ...(Number.isFinite(done?.seconds) ? { seconds: done.seconds } : {}) };
+    };
     const ownError = (error, id) => (error instanceof Refusal ? Object.assign(error, { key: error.key ?? id }) : error);
     try {
         if (route === '/v1/status') {
@@ -423,6 +605,43 @@ export async function handleExternal(request, response, { keys, status, chats =
                 return send(201, done);
             } catch (error) { return refused(ownError(error, id)); }
         }
+        const room = /^\/v1\/rooms(?:\/([^/]+)\/messages)?$/.exec(route);
+        if (room) {
+            const allowed = room[1] ? 'GET, POST' : 'GET';
+            if (!allowed.split(', ').includes(request.method)) return send(405, { error: `Call this address with ${allowed}.` }, { allow: allowed });
+            let id;
+            try { id = keys.check(request.headers.authorization); } catch (error) { return refused(error); }
+            try {
+                if (!room[1]) { const body = roomsListed(id); note(id, 200); return send(200, body); }
+                let ref;
+                try { ref = decodeURIComponent(room[1]); } catch { ref = ''; }
+                if (request.method === 'GET') { const body = roomReading(id, ref, readPart((k) => url.searchParams.get(k))); note(id, 200); return send(200, body); }
+                if (!String(request.headers['content-type'] ?? '').startsWith('application/json')) throw new Refusal(415, 'Send JSON: {"text": "..."}.');
+                let body;
+                try { body = JSON.parse(await bodyOf(SAY_MAX * 4 + 4096)); } catch (error) { if (error instanceof Refusal) throw error; throw new Refusal(400, 'The request is not JSON.'); }
+                const done = await roomSaying(id, ref, body?.text, body?.to);
+                note(id, 201);
+                return send(201, done);
+            } catch (error) { return refused(ownError(error, id)); }
+        }
+        const box = /^\/v1\/boxes(?:\/([^/]+)\/say)?$/.exec(route);
+        if (box) {
+            const allowed = box[1] ? 'POST' : 'GET';
+            if (request.method !== allowed) return send(405, { error: `Call this address with ${allowed}.` }, { allow: allowed });
+            let id;
+            try { id = keys.check(request.headers.authorization); } catch (error) { return refused(error); }
+            try {
+                if (!box[1]) { const body = boxesListed(id); note(id, 200); return send(200, body); }
+                let ref;
+                try { ref = decodeURIComponent(box[1]); } catch { ref = ''; }
+                if (!String(request.headers['content-type'] ?? '').startsWith('application/json')) throw new Refusal(415, 'Send JSON: {"text": "..."}.');
+                let body;
+                try { body = JSON.parse(await bodyOf(SPEAK_MAX * 4 + 1024)); } catch (error) { if (error instanceof Refusal) throw error; throw new Refusal(400, 'The request is not JSON.'); }
+                const done = await boxSaying(id, ref, body?.text);
+                note(id, 200);
+                return send(200, done);
+            } catch (error) { return refused(ownError(error, id)); }
+        }
         if (route === '/mcp') {
             if (request.method !== 'POST') return send(405, { error: 'MCP is spoken with POST here (no event stream).' }, { allow: 'POST' });
             let id;
@@ -435,8 +654,9 @@ export async function handleExternal(request, response, { keys, status, chats =
                 note(id, 400, '/mcp'); return send(400, { jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid Request' } });
             }
             const args = msg.params?.arguments && typeof msg.params.arguments === 'object' && !Array.isArray(msg.params.arguments) ? msg.params.arguments : {};
-            /* The journal says which tool, and on which conversation. */
-            const what = `/mcp ${msg.method.slice(0, 40)}${msg.method === 'tools/call' ? ` ${String(msg.params?.name ?? '').slice(0, 40)}${typeof args.conversation === 'string' ? ` ${args.conversation.slice(0, 32)}` : ''}` : ''}`;
+            /* The journal says which tool, and on which conversation, room or box. */
+            const on = [args.conversation, args.room, args.box].find((v) => typeof v === 'string');
+            const what = `/mcp ${msg.method.slice(0, 40)}${msg.method === 'tools/call' ? ` ${String(msg.params?.name ?? '').slice(0, 40)}${on ? ` ${on.slice(0, 36)}` : ''}` : ''}`;
             /* A notification (no id) is taken, never answered. */
             if (msg.id === undefined || msg.id === null) { note(id, 202, what); response.writeHead(202, { ...headers, 'cache-control': 'no-store' }).end(); return true; }
             const answer = (result, code = 200) => { note(id, code, what); return send(200, { jsonrpc: '2.0', id: msg.id, result }); };
@@ -447,7 +667,7 @@ export async function handleExternal(request, response, { keys, status, chats =
                 const asked = String(msg.params?.protocolVersion ?? '');
                 return answer({ protocolVersion: MCP_VERSIONS.includes(asked) ? asked : MCP_VERSIONS[0], capabilities: { tools: { listChanged: false } },
                     serverInfo: { name: 'clavarium', title: 'Clavarium', version: version ?? '0' },
-                    instructions: 'This Clavarium, as far as this key was given it: its state (clavarium_status), the conversations given to it (clavarium_conversations), to read (clavarium_read) or to talk in (clavarium_say).' });
+                    instructions: 'This Clavarium, as far as this key was given it: its state (clavarium_status), the conversations given to it (clavarium_conversations), to read (clavarium_read) or to talk in (clavarium_say); its rooms (clavarium_rooms, clavarium_room_read, clavarium_room_say); its voice boxes (clavarium_boxes; clavarium_box_say says a short text aloud in the home).' });
             }
             case 'ping': return answer({});
             case 'tools/list': return answer({ tools: TOOLS });
@@ -460,14 +680,28 @@ export async function handleExternal(request, response, { keys, status, chats =
                         return result(await status());
                     }
                     if (name === CONVERSATIONS_TOOL.name) return result(listed(id));
-                    if (typeof args.conversation !== 'string') return fail(-32602, 'conversation: the id of a conversation.');
-                    if (name === READ_TOOL.name) return result(reading(id, args.conversation, readPart((k) => (args[k] === undefined ? null : typeof args[k] === 'number' ? String(args[k]) : args[k]))));
-                    const done = await saying(id, args.conversation, args.text);
+                    if (name === ROOMS_TOOL.name) return result(roomsListed(id));
+                    if (name === BOXES_TOOL.name) return result(boxesListed(id));
+                    const part = () => readPart((k) => (args[k] === undefined ? null : typeof args[k] === 'number' ? String(args[k]) : args[k]));
+                    let done;
+                    if (name === ROOM_READ_TOOL.name || name === ROOM_SAY_TOOL.name) {
+                        if (typeof args.room !== 'string') return fail(-32602, 'room: the id of a room.');
+                        if (name === ROOM_READ_TOOL.name) return result(roomReading(id, args.room, part()));
+                        done = await roomSaying(id, args.room, args.text, args.to);
+                    } else if (name === BOX_SAY_TOOL.name) {
+                        if (typeof args.box !== 'string') return fail(-32602, 'box: the id of a voice box.');
+                        done = await boxSaying(id, args.box, args.text);
+                    } else {
+                        if (typeof args.conversation !== 'string') return fail(-32602, 'conversation: the id of a conversation.');
+                        if (name === READ_TOOL.name) return result(reading(id, args.conversation, part()));
+                        done = await saying(id, args.conversation, args.text);
+                    }
                     note(id, 201, what);
                     return send(200, { jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: JSON.stringify(done) }], structuredContent: done, isError: false } });
                 } catch (error) {
                     if (!(error instanceof Refusal)) throw error;
-                    /* Not given: refused as the API refuses it. Anything else is the tool's own failure, said to the caller. */
+                    /* Not given: refused as the API refuses it (too many, too). Anything else is the tool's own failure, said to the caller. */
+                    if (error.status === 429) { note(id, 429, what); return send(429, { jsonrpc: '2.0', id: msg.id, error: { code: -32002, message: error.message } }, { 'retry-after': String(error.retry ?? 60) }); }
                     if (error.status === 403) { note(id, 403, what); return send(403, { jsonrpc: '2.0', id: msg.id, error: { code: -32001, message: error.message } }); }
                     note(id, error.status, what);
                     return send(200, { jsonrpc: '2.0', id: msg.id, result: { content: [{ type: 'text', text: error.message }], isError: true } });
@@ -477,7 +711,7 @@ export async function handleExternal(request, response, { keys, status, chats =
             }
         }
         note(null, 404);
-        return send(404, { error: 'Not found. GET /api/ext/v1/status, /api/ext/v1/conversations, or MCP at /api/ext/mcp.' });
+        return send(404, { error: 'Not found. GET /api/ext/v1/status, /api/ext/v1/conversations, /api/ext/v1/rooms, /api/ext/v1/boxes, or MCP at /api/ext/mcp.' });
     } catch (error) {
         if (error instanceof Refusal) return refused(error);
         note(null, 500);
@@ -503,9 +737,9 @@ export async function handleApiKeys(request, response, keys, originOk, headers =
         try { body = text ? JSON.parse(text) : {}; } catch { return send(400, { error: 'The request is not JSON.' }); }
         if (!body || typeof body !== 'object') body = {};
         if (pathname === '/api/apikeys') {
-            const made = keys.create({ label: body.label, scopes: body.scopes ?? [], conversations: body.conversations ?? {}, days: body.days === undefined ? DEFAULT_DAYS : body.days }, who);
+            const made = keys.create({ label: body.label, scopes: body.scopes ?? [], conversations: body.conversations ?? {}, rooms: body.rooms ?? {}, boxes: body.boxes ?? {}, days: body.days === undefined ? DEFAULT_DAYS : body.days }, who);
             /* Its name and scopes; never the secret. */
-            const what = [...made.key.scopes, ...made.key.conversations.map((c) => `${c.name} ${c.level}`)];
+            const what = [...made.key.scopes, ...made.key.conversations.map((c) => `${c.name} ${c.level}`), ...made.key.rooms.map((r) => `room ${r.id.slice(0, 8)} ${r.level}`), ...made.key.boxes.map((b) => `voice box ${b.id.slice(0, 8)} ${b.level}`)];
             events?.add({ kind: 'access', text: `API key "${made.key.label}" made${what.length ? ` (${what.join(', ')})` : ' (no scope)'}`, who: who || null });
             return send(201, made);
         }
@@ -516,6 +750,15 @@ export async function handleApiKeys(request, response, keys, originOk, headers =
             events?.add({ kind: 'access', text: `API key "${key.label}": ${body.conversation} ${level ?? 'taken back'}`, who: who || null });
             return send(200, { key });
         }
+        const one = /^\/api\/apikeys\/([0-9a-f-]{36})\/(rooms|boxes)$/.exec(pathname);
+        if (one) {
+            const level = body.level === undefined ? null : body.level;
+            const room = one[2] === 'rooms';
+            const ref = room ? body.room : body.box;
+            const key = room ? keys.setRoom(one[1], ref, level) : keys.setBox(one[1], ref, level);
+            events?.add({ kind: 'access', text: `API key "${key.label}": ${room ? 'room' : 'voice box'} ${String(ref).slice(0, 8)} ${level ?? 'taken back'}`, who: who || null });
+            return send(200, { key });
+        }
         const revoke = /^\/api\/apikeys\/([0-9a-f-]{36})\/revoke$/.exec(pathname);
         if (revoke) {
             const label = keys.get(revoke[1])?.label;

package/server/boxes.mjs

@@ -284,12 +284,12 @@ export function piecesOf(pcm, { least = 8, most = 14 } = {}) {
 
 export class Boxes {
     #file; #codes = new Map(); #links = new Map(); #tries = []; #now;
-    #exists; #hear; #say; #note; #speak; #log; #changed; #images = new Map(); #origin; #spawn; #fetch; #streams = new Map(); #recordDir; #parts; #keep; #react; #learn; #collect; #stopSay = new Map();
+    #exists; #hear; #say; #note; #speak; #log; #removed; #changed; #images = new Map(); #origin; #spawn; #fetch; #streams = new Map(); #recordDir; #parts; #keep; #react; #learn; #collect; #stopSay = new Map();
 
     /* file: a JsonFile holding [{ id, name, conversation, keyHash, firmware, createdAt, seenAt }].
        exists(conversation), hear(wav) -> text, say(conversation, text, room), speak(text) -> PCM 16 kHz. */
-    constructor({ file, exists = () => true, hear, say, note = null, speak, changed = () => {}, origin = () => null, now = () => Date.now(), log = () => {}, spawn = spawnProcess, fetcher = fetch, recordDir = null, parts = null, keep = null, react = async () => null, learn = null, collect = null }) {
-        this.#react = react; this.#learn = learn; this.#collect = collect;
+    constructor({ file, removed = () => {}, exists = () => true, hear, say, note = null, speak, changed = () => {}, origin = () => null, now = () => Date.now(), log = () => {}, spawn = spawnProcess, fetcher = fetch, recordDir = null, parts = null, keep = null, react = async () => null, learn = null, collect = null }) {
+        this.#removed = removed; this.#react = react; this.#learn = learn; this.#collect = collect;
         this.#spawn = spawn; this.#fetch = fetcher; this.#recordDir = recordDir; this.#parts = parts; this.#keep = keep;
         this.#file = file; this.#changed = changed; this.#origin = origin; this.#exists = exists; this.#hear = hear; this.#say = say; this.#note = note; this.#speak = speak; this.#now = now; this.#log = log;
     }
@@ -302,7 +302,8 @@ export class Boxes {
 
     /* What the operator sees: never the key, nor its hash. */
     all() {
-        return this.#all().map(({ keyHash, ...b }) => ({ ...b, online: this.#links.has(b.id), muted: this.#links.get(b.id)?.muted ?? null, volume: b.volume ?? this.#links.get(b.id)?.volume ?? VOLUME_DEFAULT }));
+        return this.#all().map(({ keyHash, ...b }) => { const l = this.#links.get(b.id);
+            return { ...b, online: Boolean(l), muted: l?.muted ?? null, volume: b.volume ?? l?.volume ?? VOLUME_DEFAULT, heardAt: l?.heardAt ? new Date(l.heardAt).toISOString() : null }; });
     }
 
     code(conversation, name, zone = '') {
@@ -436,6 +437,21 @@ export class Boxes {
         return { ok: true };
     }
 
+    /* SAID ALOUD FOR AN API KEY (apikeys.mjs, "speak"): a short text, as given -- never another assistant's call, the
+       box does not listen after, nothing of its settings touched. `by`: the key's signature, for the log. */
+    async announce(id, text, by = null) {
+        const link = this.#links.get(id);
+        if (!link) throw new Refusal(409, 'This voice box is not connected.');
+        /* A meeting being recorded is not spoken over. */
+        if (link.recording) throw new Refusal(409, 'This voice box is recording: not now.');
+        const words = forSpeech(text);
+        if (!words) throw new Refusal(400, 'Nothing to say.');
+        const pcm = await this.#speak(words);
+        link.play(pcm);
+        this.#log(`voice box ${link.box().name}: said aloud for the API key "${String(by?.name ?? '?').slice(0, 40)}"`);
+        return { ok: true, seconds: Math.round(pcm.length / 32_000) };
+    }
+
     /* LISTENING TO THE INTERNET: a radio, a podcast, a music file, a playlist, read by this server (ffmpeg,
        any format it knows) and sent on to the box at the pace it is played, a few seconds ahead -- until it
        ends, stop(), or the person presses the button or says the wake word (the box then starts a sentence). */
@@ -517,6 +533,7 @@ export class Boxes {
         this.#save(list.filter((b) => b.id !== id));
         this.#links.get(id)?.socket.close(4001, 'withdrawn');
         try { this.#learn?.forget(id); } catch { /* nothing kept */ }
+        try { this.#removed(id); } catch { /* the caller's */ }
     }
 
     /* THE WAKE WORD THAT LEARNS (wakelearn.mjs): "normal" keeps nothing, "learn" keeps each wake clip with

package/server/grants.mjs

@@ -20,6 +20,8 @@
  *   git               see the files           change them              -
  *   secret            never                   -                        be handed to a conversation
  *   server            read its state          -                        -
+ *   room              read its thread         post in it               -
+ *   box               read its state          make it say a text aloud -
  *
  * Three kinds of subject: a CONVERSATION (what is attached to it reaches its
  * machine), a PAIRING (what a device was given by a code) and an API KEY
@@ -29,8 +31,11 @@
  * An API key is not a device and not a conversation: it is given only what
  * its scopes name -- "server:status" (read), and conversations one by one,
  * their chat to read ("r") or to talk in ("rw"), never their terminal ("x")
- * -- never a secret nor a folder in this version; and nothing else is ever
- * given "server:".
+ * -- rooms one by one, their thread to read ("r") or to post in ("rw"), and
+ * voice boxes one by one, their state ("r") or a short text said aloud
+ * ("rw": never to listen, record, set or update it) -- never a secret nor a
+ * folder in this version; nothing else is ever given "server:", "room:" or
+ * "box:".
  *
  * No groups, no inheritance. One rule sits on top, in the door: whoever was
  * given a conversation, its terminal or its chat, sees the files of that
@@ -49,9 +54,9 @@
  */
 import { Refusal } from './conversations.mjs';
 
-export const RIGHTS = Object.freeze({ conversation: 'rwx', folder: 'rw', mailbox: 'r', git: 'rw', secret: 'x', server: 'r' });
+export const RIGHTS = Object.freeze({ conversation: 'rwx', folder: 'rw', mailbox: 'r', git: 'rw', secret: 'x', server: 'r', room: 'rw', box: 'rw' });
 const SUBJECT = /^(conversation:[a-z]([a-z0-9-]{0,30}[a-z0-9])?|(pairing|apikey):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/;
-const ASSET = /^(conversation|folder|mailbox|git):[a-z]([a-z0-9-]{0,30}[a-z0-9])?$|^secret:[A-Z][A-Z0-9_]{0,39}$|^server:status$/;
+const ASSET = /^(conversation|folder|mailbox|git):[a-z]([a-z0-9-]{0,30}[a-z0-9])?$|^secret:[A-Z][A-Z0-9_]{0,39}$|^server:status$|^(room|box):[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 
 export const typeOf = (asset) => String(asset).split(':')[0];
 export const nameOf = (asset) => String(asset).slice(String(asset).indexOf(':') + 1);
@@ -98,7 +103,8 @@ export class Grants {
         /* The state of the server is given to an API key only; an API key is given only that, and
            conversations one by one -- their chat, to read or to write in, never their terminal. */
         if (typeOf(asset) === 'server' && !subject.startsWith('apikey:')) throw new Refusal(400, 'The state of the server is given to an API key only.');
-        if (subject.startsWith('apikey:') && !['server', 'conversation'].includes(typeOf(asset))) throw new Refusal(400, 'An API key is given the state of the server and conversations, nothing else.');
+        if (['room', 'box'].includes(typeOf(asset)) && !subject.startsWith('apikey:')) throw new Refusal(400, 'A room or a voice box is given to an API key only.');
+        if (subject.startsWith('apikey:') && !['server', 'conversation', 'room', 'box'].includes(typeOf(asset))) throw new Refusal(400, 'An API key is given the state of the server, conversations, rooms and voice boxes, nothing else.');
         if (subject.startsWith('apikey:') && clean.includes('x')) throw new Refusal(400, 'An API key reads a conversation or talks in it, never uses its terminal.');
         this.#store.put({ name: this.#key(subject, asset), subject, asset, rights: clean });
         return clean;