@webship.co/workspace 0.0.0-stage → 1.0.0-alpha1

package/actions/video-edit.js

@@ -0,0 +1,54 @@
+/**
+ * Edit a video into a new version: the tabs of the Edit modal post here.
+ *
+ * The form is `video-edit.js`; the work is `videos/cmd-tools-video-edit.sh`, run on the host in a screen
+ * session like every other long action. Only a new section spoken with ElevenLabs spends credits, and that
+ * needs `confirm=yes`, which only the confirm dialog's button sends.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { workspaceDir } = require('../workspaces');
+const { startInScreen, screenStartedHtml } = require('../jobs');
+const voice = require('../audio-voice');
+const videoEdit = require('../video-edit');
+
+async function video_edit({ form, send, workspace }) {
+  if (workspace !== 'videos') return send('<div class="msg error">Videos are edited in the videos workspace.</div>', 400);
+  const found = form.mode === 'sections' ? await voice.loadEngines() : { engines: [] };
+  const p = videoEdit.plan(form, found.engines);
+  if (p.error) return send(`<div class="msg error">${esc(p.error)}</div>`, 400);
+  if (p.spends && form.confirm !== 'yes') return send(videoEdit.spendHtml(p));
+  const stringsFile = Object.keys(p.strings).length ? videoEdit.writeStrings(p.strings) : null;
+  const opts = { workspace, project: path.basename(p.out, '.mp4'), projectDir: workspaceDir('videos'), verb: 'edit',
+    cmdLine: videoEdit.commandLine(p, stringsFile, true), label: `video edit ${p.out}` };
+  const started = await startInScreen(opts);
+  if (!started.ok) {
+    if (stringsFile) fs.rmSync(path.dirname(stringsFile), { recursive: true, force: true });
+    return send(screenStartedHtml(started, opts.label, opts.project), started.already ? 409 : 500);
+  }
+  return send(voice.progressHtml({ kind: 'video', file: p.out, session: started.session, t0: Date.now(), engine: '', edit: '1' }, null));
+}
+
+// Ask the AI to make the change: a Claude Code screen in the videos folder, briefed with the video, its script,
+// the tools, the rules, the settings already chosen on the tab, and the person's own words.
+async function video_edit_ai({ form, send, res }) {
+  const brief = videoEdit.askBrief(form);
+  if (brief.error) return send(`<div class="msg error">${esc(brief.error)}</div>`, 400);
+  let out = null;
+  await require('./screens')['/actions/screen-new']({
+    form: { target: brief.target, kind: 'claude', session: brief.session, command: brief.prompt },
+    send: (html, status = 200) => { out = { html, status }; },
+    res,
+  });
+  if (!out || out.status >= 400) return send((out && out.html) || '<div class="msg error">The session did not start.</div>', (out && out.status) || 500);
+  const sessionName = `${brief.target.startsWith('p:') ? brief.target.slice(2).replace(':', '--') : 'videos'}--${brief.session}`.toLowerCase();
+  return send(`<div class="msg assistant">
+      <p>The AI (Claude Code) is working on <strong>${esc(brief.file)}</strong> in the session <code>${esc(sessionName)}</code>.</p>
+      <p class="uk-text-meta">Watch it, answer it and approve its steps on <a href="/screens">Screens</a>, or <code>screen -r ${esc(sessionName)}</code> in your own terminal.
+        The new version appears in the list when it is done; the original is not touched.</p></div>`);
+}
+
+module.exports = { '/actions/video-edit': video_edit, '/actions/video-edit-ai': video_edit_ai };

package/ai-inventory.js

@@ -0,0 +1,182 @@
+/**
+ * What "@" and "/" can offer, and what the AI Assistant is told it has.
+ *
+ * ONE inventory, read by three callers that used to disagree or not know at all:
+ *
+ *   - the suggestion popup in any prompt field (@ for agents and skills, / for commands),
+ *   - the Ace completer on the New screen form,
+ *   - the assistant's own system prompt, which never listed these at all — so it could
+ *     not use a skill it had, and would improvise instead of invoking one.
+ *
+ * The DESCRIPTION is why this is not just a directory listing. Claude Code chooses an
+ * agent or a skill by its frontmatter `description`, and a picker that shows only names
+ * makes the reader guess between `webship-workspace-build` and `webship-workspace-backups`.
+ * The same line is what lets the assistant pick correctly, so both read it from the file
+ * rather than from a hand-kept table that would drift.
+ *
+ * Three places hold items, and precedence runs the same way Claude Code resolves them:
+ * a project's own .claude/ wins over ~/.claude, which wins over the workspace draft
+ * folders (ai-agents/, ai-skills/, ai-commands/, ai-prompts/). `where` says which, so
+ * the list can show it and the assistant knows whether an item is actually installed.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { ROOT } = require('./workspaces');
+
+/**
+ * The workspace tooling itself: `webship-workspace` and its skills (-build, -backups,
+ * -graphify, -dashboard, -authoring, -site-templates, -upsun, -linux-install).
+ *
+ * These are BUILT IN to the AI Assistant — it already operates this workspace, and its
+ * system prompt carries these rules whether anybody names them or not. So offering them
+ * in the picker is noise at best and misleading at worst: it implies that building a
+ * project needs you to remember `@webship-workspace-build` first, when asking for a build
+ * is enough. Nine rows out of 135, and they crowd the top of the list because they share
+ * a prefix with the product's own name.
+ *
+ * They stay in the inventory — the assistant is still told it has them, so it can say
+ * which one it is following — and are filtered out of the SUGGESTIONS only.
+ */
+const BUILT_IN = /^webship-workspace(-|$)/;
+
+// Kind -> which trigger character offers it.
+//
+// This mirrors the CLI rather than inventing a scheme: in Claude Code a slash command is
+// typed as `/name`, and an agent is named in prose. Skills appear under BOTH here on
+// purpose — a skill is a capability you name (@) and also the thing you most often want
+// to invoke directly (/) — and prompts under neither, because a prompt is a whole
+// `claude …` launch command for a NEW session, so it cannot be dropped into a message
+// that is already running. The New screen form offers those in its own template picker.
+const TRIGGERS = {
+  agent: ['@'],
+  skill: ['@', '/'],
+  command: ['/'],
+};
+
+// A frontmatter description, as one line.
+//
+// Read from the head of the file only: a skill can be hundreds of lines and none of the
+// rest is frontmatter. The value may be folded over several lines in YAML, so a
+// continuation (indented, no `key:` of its own) is joined back on.
+const HEAD_BYTES = 4096;
+function descriptionOf(file) {
+  let head = '';
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(HEAD_BYTES);
+    const read = fs.readSync(fd, buf, 0, HEAD_BYTES, 0);
+    fs.closeSync(fd);
+    head = buf.slice(0, read).toString('utf8');
+  } catch (_) { return ''; }
+  if (!/^---\s*$/m.test(head.split('\n')[0] || '')) return '';
+  const lines = head.split('\n').slice(1);
+  let out = '';
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (/^---\s*$/.test(line)) break;
+    const m = line.match(/^description:\s*(.*)$/);
+    if (!m) continue;
+    out = m[1].trim().replace(/^["']|["']$/g, '');
+    // A folded value: following lines that are indented and are not themselves a key.
+    for (let j = i + 1; j < lines.length; j += 1) {
+      if (/^---\s*$/.test(lines[j])) break;
+      if (/^\s+\S/.test(lines[j]) && !/^\s*[a-zA-Z_-]+:/.test(lines[j])) {
+        out += ` ${lines[j].trim()}`;
+      } else break;
+    }
+    break;
+  }
+  return out.replace(/\s+/g, ' ').trim();
+}
+
+/** Items of one kind in one directory. Skills are directories with a SKILL.md. */
+function readKind(dir, kind, where, out) {
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+  for (const e of entries) {
+    let name = '';
+    let file = '';
+    if (kind === 'skill') {
+      if (!e.isDirectory()) continue;
+      file = path.join(dir, e.name, 'SKILL.md');
+      if (!fs.existsSync(file)) continue;
+      name = e.name;
+    } else {
+      if (!e.isFile() || !e.name.endsWith('.md')) continue;
+      // A folder's own documentation is not an item in it.
+      if (['README.md', 'AGENTS.md', 'CLAUDE.md'].includes(e.name)) continue;
+      name = e.name.replace(/\.md$/, '');
+      file = path.join(dir, e.name);
+    }
+    const key = `${kind}:${name}`;
+    // First writer wins, and callers add in precedence order: a project's own copy of an
+    // item is the one that would actually run there, so it must not be overwritten by
+    // the global one found later.
+    if (out.has(key)) continue;
+    out.set(key, { name, kind, where, file, description: descriptionOf(file),
+      triggers: TRIGGERS[kind] || [], builtIn: BUILT_IN.test(name) });
+  }
+}
+
+// The filesystem is walked per request otherwise, and a keystroke in the composer asks
+// for this list. Short enough that installing a skill shows up while you are looking.
+const TTL = 5000;
+const _cache = new Map();
+
+/**
+ * Everything "@" and "/" can offer here.
+ * @param {string} [workspace] the workspace key, when a page is scoped to one
+ * @param {string} [project]   a project inside it, whose own .claude/ takes precedence
+ */
+function aiInventory(workspace, project) {
+  const ck = `${workspace || ''}/${project || ''}`;
+  const hit = _cache.get(ck);
+  if (hit && Date.now() - hit.at < TTL) return hit.items;
+
+  const home = process.env.HOME || '';
+  const items = new Map();
+
+  // Precedence, highest first.
+  if (workspace && project) {
+    const pDir = path.join(ROOT, workspace, project, '.claude');
+    readKind(path.join(pDir, 'agents'), 'agent', 'this project', items);
+    readKind(path.join(pDir, 'skills'), 'skill', 'this project', items);
+    readKind(path.join(pDir, 'commands'), 'command', 'this project', items);
+  }
+  readKind(path.join(home, '.claude', 'agents'), 'agent', 'installed', items);
+  readKind(path.join(home, '.claude', 'skills'), 'skill', 'installed', items);
+  readKind(path.join(home, '.claude', 'commands'), 'command', 'installed', items);
+  // The workspace drafts. Anything only here is NOT loaded by a session yet, which the
+  // label has to say — otherwise a draft reads as available and silently does nothing.
+  readKind(path.join(ROOT, 'ai-agents'), 'agent', 'workspace draft', items);
+  readKind(path.join(ROOT, 'ai-skills'), 'skill', 'workspace draft', items);
+  readKind(path.join(ROOT, 'ai-commands'), 'command', 'workspace draft', items);
+
+  const list = [...items.values()].sort((a, b) => a.name.localeCompare(b.name));
+  _cache.set(ck, { at: Date.now(), items: list });
+  return list;
+}
+
+/** Just the items a trigger character offers, optionally filtered by what is typed. */
+function suggestFor(trigger, typed, workspace, project) {
+  const q = String(typed || '').toLowerCase();
+  return aiInventory(workspace, project)
+    // The assistant's own tooling is not something to pick — see BUILT_IN above.
+    .filter((i) => !i.builtIn)
+    .filter((i) => i.triggers.includes(trigger))
+    .filter((i) => !q || i.name.toLowerCase().includes(q)
+      || (i.description || '').toLowerCase().includes(q))
+    .sort((a, b) => {
+      // What the user is typing, first: a name that STARTS with it beats one that
+      // merely contains it, and a description match comes last.
+      const rank = (i) => (i.name.toLowerCase().startsWith(q) ? 0
+        : i.name.toLowerCase().includes(q) ? 1 : 2)
+        // then by how close to hand it is
+        + (i.where === 'this project' ? 0 : i.where === 'installed' ? 0.1 : 0.2);
+      return rank(a) - rank(b) || a.name.localeCompare(b.name);
+    });
+}
+
+module.exports = { aiInventory, suggestFor, descriptionOf, TRIGGERS, BUILT_IN };

