clavarium 0.2.0-next.1 → 0.2.0-next.11

package/README.md

@@ -30,8 +30,9 @@ Built slice by slice; the plan is in `blueprint/architecture.html`, tab
 
 - **5 - hands**: one-click shortcuts (sent, or left to complete), and
   dictation: the microphone stays open and each phrase is typed into the
-  terminal; "auto" presses Enter once the person has stopped. Dictation needs
-  `CLAVARIUM_TRANSCRIPTION_URL` (and `_KEY`) in the environment.
+  terminal; "auto" presses Enter once the person has stopped. Its engine is chosen
+  in Settings, Dictation (a provider, its key one of the secrets);
+  `CLAVARIUM_TRANSCRIPTION_URL` (and `_KEY`) in the environment is the fallback.
 
 - **6 - the app and sharing**: the page is installable; a conversation is
   shared with a one-use QR code; the device that scans it makes its own key,

package/deploy/install.sh

@@ -38,6 +38,9 @@
 #                      server mode)
 #   --relay-installed  the relay was set up already (by `clavarium online`):
 #                      do not print the command to run on it
+#   --name NAME        the name of this Clavarium, under its icon and in its
+#                      tab (default: drawn from --domain); changed in Settings.
+#                      Letters, digits, spaces, dots, hyphens: 30 at most
 #   --dry-run          check the parameters, say what would be done, do nothing
 #
 # AFTER --local, going online is one command: `sudo clavarium online --relay
@@ -107,12 +110,12 @@ DEX_LAYER="680f1119fdbcdd7f0ad8985b2534ded871b08b5b77c40f337c38aebd062b59c2"
 DEX_SHA256="217aa675738d1cbaf25fe8d7bc04cb00dbc60f91d8465b76b8d8af963d571337"
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 
-bad() { echo "install: $*" >&2; echo "usage: install.sh --domain NAME --operator EMAIL [--operator EMAIL...] [--port N] [--relay HOST [--relay-port N]] [--core-only] [--version X.Y.Z | --from-dir DIR] [--updates auto|asap|ask|off] [--update-window HH:MM-HH:MM] [--channel latest|next] [--dry-run]" >&2; echo "   or: install.sh --local [--port N] [same options] [--dry-run]     to try it on this machine, with no domain" >&2; exit 64; }
+bad() { echo "install: $*" >&2; echo "usage: install.sh --domain NAME --operator EMAIL [--operator EMAIL...] [--port N] [--relay HOST [--relay-port N]] [--core-only] [--version X.Y.Z | --from-dir DIR] [--updates auto|asap|ask|off] [--update-window HH:MM-HH:MM] [--channel latest|next] [--name NAME] [--dry-run]" >&2; echo "   or: install.sh --local [--port N] [same options] [--dry-run]     to try it on this machine, with no domain" >&2; exit 64; }
 refuse() { echo "install: REFUSED: $*" >&2; exit 78; }
 step() { echo "== $*"; }
 
 DOMAIN=""; OPERATORS=""; PORT="7717"; CORE_ONLY="no"; DRY="no"; RELAY=""; RELAY_PORT="22"; LOCAL="no"; KEEP_RELEASE="no"; RELAY_INSTALLED="no"
-VERSION=""; FROM_DIR=""; UPDATES=""; WINDOW=""; CHANNEL=""
+VERSION=""; FROM_DIR=""; UPDATES=""; WINDOW=""; CHANNEL=""; APP_NAME=""
 while [ $# -gt 0 ]; do
     case "$1" in
         --domain) DOMAIN="${2:-}"; shift 2 || bad "--domain needs a value" ;;
@@ -129,6 +132,7 @@ while [ $# -gt 0 ]; do
         --channel) CHANNEL="${2:-}"; shift 2 || bad "--channel needs a value" ;;
         --keep-release) KEEP_RELEASE="yes"; shift ;;
         --relay-installed) RELAY_INSTALLED="yes"; shift ;;
+        --name) APP_NAME="${2:-}"; [ -n "$APP_NAME" ] || bad "--name needs a value"; shift 2 ;;
         --dry-run) DRY="yes"; shift ;;
         *) bad "unknown parameter: $1" ;;
     esac
@@ -170,6 +174,8 @@ fi
 [ -z "$UPDATES" ] || [[ "$UPDATES" =~ ^(auto|asap|ask|off)$ ]] || bad "--updates is auto, asap, ask or off"
 [ -z "$WINDOW" ] || { [[ "$WINDOW" =~ ^([01][0-9]|2[0-3]):[0-5][0-9]-([01][0-9]|2[0-3]):[0-5][0-9]$ ]] && [ "${WINDOW%-*}" != "${WINDOW#*-}" ]; } || bad "--update-window is two times, like 02:00-05:00"
 [ -z "$CHANNEL" ] || [[ "$CHANNEL" =~ ^(latest|next)$ ]] || bad "--channel is latest or next"
+# It goes in the unit file, between quotes: plain characters only (any other is chosen in Settings).
+[ -z "$APP_NAME" ] || [[ "$APP_NAME" =~ ^[A-Za-z0-9]([A-Za-z0-9\ ._-]{0,28}[A-Za-z0-9.])?$ ]] || bad "--name is letters, digits, spaces, dots and hyphens, 30 at most, like \"Home lab\""
 # What the updates will be, as the settings file has them or as asked now.
 had() { { sed -n "s/^$1=//p" "$UPDATE_CONF" 2>/dev/null || true; } | head -1; }
 SHOW_MODE="${UPDATES:-$(had MODE)}"; SHOW_MODE="${SHOW_MODE:-auto}"
