@clearlysh/beehaven 0.8.16

package/dist/agent-identity-daemon.js

@@ -0,0 +1,135 @@
+/**
+ * agent-identity-daemon — daemon-side minting + verification of
+ * AgentIdentity tokens.
+ *
+ * The daemon is the only party that holds the signing secret. The CLI
+ * never sees it — `beehaven agent login` asks the daemon to mint a token
+ * over IPC (`agent:mint`), and the daemon verifies tokens on the
+ * building-call path (`verifyAgentToken`).
+ *
+ * Secret resolution (first hit wins):
+ *   1. process.env.AGENT_IDENTITY_SECRET — explicit, used in prod/cloud
+ *      where the same secret must also be set on the Worker (so cloud
+ *      DOs can verify cloud-routed agent calls).
+ *   2. macOS/Linux keychain account "agent-identity-secret" — persists
+ *      across daemon restarts on this machine.
+ *   3. ~/.beehaven/agent-identity-secret (mode 600) — non-keychain hosts.
+ *   4. Generate a strong random secret + persist it. Local-dev
+ *      convenience so the 4-terminals demo works without manual setup;
+ *      the secret only needs to be stable on THIS machine because mint
+ *      AND verify both run in the daemon.
+ *
+ * Secrets shorter than 32 chars are refused (fail closed) — we never
+ * mint with a weak/empty key.
+ *
+ * @clearly-sh/beehaven-core is an optional peer dep, so AgentIdentity is
+ * loaded via dynamic import (matching daemon.ts's pattern). The option /
+ * claims shapes below mirror core's exported types.
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { keychain } from './keychain.js';
+// ── Secret resolution ────────────────────────────────
+const KC_ACCOUNT = 'agent-identity-secret';
+const SECRET_FILE = join(homedir(), '.beehaven', 'agent-identity-secret');
+const MIN_SECRET_LEN = 32;
+let _cachedSecret = null;
+/**
+ * Resolve the AgentIdentity signing secret, generating + persisting one
+ * on first use if nothing is configured. Always returns a secret that is
+ * at least 32 chars. Cached for the process lifetime.
+ */
+export function resolveAgentIdentitySecret() {
+    if (_cachedSecret)
+        return _cachedSecret;
+    // 1. Explicit env (prod / cloud parity).
+    const fromEnv = process.env.AGENT_IDENTITY_SECRET;
+    if (fromEnv && fromEnv.length >= MIN_SECRET_LEN) {
+        _cachedSecret = fromEnv;
+        return _cachedSecret;
+    }
+    if (fromEnv && fromEnv.length < MIN_SECRET_LEN) {
+        console.warn('[agent-identity] AGENT_IDENTITY_SECRET is set but shorter than 32 chars — ignoring it and using a locally-generated secret. Fix the env var for prod/cloud parity.');
+    }
+    // 2. Keychain (persists across daemon restarts on this machine).
+    try {
+        const fromKc = keychain.get(KC_ACCOUNT);
+        if (fromKc && fromKc.length >= MIN_SECRET_LEN) {
+            _cachedSecret = fromKc;
+            return _cachedSecret;
+        }
+    }
+    catch {
+        /* keychain unavailable — fall through */
+    }
+    // 3. File fallback (non-keychain hosts / containers).
+    try {
+        if (existsSync(SECRET_FILE)) {
+            const fromFile = readFileSync(SECRET_FILE, 'utf8').trim();
+            if (fromFile.length >= MIN_SECRET_LEN) {
+                _cachedSecret = fromFile;
+                return _cachedSecret;
+            }
+        }
+    }
+    catch {
+        /* unreadable — fall through */
+    }
+    // 4. Generate + persist.
+    const generated = randomBytes(48).toString('hex'); // 96 hex chars
+    let persisted = false;
+    try {
+        persisted = keychain.set(KC_ACCOUNT, generated);
+    }
+    catch {
+        /* try file next */
+    }
+    if (!persisted) {
+        try {
+            mkdirSync(dirname(SECRET_FILE), { recursive: true });
+            writeFileSync(SECRET_FILE, generated, { mode: 0o600 });
+            persisted = true;
+        }
+        catch {
+            /* in-memory only for this process lifetime */
+        }
+    }
+    if (!persisted) {
+        console.warn('[agent-identity] could not persist the signing secret to keychain or disk — agent tokens will be invalidated on the next daemon restart.');
+    }
+    _cachedSecret = generated;
+    return _cachedSecret;
+}
+// ── Core loader (optional peer dep → dynamic import) ──
+let _AgentIdentity = null;
+async function loadAgentIdentity() {
+    if (_AgentIdentity)
+        return _AgentIdentity;
+    // @ts-ignore — optional peer dependency, resolved at runtime
+    const mod = await import('@clearly-sh/beehaven-core/server');
+    if (!mod?.AgentIdentity) {
+        throw new Error('AgentIdentity not found in @clearly-sh/beehaven-core/server — update the core SDK.');
+    }
+    _AgentIdentity = mod.AgentIdentity;
+    return _AgentIdentity;
+}
+// ── Public API ───────────────────────────────────────
+/** Mint a signed AgentIdentity token. Daemon-only (holds the secret). */
+export async function mintAgentToken(opts) {
+    const secret = resolveAgentIdentitySecret();
+    if (!secret || secret.length < MIN_SECRET_LEN) {
+        throw new Error('Cannot mint agent identity: no signing secret available. Set AGENT_IDENTITY_SECRET (>=32 chars) or run inside the Hive Mac app.');
+    }
+    const AgentIdentity = await loadAgentIdentity();
+    return AgentIdentity.issue(opts, secret);
+}
+/** Verify a token. Returns null if invalid, expired, tampered, or unsigned. */
+export async function verifyAgentToken(token) {
+    const secret = resolveAgentIdentitySecret();
+    if (!secret || secret.length < MIN_SECRET_LEN)
+        return null;
+    const AgentIdentity = await loadAgentIdentity();
+    return AgentIdentity.verify(token, secret);
+}