package/ai-items.js

@@ -0,0 +1,202 @@
+/**
+ * The AI-items domain: agents, skills and prompts, in their three places —
+ * this workspace's folders (drafts), ~/.claude (what a session loads) and the
+ * shared repo (what the team has) — plus the git-blob comparison that says
+ * when the repo's copy differs from the folder's. The handlers live in
+ * actions/ai-items.js; the rendering in server.js imports the same primitives,
+ * so the buttons and the CLI can never disagree about where things are.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { loadWorkspaces, workspaceDir, sourceOf } = require('./workspaces');
+const { repoTree, invalidateRepoTree, gitBlobSha } = require('./repo-blobs');
+
+/* ---------------- file-item workspaces (agents, skills, prompts, docs) --- */
+
+// Where each editable kind installs into the live Claude Code CLI setup.
+const INSTALL_TARGETS = {
+  'ai-agents': path.join(process.env.HOME, '.claude', 'agents'),
+  'ai-skills': path.join(process.env.HOME, '.claude', 'skills'),
+  // Commands and prompts are two kinds that share one destination: a command is a
+  // $ARGUMENTS spec typed mid-session, a prompt is a whole `claude …` launch command
+  // for a new session. Installing one writes over the other where names collide.
+  'ai-commands': path.join(process.env.HOME, '.claude', 'commands'),
+  'ai-prompts': path.join(process.env.HOME, '.claude', 'commands'),
+};
+
+// Agents, skills and prompts exist in three places: this workspace folder
+// (drafts), ~/.claude (what a session loads) and webship/ai-agents (what
+// the team has). The item lists show all three, merged by name, so it is
+// obvious what is only local, only installed, or only in the repo.
+const AI_ITEMS_REPO = () => process.env.AI_ITEMS_REPO || sourceOf('ai_items', 'repo', 'webship/ai-agents');
+const AI_ITEMS_REF = () => process.env.AI_ITEMS_REF || sourceOf('ai_items', 'ref', 'main');
+// A prompt is the whole `claude …` launch command for a NEW session, so the only way
+// to use one is to start a session with it — the dashboard's New screen form, or the
+// CLI by hand. It is not a slash command, so nothing of a prompt's syncs into ~/.claude
+// or a project's .claude/. It keeps its INSTALL_TARGETS entry only so listClaudeItems
+// can still SHOW what a machine already has there.
+// AI Commands is the kind that DOES install: same destination, different shape.
+const NO_CLAUDE_SYNC = new Set(['ai-prompts']);
+
+// Where each kind sits IN THE REPO. Prompts are the one kind whose directory name
+// differs from the CLI's: webship/ai-agents keeps them at the top level, in
+// prompts/, beside the agents and skills they invoke.
+const AI_ITEMS_REPO_PATHS = { 'ai-agents': '.claude/agents', 'ai-skills': '.claude/skills',
+  'ai-commands': '.claude/commands', 'ai-prompts': 'prompts' };
+// Where each kind installs INSIDE A PROJECT — always the project's own .claude/,
+// which is what Claude Code reads there. Not the same map as above: a project's
+// prompts go to .claude/commands, never to a prompts/ directory of its own.
+const AI_ITEMS_PROJECT_PATHS = { 'ai-agents': '.claude/agents', 'ai-skills': '.claude/skills',
+  'ai-commands': '.claude/commands', 'ai-prompts': '.claude/commands' };
+
+// What ~/.claude currently has, by kind.
+function listClaudeItems(key) {
+  const dir = INSTALL_TARGETS[key];
+  if (!dir) return new Set();
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    if (key === 'ai-skills') {
+      return new Set(entries.filter((e) => e.isDirectory()
+        && fs.existsSync(path.join(dir, e.name, 'SKILL.md'))).map((e) => e.name));
+    }
+    return new Set(entries.filter((e) => e.isFile() && e.name.endsWith('.md')
+      && !['README.md', 'AGENTS.md', 'CLAUDE.md'].includes(e.name))
+      .map((e) => e.name.replace(/\.md$/, '')));
+  } catch (_) { return new Set(); }
+}
+
+// Blob shas for every shared item, grouped by name, from the ONE cached recursive
+// Trees call repo-blobs makes per repo@ref — the same identity git itself uses, so
+// comparing them against locally computed blob shas answers "does the repo's copy
+// differ from this folder's?" without fetching a single file body. `null` means
+// the repo was unreachable (an unauthenticated container), which the UI states
+// rather than implying the repo has nothing.
+async function repoItemBlobs(key) {
+  if (!AI_ITEMS_REPO_PATHS[key]) return null;
+  const tree = await repoTree(AI_ITEMS_REPO(), AI_ITEMS_REF());
+  if (!tree) return null;
+  const prefix = `${AI_ITEMS_REPO_PATHS[key]}/`;
+  const map = new Map(); // item name -> Map<path-inside-item, blob sha>
+  for (const [p, sha] of tree) {
+    if (!p.startsWith(prefix)) continue;
+    const rest = p.slice(prefix.length);
+    let name; let inner;
+    if (key === 'ai-skills') {
+      const slash = rest.indexOf('/');
+      if (slash < 1) continue;
+      name = rest.slice(0, slash);
+      inner = rest.slice(slash + 1);
+    } else {
+      if (!rest.endsWith('.md') || rest.includes('/')) continue;
+      name = rest.slice(0, -3);
+      inner = '';
+    }
+    if (['README', 'AGENTS', 'CLAUDE', 'RULES'].includes(name)) continue;
+    if (!map.has(name)) map.set(name, new Map());
+    map.get(name).set(inner, sha);
+  }
+  return map;
+}
+
+// The names alone — the same tree, so a page listing names AND comparing blobs
+// still costs one network call, not two.
+async function listRepoItems(key) {
+  const blobs = await repoItemBlobs(key);
+  return blobs === null ? null : new Set(blobs.keys());
+}
+
+// Does the repo's copy of one item differ from this folder's? null = not comparable
+// (not in the repo, or the tree was unreachable).
+function repoDiffers(key, name, repoBlobs) {
+  if (!repoBlobs || !repoBlobs.has(name)) return null;
+  const theirs = repoBlobs.get(name);
+  const dir = workspaceDir(key);
+  try {
+    if (key !== 'ai-skills') {
+      return theirs.get('') !== gitBlobSha(path.join(dir, `${name}.md`));
+    }
+    // A skill is a directory: same files with the same blob shas, or it differs.
+    const base = path.join(dir, name);
+    const mine = new Map();
+    const walk = (d, rel) => {
+      for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+        if (e.name === '.git') continue;
+        const full = path.join(d, e.name);
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) walk(full, r);
+        else if (e.isFile()) mine.set(r, gitBlobSha(full));
+      }
+    };
+    walk(base, '');
+    if (mine.size !== theirs.size) return true;
+    for (const [rel, sha] of theirs) if (mine.get(rel) !== sha) return true;
+    return false;
+  } catch (_) {
+    return null;
+  }
+}
+
+const ITEM_TEMPLATES = {
+  agents: (name) => `---
+name: ${name}
+description: Use this agent to <when to invoke it>.
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+---
+
+# ${name}
+
+You are the specialist agent for <what this agent does>.
+
+## Instructions
+
+- <how to work>
+`,
+  skills: (name) => `---
+name: ${name}
+description: <what this skill does and when to use it>
+---
+
+# ${name}
+
+## Instructions
+
+- <steps the skill follows>
+`,
+  prompts: (name) => `<Write the reusable prompt here — installing it makes it available in Claude Code as /${name}>
+`,
+  docs: (name) => `# ${name}
+
+<Write the document here — Markdown; use "Make PDF" to render a PDF next to it.>
+`,
+};
+
+// The file that holds an item's content, given its display name.
+function itemFile(key, name) {
+  const dir = workspaceDir(key);
+  if (key === 'ai-skills') return path.join(dir, name, 'SKILL.md');
+  return path.join(dir, `${name}.md`);
+}
+
+// Where an install can land besides the global ~/.claude: any real project, so a session started
+// under it (and only there) sees the item. Site workspaces only — a "project" in `docs/` or
+// `agents/` itself would be another item, not something Claude Code scopes to.
+function installTargetWorkspaces() {
+  return Object.values(loadWorkspaces()).filter((w) => w.kind !== 'files');
+}
+
+// Every write toward the repo or the folders makes the cached tree stale.
+function invalidateRepoCaches() {
+  invalidateRepoTree(AI_ITEMS_REPO());
+}
+
+module.exports = {
+  INSTALL_TARGETS, NO_CLAUDE_SYNC, AI_ITEMS_REPO, AI_ITEMS_REF, AI_ITEMS_REPO_PATHS, AI_ITEMS_PROJECT_PATHS,
+  listClaudeItems, listRepoItems, repoItemBlobs, gitBlobSha, repoDiffers,
+  ITEM_TEMPLATES, itemFile, installTargetWorkspaces, invalidateRepoCaches,
+};