@@ -188,6 +194,7 @@ if [ "$DRY" = "yes" ]; then
 would install Clavarium:
   address     $([ "$LOCAL" = "yes" ] && echo "http://127.0.0.1:$PORT, from this machine only (--local)" || echo "https://$DOMAIN")
   operators   $([ "$LOCAL" = "yes" ] && echo "whoever can open a page on this machine: no sign-in" || echo "$OPERATORS")
+  name        $([ -n "$APP_NAME" ] && echo "$APP_NAME" || echo "drawn from the address; changed in Settings")
   server      127.0.0.1:$PORT, as the account "$ACCOUNT", Node.js $NODE_VERSION
   release     $([ "$KEEP_RELEASE" = "yes" ] && echo "the one that runs, kept (--keep-release)" || [ -n "$VERSION" ] && echo "clavarium@$VERSION from npm, checked (integrity, provenance from github.com/clavarium/clavarium, npm audit signatures)" || echo "the working tree $FROM_DIR, as it is (development: not checked)")
   updates     $(case "$SHOW_MODE" in auto) echo "automatic, between ${SHOW_WINDOW%-*} and ${SHOW_WINDOW#*-}" ;; asap) echo "as soon as a version is out" ;; ask) echo "said in Settings, done when you say" ;; off) echo "off" ;; esac), channel $SHOW_CHANNEL
@@ -335,7 +342,7 @@ User=$ACCOUNT
 Group=$ACCOUNT
 WorkingDirectory=$CODE/current/app
 EnvironmentFile=$ETC/server.env
-ExecStart=$CODE/current/node/bin/node server/main.mjs --host "sudo -n $HOST_PROGRAM" --data $DATA --vault-key $VAULT/vault.key --port $PORT$([ "$LOCAL" = "yes" ] || echo " --operators $OPERATORS --public-origin https://$DOMAIN")
+ExecStart=$CODE/current/node/bin/node server/main.mjs --host "sudo -n $HOST_PROGRAM" --data $DATA --vault-key $VAULT/vault.key --port $PORT$([ "$LOCAL" = "yes" ] || echo " --operators $OPERATORS --public-origin https://$DOMAIN")$([ -z "$APP_NAME" ] || echo " --name \"$APP_NAME\"")
 Restart=on-failure
 RestartSec=3
 

package/npm-shrinkwrap.json