package/dist/agent-onboard.js

@@ -0,0 +1,156 @@
+/**
+ * agent-onboard.ts — the walkthrough that turns "you have no agent identity"
+ * into one, at the moment someone first needs it.
+ *
+ * WHY THIS EXISTS AT ALL. `beehaven speak` used to work for anybody: no identity,
+ * no voice binding, one shared house voice. That is convenient exactly once — the
+ * first time. After that every agent on the machine sounds identical, nothing in
+ * the transcript says who spoke, and the avatar cannot hydrate a per-agent voice
+ * because there is no agent to hydrate from. The identity is what makes a voice
+ * *someone's*, so `speak` now requires one.
+ *
+ * ⚠⚠ A REQUIREMENT WITHOUT A PATH IS A WALL. Refusing with "run `beehaven agent
+ * login <name>`" would be correct and useless: the caller is mid-task, does not
+ * know what a `kind` is, has no idea which voices exist, and has just been told
+ * that the thing they ran does not work. This asks the three questions that
+ * matter, in order, with defaults that are right for the common case — and it
+ * ends by RUNNING the login, not by printing it.
+ *
+ * ⚠ NON-INTERACTIVE CALLERS GET THE COMMAND, NOT A HANG. A prompt written to a
+ * pipe blocks forever and looks like the CLI has frozen. `stdin.isTTY` decides,
+ * and the non-TTY branch prints the exact one-liner (including the voice flag)
+ * so a script or a CI job can be fixed in one edit. This matters more than usual
+ * here: the callers most likely to hit this are agents, not people.
+ */
+import { createInterface } from 'node:readline';
+import { color } from './spinner.js';
+import { isValidAgentName, loadAgent } from './agent-state.js';
+/**
+ * Voice providers an identity may bind to, with the voice id each expects.
+ *
+ * ⚠ `qwen3-mlx` LEADS because it is the only fully local one that can speak in a
+ * CLONED voice, which is the whole reason to give an agent its own voice rather
+ * than a shared one. The rest are ordered by how little they need: `macos` needs
+ * nothing, `kokoro` needs a downloaded model, the cloud ones need an account.
+ */
+export const VOICE_CHOICES = [
+    /**
+     * ⚠⚠ AN EMPTY VOICE HERE MEANS "A DIFFERENT PERSON EVERY UTTERANCE", NOT "the
+     * default one". On the Base checkpoint the model SAMPLES a speaker when none is
+     * conditioned, so the base voice is not a voice — it is a draw. Measured spread
+     * across repeated runs of one sentence: ~75%.
+     *
+     * ⚠ AND A PRESET NAME DOES NOT FIX IT — Base discards the name (`ethan` vs
+     * `eric` measured 0.6% apart, i.e. identical). Only a REFERENCE RECORDING pins
+     * the timbre: a cloned profile measured ~4%.
+     *
+     * The default stays empty because there is no name this file can assume exists —
+     * the registry is per-machine. `beehaven voice clone <name> <audio>` is the step
+     * that makes this provider sound the same twice, and the note says so.
+     */
+    { provider: 'qwen3-mlx', label: 'Qwen3-TTS (on-device, MLX)', defaultVoice: '', note: 'local; needs a `beehaven voice clone` name to sound the same twice' },
+    { provider: 'macos', label: 'macOS say', defaultVoice: 'Samantha', note: 'offline, always available, robotic' },
+    { provider: 'kokoro', label: 'Kokoro (on-device)', defaultVoice: 'claudette', note: 'local; needs the downloaded model' },
+    { provider: 'openai', label: 'GPT Audio', defaultVoice: 'marin', note: 'cloud; included with Clearly' },
+    { provider: 'elevenlabs', label: 'ElevenLabs', defaultVoice: 'EXAVITQu4vr4xnSDxMaL', note: 'cloud; needs your own API key' },
+];
+export function isKnownVoiceProvider(p) {
+    return VOICE_CHOICES.some((v) => v.provider === p);
+}
+/** `provider[:voiceId]` → the pair, filling in the provider's default voice. */
+export function parseVoiceBinding(raw) {
+    const trimmed = String(raw || '').trim();
+    if (!trimmed)
+        return null;
+    const [provider, ...rest] = trimmed.split(':');
+    const p = provider.trim();
+    if (!p)
+        return null;
+    const explicit = rest.length ? rest.join(':').trim() : '';
+    const known = VOICE_CHOICES.find((v) => v.provider === p);
+    return { provider: p, voiceId: explicit || known?.defaultVoice };
+}
+function ask(rl, q) {
+    return new Promise((resolve) => rl.question(q, (a) => resolve(a.trim())));
+}
+/**
+ * The command that would produce the same identity — printed to non-interactive
+ * callers, and echoed after an interactive run so the choice is reproducible.
+ */
+export function loginCommandFor(r) {
+    const v = r.voice.voiceId ? `${r.voice.provider}:${r.voice.voiceId}` : r.voice.provider;
+    // ⚠ `--agent-voice`, never `--voice` — see the flag declaration in cli.ts.
+    return `beehaven agent login ${r.name} --kind ${r.kind} --agent-voice ${v}`;
+}
+/**
+ * Ask the three questions. Returns null when the caller cannot be prompted or
+ * abandons the walkthrough — the caller decides what to do about that, because
+ * "refuse" and "fall back" are different answers for different commands.
+ */
+export async function runAgentOnboarding(opts) {
+    const suggested = opts.suggestedName && isValidAgentName(opts.suggestedName) ? opts.suggestedName : 'assistant';
+    if (!process.stdin.isTTY) {
+        console.error(`  ${color.red('✗')} ${opts.reason}`);
+        console.error('');
+        console.error('  This needs an agent identity — it is what binds a voice to a speaker.');
+        // ⚠ `--agent-voice`. Printing `--voice` here would hand the reader the boolean
+        //   flag that silently drops the binding — the exact trap this file documents.
+        console.error(`  Create one:  ${color.cyan(`beehaven agent login ${suggested} --agent-voice qwen3-mlx:ethan`)}`);
+        console.error(`  Then re-run. Voices: ${VOICE_CHOICES.map((v) => v.provider).join(' | ')}`);
+        return null;
+    }
+    console.error('');
+    console.error(`  ${color.yellow('●')} ${opts.reason}`);
+    console.error('');
+    console.error('  An agent identity is who is speaking — it carries the voice, the avatar');
+    console.error('  binding and the permissions. Three questions and you are done.');
+    console.error('');
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        // 1 — name
+        let name = '';
+        for (let i = 0; i < 3 && !name; i++) {
+            const answer = await ask(rl, `  Name for this agent [${suggested}]: `);
+            const candidate = answer || suggested;
+            if (!isValidAgentName(candidate)) {
+                console.error(`    ${color.red('✗')} letters, digits, '.', '_', '-' only (max 64).`);
+                continue;
+            }
+            // ⚠ REFUSE A NAME ALREADY ON THIS MACHINE rather than silently re-minting
+            // over it — that would move an existing agent's avatar and voice without
+            // saying so, and the previous binding would simply stop being true.
+            if (loadAgent(candidate)) {
+                console.error(`    ${color.red('✗')} "${candidate}" already exists here. Use it with --agent ${candidate}, or pick another name.`);
+                continue;
+            }
+            name = candidate;
+        }
+        if (!name)
+            return null;
+        // 2 — voice
+        console.error('');
+        console.error('  Voice:');
+        VOICE_CHOICES.forEach((v, i) => {
+            console.error(`    ${i + 1}) ${v.label.padEnd(30)} ${color.dim(v.note)}`);
+        });
+        let choice = VOICE_CHOICES[0];
+        const picked = await ask(rl, `  Pick 1-${VOICE_CHOICES.length} [1]: `);
+        const idx = picked ? Number(picked) - 1 : 0;
+        if (Number.isInteger(idx) && idx >= 0 && idx < VOICE_CHOICES.length)
+            choice = VOICE_CHOICES[idx];
+        // ⚠ An empty default is shown as "base voice" rather than as blank brackets,
+        //   which read as a question with no answer.
+        const shown = choice.defaultVoice || 'base voice';
+        const voiceId = (await ask(rl, `  Voice id [${shown}]: `)) || choice.defaultVoice;
+        // 3 — kind. Asked last and defaulted, because it is the one nobody has an
+        // opinion about on their first run.
+        const kindRaw = await ask(rl, '  Kind — claude-code | daemon-agent | clearly-ai [claude-code]: ');
+        const kind = (['claude-code', 'daemon-agent', 'clearly-ai'].includes(kindRaw)
+            ? kindRaw
+            : 'claude-code');
+        return { name, kind, voice: { provider: choice.provider, voiceId } };
+    }
+    finally {
+        rl.close();
+    }
+}