package/assistant-cast.js

@@ -0,0 +1,176 @@
+/**
+ * Who the assistant's avatar can be, and which voices it can speak in.
+ *
+ * Avatars. Only the ones named in settings.yml `assistant.avatars:` are offered, so a machine shows
+ * what its owner chose and nothing else. `druplicon` ships with the dashboard; any other name is looked
+ * up in the avatars workspace (`<root>/avatars/<project>/`): a character file there
+ * (`characters/<name>.json` or `characters/osa-<name>.json`) gives its model, display name and credit,
+ * and a bare model (`public/models/<name>.vrm`) is enough on its own. The models stay where they are and
+ * are served from there, never copied into this repository: their licences are their own, and some
+ * (fan-made ones) are for personal use only.
+ *
+ * Voices. Besides the browser's own voices, the ElevenLabs voices of the account in settings.yml
+ * `elevenlabs:`, once a real key is there. Listing them is free; speaking with one spends credits, which
+ * is why it happens only when someone picks an ElevenLabs voice. The key never leaves this server: the
+ * page posts the words and gets the audio back. What was spoken is kept in `.voice-cache/`, so a
+ * sentence heard again costs nothing.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const DEFAULT_MODEL = 'eleven_multilingual_v2';
+const CACHE_DIR = path.join(__dirname, '.voice-cache');
+const CACHE_MAX = 400;
+const MAX_TEXT = 600;
+const BASES = {
+  us: 'https://api.us.elevenlabs.io',
+  eu: 'https://api.eu.residency.elevenlabs.io',
+  in: 'https://api.in.residency.elevenlabs.io',
+  sg: 'https://api.sg.residency.elevenlabs.io',
+};
+
+const NAME_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+// The avatars that ship with the dashboard, in public/avatar/.
+const BUILT_IN = {
+  druplicon: { name: 'Druplicon', model: '/avatar/druplicon.vrm',
+    credit: 'Druplicon, the Drupal drop, built in code. Druplicon is licensed under the GPL; Drupal is a registered trademark of Dries Buytaert.' },
+};
+const titleOf = (id) => id.replace(/^osa-/, '').split(/[-_]/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join(' ');
+
+/** The set of moves an avatar does beyond the shared ones (public/assistant-avatar-moves.js), or ''. */
+const moveSetOf = (id) => (/^labiba/.test(String(id || '')) ? 'labiba' : '');
+
+/** The hair colour an avatar starts with (settings.yml assistant.avatar_hair.<id>), as #rrggbb, or ''. */
+function hairOf(settings, id) {
+  const v = String(((settings.assistant || {}).avatar_hair || {})[id] || '').trim().replace(/^['"]|['"]$/g, '');
+  return /^#[0-9a-f]{6}$/i.test(v) ? v.toLowerCase() : '';
+}
+
+/**
+ * The Claude Code agent an avatar brings (settings.yml assistant.avatar_agents.<id>), when it is
+ * installed for this user; '' keeps the assistant's own agent.
+ */
+function agentOf(settings, id, home = process.env.HOME || '') {
+  const name = String(((settings.assistant || {}).avatar_agents || {})[id] || '').trim();
+  return /^[a-z0-9][a-z0-9-]{0,62}$/.test(name) && fs.existsSync(path.join(home, '.claude', 'agents', `${name}.md`)) ? name : '';
+}
+
+/** The avatars settings.yml names, with what the page needs to show each one. Unknown names are left out. */
+function avatarCast(settings = {}, root = '') {
+  const a = settings.assistant || {};
+  const named = Array.isArray(a.avatars) && a.avatars.length ? a.avatars : ['druplicon'];
+  const out = [];
+  for (const raw of named) {
+    const id = String(raw || '').trim().toLowerCase();
+    if (!NAME_RE.test(id) || id === 'none' || out.some((x) => x.id === id)) continue;
+    const more = { moves: moveSetOf(id), hair: hairOf(settings, id) };
+    // The model's link carries its file's time, so a rebuilt model is fetched at once rather than after
+    // the hour a browser may keep it.
+    if (BUILT_IN[id]) { out.push({ id, ...BUILT_IN[id], model: `${BUILT_IN[id].model}?v=${stamp(path.join(__dirname, 'public', BUILT_IN[id].model))}`, ...more }); continue; }
+    const found = findAvatar(id, root);
+    if (found) out.push({ id, name: found.name, model: `/avatar/model/${id}.vrm?v=${stamp(found.file)}`, credit: found.credit, ...more });
+  }
+  return out;
+}
+
+const stamp = (file) => { try { return Math.round(fs.statSync(file).mtimeMs).toString(36); } catch (_) { return '0'; } };
+
+/** The model file of an avatar, inside `<root>/avatars`, or null. */
+function findAvatar(id, root) {
+  if (!NAME_RE.test(id) || !root) return null;
+  const base = path.join(root, 'avatars');
+  let projects = [];
+  try { projects = fs.readdirSync(base, { withFileTypes: true }).filter((e) => e.isDirectory() && !e.name.startsWith('.')).map((e) => e.name).sort(); } catch (_) { return null; }
+  const inside = (file) => {
+    try {
+      const real = fs.realpathSync(file);
+      return real.startsWith(fs.realpathSync(base) + path.sep) && /\.vrm$/i.test(real) && fs.statSync(real).isFile() ? real : null;
+    } catch (_) { return null; }
+  };
+  for (const p of projects) {
+    for (const stem of [id, `osa-${id}`]) {
+      let c = null;
+      try { c = JSON.parse(fs.readFileSync(path.join(base, p, 'characters', `${stem}.json`), 'utf8')); } catch (_) { continue; }
+      const rel = String((c && c.model) || '').replace(/^\/+/, '');
+      if (!/^models\/[\w.-]+\.vrm$/i.test(rel)) continue;
+      const file = inside(path.join(base, p, 'public', rel));
+      if (file) return { file, name: String(c.name || titleOf(id)).slice(0, 40), credit: String(c.credit || '').slice(0, 400) };
+    }
+  }
+  for (const p of projects) {
+    for (const stem of [id, `osa-${id}`]) {
+      const file = inside(path.join(base, p, 'public', 'models', `${stem}.vrm`));
+      if (file) return { file, name: titleOf(id), credit: `From the ${p} avatar project; its README states the model's licence.` };
+    }
+  }
+  return null;
+}
+
+/** GET /avatar/model/<id>.vrm: only a model of an avatar settings.yml names. */
+function serveAvatarModel(res, id, settings, root) {
+  const listed = avatarCast(settings, root).some((a) => a.id === id && !BUILT_IN[a.id]);
+  const found = listed ? findAvatar(id, root) : null;
+  if (!found) { res.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' }); return res.end('No such avatar.'); }
+  res.writeHead(200, { 'Content-Type': 'model/gltf-binary', 'Cache-Control': 'private, max-age=3600', 'X-Content-Type-Options': 'nosniff' });
+  fs.createReadStream(found.file).pipe(res);
+}
+
+// ---- ElevenLabs ----------------------------------------------------------------------------------
+
+/** The account's key from settings.yml, or '' while it is a placeholder or missing. */
+function elevenKey(settings = {}) {
+  const k = String((settings.elevenlabs && settings.elevenlabs.api_key) || '').trim();
+  return /^[A-Za-z0-9_.-]{20,}$/.test(k) && !/change/i.test(k) ? k : '';
+}
+const elevenBase = (settings = {}) => process.env.ELEVENLABS_API_BASE
+  || BASES[String((settings.elevenlabs && settings.elevenlabs.region) || '').toLowerCase()] || 'https://api.elevenlabs.io';
+
+let voicesMemo = { at: 0, sig: '', list: null };
+
+/** The account's voices, `{ id, name, label }`, kept ten minutes. Free: it lists, it does not speak. */
+async function elevenVoices(settings = {}, { fetchImpl = fetch } = {}) {
+  const key = elevenKey(settings);
+  if (!key) return { connected: false, voices: [] };
+  const sig = crypto.createHash('sha256').update(key + elevenBase(settings)).digest('hex');
+  if (voicesMemo.sig === sig && voicesMemo.list && Date.now() - voicesMemo.at < 600000) return { connected: true, voices: voicesMemo.list };
+  const r = await fetchImpl(`${elevenBase(settings)}/v2/voices?page_size=100`, { headers: { 'xi-api-key': key }, signal: AbortSignal.timeout(10000) });
+  if (!r.ok) return { connected: true, voices: [], error: r.status === 401 ? 'ElevenLabs rejected the key.' : `ElevenLabs answered ${r.status}.` };
+  const body = await r.json();
+  const list = (body.voices || []).filter((v) => /^[A-Za-z0-9]{16,32}$/.test(String(v.voice_id || ''))).map((v) => {
+    const l = v.labels || {};
+    return { id: v.voice_id, name: String(v.name || v.voice_id).slice(0, 60), label: [l.accent, l.gender, l.age].filter(Boolean).join(', ').slice(0, 60) };
+  });
+  voicesMemo = { at: Date.now(), sig, list };
+  return { connected: true, voices: list };
+}
+
+/** The audio of `text` in an ElevenLabs voice, as an mp3 Buffer; from the cache when it was spoken before. */
+async function elevenSpeak(settings = {}, { voice, text }, { fetchImpl = fetch, cacheDir = CACHE_DIR } = {}) {
+  const key = elevenKey(settings);
+  if (!key) throw Object.assign(new Error('ElevenLabs is not connected.'), { status: 409 });
+  const id = String(voice || '');
+  const words = String(text || '').replace(/\s+/g, ' ').trim().slice(0, MAX_TEXT);
+  if (!/^[A-Za-z0-9]{16,32}$/.test(id) || !words) throw Object.assign(new Error('A voice and some words, please.'), { status: 400 });
+  const model = String((settings.elevenlabs && (settings.elevenlabs.model_id || settings.elevenlabs.model)) || DEFAULT_MODEL).replace(/[^\w.-]/g, '') || DEFAULT_MODEL;
+  const file = path.join(cacheDir, `${crypto.createHash('sha256').update(`${id}\n${model}\n${words}`).digest('hex')}.mp3`);
+  try { return fs.readFileSync(file); } catch (_) { /* not spoken yet */ }
+  const r = await fetchImpl(`${elevenBase(settings)}/v1/text-to-speech/${id}?output_format=mp3_44100_128`, {
+    method: 'POST', signal: AbortSignal.timeout(30000),
+    headers: { 'xi-api-key': key, 'Content-Type': 'application/json', Accept: 'audio/mpeg' },
+    body: JSON.stringify({ text: words, model_id: model }),
+  });
+  if (!r.ok) throw Object.assign(new Error(r.status === 401 ? 'ElevenLabs rejected the key.' : `ElevenLabs answered ${r.status}.`), { status: 502 });
+  const audio = Buffer.from(await r.arrayBuffer());
+  try {
+    fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(file, audio, { mode: 0o600 });
+    const kept = fs.readdirSync(cacheDir).filter((f) => f.endsWith('.mp3'))
+      .map((f) => ({ f, t: fs.statSync(path.join(cacheDir, f)).mtimeMs })).sort((a, b) => b.t - a.t);
+    for (const old of kept.slice(CACHE_MAX)) fs.unlinkSync(path.join(cacheDir, old.f));
+  } catch (_) { /* spoken, just not kept */ }
+  return audio;
+}
+
+module.exports = { BUILT_IN, avatarCast, moveSetOf, hairOf, agentOf, findAvatar, serveAvatarModel, elevenKey, elevenVoices, elevenSpeak };