@@ -1,17 +1,17 @@
 {
   "name": "clavarium",
-  "version": "0.2.0-next.1",
+  "version": "0.2.0-next.11",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "clavarium",
-      "version": "0.2.0-next.1",
+      "version": "0.2.0-next.11",
       "license": "MIT",
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",
         "@xterm/xterm": "^6.0.0",
-        "clavarium-parley": "0.10.0-next.2",
+        "clavarium-parley": "0.10.0-next.4",
         "mermaid": "11.17.2",
         "node-pty": "^1.1.0",
         "pdfjs-dist": "6.4.299",
@@ -686,9 +686,9 @@
       }
     },
     "node_modules/clavarium-parley": {
-      "version": "0.10.0-next.2",
-      "resolved": "https://registry.npmjs.org/clavarium-parley/-/clavarium-parley-0.10.0-next.2.tgz",
-      "integrity": "sha512-/6pAEMEKgug1FerqBKzqoMcWmnR6eYWtfiGt1Oa1gz9vWFuupxXlTeUFurukgfqLiEVOU6U+g1qJUff8PtTLBQ==",
+      "version": "0.10.0-next.4",
+      "resolved": "https://registry.npmjs.org/clavarium-parley/-/clavarium-parley-0.10.0-next.4.tgz",
+      "integrity": "sha512-axfpTiDMmxO0RofGc475DywHuoOLz/Jnh1o44WbyOHba6PCj0KDE/WBo36OJQCt47/3AQWMlttYn5nSBvDV1hg==",
       "license": "MIT",
       "bin": {
         "parley": "bin/parley.mjs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavarium",
-  "version": "0.2.0-next.1",
+  "version": "0.2.0-next.11",
   "license": "MIT",
   "type": "module",
   "description": "A conversation is a VM with a terminal in it. Everything else is a folder.",
@@ -35,7 +35,8 @@
     "prepare": "git config core.hooksPath hooks 2>/dev/null || true",
     "check:hooks": "node tools/check-hooks.mjs",
     "test:e2e": "node --test --test-concurrency=1 \"e2e/*.e2e.mjs\"",
-    "toolbox": "node deploy/parley-archive.mjs"
+    "toolbox": "node deploy/parley-archive.mjs",
+    "acceptance": "node acceptance/run.mjs"
   },
   "engines": {
     "node": ">=22"
@@ -43,7 +44,7 @@
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
-    "clavarium-parley": "0.10.0-next.2",
+    "clavarium-parley": "0.10.0-next.4",
     "mermaid": "11.17.2",
     "node-pty": "^1.1.0",
     "pdfjs-dist": "6.4.299",

package/server/api.mjs

@@ -22,6 +22,13 @@
  *   GET  /api/conversations/<name>/guide         what its tool is told about where it is: the exact texts, the owner's lines
  *   POST /api/conversations/<name>/guide         {lines}: the owner's own lines for it (short, plain text)
  *   POST /api/conversations/<name>/guide/tell    its guide written again, and one line typed in its terminal to read it
+ *   POST /api/conversations/<name>/group    {group}: its folder in the list ('' none); first in it
+ *   POST /api/conversations/<name>/move     {to: up|down}: one place among those of its folder
+ *   POST /api/groups/rename                 {from, to}: for all its conversations
+ *   POST /api/groups/move                   {group, to: up|down}
+ *   POST /api/order                         {order?, groups?}: the whole order, as a drag and drop leaves it
+ *   GET  /api/instance                      {name, defaultName, given}: the name of this Clavarium
+ *   POST /api/instance                      {name}: '' for the one drawn from its address
  *   GET  /api/resources
  *   POST /api/resources                     {name} | {name, type: 'git', from?, via?: {method, key?, user?, secret?}}
  *   GET  /api/git-keys                      SSH keys made here: the public half only
@@ -37,6 +44,8 @@
  *   POST /api/updates/apply                 { version }: update to the version that is out (in the background)
  *   POST /api/updates/back                  { version }: go back to a release that is kept (in the background)
  *   GET  /api/git/<name>/outgoing?target=<branch>&branch=<branch>   what would go from the agent's branch, to that branch of the remote
+ *   GET  /api/git/<name>/graph              the branch diagram: branches and their last commits
+ *   GET  /api/git/<name>/commit?id=<sha>    one commit, as a review shows it (&base=<sha>: the commits from base to it)
  *   POST /api/git/<name>/push               {head, target?, sure?}: exactly that reviewed commit, to exactly that branch
  *   GET  /api/git/<name>/keep               origin kept up to date, checks, automatic sending, log
  *   POST /api/git/<name>/keep               {refreshMinutes?, alert?, checkCommand?, checkSeconds?, runHook?, requireForSend?, fsck?}
@@ -62,6 +71,10 @@
  *   POST /api/shortcuts/<id>/remove
  *   GET  /api/voice                         is dictation available?
  *   POST /api/voice                         the body IS a WAV recording -> {text}
+ *   GET  /api/dictation                     the engine chosen in Settings (never a key: a secret's name)
+ *   POST /api/dictation                     {provider, url, model, secret, language}: chosen, at once
+ *   POST /api/dictation/off                 the environment's engine, if any, again
+ *   POST /api/dictation/try?provider=&url=&model=&secret=&language=   a WAV -> {text}, nothing saved
  *   GET  /api/files?c=<conversation>&r=<resource>&p=<path>          a listing
  *   GET  /api/flows                         who gets what: devices, conversations, assets, the rights between them, the flows
  *   POST /api/flows/name                    {around, name}: a flow named by the owner ('' gives it back its own)
@@ -102,7 +115,7 @@ function readBody(request, max = BODY_MAX) {
 }
 
 /* Returns true when the request was an API request (answered here). */
-export async function handleApi(request, response, conversations, headers, resources, originOk = sameOrigin, shortcuts, voice, sharing, secrets, network, signin, mailboxes, gitReview, platform, answerer, wakeups, alerts, talk, gitAccess, gitKeeper, shelf, health, setup, repair, guide, capacity, updates) {
+export async function handleApi(request, response, conversations, headers, resources, originOk = sameOrigin, shortcuts, voice, sharing, secrets, network, signin, mailboxes, gitReview, platform, answerer, wakeups, alerts, talk, gitAccess, gitKeeper, shelf, health, setup, repair, guide, capacity, updates, instance) {
     const { pathname } = new URL(request.url ?? '/', 'http://local');
     if (!pathname.startsWith('/api/')) return false;
     const send = (status, body) => {
@@ -130,14 +143,18 @@ export async function handleApi(request, response, conversations, headers, resou
         return resources.folder(any.name);
     };
     try {
-        if (request.method === 'GET' && pathname === '/api/voice') return send(200, { available: voice !== undefined, engine: voice?.model ?? null }), true;
-        if (request.method === 'POST' && pathname === '/api/voice') {
+        if (request.method === 'GET' && pathname === '/api/voice') return send(200, { available: voice?.current() !== undefined, engine: voice?.model ?? null }), true;
+        if (request.method === 'GET' && pathname === '/api/dictation' && voice) return send(200, voice.about()), true;
+        if (request.method === 'POST' && (pathname === '/api/voice' || (pathname === '/api/dictation/try' && voice))) {
             if (!originOk(request.headers) || request.headers['content-type'] !== 'audio/wav') {
                 return send(403, { error: 'This request does not come from this site.' }), true;
             }
             const parts = []; let size = 0;
             for await (const chunk of request) { size += chunk.length; if (size > AUDIO_MAX) throw new Refusal(413, 'The recording is too long.'); parts.push(chunk); }
-            return send(200, { text: await transcribe(voice, Buffer.concat(parts)) }), true;
+            const audio = Buffer.concat(parts);
+            /* "Try it": the choice in the form, in the address's parameters (no key in it: a secret's name). */
+            if (pathname === '/api/dictation/try') return send(200, { text: await voice.try(Object.fromEntries(query), audio) }), true;
+            return send(200, { text: voice ? await voice.transcribe(audio) : await transcribe(undefined, audio) }), true;
         }
         if (request.method === 'GET' && pathname === '/api/files') return send(200, await list(attached(), query.get('p') ?? '')), true;
         if (request.method === 'GET' && pathname === '/api/files/machine') {
@@ -192,6 +209,7 @@ export async function handleApi(request, response, conversations, headers, resou
             if (pathname === '/api/git-keys' && gitAccess) return send(200, gitAccess.keys()), true;
             if (pathname === '/api/git-hosts' && gitAccess) return send(200, gitAccess.hosts()), true;
             if (pathname === '/api/platform' && platform) return send(200, platform), true;
+            if (pathname === '/api/instance' && instance) return send(200, instance.about()), true;
             if (pathname === '/api/shelf' && shelf) return send(200, shelf.about()), true;
             /* Settings, Updates (updates.mjs): what runs, what is out, the mode, what happened. */
             if (pathname === '/api/updates' && updates) return send(200, updates.about()), true;
@@ -215,6 +233,8 @@ export async function handleApi(request, response, conversations, headers, resou
             if (answered && answerer) return send(200, answerer.log(decodeURIComponent(answered[1]))), true;
             /* A repository: where its commits go, and what would go now. */
             const repo = /^\/api\/git\/([a-z0-9-]{1,32})(\/outgoing|\/keep)?$/.exec(pathname);
+            const drawn = /^\/api\/git\/([a-z0-9-]{1,32})\/(graph|commit)$/.exec(pathname);
+            if (drawn && gitReview) return send(200, drawn[2] === 'graph' ? await gitReview.graph(drawn[1]) : await gitReview.commit(drawn[1], query.get('id'), query.get('base'))), true;
             if (repo && repo[2] === '/keep' && gitKeeper) return send(200, gitKeeper.about(repo[1])), true;
             if (repo && gitReview) return send(200, repo[2] ? await gitReview.outgoing(repo[1], { target: query.get('target') ?? undefined, branch: query.get('branch') ?? undefined }) : gitReview.settings(repo[1])), true;
             const watched = /^\/api\/conversations\/([^/]+)\/signin$/.exec(pathname);
@@ -289,7 +309,7 @@ export async function handleApi(request, response, conversations, headers, resou
         if (dropped && secrets) { secrets.remove(dropped[1]); return send(200, { ok: true }), true; }
         if (pathname === '/api/alerts' && alerts) return send(201, alerts.add(body.subscription, body.label)), true;
         if (pathname === '/api/alerts/remove' && alerts) return send(200, alerts.remove(String(body.endpoint ?? ''))), true;
-        if (pathname === '/api/alerts/test' && alerts) return send(200, { reached: await alerts.tell({ title: 'Clavarium', body: 'This is what an alert looks like.', url: '/' }) }), true;
+        if (pathname === '/api/alerts/test' && alerts) return send(200, { reached: await alerts.tell({ title: instance?.name() ?? 'Clavarium', body: 'This is what an alert looks like.', url: '/' }) }), true;
         if (pathname === '/api/talk/settings' && talk) return send(200, talk.setWords({ lang: body.lang, own: body.own })), true;
         if (pathname === '/api/talk/thread' && talk) return send(200, talk.setThread({ levels: body.levels })), true;
         const guiding = /^\/api\/conversations\/([^/]+)\/guide(\/tell)?$/.exec(pathname);
@@ -370,7 +390,7 @@ export async function handleApi(request, response, conversations, headers, resou
         if (kept && gitKeeper) {
             if (kept[2] === 'keep') return send(200, gitKeeper.set(kept[1], body)), true;
             if (kept[2] === 'refresh') return send(200, await gitKeeper.refresh(kept[1])), true;
-            return send(200, await gitKeeper.check(kept[1], body)), true;
+            return send(200, body?.again === true ? await gitKeeper.checkAgain(kept[1], body) : await gitKeeper.check(kept[1], body)), true;
         }
         /* Automatic sending belongs to the attachment: set in the conversation's panel. */
         const sending = /^\/api\/conversations\/([^/]+)\/git\/([a-z0-9-]{1,32})\/auto$/.exec(pathname);
@@ -424,6 +444,15 @@ export async function handleApi(request, response, conversations, headers, resou
         if (asking) return send(200, conversations.setAskFirst(decodeURIComponent(asking[1]), body.on)), true;
         const naming = /^\/api\/conversations\/([^/]+)\/chat-name$/.exec(pathname);
         if (naming) return send(200, conversations.setChatName(decodeURIComponent(naming[1]), body.name)), true;
+        /* The list: folders and order, the same on every device (conversations.mjs). */
+        if (pathname === '/api/instance' && instance) return send(200, instance.setName(body.name)), true;
+        if (pathname === '/api/dictation' && voice) return send(200, voice.set(body)), true;
+        if (pathname === '/api/dictation/off' && voice) return send(200, voice.off()), true;
+        if (pathname === '/api/order') return send(200, conversations.setOrder({ order: body.order, groups: body.groups })), true;
+        if (pathname === '/api/groups/rename') return send(200, conversations.renameGroup(body.from, body.to)), true;
+        if (pathname === '/api/groups/move') return send(200, conversations.moveGroup(body.group, body.to)), true;
+        const grouping = /^\/api\/conversations\/([^/]+)\/(group|move)$/.exec(pathname);
+        if (grouping) return send(200, grouping[2] === 'group' ? conversations.setGroup(decodeURIComponent(grouping[1]), body.group) : conversations.move(decodeURIComponent(grouping[1]), body.to)), true;
         const titling = /^\/api\/conversations\/([^/]+)\/title$/.exec(pathname);
         if (titling) return send(200, conversations.setTitle(decodeURIComponent(titling[1]), body.title)), true;
         const hiding = /^\/api\/conversations\/([^/]+)\/hidden$/.exec(pathname);

package/server/bridge.mjs

@@ -142,9 +142,10 @@ export function attachBridge(server, { spawn, onLeft = () => {}, onEnded = () =>
         const terminal = await spawn(name, cols, rows, say);
         /* While it was being opened another one may have been: the newest wins. */
         if (live.has(name)) close(name);
-        const kept = { terminal, sink, cols, rows };
+        const kept = { terminal, sink, cols, rows, openedAt: Date.now(), outputAt: Date.now() };
         live.set(name, kept);
         terminal.onData((bytes) => {
+            kept.outputAt = Date.now();
             if (kept.sink?.readyState === 1) { kept.sink.send(bytes, { binary: true }); return; }
             if (!kept.sink) { const answer = answerForAbsentScreen(bytes); if (answer) terminal.write(answer); }
         });
@@ -267,5 +268,9 @@ export function attachBridge(server, { spawn, onLeft = () => {}, onEnded = () =>
     /* `type(name, line, ms)`: see above. `droppedAt(name)`: when it was last
        closed for its machine's sake, or undefined. */
     const drop = (name) => { dropped.set(name, Date.now()); close(name); };
-    return { seats, drop, warm, type, open: (name) => live.has(name), droppedAt: (name) => dropped.get(name) };
+    /* `settled(name)`: how long its terminal has been open, and how long
+       since anything came out of it -- THAT something came, never what: a
+       tool still drawing its first screen is not reading its keyboard yet. */
+    const settled = (name) => { const kept = live.get(name); return kept ? { openFor: Date.now() - kept.openedAt, quietFor: Date.now() - kept.outputAt } : null; };
+    return { seats, drop, warm, type, settled, open: (name) => live.has(name), droppedAt: (name) => dropped.get(name) };
 }

package/server/conversations.mjs

@@ -6,7 +6,8 @@
  *   - Sleep is a button, never a guess: telling a long job from an idle tool
  *     cannot be done without reading the tool, and this server does not read.
  */
-import { isConversationName, identifierFrom, titleProblem } from './names.mjs';
+import { isConversationName, identifierFrom, titleProblem, groupProblem } from './names.mjs';
+import { JsonFile } from './store.mjs';
 import { attachCommand, SOCKET } from './tmux.mjs';
 import { WORK, VM_USER, SHARING_STEP } from './vm.mjs';
 import { resumeOrFresh } from './tools.mjs';
@@ -37,6 +38,8 @@ export const STARTING_MS = 180_000;
 export const ANSWER_MS = 90_000;
 /* What the folders of a machine just started are waited for, at most, before its tool starts. */
 const MOUNTED_MS = 30_000;
+/* How long a stop waits for folders being mounted (six folders took a minute on a real host). */
+const CALM_MS = 180_000;
 const POLL_MS = 2000;
 /* The tool's screen not drawn this long after its terminal was opened: its
    start is said to be over all the same (the page then opens it itself). */
@@ -60,7 +63,7 @@ const buildProgress = (since) => ({ kind: 'build', steps: ['starting', 'preparin
 const firstLine = (text) => String(text ?? '').trim().split('\n').filter(Boolean).pop()?.slice(0, 200) ?? '';
 
 export class Conversations {
-    #store; #vms; #tools; #stopDelayMs; #timers = new Map(); #watching = new Map(); #fresh = new Set(); #mountAgain = new Set(); #uid; #gid;
+    #layout; #store; #vms; #tools; #stopDelayMs; #timers = new Map(); #watching = new Map(); #fresh = new Set(); #mountAgain = new Set(); #uid; #gid;
     /* Set by the server: prepares the VM before the tool is attached, and
        names the program the tool is started through. See secrets.mjs. */
     prepare = async () => {};
@@ -78,6 +81,13 @@ export class Conversations {
        when it was just built, restarted or its work moved; otherwise only
        looked at, and put back if they came loose (health.mjs). */
     mounted = async () => {};
+    /* Set by the server: what is being done to its machine's folders just
+       now (a look of health.mjs that may mount one again), or null. */
+    quiet = () => null;
+    /* Folders being mounted again after a start, by name: a stop waits for
+       them (#calm). Stopping a machine while the VM manager mounts a folder
+       in it was seen to hang the VM manager itself, for every machine. */
+    #mounting = new Map();
     /* Set by the server: told when its machine was restarted or built again
        by this server, in words for its chat, and whether the tool runs again
        (its chat says it, and the tool is told to read it again: talk.mjs). */
@@ -90,8 +100,8 @@ export class Conversations {
     /* `uid`/`gid`: the account this server runs as; files the tool writes in
        its kept work folder belong to it on the host. */
     #startingMs; #answerMs; #pollMs;
-    constructor({ store, vms, tools, stopDelayMs = STOP_DELAY_MS, uid = process.getuid(), gid = process.getgid(), startingMs = STARTING_MS, answerMs = ANSWER_MS, pollMs = POLL_MS }) {
-        this.#store = store; this.#vms = vms; this.#tools = tools; this.#stopDelayMs = stopDelayMs; this.#uid = uid; this.#gid = gid;
+    constructor({ store, vms, tools, layout = new JsonFile(undefined, {}), stopDelayMs = STOP_DELAY_MS, uid = process.getuid(), gid = process.getgid(), startingMs = STARTING_MS, answerMs = ANSWER_MS, pollMs = POLL_MS }) {
+        this.#layout = layout; this.#store = store; this.#vms = vms; this.#tools = tools; this.#stopDelayMs = stopDelayMs; this.#uid = uid; this.#gid = gid;
         this.#startingMs = startingMs; this.#answerMs = answerMs; this.#pollMs = pollMs;
         /* A build interrupted by a restart of this server cannot be resumed
            blindly: it is marked failed, and says so. */
@@ -177,11 +187,30 @@ export class Conversations {
     /* The sign-in rules of a conversation's tool, or undefined. */
     signinRules(name) { return this.#tools.find((t) => t.id === this.#store.get(name)?.tool)?.signin; }
 
+    /* THE ORDER OF THE LIST, the same on every device: the conversations
+     * (one order; a folder shows its own in it) and the folders. Kept in a
+     * file of its own; what is not in it (made before, or by an older
+     * version) comes after, in the order it was made. A folder is only a
+     * word on its conversations: with none left, it is gone. */
+    #order() {
+        const all = this.#store.all();
+        const names = new Set(all.map((c) => c.name));
+        const kept = this.#layout.get();
+        const order = [...new Set((Array.isArray(kept.order) ? kept.order : []).filter((n) => names.has(n)))];
+        for (const c of all) if (!order.includes(c.name)) order.push(c.name);
+        const present = [...new Set(all.map((c) => c.group).filter(Boolean))];
+        const groups = [...new Set((Array.isArray(kept.groups) ? kept.groups : []).filter((g) => present.includes(g)))];
+        for (const g of present) if (!groups.includes(g)) groups.push(g);
+        return { order, groups };
+    }
+    #keepOrder({ order, groups }) { this.#layout.set({ order, groups }); }
+
     list() {
-        return this.#store.all().map((c) => {
+        const { order, groups } = this.#order();
+        return this.#store.all().sort((a, b) => order.indexOf(a.name) - order.indexOf(b.name)).map((c) => {
             const tool = this.#tools.find((t) => t.id === c.tool);
             /* An AI tool has an instruction file; a shell has none: what is dictated there is never marked. */
-            return { ...c, toolLabel: tool?.label ?? c.tool, memoryMinMb: tool?.memoryMb, resumes: Boolean(tool?.resume), rights: Boolean(tool?.rights), ai: Boolean(tool?.instructions), voiceMark: Boolean(tool?.instructions) && c.voiceMark !== false };
+            return { ...c, rank: order.indexOf(c.name), ...(c.group ? { groupRank: groups.indexOf(c.group) } : {}), toolLabel: tool?.label ?? c.tool, memoryMinMb: tool?.memoryMb, resumes: Boolean(tool?.resume), rights: Boolean(tool?.rights), ai: Boolean(tool?.instructions), voiceMark: Boolean(tool?.instructions) && c.voiceMark !== false };
         });
     }
 
@@ -211,8 +240,9 @@ export class Conversations {
         return { name: id, title: title !== undefined && title !== id ? title : undefined };
     }
 
-    create({ name: given, title: read, tool, memoryMb, workOnDisk }) {
+    create({ name: given, title: read, tool, memoryMb, workOnDisk, group }) {
         const { name, title } = this.#naming({ name: given, title: read });
+        if (group !== undefined) { const problem = groupProblem(group); if (problem) throw new Refusal(400, problem); }
         if (!isConversationName(name)) throw new Refusal(400, 'A name is 1 to 32 lower-case letters, digits or hyphens; it starts with a letter and does not end with a hyphen.');
         const chosen = this.#tools.find((t) => t.id === tool);
         if (!chosen) throw new Refusal(400, 'Unknown tool.');
@@ -222,8 +252,11 @@ export class Conversations {
         }
         if (this.#store.get(name)) throw new Refusal(409, 'A conversation already has this name.');
         const now = new Date().toISOString();
-        const conversation = { name, ...(title ? { title } : {}), tool, memoryMb: memory, diskGb: DISK_GB, fixed: FIXES, work: workOnDisk === true ? 'disk' : 'kept', phase: 'building', step: 'Starting the machine', createdAt: now, buildingSince: now, progress: buildProgress(now) };
+        const conversation = { name, ...(title ? { title } : {}), ...(group ? { group } : {}), tool, memoryMb: memory, diskGb: DISK_GB, fixed: FIXES, work: workOnDisk === true ? 'disk' : 'kept', phase: 'building', step: 'Starting the machine', createdAt: now, buildingSince: now, progress: buildProgress(now) };
+        /* A new one comes first in its folder (or first of those in none). */
+        const { order, groups } = this.#order();
         this.#store.put(conversation);
+        this.#keepOrder({ order: [name, ...order], groups: group && !groups.includes(group) ? [...groups, group] : groups });
         this.built = this.#build(name, chosen, memory);
         return conversation;
     }
@@ -402,7 +435,10 @@ export class Conversations {
         const again = this.#mountAgain.delete(name);
         if (again || stopped) {
             this.#reach(name, 'folders'); tell();
-            await Promise.race([Promise.resolve().then(() => this.mounted(name, again)).catch(() => {}), new Promise((r) => { setTimeout(r, MOUNTED_MS).unref?.(); })]);
+            const mounting = Promise.resolve().then(() => this.mounted(name, again)).catch(() => {});
+            this.#mounting.set(name, mounting);
+            void mounting.finally(() => { if (this.#mounting.get(name) === mounting) this.#mounting.delete(name); });
+            await Promise.race([mounting, new Promise((r) => { setTimeout(r, MOUNTED_MS).unref?.(); })]);
         }
         /* Woken from sleep: its tool is still there when its session is. */
         if (asleep) {
@@ -483,6 +519,78 @@ export class Conversations {
         return this.#store.get(name);
     }
 
+    /* ITS FOLDER in the list ('' for none): first among those of that folder. */
+    setGroup(name, group) {
+        const c = this.#store.get(name);
+        if (!c) throw new Refusal(404, 'No such conversation.');
+        const problem = groupProblem(group);
+        if (problem) throw new Refusal(400, problem);
+        if ((c.group ?? '') === group) return c;
+        const { order, groups } = this.#order();
+        this.#store.patch(name, { group: group || undefined });
+        this.#keepOrder({ order: [name, ...order.filter((n) => n !== name)], groups: group && !groups.includes(group) ? [...groups, group] : groups });
+        return this.#store.get(name);
+    }
+
+    /* A folder renamed, for all its conversations; to the name of another, they join it. */
+    renameGroup(from, to) {
+        const problem = groupProblem(to);
+        if (problem) throw new Refusal(400, problem);
+        if (!to) throw new Refusal(400, 'Give the new name of the folder.');
+        const inside = this.#store.all().filter((c) => typeof from === 'string' && from && c.group === from);
+        if (inside.length === 0) throw new Refusal(404, 'No such folder.');
+        const { order, groups } = this.#order();
+        for (const c of inside) this.#store.patch(c.name, { group: to });
+        const renamed = groups.includes(to) ? groups.filter((g) => g !== from) : groups.map((g) => (g === from ? to : g));
+        this.#keepOrder({ order, groups: renamed });
+        return { renamed: inside.length, group: to };
+    }
+
+    /* One place up or down among the others of its folder (`to`: 'up' or 'down').
+       A hidden one is passed over by one that is shown: it is not in sight. */
+    move(name, to) {
+        const c = this.#store.get(name);
+        if (!c) throw new Refusal(404, 'No such conversation.');
+        if (to !== 'up' && to !== 'down') throw new Refusal(400, 'Say up or down.');
+        const { order, groups } = this.#order();
+        const byName = new Map(this.#store.all().map((x) => [x.name, x]));
+        const peers = order.filter((n) => (byName.get(n).group ?? '') === (c.group ?? '') && (c.hidden === true || byName.get(n).hidden !== true || n === name));
+        const at = peers.indexOf(name);
+        const other = peers[to === 'up' ? at - 1 : at + 1];
+        if (other === undefined) return { order: this.list().map((x) => x.name) };
+        const i = order.indexOf(name); const j = order.indexOf(other);
+        [order[i], order[j]] = [order[j], order[i]];
+        this.#keepOrder({ order, groups });
+        return { order };
+    }
+
+    /* A folder one place up or down among the folders. */
+    moveGroup(group, to) {
+        if (to !== 'up' && to !== 'down') throw new Refusal(400, 'Say up or down.');
+        const { order, groups } = this.#order();
+        const at = groups.indexOf(group);
+        if (typeof group !== 'string' || at < 0) throw new Refusal(404, 'No such folder.');
+        const j = to === 'up' ? at - 1 : at + 1;
+        if (j >= 0 && j < groups.length) [groups[at], groups[j]] = [groups[j], groups[at]];
+        this.#keepOrder({ order, groups });
+        return { groups };
+    }
+
+    /* A whole order, as a drag and drop leaves it: names it does not know are
+       left out, and those it forgets keep their places after the others. */
+    setOrder({ order: wanted, groups: wantedGroups } = {}) {
+        const { order, groups } = this.#order();
+        const pick = (list, known) => {
+            if (list === undefined) return known;
+            if (!Array.isArray(list) || list.length > 10_000 || list.some((x) => typeof x !== 'string')) throw new Refusal(400, 'Give a list of names.');
+            const chosen = [...new Set(list.filter((x) => known.includes(x)))];
+            return [...chosen, ...known.filter((x) => !chosen.includes(x))];
+        };
+        const next = { order: pick(wanted, order), groups: pick(wantedGroups, groups) };
+        this.#keepOrder(next);
+        return next;
+    }
+
     /* What is dictated into its terminal starts with a microphone sign, once
        per message (true, the default for a tool that is an AI), or not. */
     setVoiceMark(name, on) {
@@ -670,6 +778,7 @@ export class Conversations {
     async #cycle(name, c, between, restart) {
         const step = (text) => { if (this.#store.get(name)) this.#store.patch(name, { step: text }); };
         try {
+            await this.#calm(name, step);
             this.drop(name);
             let state = await this.#vms.state(name);
             if (state !== 'Stopped') {
@@ -682,14 +791,15 @@ export class Conversations {
                     await this.#watched(name, 'stop', this.#vms.kill(name));
                     state = await this.#vms.state(name);
                 }
-                if (state !== 'Stopped') return `the machine did not stop (it is ${state ?? 'gone'}).`;
+                if (state !== 'Stopped') return `the machine did not stop (${state ? `it is ${state}` : 'its state could not be read'}).`;
             }
             const failed = await between();
             if (!restart) return failed;
             step('Starting the machine');
             this.#reach(name, 'starting');
             const started = await this.#watched(name, 'start', this.#vms.start(name));
-            if (started.code !== 0) return `${failed ? `${failed} And ` : ''}the machine did not start (${firstLine(started.stderr) || firstLine(started.stdout) || `exit ${started.code}`}).`;
+            /* The VM manager may fail its start for its own mounts while the machine runs: those are mounted again here. */
+            if (started.code !== 0 && (await this.#vms.state(name).catch(() => undefined)) !== 'Running') return `${failed ? `${failed} And ` : ''}the machine did not start (${firstLine(started.stderr) || firstLine(started.stdout) || `exit ${started.code}`}).`;
             /* Whatever was put in its memory is gone: the next opening prepares it again, its folders first. */
             this.#fresh.add(name);
             this.#mountAgain.add(name);
@@ -698,6 +808,18 @@ export class Conversations {
         } catch { return 'it stopped on an unexpected error.'; }
     }
 
+    /* Before its machine is stopped: its folders being mounted again are
+       left to finish, within a bound (a new look does not start meanwhile:
+       health.mjs leaves a machine that is not `ready` alone). */
+    async #calm(name, step) {
+        const pending = [this.#mounting.get(name), this.quiet(name)].filter(Boolean);
+        if (pending.length === 0) return;
+        step('Waiting for its folders to be mounted');
+        let timer;
+        await Promise.race([Promise.allSettled(pending), new Promise((r) => { timer = setTimeout(r, CALM_MS); timer.unref?.(); })]);
+        clearTimeout(timer);
+    }
+
     /* `chat`: the same, as its chat says it. */
     async #settle(name, said, chat, failed = false) {
         if (!this.#store.get(name)) return;

package/server/door.mjs

@@ -158,13 +158,13 @@ export async function handleDoor(request, response, { devices, conversations, re
         if (request.method === 'GET' && route === '/shortcuts') { need(part.terminal || part.chat === 'write', 'the terminal or the chat'); return send(200, shortcuts.list()); }
         /* What is dictated goes into the terminal, or into the chat's box: one of the two must be its to write in. */
         const speaks = part.terminal || part.chat === 'write';
-        if (request.method === 'GET' && route === '/voice') return send(200, { available: voice !== undefined && speaks, engine: speaks ? voice?.model ?? null : null });
+        if (request.method === 'GET' && route === '/voice') return send(200, { available: voice?.current() !== undefined && speaks, engine: speaks ? voice?.model ?? null : null });
         if (request.method === 'POST' && route === '/voice') {
             need(speaks, 'the terminal or the chat');
             if (request.headers['content-type'] !== 'audio/wav') return send(400, { error: 'A recording is a WAV file.' });
             const parts = []; let size = 0;
             for await (const chunk of request) { size += chunk.length; if (size > AUDIO_MAX) throw new Refusal(413, 'The recording is too long.'); parts.push(chunk); }
-            return send(200, { text: await transcribe(voice, Buffer.concat(parts)) });
+            return send(200, { text: voice ? await voice.transcribe(Buffer.concat(parts)) : await transcribe(undefined, Buffer.concat(parts)) });
         }
         /* Its conversation's chat, whatever conversation the address names: the device's own. */
         /* Only for a pairing given its chat: to read it, or to write there too. */

package/server/gitchecks.mjs

@@ -101,14 +101,14 @@ export class GitChecks {
         return Boolean(await this.#conversations.running(conversation).catch(() => false));
     }
 
-    /* -> { status: 'passed' | 'failed' | 'none' | 'unavailable', output, machine, at, head, target }.
+    /* -> { status: 'passed' | 'failed' | 'none' | 'unavailable', output, machine, at, head, branch, target }.
        'none': nothing to run (no hook, no command). 'unavailable': no
        machine to run them in, or it did not answer.
        `machine`: the conversation whose machine must run them (automatic
        sending: the one whose settings decided), else any that has it. */
     async run(repository, { head, branch, target, remoteTip, remote, command = '', hook = true, seconds = 600, machine: wanted }) {
         const at = this.#now().toISOString();
-        const base = { head, target, at, machine: null };
+        const base = { head, branch, target, at, machine: null };
         if (!hook && !command) return { ...base, status: 'none', output: 'No check is set: no pre-push hook asked for, no check command.' };
         const machine = wanted === undefined ? await this.machineFor(repository) : (await this.runs(wanted, repository) ? wanted : undefined);
         if (!machine) return { ...base, status: 'unavailable', output: 'No machine that has this repository attached is running: the checks could not run. Open a conversation it is attached to, then look again.' };