package/dist/agent-scope.js

@@ -0,0 +1,79 @@
+/**
+ * agent-scope — WHICH PROCESS IS CALLING. Dependency-free, on purpose.
+ *
+ * ⚠⚠ IT LIVES ALONE BECAUSE BOTH SIDES NEED IT AND NEITHER MAY IMPORT THE OTHER.
+ * `cli-state` (the cursor) needs to know which agent is bound to this process, and
+ * `agent-state` (the identity) needs to know what this process's scope IS. Putting the
+ * derivation in either one makes a cycle; the first attempt papered over that with
+ * `require()` inside an ESM package, which throws `ReferenceError` and — because both call
+ * sites are wrapped in try/catch for good reasons — was swallowed in silence. `agent login`
+ * wrote a correct binding and `pwd` reported "Agent: none" three commands later.
+ *
+ * ⚠ NOTHING IS IMPORTED HERE. That is the invariant: the moment this file imports either
+ * side, the cycle is back.
+ *
+ * ── WHY NOT TTY ──────────────────────────────────────────────────────────────────────────
+ * `electron/terminal-bridge.ts` allocates a REAL pty via `os.forkpty()` — chosen precisely
+ * because Electron gives children socket stdio, which breaks `script`. So an agent running
+ * in the in-app terminal has `isTTY: true` on all three streams and is indistinguishable
+ * from a person. `!isTTY` proves non-interactive; `isTTY` proves nothing at all. A
+ * TTY-based check would have missed exactly the agents that run inside this product.
+ *
+ * So identify an agent by ITS OWN MARKER, which works on a pty.
+ */
+/**
+ * A stable, per-run handle for the calling process.
+ *
+ * Returns `''` for a human at a terminal — the one case that must keep sharing the
+ * unscoped `target.json`, because anything else silently moves where an existing user's
+ * `cd` is recorded.
+ */
+export function deriveAgentScope(env = process.env) {
+    const explicit = (env.BEEHAVEN_AGENT || '').trim();
+    if (explicit)
+        return explicit; // an explicit choice always wins
+    // Claude Code — its own marker (`daemon-omni.ts` already relies on it: "the SDK refuses to
+    // start when CLAUDECODE=1 is set … it's how it refuses to recurse"), plus a per-session id.
+    if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT) {
+        const sid = (env.CLAUDE_CODE_SESSION_ID || '').replace(/[^A-Za-z0-9]/g, '');
+        return sid ? `claude-${sid.slice(0, 12)}` : 'claude';
+    }
+    // Other rooms the desktop hosts. Extend HERE, so the ladder stays in one place.
+    if (env.CODEX_SESSION_ID) {
+        return `codex-${String(env.CODEX_SESSION_ID).replace(/[^A-Za-z0-9]/g, '').slice(0, 12)}`;
+    }
+    if (env.GEMINI_CLI_SESSION_ID) {
+        return `gemini-${String(env.GEMINI_CLI_SESSION_ID).replace(/[^A-Za-z0-9]/g, '').slice(0, 12)}`;
+    }
+    /**
+     * ⚠ NO MARKER AND NO TTY IS STILL NOT A PERSON. Key on the PARENT pid — stable for the
+     * life of one process tree, different for a concurrent one. Not perfect (pids are reused
+     * eventually), but the failure mode of a collision here is two runs of the SAME tool,
+     * which is far milder than the shared-file failure it replaces: two DIFFERENT agents.
+     */
+    if (!process.stdin.isTTY && !process.stdout.isTTY)
+        return `pid-${process.ppid}`;
+    return ''; // a human at a terminal
+}
+export function principalKind(input) {
+    const now = input.now ?? Date.now();
+    if (input.agentSessionId) {
+        const expired = typeof input.agentExpiresAt === 'number' && input.agentExpiresAt <= now;
+        return expired ? 'expired' : 'agent';
+    }
+    // ⚠ An agent runtime must NAME ITSELF; it may not fall through to the human's account.
+    if (input.agentRuntime)
+        return 'refuse';
+    return input.accountUserId && input.accountToken ? 'human' : 'refuse';
+}
+export function isAgentRuntime(env = process.env) {
+    if ((env.BEEHAVEN_AGENT || '').trim())
+        return true;
+    if (env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT)
+        return true;
+    if (env.CODEX_SESSION_ID)
+        return true;
+    if (env.GEMINI_CLI_SESSION_ID)
+        return true;
+    return false;
+}