clavarium 0.2.368-next.1 → 0.2.369-next.1

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "clavarium",
-  "version": "0.2.368-next.1",
+  "version": "0.2.369-next.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "clavarium",
-      "version": "0.2.368-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.368-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/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;

package/server/main.mjs

@@ -235,7 +235,7 @@ function serve(port, conversations, resources, { gate = () => 'local', originOk,
         /* THE DOOR FOR PROGRAMS (apikeys.mjs): an API key is the right, never the gate -- the front lets
            /api/ext/ through without sign-on, and strips the identity headers there. */
         if (apikeys && (pathname === '/api/ext' || pathname.startsWith('/api/ext/'))) {
-            await handleExternal(request, response, { keys: apikeys.keys, status: apikeys.status, chats: apikeys.chats, headers: HEADERS, originOk, version: platform?.version ?? null });
+            await handleExternal(request, response, { keys: apikeys.keys, status: apikeys.status, chats: apikeys.chats, rooms: apikeys.rooms, boxes: apikeys.boxes, headers: HEADERS, originOk, version: platform?.version ?? null });
             return;
         }
         if (door && pathname.startsWith('/c/')) {
@@ -675,6 +675,8 @@ export async function startHome({ port, host, dataDir, mntDir = dataDir, gitRese
         /* The voice by default: Kyutai's Pocket TTS, run here (pocket.mjs); CLAVARIUM_POCKET=0 to leave it out. */
         pocket: process.env.CLAVARIUM_POCKET === '0' ? null : new Pocket({ dir: `${dataDir}/voices`, log: speechLog }) });
     boxes = new Boxes({ file: new JsonFile(`${dataDir}/boxes.json`, []),
+        /* A box withdrawn: what an API key was given of it goes with it. */
+        removed: (id) => grants.forgetAsset(`box:${id}`),
         /* A box speaks in a conversation, or in a room ('room:<id>', #281). */
         exists: (name) => all.list().some((c) => c.name === name) || (/^room:/.test(name) && Boolean(rooms?.has(name.slice(5)))),
         /* A long recording (a meeting): transcribed in parts, kept beside the conversation for its assistant. */
@@ -696,6 +698,7 @@ export async function startHome({ port, host, dataDir, mntDir = dataDir, gitRese
         log: (line) => events.add({ kind: 'server', text: line }) });
     /* Rooms (#268): a thread shared by several AIs, the person and boxes (rooms.mjs). */
     rooms = new Rooms({ file: new JsonFile(`${dataDir}/rooms.json`, []), dir: `${dataDir}/rooms`,
+        removed: (id) => grants.forgetAsset(`room:${id}`),
         say: (name, text, extra, files) => talk.say(name, text, undefined, files, undefined, extra),
         attach: (name, fileName, request) => talk.attach(name, fileName, request),
         rooms: (name, list) => talk.rooms(name, list), conversations: () => all.list(), boxes: () => boxes.all(),
@@ -724,7 +727,8 @@ export async function startHome({ port, host, dataDir, mntDir = dataDir, gitRese
     for (const name of ['clavarium-parley', 'clavarium-tether', 'clavarium-binder', 'clavarium-docket']) {
         try { components[name.slice('clavarium-'.length)] = JSON.parse(readFileSync(packageFile(name, 'package.json'), 'utf8')).version; } catch { /* not installed here */ }
     }
-    const apiKeys = new ApiKeys({ store: new Store(`${dataDir}/apikeys.json`), grants, journal: `${dataDir}/apikeys.log`, exists: (name) => all.list().some((c) => c.name === name) });
+    const apiKeys = new ApiKeys({ store: new Store(`${dataDir}/apikeys.json`), grants, journal: `${dataDir}/apikeys.log`, exists: (name) => all.list().some((c) => c.name === name),
+        roomExists: (id) => rooms.has(id), boxExists: (id) => boxes.all().some((b) => b.id === id) });
     /* What the host program says of the server is never waited for long: a key gets what is known. */
     const briefly = { brief: () => quick(capacity.brief(), 3000, null), room: () => quick(capacity.room(), 3000, null) };
     const apikeys = { keys: apiKeys, status: () => statusOf({ conversations: all, talk, health, answerer, capacity: briefly, history, platform, updates, components }),
@@ -735,6 +739,20 @@ export async function startHome({ port, host, dataDir, mntDir = dataDir, gitRese
             chatOn: (name) => { try { return talk.of(name, { state: '1' }).on === true; } catch { return false; } },
             read: (name, part) => talk.of(name, part),
             say: (name, text, by) => talk.say(name, text, undefined, [], undefined, { by }),
+        },
+        /* Its rooms: read as the room's page reads them (names of the moment), never marked seen; posted as the person
+           posts there (rooms.mjs say, `as` the key). */
+        rooms: {
+            list: () => rooms.list().map((r) => ({ id: r.id, name: r.name, host: r.members.find((m) => m.host)?.name ?? null, members: r.members.map((m) => ({ name: m.name, kind: m.kind })) })),
+            read: (id, part) => rooms.read(id, { ...part, ...(part.last ? { last: Number(part.last) } : {}), seen: false }),
+            say: (id, text, how) => rooms.say(id, text, how),
+        },
+        /* Its voice boxes: their state only, and a short text said aloud (boxes.mjs announce). */
+        boxes: {
+            list: () => { const names = new Map([...all.list().map((c) => [c.name, c.title || c.name]), ...rooms.list().map((r) => [`room:${r.id}`, r.name])]);
+                return boxes.all().map((b) => ({ id: b.id, name: b.name, online: b.online, volume: b.volume, heardAt: b.heardAt ?? null,
+                    where: /^room:/.test(String(b.conversation)) ? { kind: 'room', name: names.get(b.conversation) ?? null } : { kind: 'conversation', name: names.get(b.conversation) ?? null } })); },
+            say: (id, text, by) => boxes.announce(id, text, by),
         } };
     const features = new Features({ file: new JsonFile(`${dataDir}/features.json`, {}), context: async () => ({
         secrets: secrets.list(), dictation: voice.about(), boxes: boxes.all(), alerts: alerts.about().devices.length,

package/server/rooms.mjs

@@ -60,7 +60,7 @@ export const masked = (text) => { const str = String(text ?? ''); const hits = s
 export const lookOf = (name) => { const text = String(name ?? ''); let h = 0; for (const ch of text) h = (h * 31 + ch.codePointAt(0)) >>> 0; return { initial: ([...text.trim()][0] ?? '?').toUpperCase(), hue: h % 360 }; };
 
 export class Rooms {
-    #file; #dir; #say; #attach; #read; #rooms; #conversations; #boxes; #now; #speak; #reachOf; #shownIn; #hops = new Map(); #thinking = new Map();
+    #file; #dir; #say; #attach; #read; #rooms; #conversations; #boxes; #now; #speak; #reachOf; #shownIn; #removed; #hops = new Map(); #thinking = new Map();
     /* file: a JsonFile of the rooms; dir: where their threads are; say(name, text, extra): a message written in a
        conversation's own chat (talk.say; its 4th argument the paths of its files there); attach(name, fileName,
        request): a file put in a conversation's chat as the person attaches one (talk.attach); rooms(name, list): what a conversation is told of its rooms (talk.rooms);
@@ -68,9 +68,10 @@ export class Rooms {
        reach(name, path): how a conversation's chat opens a path of its own ("work:a.png"), or null (talk.reachOf);
        shown(name, ref): whether that chat has that file (talk.shown) -- what an AI shows in a room is read through them.
        read(name, ref): that file of that conversation ({ name, size, stream }), read with its rights -- what an AI
-       shows or cites to another AI of the room is copied from it (#carried). */
-    constructor({ file, dir, say, attach = async () => { throw new Refusal(409, 'Files cannot be given here.'); }, rooms = () => {}, conversations = () => [], boxes = () => [], speak = () => {}, now = () => new Date(), reach = () => null, shown = () => false, read = async () => { throw new Refusal(404, 'No such file.'); } }) {
-        this.#speak = speak; this.#attach = attach; this.#read = read; this.#reachOf = reach; this.#shownIn = shown;
+       shows or cites to another AI of the room is copied from it (#carried).
+       removed(id): a room removed (what was given of it, to an API key, goes with it). */
+    constructor({ file, dir, say, removed = () => {}, attach = async () => { throw new Refusal(409, 'Files cannot be given here.'); }, rooms = () => {}, conversations = () => [], boxes = () => [], speak = () => {}, now = () => new Date(), reach = () => null, shown = () => false, read = async () => { throw new Refusal(404, 'No such file.'); } }) {
+        this.#removed = removed; this.#speak = speak; this.#attach = attach; this.#read = read; this.#reachOf = reach; this.#shownIn = shown;
         this.#file = file; this.#dir = dir; this.#say = say; this.#rooms = rooms; this.#conversations = conversations; this.#boxes = boxes; this.#now = now;
     }
     #all() { const v = this.#file.get(); return Array.isArray(v) ? v : []; }
@@ -158,7 +159,7 @@ export class Rooms {
         this.#save(list);
         return this.get(id);
     }
-    remove(id) { this.#find(id); this.#save(this.#all().filter((r) => r.id !== id)); rmSync(`${this.#dir}/${id}`, { recursive: true, force: true }); }
+    remove(id) { this.#find(id); this.#save(this.#all().filter((r) => r.id !== id)); rmSync(`${this.#dir}/${id}`, { recursive: true, force: true }); try { this.#removed(id); } catch { /* the caller's */ } }
 
     /* ITS THREAD, as a screen reads it (Parley's read, the members' names of the moment). */
     read(id, options) {
@@ -247,11 +248,20 @@ export class Rooms {
     }
 
     /* SOMEONE OF THE PERSON'S SIDE SPEAKS (the person here, a box): kept in the room, given to the host -- or to the
-       AIs named (to: their member ids). Its files (paths from attach): in the thread, and a copy to each of those AIs. */
-    async say(id, text, { by, box, to, files } = {}) {
+       AIs named (to: their member ids). Its files (paths from attach): in the thread, and a copy to each of those AIs.
+       `as`: an API key ({ id, name, kind, look }, apikeys.mjs), not a member: signed with its own name, never the
+       person's -- and its `to` are the NAMES of the room's AIs (it is never told an id). */
+    async say(id, text, { by, box, to, files, as } = {}) {
         const room = this.#find(id); const members = this.#shown(room);
+        if (as && (files !== undefined || box || by)) throw new Refusal(400, 'An API key says words only.');
+        if (as && (typeof as.id !== 'string' || !as.id.startsWith('apikey:') || !as.name)) throw new Refusal(400, 'Not an API key.');
+        if (as && Array.isArray(to)) {
+            const ais = to.map((n) => members.find((m) => m.kind === 'ai' && m.name.toLowerCase() === String(n).trim().toLowerCase()));
+            if (ais.some((m) => !m)) throw new Refusal(400, 'to: the names of AIs of this room.');
+            to = ais.map((m) => m.id);
+        }
         /* A box bound to this room speaks in it in its own name (#281): found by its box id. */
-        const who = box ? members.find((m) => m.kind === 'box' && m.ref === box) : by ? members.find((m) => m.id === by && m.kind !== 'ai') : members.find((m) => m.kind === 'person');
+        const who = as ? { id: as.id, name: String(as.name).slice(0, 40), kind: as.kind ?? 'ai', look: as.look ?? lookOf(as.name), ref: 'apikey' } : box ? members.find((m) => m.kind === 'box' && m.ref === box) : by ? members.find((m) => m.id === by && m.kind !== 'ai') : members.find((m) => m.kind === 'person');
         if (!who) throw new Refusal(400, 'Not a member of this room.');
         const attached = this.#filesSaid(room.id, files);
         const t = this.#thread(room.id);

package/server/settingswords.mjs

@@ -80,6 +80,9 @@ export const SETTINGS_WORDS_FR = {
     'set-apikeys-convs': 'Conversations', 'set-apikeys-convs-hint': 'Une par une : lire ou parler', 'set-apikeys-off': 'Non',
     'set-apikeys-read': 'Lire', 'set-apikeys-talk': 'Parler', 'set-apikeys-no-convs': 'Aucune conversation pour l\'instant',
     'set-apikeys-journal': 'Journal', 'set-apikeys-no-use': 'Aucun appel pour l\'instant',
+    'set-apikeys-rooms': 'Salons', 'set-apikeys-rooms-hint': 'Un par un : lire ou parler', 'set-apikeys-no-rooms': 'Aucun salon pour l\'instant',
+    'set-apikeys-boxes': 'Boîtiers vocaux', 'set-apikeys-boxes-hint': 'Un par un : état, ou parler à voix haute', 'set-apikeys-no-boxes': 'Aucun boîtier pour l\'instant',
+    'set-apikeys-state': 'État', 'set-apikeys-speak': 'Parler à voix haute',
     /* The rights of an asset (06-11, kit.js RIGHTS): what it has (a pill), a choice, its one line. */
     'set-rt-none': 'Aucun', 'set-rt-read': 'Lit', 'set-rt-write': 'Écrit', 'set-rt-use': 'Utilise', 'set-rt-watch': 'Surveille',
     'set-rt-propose': 'Propose', 'set-rt-frame': 'Encadré', 'set-rt-free': 'Libre', 'set-rt-terminal': 'Terminal', 'set-rt-chat': 'Chat',

package/web/app.js

@@ -6554,7 +6554,27 @@
         }
         return box;
     }
+    /* ITS ROOMS AND VOICE BOXES (07-11), one by one the same way: a room Off / Read / Talk, a box Off / State /
+       Speak aloud -- said plainly: it is heard in the home. `kind`: 'rooms' or 'boxes'; `chosen`: id -> level. */
+    const apiKeyBoxWord = (level) => (level === 'speak' ? uiSaid('set-apikeys-speak', 'Speak aloud') : uiSaid('set-apikeys-state', 'State'));
+    const apiKeyItems = (kind) => (kind === 'rooms' ? roomsNow().filter((r) => r && r.id).map((r) => ({ id: r.id, name: r.name })) : boxesNow().filter((b) => b && b.id).map((b) => ({ id: b.id, name: b.name })));
+    function apiKeyOnePicker(kind, chosen, onChange) {
+        const box = el('div', `apikey-${kind}`);
+        const list = apiKeyItems(kind);
+        if (!list.length) box.append(el('small', 'hint', kind === 'rooms' ? uiSaid('set-apikeys-no-rooms', 'No room yet') : uiSaid('set-apikeys-no-boxes', 'No voice box yet')));
+        const options = kind === 'rooms'
+            ? [{ value: '', label: uiSaid('set-apikeys-off', 'Off') }, { value: 'read', label: apiKeyLevelWord('read') }, { value: 'talk', label: apiKeyLevelWord('talk') }]
+            : [{ value: '', label: uiSaid('set-apikeys-off', 'Off') }, { value: 'state', label: apiKeyBoxWord('state') }, { value: 'speak', label: apiKeyBoxWord('speak') }];
+        for (const x of list) {
+            const row = el('div', kind === 'rooms' ? 'apikey-conv apikey-room' : 'apikey-conv apikey-box'); row.dataset.id = x.id;
+            row.append(el('span', '', x.name), KIT.Segmented({ options, value: chosen.get(x.id) ?? '', label: x.name, onChange: (v) => onChange(x.id, v || null) }));
+            box.append(row);
+        }
+        return box;
+    }
     const apiKeyNewConvs = new Map();
+    const apiKeyNewRooms = new Map();
+    const apiKeyNewBoxes = new Map();
     /* The key whose conversations or journal are open under it, kept across a repaint. */
     let apiKeyOpen = null;
     async function paintApiKeyJournal(box, id) {
@@ -6574,6 +6594,7 @@
         const got = DEVICE ? null : await fetch(`${API}/apikeys`).then((r) => (r.ok ? r.json() : null)).catch(() => null);
         $('settings-ch-apikeys').hidden = !got || !Array.isArray(got.keys);
         if (!got || !Array.isArray(got.keys)) return;
+        await Promise.all([loadRooms(), loadBoxes()]);
         const scopeWord = (id) => uiSaid(`set-apikeys-scope-${id}`, got.scopes.find((x) => x.id === id)?.label ?? id);
         const live = got.keys.filter((k) => !k.expired).length;
         chapterNow('s-apikeys', got.keys.length ? uiSaid(live === 1 ? 'set-apikeys-n1' : 'set-apikeys-n', live === 1 ? '1 key' : '{n} keys', { n: live }) : uiSaid('set-apikeys-about', 'For a program or an AI.'));
@@ -6594,7 +6615,9 @@
             what.append(head);
             const tags = el('span', 'apikey-scopes');
             const given = [...k.scopes.map((sc) => ({ text: scopeWord(sc) })),
-                ...(k.conversations ?? []).map((c) => ({ text: `${shownName(conversations.find((x) => x.name === c.name) ?? { name: c.name })} · ${apiKeyLevelWord(c.level)}`, tone: c.level === 'talk' ? 'note' : undefined }))];
+                ...(k.conversations ?? []).map((c) => ({ text: `${shownName(conversations.find((x) => x.name === c.name) ?? { name: c.name })} · ${apiKeyLevelWord(c.level)}`, tone: c.level === 'talk' ? 'note' : undefined })),
+                ...(k.rooms ?? []).map((r) => ({ text: `${roomsNow().find((x) => x.id === r.id)?.name ?? r.id.slice(0, 8)} · ${apiKeyLevelWord(r.level)}`, icon: 'room', tone: r.level === 'talk' ? 'note' : undefined })),
+                ...(k.boxes ?? []).map((b) => ({ text: `${boxesNow().find((x) => x.id === b.id)?.name ?? b.id.slice(0, 8)} · ${apiKeyBoxWord(b.level)}`, icon: 'box', tone: b.level === 'speak' ? 'note' : undefined }))];
             tags.append(KIT.Chips(given.length ? given : [{ text: uiSaid('set-apikeys-no-scope', 'No scope') }]));
             what.append(tags);
             const by = k.createdBy ? (k.createdBy === got.me ? uiSaid('set-apikeys-by-you', 'by you') : k.createdBy) : '';
@@ -6617,12 +6640,20 @@
             const more = el('div', 'apikey-more'); more.hidden = true;
             const open = async (kind) => {
                 apiKeyOpen = apiKeyOpen?.id === k.id && apiKeyOpen.what === kind ? null : { id: k.id, what: kind };
-                for (const b of acts.querySelectorAll('button[data-act="convs"], button[data-act="journal"]')) b.setAttribute('aria-expanded', String(apiKeyOpen?.id === k.id && apiKeyOpen.what === b.dataset.act));
+                for (const b of acts.querySelectorAll('button[data-act="convs"], button[data-act="rooms"], button[data-act="boxes"], button[data-act="journal"]')) b.setAttribute('aria-expanded', String(apiKeyOpen?.id === k.id && apiKeyOpen.what === b.dataset.act));
                 more.hidden = apiKeyOpen?.id !== k.id;
                 more.replaceChildren();
                 if (!apiKeyOpen || apiKeyOpen.id !== k.id) return;
                 if (kind === 'journal') { more.dataset.what = 'journal'; await paintApiKeyJournal(more, k.id); return; }
-                more.dataset.what = 'convs';
+                more.dataset.what = kind;
+                if (kind === 'rooms' || kind === 'boxes') {
+                    more.append(apiKeyOnePicker(kind, new Map((k[kind] ?? []).map((x) => [x.id, x.level])), async (ref, level) => {
+                        $('apikeys-error').hidden = true;
+                        try { await post(`${API}/apikeys/${k.id}/${kind}`, { [kind === 'rooms' ? 'room' : 'box']: ref, level }); } catch (error) { $('apikeys-error').textContent = error.message; $('apikeys-error').hidden = false; }
+                        await paintApiKeys();
+                    }));
+                    return;
+                }
                 more.append(apiKeyConvPicker(new Map((k.conversations ?? []).map((c) => [c.name, c.level])), async (name, level) => {
                     $('apikeys-error').hidden = true;
                     try { await post(`${API}/apikeys/${k.id}/conversations`, { conversation: name, level }); } catch (error) { $('apikeys-error').textContent = error.message; $('apikeys-error').hidden = false; }
@@ -6633,7 +6664,15 @@
             const journal = el('button', '', uiSaid('set-apikeys-journal', 'Journal')); journal.type = 'button'; journal.dataset.act = 'journal';
             convs.addEventListener('click', () => void open('convs'));
             journal.addEventListener('click', () => void open('journal'));
-            acts.append(convs, journal, revoke);
+            acts.append(convs);
+            /* Rooms, voice boxes: offered when there are some (or the key has some still). */
+            for (const [kind, word] of [['rooms', uiSaid('set-apikeys-rooms', 'Rooms')], ['boxes', uiSaid('set-apikeys-boxes', 'Voice boxes')]]) {
+                if (!apiKeyItems(kind).length && !(k[kind] ?? []).length) continue;
+                const b = el('button', '', word); b.type = 'button'; b.dataset.act = kind;
+                b.addEventListener('click', () => void open(kind));
+                acts.append(b);
+            }
+            acts.append(journal, revoke);
             row.append(what, acts, more);
             rows.append(row);
             if (apiKeyOpen?.id === k.id) { const kind = apiKeyOpen.what; apiKeyOpen = null; void open(kind); }
@@ -6643,8 +6682,10 @@
         $('apikeys-form').hidden = !on; $('apikeys-new-row').hidden = on; $('apikeys-error').hidden = true;
         if (on) {
             $('apikeys-label').value = ''; $('apikeys-days').value = '90'; for (const b of $('apikeys-scopes').querySelectorAll('input')) b.checked = false;
-            apiKeyNewConvs.clear();
+            apiKeyNewConvs.clear(); apiKeyNewRooms.clear(); apiKeyNewBoxes.clear();
             $('apikeys-convs').replaceChildren(apiKeyConvPicker(apiKeyNewConvs, (name, level) => { if (level) apiKeyNewConvs.set(name, level); else apiKeyNewConvs.delete(name); }));
+            $('apikeys-rooms').replaceChildren(apiKeyOnePicker('rooms', apiKeyNewRooms, (id, level) => { if (level) apiKeyNewRooms.set(id, level); else apiKeyNewRooms.delete(id); }));
+            $('apikeys-boxes').replaceChildren(apiKeyOnePicker('boxes', apiKeyNewBoxes, (id, level) => { if (level) apiKeyNewBoxes.set(id, level); else apiKeyNewBoxes.delete(id); }));
             $('apikeys-label').focus();
         }
     };
@@ -6656,14 +6697,15 @@
         const days = $('apikeys-days').value;
         try {
             const scopes = [...$('apikeys-scopes').querySelectorAll('input:checked')].map((b) => b.value);
-            const r = await post(`${API}/apikeys`, { label: $('apikeys-label').value.trim(), scopes, conversations: Object.fromEntries(apiKeyNewConvs), days: days === 'never' ? null : Number(days) });
+            const r = await post(`${API}/apikeys`, { label: $('apikeys-label').value.trim(), scopes, conversations: Object.fromEntries(apiKeyNewConvs), rooms: Object.fromEntries(apiKeyNewRooms), boxes: Object.fromEntries(apiKeyNewBoxes), days: days === 'never' ? null : Number(days) });
             apiKeyFormShown(false);
             $('apikeys-secret').value = r.secret; $('apikeys-once').hidden = false;
             /* 06-11 (the owner): the configuration an AI tool takes, ready to paste -- its MCP door and the key, shown this once too. */
             const slug = (appName || 'clavarium').toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'clavarium';
             $('apikeys-config').textContent = JSON.stringify({ mcpServers: { [slug]: { type: 'http', url: `${location.origin}/api/ext/mcp`, headers: { Authorization: `Bearer ${r.secret}` } } } }, null, 2);
-            /* The curl line reads what it was given: the status, or else its conversations. */
-            $('apikeys-curl').textContent = `curl -H "Authorization: Bearer ${r.secret}" ${location.origin}/api/ext/v1/${scopes.includes('status') || !apiKeyNewConvs.size ? 'status' : 'conversations'}`;
+            /* The curl line reads what it was given: the status, or else its conversations, rooms or voice boxes. */
+            const first = scopes.includes('status') ? 'status' : apiKeyNewConvs.size ? 'conversations' : apiKeyNewRooms.size ? 'rooms' : apiKeyNewBoxes.size ? 'boxes' : 'status';
+            $('apikeys-curl').textContent = `curl -H "Authorization: Bearer ${r.secret}" ${location.origin}/api/ext/v1/${first}`;
         } catch (error) { $('apikeys-error').textContent = error.message; $('apikeys-error').hidden = false; return; }
         await paintApiKeys();
     });

package/web/index.html

@@ -1053,6 +1053,8 @@
           <div class="set-row"><div class="set-what"><label for="apikeys-label" data-said="set-apikeys-name">Name</label><small data-said="set-apikeys-name-hint">What it is for</small></div><div class="set-control"><input id="apikeys-label" maxlength="40" spellcheck="false" required></div></div>
           <div class="set-row"><div class="set-what"><span data-said="set-apikeys-scopes">Server</span><small data-said="set-apikeys-scopes-hint">What the key sees of it</small></div><div class="set-control" id="apikeys-scopes"></div></div>
           <div class="set-row"><div class="set-what"><span data-said="set-apikeys-convs">Conversations</span><small data-said="set-apikeys-convs-hint">One by one: read or talk</small></div><div class="set-control" id="apikeys-convs"></div></div>
+          <div class="set-row"><div class="set-what"><span data-said="set-apikeys-rooms">Rooms</span><small data-said="set-apikeys-rooms-hint">One by one: read or talk</small></div><div class="set-control" id="apikeys-rooms"></div></div>
+          <div class="set-row"><div class="set-what"><span data-said="set-apikeys-boxes">Voice boxes</span><small data-said="set-apikeys-boxes-hint">One by one: state, or speak aloud</small></div><div class="set-control" id="apikeys-boxes"></div></div>
           <div class="set-row"><div class="set-what"><label for="apikeys-days" data-said="set-apikeys-expires">Expires</label></div><div class="set-control"><select id="apikeys-days"><option value="30" data-said="set-apikeys-30">In 30 days</option><option value="90" data-said="set-apikeys-90" selected>In 90 days</option><option value="365" data-said="set-apikeys-365">In a year</option><option value="never" data-said="set-apikeys-never">Never</option></select></div></div>
           <div class="action-row"><span class="error" id="apikeys-error" role="alert" hidden></span><button type="button" id="apikeys-cancel" data-said="set-apikeys-cancel">Cancel</button><button type="submit" class="primary" data-said="set-apikeys-create">Create</button></div>
         </form>