@clearlysh/beehaven 0.8.16

package/dist/app-manifest.js

@@ -0,0 +1,221 @@
+/**
+ * .app manifest schema and validator.
+ *
+ * A .app is a zip archive containing:
+ *
+ *   app.json                  ← the manifest described by this file
+ *   src/buildings/*.js?       ← optional — compiled Workspace classes
+ *   ui/**                     ← optional — static frontend files (HTML/JS/CSS)
+ *   recipes/*.json?           ← optional — named Pipeline specs callable by id
+ *   assets/**?                ← optional — images, samples, presets
+ *
+ * Apps are installed to ~/.beehaven/apps/<name>@<version>/. The daemon
+ * scans that directory at startup and:
+ *   - registers each manifest.buildings[type].entry as a local building,
+ *   - exposes each manifest.ui/ directory at http://127.0.0.1:9800/apps/<name>/,
+ *   - makes each manifest.recipes[id] callable via the `pipeline` IPC RPC.
+ *
+ * The same Workspace RPC surface drives BOTH Claude (via IPC) and the
+ * browser UI (via WebSocket). An app is "an app for LLMs and an app for
+ * humans in one package" — the shared RPC contract is the seam.
+ */
+/**
+ * Lightweight structural validation — NOT a schema compiler. We reject
+ * manifests the loader cannot safely use; everything else passes.
+ */
+export function validateAppManifest(m) {
+    const errors = [];
+    const warnings = [];
+    const req = (cond, msg) => {
+        if (!cond)
+            errors.push(msg);
+    };
+    const warn = (cond, msg) => {
+        if (!cond)
+            warnings.push(msg);
+    };
+    req(m && typeof m === 'object', 'manifest must be an object');
+    if (!m || typeof m !== 'object')
+        return { valid: false, errors, warnings };
+    req(typeof m.name === 'string' && /^[a-z0-9][a-z0-9-_.]*$/.test(m.name), 'name must be a lowercase dash-separated identifier');
+    req(typeof m.version === 'string' && /^\d+\.\d+\.\d+(-[0-9a-z.]+)?$/i.test(m.version), 'version must be semver (e.g. 1.0.0 or 1.0.0-beta.1)');
+    req(!!m.vendor && typeof m.vendor === 'object', 'vendor object is required');
+    if (m.vendor) {
+        req(typeof m.vendor.name === 'string', 'vendor.name is required');
+        req(typeof m.vendor.id === 'string', 'vendor.id is required');
+    }
+    // Must have at LEAST one of buildings, recipes, or frontend — an empty
+    // app is almost always a bug.
+    const hasPayload = (m.buildings && Object.keys(m.buildings).length > 0) ||
+        (m.recipes && Object.keys(m.recipes).length > 0) ||
+        (m.frontend && typeof m.frontend === 'object');
+    req(hasPayload, 'manifest must declare at least one of: buildings, recipes, frontend');
+    if (m.buildings) {
+        for (const [key, b] of Object.entries(m.buildings)) {
+            const building = b;
+            // `runtime` is canonical, `hosted` is a deprecated alias. When both
+            // are set, `runtime` wins. Backward-compat: existing hives only
+            // setting `hosted` continue to work unchanged.
+            const runtime = building?.runtime ?? building?.hosted ?? 'local';
+            if (runtime === 'local') {
+                req(typeof building?.entry === 'string', `buildings["${key}"].entry must be a string path for runtime="local"`);
+            }
+            else if (runtime === 'cloud') {
+                req(typeof building?.cloudUrl === 'string', `buildings["${key}"].cloudUrl must be a URL for runtime="cloud"`);
+            }
+            else if (runtime === 'browser') {
+                req(typeof building?.entry === 'string', `buildings["${key}"].entry must be a string path for runtime="browser"`);
+                if (building?.fallbackFor !== undefined) {
+                    req(typeof building.fallbackFor === 'string' && m.buildings[building.fallbackFor], `buildings["${key}"].fallbackFor must reference an existing local building (got "${building.fallbackFor}")`);
+                }
+            }
+            else {
+                errors.push(`buildings["${key}"].runtime must be "local", "cloud", or "browser" (got "${runtime}")`);
+            }
+            // `requires` references a resource id — must be a string array.
+            if (building?.requires !== undefined) {
+                req(Array.isArray(building.requires) &&
+                    building.requires.every((r) => typeof r === 'string'), `buildings["${key}"].requires must be a string[] of resource ids`);
+            }
+            // `handles` references action ids — used for browser fallback routing.
+            if (building?.handles !== undefined) {
+                req(Array.isArray(building.handles) &&
+                    building.handles.every((h) => typeof h === 'string'), `buildings["${key}"].handles must be a string[] of action ids`);
+            }
+        }
+    }
+    if (m.resources) {
+        req(typeof m.resources === 'object' && !Array.isArray(m.resources), 'resources must be an object with required/user-selectable/optional arrays');
+        if (m.resources && typeof m.resources === 'object') {
+            for (const flavor of ['required', 'user-selectable', 'optional']) {
+                const arr = m.resources[flavor];
+                if (arr === undefined)
+                    continue;
+                req(Array.isArray(arr), `resources.${flavor} must be an array`);
+                if (Array.isArray(arr)) {
+                    for (let i = 0; i < arr.length; i++) {
+                        const ref = arr[i];
+                        if (typeof ref === 'string') {
+                            req(/^[a-z][a-z0-9-_.]*$/.test(ref), `resources.${flavor}[${i}] ("${ref}") must be a lowercase dash-separated id`);
+                        }
+                        else if (ref && typeof ref === 'object') {
+                            req(typeof ref.id === 'string', `resources.${flavor}[${i}].id is required`);
+                        }
+                        else {
+                            errors.push(`resources.${flavor}[${i}] must be a string or ResourceRef object`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (m.actions) {
+        req(typeof m.actions === 'object' && !Array.isArray(m.actions), 'actions must be an object keyed by dotted action id');
+        if (m.actions && typeof m.actions === 'object') {
+            for (const [id, a] of Object.entries(m.actions)) {
+                const spec = a;
+                req(/^[a-z][a-z0-9_-]*\.[a-z][a-z0-9_-]*$/.test(id), `actions["${id}"] id must be "<building>.<action>" (lowercase, dotted)`);
+                req(spec && typeof spec === 'object', `actions["${id}"] must be an object`);
+                if (spec && typeof spec === 'object') {
+                    req(typeof spec.building === 'string', `actions["${id}"].building is required`);
+                    // Cross-reference: the action's `building` must exist in `buildings`.
+                    if (spec.building && m.buildings && !m.buildings[spec.building]) {
+                        warnings.push(`actions["${id}"].building ("${spec.building}") doesn't match any declared building — typo?`);
+                    }
+                }
+            }
+        }
+    }
+    if (m.frontend) {
+        const fhosted = m.frontend.hosted ?? (m.frontend.dir ? 'local' : m.frontend.cloudUrl ? 'cloud' : 'local');
+        if (fhosted === 'local') {
+            req(typeof m.frontend.dir === 'string', 'frontend.dir must be a string path for hosted="local"');
+        }
+        else {
+            req(typeof m.frontend.cloudUrl === 'string', 'frontend.cloudUrl must be a URL for hosted="cloud"');
+        }
+    }
+    if (m.recipes) {
+        for (const [id, r] of Object.entries(m.recipes)) {
+            if (typeof r === 'string')
+                continue; // path to JSON file — resolved on load
+            req(Array.isArray(r?.steps), `recipes["${id}"].steps must be an array`);
+        }
+    }
+    warn(!m.license || !!m.license.tier, 'license.tier is recommended (free|pro|enterprise|byol)');
+    warn(!m.signature, 'manifest is unsigned — signed apps will be required in a future release');
+    if (m.tray) {
+        req(typeof m.tray === 'object' && !Array.isArray(m.tray), 'tray must be an object');
+        if (m.tray && Array.isArray(m.tray.settings)) {
+            for (let i = 0; i < m.tray.settings.length; i++) {
+                const s = m.tray.settings[i];
+                if (!s || typeof s !== 'object') {
+                    errors.push(`tray.settings[${i}] must be an object`);
+                    continue;
+                }
+                req(typeof s.key === 'string' && s.key.length > 0, `tray.settings[${i}].key is required`);
+                // action + actionField paired (one without the other = no-op).
+                if ((s.action && !s.actionField) || (s.actionField && !s.action)) {
+                    warnings.push(`tray.settings[${i}] (${s.key}): action + actionField must be set together`);
+                }
+                // cloudSync — formalize per task #79 + harden per bug #12 from
+                // the 2.19.0 audit. Constraints:
+                //   - kebab-case (lowercase letters + digits + hyphens,
+                //     starting with a letter)
+                //   - max 64 chars
+                //   - MUST NOT contain ':' — that's reserved for the daemon's
+                //     app-namespacing layer (which prepends the app name) so
+                //     a hostile manifest can't escape its own namespace by
+                //     pre-namespacing into another hive's settings space.
+                if (s.cloudSync !== undefined) {
+                    req(typeof s.cloudSync === 'string', `tray.settings[${i}].cloudSync must be a string`);
+                    if (typeof s.cloudSync === 'string') {
+                        req(/^[a-z][a-z0-9-]*$/.test(s.cloudSync), `tray.settings[${i}].cloudSync ("${s.cloudSync}") must be kebab-case (lowercase letters + digits + hyphens, starting with a letter)`);
+                        req(s.cloudSync.length <= 64, `tray.settings[${i}].cloudSync must be ≤64 chars (got ${s.cloudSync.length})`);
+                        req(!s.cloudSync.includes(':'), `tray.settings[${i}].cloudSync must not contain ':' — the daemon prepends the app name automatically to prevent cross-app key collisions`);
+                    }
+                }
+            }
+        }
+    }
+    if (m.agentDocs) {
+        req(typeof m.agentDocs === 'object' && !Array.isArray(m.agentDocs), 'agentDocs must be an object');
+        if (m.agentDocs && typeof m.agentDocs === 'object' && !Array.isArray(m.agentDocs)) {
+            // Every known key must be a non-empty relative path. We reject `..`
+            // path segments (real traversal) but allow filenames like `..foo` —
+            // the earlier `includes('..')` check had a false-positive on those.
+            // Also reject absolute paths and empty strings; an empty string
+            // would join to the install dir itself and crash on readFileSync.
+            const safe = (p) => typeof p === 'string' && p.length > 0 && !/(^|\/)\.\.($|\/)/.test(p) && !p.startsWith('/');
+            const known = ['claudeCode', 'cursor', 'mcp'];
+            for (const k of known) {
+                if (m.agentDocs[k] !== undefined) {
+                    req(safe(m.agentDocs[k]), `agentDocs.${k} must be a non-empty relative path inside the archive (no .. segments or absolute paths)`);
+                }
+            }
+            // Warn — don't reject — on unrecognized keys so a typo like
+            // `claudCode` doesn't silently disable skill install. Forward-
+            // compatible with future surfaces (cursor, mcp already reserved).
+            for (const k of Object.keys(m.agentDocs)) {
+                if (!known.includes(k)) {
+                    warnings.push(`agentDocs.${k} is not a recognized key (known: ${known.join(', ')}). Typo?`);
+                }
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors, warnings };
+}
+/** Safe JSON parse with typed result. */
+export function parseAppManifest(json) {
+    try {
+        const parsed = JSON.parse(json);
+        const result = validateAppManifest(parsed);
+        if (!result.valid) {
+            return { error: `Invalid manifest: ${result.errors.join('; ')}` };
+        }
+        return { manifest: parsed };
+    }
+    catch (err) {
+        return { error: `Failed to parse JSON: ${err?.message ?? err}` };
+    }
+}

package/dist/app-signer.js

@@ -0,0 +1,54 @@
+/**
+ * Sign .app archives with an Ed25519 private key.
+ *
+ * Separated from app-signing.ts because the verifier ships in every CLI
+ * build (end users need it), but the signer is only used by the release
+ * pipeline — keeping the private-key-handling code in a distinct module
+ * makes it obvious what should never ship in a bundled build.
+ *
+ * Usage (release CI):
+ *   beehaven app pack ./my-hive --key $HOME/.clearly/release-2026.pem \
+ *                                --signer clearly-release-2026
+ *
+ * Key generation:
+ *   openssl genpkey -algorithm ed25519 -out release-2026.pem
+ *   openssl pkey -in release-2026.pem -pubout -out release-2026.pub
+ *
+ * The .pub file's contents go into TRUSTED_SIGNERS in app-signing.ts.
+ */
+import { createHash, createPrivateKey, sign } from 'crypto';
+import { readFileSync } from 'fs';
+/**
+ * Produce a detached signature envelope for an archive.
+ *
+ * @param archivePath       path to the .app zip file to sign
+ * @param privateKeyPath    path to the Ed25519 PEM (PKCS#8 or SEC1)
+ * @param signerId          the pinned id that must match a TRUSTED_SIGNERS
+ *                          entry in the verifier (e.g. "clearly-release-2026")
+ */
+export async function signAppArchive(archivePath, privateKeyPath, signerId) {
+    // Hash the archive. Signing the hex digest rather than the raw bytes
+    // keeps verification cheap and makes bad-hash diagnostics clear when
+    // something mismatches — the verifier hashes the archive itself and
+    // compares before checking the signature.
+    const bytes = readFileSync(archivePath);
+    const digest = createHash('sha256').update(bytes).digest('hex');
+    // Read the PEM. createPrivateKey validates shape and algorithm; anything
+    // non-Ed25519 throws here with a clear error.
+    const pemBytes = readFileSync(privateKeyPath);
+    const key = createPrivateKey(pemBytes);
+    if (key.asymmetricKeyType !== 'ed25519') {
+        throw new Error(`Expected an ed25519 private key at ${privateKeyPath}, got ${key.asymmetricKeyType}`);
+    }
+    // Sign the hex digest string. Ed25519 signs the message directly (no
+    // pre-hash — it hashes internally) so `algorithm = null` is the
+    // correct Node crypto call.
+    const signature = sign(null, Buffer.from(digest, 'utf-8'), key);
+    return {
+        v: 1,
+        alg: 'ed25519',
+        signer: signerId,
+        sha256: digest,
+        sig: signature.toString('base64'),
+    };
+}

package/dist/app-signing.js

@@ -0,0 +1,127 @@
+/**
+ * App signing — verify `.app` archive signatures before install.
+ *
+ * Threat model:
+ *   - `beehaven app install https://…/foo.app` pipes a curl download
+ *     into unzip. A MITM, CDN compromise, or malicious mirror can serve
+ *     arbitrary bytes that become installed buildings with unrestricted
+ *     filesystem access inside the daemon process.
+ *   - A private npm/GitHub release without signing gives the same risk:
+ *     anyone with repo write access ships RCE.
+ *
+ * Protection:
+ *   - Each `.app` archive may be accompanied by a `.app.sig` detached
+ *     signature. The signature is an Ed25519 signature over the SHA-256
+ *     of the archive, made by one of the keys in TRUSTED_SIGNERS below.
+ *   - On install, we fetch/read both files, verify the sig, then proceed.
+ *     No sig = reject unless the user explicitly passes --allow-unsigned.
+ *
+ * Signature format (JSON, one object per file):
+ *   {
+ *     "v": 1,
+ *     "alg": "ed25519",
+ *     "signer": "clearly-release-2026",
+ *     "sha256": "64-char hex",
+ *     "sig": "base64 ed25519 signature"
+ *   }
+ *
+ * The signer id is pinned so rotating keys without updating the pin is
+ * impossible. Adding a new key requires updating TRUSTED_SIGNERS in code.
+ */
+import { createHash, createPublicKey, verify } from 'crypto';
+import { readFileSync } from 'fs';
+/**
+ * The real Clearly release key(s) get dropped in here before the CLI
+ * publishes. Keeping this empty in source means the CLI rejects every
+ * signed install until the pin is supplied — we fail closed on the CI
+ * side rather than shipping with a placeholder key that attackers can
+ * abuse.
+ *
+ * Tests / local dev: use the `trustedSigners` argument of verifyAppSig()
+ * to inject a test key pair, or pass --allow-unsigned to cmdAppInstall.
+ */
+export const TRUSTED_SIGNERS = [
+// Uncomment + paste production pubkey here before first signed release.
+// {
+//   id: 'clearly-release-2026-01',
+//   publicKeyPem:
+//     '-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA…\n-----END PUBLIC KEY-----\n',
+//   note: 'Clearly prod release signing key (2026-Q1)',
+// },
+];
+/**
+ * Verify a `.app.sig` envelope against a local archive path.
+ *
+ * @param archivePath   path to the .app file on disk
+ * @param envelope      parsed signature envelope, typically JSON from .app.sig
+ * @param trustedKeys   override TRUSTED_SIGNERS; used by tests
+ */
+export function verifyAppSignature(archivePath, envelope, trustedKeys = TRUSTED_SIGNERS) {
+    // Envelope shape checks
+    if (!envelope || envelope.v !== 1)
+        return { ok: false, reason: 'Unsupported signature version' };
+    if (envelope.alg !== 'ed25519')
+        return { ok: false, reason: `Unsupported algorithm ${envelope.alg}` };
+    if (typeof envelope.signer !== 'string')
+        return { ok: false, reason: 'Missing signer id' };
+    if (typeof envelope.sha256 !== 'string' || !/^[0-9a-f]{64}$/i.test(envelope.sha256)) {
+        return { ok: false, reason: 'Missing or malformed sha256 digest' };
+    }
+    if (typeof envelope.sig !== 'string')
+        return { ok: false, reason: 'Missing signature bytes' };
+    // Signer must be one we've pinned
+    const signer = trustedKeys.find((s) => s.id === envelope.signer);
+    if (!signer)
+        return { ok: false, reason: `Unknown signer "${envelope.signer}"` };
+    // Hash the archive locally and compare with the signed digest. This
+    // binds the signature to the exact bytes on disk — a MITM can't swap
+    // the archive while reusing a valid sig, and we detect silent
+    // corruption in flight.
+    const actualDigest = sha256OfFile(archivePath);
+    if (actualDigest.toLowerCase() !== envelope.sha256.toLowerCase()) {
+        return {
+            ok: false,
+            reason: `Archive sha256 mismatch (expected ${envelope.sha256}, got ${actualDigest})`,
+        };
+    }
+    // Verify Ed25519 signature over the digest. We sign the digest (not
+    // the whole file) so verification cost is constant even for 100MB hives.
+    let pubKey;
+    try {
+        pubKey = createPublicKey(signer.publicKeyPem);
+    }
+    catch {
+        return { ok: false, reason: `Malformed trusted public key for "${signer.id}"` };
+    }
+    let sigBuf;
+    try {
+        sigBuf = Buffer.from(envelope.sig, 'base64');
+    }
+    catch {
+        return { ok: false, reason: 'Signature is not valid base64' };
+    }
+    // Node's verify() with `null` algorithm does Ed25519 verification
+    // directly (ed25519 signs its own SHA-512 internally — we're signing
+    // the hex digest string so each byte matters).
+    const digestBytes = Buffer.from(envelope.sha256.toLowerCase(), 'utf-8');
+    const ok = verify(null, digestBytes, pubKey, sigBuf);
+    if (!ok)
+        return { ok: false, reason: 'Signature does not verify against pinned key' };
+    return { ok: true, signerId: signer.id };
+}
+/** Parse a `.app.sig` file from disk. Returns null on malformed JSON. */
+export function loadSignatureEnvelope(sigPath) {
+    try {
+        const raw = readFileSync(sigPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Compute the sha256 hex of a file (streaming for large archives). */
+export function sha256OfFile(path) {
+    const buf = readFileSync(path);
+    return createHash('sha256').update(buf).digest('hex');
+}

package/dist/audio-play.js

@@ -0,0 +1,98 @@
+/**
+ * audio-play.ts — play a synthesized audio buffer on THIS machine, with no
+ * desktop app and no GUI session.
+ *
+ * WHY THIS EXISTS. `beehaven speak` used to have exactly one voice path: RPC the
+ * desktop avatar building (`avatar/live`) and let the Mac app's on-device Kokoro
+ * play it. Headless — a CLI-owned daemon, an agent in a terminal, CI, Linux —
+ * that building is never loaded, so speak warned loudly and dropped to macOS
+ * `say`. On Linux it had no voice at all.
+ *
+ * The answer WAS a cloud rung (`voice-synthesize` → the KOKORO_TTS container),
+ * and this file existed to turn its returned WAV bytes into sound.
+ *
+ * ⚠⚠ THAT RUNG IS GONE (2026-08-27) AND THIS FILE OUTLIVED IT ON PURPOSE.
+ * `speak` is on-device only now, so the headless gap it was written for is
+ * answered by `qwen3-mlx` instead — which synthesizes to a FILE. Hence
+ * `playAudioFile` survives and the buffer/base64 pair was deleted with the
+ * caller that needed them: nothing else ever held audio as bytes.
+ *
+ * DESIGN. No npm audio dependency — every player here ships with the OS or is a
+ * thing the user already installed. We probe in order and use the first that
+ * exists, so a box with none of them degrades to a clear message instead of a
+ * stack trace.
+ */
+import { spawn } from 'child_process';
+/** Players by platform, in preference order. `args` gets the file path appended. */
+const PLAYERS = {
+    darwin: [{ cmd: 'afplay', args: [] }],
+    linux: [
+        // -q/-nodisp keep these from scribbling over an agent's terminal output.
+        { cmd: 'paplay', args: [] },
+        { cmd: 'aplay', args: ['-q'] },
+        { cmd: 'ffplay', args: ['-nodisp', '-autoexit', '-loglevel', 'quiet'] },
+        { cmd: 'mpv', args: ['--no-video', '--really-quiet'] },
+    ],
+    win32: [
+        {
+            cmd: 'powershell',
+            args: ['-NoProfile', '-Command', '(New-Object Media.SoundPlayer $args[0]).PlaySync();'],
+        },
+    ],
+};
+/**
+ * Does `cmd` exist on PATH?
+ *
+ * Uses `which`/`where` — real binaries — and NEVER `shell: true`. The obvious
+ * `command -v` needs a shell, and spawning with a shell trips Node's DEP0190
+ * warning, which prints on stderr and lands in the middle of an agent's output.
+ * A voice-availability probe has no business emitting warnings.
+ */
+function haveCommand(cmd) {
+    return new Promise((resolve) => {
+        const probe = process.platform === 'win32' ? 'where' : 'which';
+        try {
+            const p = spawn(probe, [cmd], { stdio: 'ignore' });
+            p.on('error', () => resolve(false));
+            p.on('close', (code) => resolve(code === 0));
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+/** The first available player for this platform, or null if none are installed. */
+export async function findPlayer() {
+    for (const p of PLAYERS[process.platform] ?? []) {
+        if (await haveCommand(p.cmd))
+            return p;
+    }
+    return null;
+}
+/** The one message for "this box has no way to make sound", with the fix in it. */
+function noPlayerHint() {
+    return process.platform === 'linux'
+        ? 'install one of: paplay (pulseaudio-utils), aplay (alsa-utils), ffplay, mpv'
+        : `no supported audio player found for platform "${process.platform}"`;
+}
+/**
+ * Play an audio file already on disk, to completion.
+ *
+ * This is the path the local `qwen3-mlx` provider takes: MLX writes a wav and
+ * hands over the path, so reading 300 KB into Node just to write it back out
+ * would be pure ceremony. Never throws for the ordinary "no audio player on
+ * this box" case — speak needs to fall through to its next option, not crash.
+ */
+export async function playAudioFile(file) {
+    const player = await findPlayer();
+    if (!player)
+        return { ok: false, error: noPlayerHint() };
+    const code = await new Promise((resolve) => {
+        const p = spawn(player.cmd, [...player.args, file], { stdio: 'ignore' });
+        p.on('error', () => resolve(-1));
+        p.on('close', (c) => resolve(c ?? -1));
+    });
+    if (code !== 0)
+        return { ok: false, player: player.cmd, error: `${player.cmd} exited ${code}` };
+    return { ok: true, player: player.cmd };
+}

package/dist/avatar-protocol.js

@@ -0,0 +1,25 @@
+/**
+ * The agent-facing avatar vocabulary.
+ *
+ * Both the top-level CLI and the in-process daemon MCP server consume these
+ * closed sets. The avatar building validates them again at the local-app
+ * boundary; this module prevents the agent surfaces from drifting apart.
+ *
+ * Public spellings: `beehaven --mood <mood>` and
+ * `beehaven --emote <reaction> [reason]`. MCP spellings are
+ * `avatar_emote({ emotion })` (mood or wake/sleep lifecycle), `avatar_react({ reaction, reason? })`,
+ * and `avatar_get_state({})` for the current sticky mood + dynamic PAD mood snapshot.
+ */
+export const AVATAR_EMOTIONS = [
+    'neutral', 'happy', 'sad', 'surprised', 'angry', 'confused', 'curious', 'flirty',
+];
+/** Lifecycle is binary; thinking/listening/speaking/celebrating are activity poses, not moods. */
+export const AVATAR_LIFECYCLE_MOODS = ['wake', 'sleep'];
+/** Persistent moods accepted by `--mood`. */
+export const AVATAR_MOODS = AVATAR_EMOTIONS;
+/** Values accepted by the lower-level avatar expression/MCP surface. */
+export const AVATAR_EXPRESSIONS = [...AVATAR_MOODS, ...AVATAR_LIFECYCLE_MOODS];
+export const AVATAR_REACTIONS = [
+    'wave', 'cheer', 'hearts', 'laugh', 'dance', 'buzz',
+    'nod', 'shake', 'think', 'surprise', 'sleep',
+];

package/dist/avatar-route.js

@@ -0,0 +1,79 @@
+/**
+ * avatar-route — ONE door to the on-screen avatar, shared by speech and expressions.
+ *
+ * `say`, `speak`, `--mood`, `--emote`, and the daemon MCP avatar tools all use this
+ * route so an active agent identity addresses its own avatar before the house fallback.
+ *
+ * ## Why this is a module and not two call sites
+ *
+ * ⚠⚠ AN AGENT TOKEN RE-TARGETS THE CALL, AND A MISSING TARGET HANGS FOR THE FULL
+ * TIMEOUT. The daemon rewrites the instance whenever a token is present:
+ *
+ *     building === 'avatar' && instanceId === 'live'  ⇒  instanceId = claims.avatarId
+ *
+ * (`daemon.ts`, the `app-rpc` handler). That is the feature — N signed-in agents get
+ * N distinct on-screen avatars. But an agent whose avatar is NOT on screen addresses
+ * an instance nobody answers for, and the RPC simply times out.
+ *
+ * Measured on 2026-08-27, same machine, seconds apart:
+ *   • anonymous          → returns in milliseconds
+ *   • with an agent token → throws after the full timeout
+ *
+ * ⚠ THE COST WAS PAID TWICE, DIFFERENTLY, WHICH IS THE ARGUMENT FOR THIS FILE.
+ * `say` reported **"Avatar app not installed"** — the wrong cause, prescribing an
+ * install that changes nothing. `speak` spent 30s on the rung and then spoke in
+ * macOS `say`, so the voice silently changed based on whether an identity happened
+ * to be active. One bug, two call sites, two unrecognisable symptoms.
+ *
+ * ## The policy
+ *
+ * Try the agent's own avatar; on failure retry the MAIN one. Speaking as the house
+ * is a visible, correct outcome — and it is what an anonymous caller already got.
+ * The caller is told which one answered, because "your agent has no avatar" is a
+ * real thing to know and must not be silent.
+ */
+import { appRpcOnce } from './ipc-client.js';
+export { AVATAR_EMOTIONS, AVATAR_LIFECYCLE_MOODS, AVATAR_MOODS, AVATAR_EXPRESSIONS, AVATAR_REACTIONS, } from './avatar-protocol.js';
+/**
+ * Call an avatar action, preferring the caller's own avatar instance.
+ *
+ * ⚠ `instanceId` is deliberately NOT a parameter. `'live'` is the only value that
+ * triggers the daemon's per-agent rewrite, so accepting an override would let a
+ * caller quietly opt out of the very routing this module exists to manage.
+ */
+export async function avatarRpc(action, input, opts = {}) {
+    const timeout = opts.timeout ?? 10_000;
+    /**
+     * ⚠⚠ THE AGENT ATTEMPT IS A PROBE AND GETS A SHORT DEADLINE OF ITS OWN.
+     *
+     * Given the whole timeout it costs that whole timeout on the common path, because
+     * the failure being probed for is "nobody is listening on this instance" — which
+     * can only ever end in a timeout, never in an error. Measured before this cap:
+     * `speak` took **33s** to say one line, 30 of them spent waiting for an avatar
+     * that does not exist, and then it spoke in the WRONG ENGINE because the rung had
+     * been consumed. `say` paid 10s for the same nothing.
+     *
+     * ⚠ A LIVE AVATAR ANSWERS IN MILLISECONDS — the anonymous call was measured in
+     * single-digit ms on the same daemon — so this is not a race against real work,
+     * and the cap is ~3 orders of magnitude above the observed answer.
+     *
+     * ⚠ THE HOUSE ATTEMPT KEEPS THE FULL `timeout`. It is the one doing real work
+     * (`speak` synthesizes and plays before it returns), and capping it would turn a
+     * slow-but-working voice into a failure.
+     */
+    const probe = Math.min(opts.agentProbeMs ?? 2_500, timeout);
+    const once = (agent, ms = timeout) => appRpcOnce(action, input, { building: 'avatar', instanceId: 'live', timeout: ms, agent });
+    if (!opts.token)
+        return { result: await once(undefined), via: 'house' };
+    try {
+        return { result: await once(opts.token, probe), via: 'agent' };
+    }
+    catch (e) {
+        const agentError = e?.message ?? String(e);
+        // ⚠ A SECOND FAILURE RE-THROWS THE *HOUSE* ERROR, not the agent one: the house
+        //   attempt is the one that proves the avatar is unreachable at all, and the
+        //   agent error is already the expected shape of "no avatar for this identity".
+        const result = await once(undefined);
+        return { result, via: 'house', agentError };
+    }
+}