@clearlysh/beehaven 0.8.16

package/dist/agent-state.js

@@ -0,0 +1,482 @@
+/**
+ * agent-state — CLI-side storage + resolution of the active agent identity.
+ *
+ * Each agent identity the user mints is persisted to
+ * ~/.beehaven/agents/<name>.json (mode 600). The ACTIVE identity for a
+ * given terminal is selected by the `BEEHAVEN_AGENT` env var (inherently
+ * per-tty, so 4 windows can each be a different agent) or a per-call
+ * `--agent <name>` override.
+ *
+ * The signing secret never lives here — the daemon mints the token
+ * (`agent:mint`) and the CLI just stores the resulting record.
+ */
+import { deriveAgentScope } from './agent-scope.js';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync, renameSync, chmodSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Read the claims out of an agent token without verifying it.
+ *
+ * ⚠⚠ THE TOKEN IS THE AUTHORITY ON ITS OWN LIFETIME, AND NOT READING IT COST US THE
+ * EXPIRY CHECK ENTIRELY. `agent login` has two mint paths: the CLOUD one (tried
+ * first, and the one that succeeds whenever the daemon is connected) hand-builds its
+ * result from six fields and omits `userId`, `issuedAt` and `expiresAt`; the LOCAL
+ * fallback returns all three. So a cloud identity stored `expiresAt: undefined`.
+ *
+ * That is not cosmetic. `resolveActiveAgent` decides staleness with
+ * `typeof record.expiresAt === 'number' && record.expiresAt <= Date.now()` — and
+ * `typeof undefined === 'number'` is false, so **every cloud-minted identity was
+ * permanently un-expirable**. The refusal `speak` shows for a stale identity could
+ * never fire for the identities it was written to protect. It failed open, silently,
+ * and `whoami` printed `NaNm left` as the only hint.
+ *
+ * ⚠ DECODING IS NOT VERIFYING, deliberately. Signature checking needs the daemon's
+ * secret, which the CLI does not hold. These claims drive local bookkeeping only —
+ * what `whoami` prints and when to suggest a refresh; every real authorisation is
+ * re-verified server-side against the signature. The worst a tampered `exp` buys is
+ * a wrong hint in this one CLI.
+ */
+export function decodeAgentTokenClaims(token) {
+    try {
+        const payload = String(token || '').split('.')[0];
+        if (!payload)
+            return null;
+        const json = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : undefined);
+        return {
+            userId: typeof json?.userId === 'string' ? json.userId : undefined,
+            issuedAt: num(json?.iat),
+            expiresAt: num(json?.exp),
+        };
+    }
+    catch {
+        // A token this cannot parse is not an error here — the record still saves, and
+        // the fields simply stay unknown rather than becoming wrong.
+        return null;
+    }
+}
+const AGENTS_DIR = join(homedir(), '.beehaven', 'agents');
+/** Agent names are used as filenames — constrain to a safe charset. */
+export function isValidAgentName(name) {
+    return /^[a-zA-Z0-9._-]{1,64}$/.test(name);
+}
+export function agentsDir() {
+    return AGENTS_DIR;
+}
+function agentFilePath(name) {
+    return join(AGENTS_DIR, `${name}.json`);
+}
+/** Persist an identity atomically with owner-only permissions. */
+export function saveAgent(name, record) {
+    if (!isValidAgentName(name))
+        throw new Error(`Invalid agent name: ${name}`);
+    mkdirSync(AGENTS_DIR, { recursive: true });
+    const target = agentFilePath(name);
+    const tmp = `${target}.tmp`;
+    writeFileSync(tmp, JSON.stringify(record, null, 2), { mode: 0o600 });
+    renameSync(tmp, target);
+    try {
+        chmodSync(target, 0o600);
+    }
+    catch {
+        /* best effort */
+    }
+}
+/** Load a stored identity by name. Returns null if missing or unparseable. */
+export function loadAgent(name) {
+    if (!isValidAgentName(name))
+        return null;
+    const file = agentFilePath(name);
+    if (!existsSync(file))
+        return null;
+    try {
+        const rec = JSON.parse(readFileSync(file, 'utf8'));
+        /**
+         * ⚠ SELF-HEAL THE FIELDS THE CLOUD MINT LEFT OUT, IN MEMORY ONLY.
+         *
+         * Every identity minted before the fix has `userId`/`issuedAt`/`expiresAt`
+         * undefined, which makes it permanently un-expirable. Filling them from the
+         * token here means those records behave correctly immediately, without a
+         * migration and without asking anyone to re-login.
+         *
+         * ⚠ NO WRITE-BACK. `loadAgent` is called on almost every command; making it
+         * rewrite files on read would turn a lookup into a mutation and race two
+         * concurrent CLI invocations over the same file for no benefit. The next real
+         * `agent login` persists them properly.
+         */
+        if (rec && rec.token && (rec.expiresAt === undefined || rec.userId === undefined)) {
+            const claims = decodeAgentTokenClaims(rec.token);
+            if (claims) {
+                if (rec.userId === undefined)
+                    rec.userId = claims.userId;
+                if (rec.issuedAt === undefined)
+                    rec.issuedAt = claims.issuedAt;
+                if (rec.expiresAt === undefined)
+                    rec.expiresAt = claims.expiresAt;
+            }
+        }
+        return rec;
+    }
+    catch {
+        return null;
+    }
+}
+/** List every stored identity (sorted by name). */
+export function listAgents() {
+    if (!existsSync(AGENTS_DIR))
+        return [];
+    const out = [];
+    for (const file of readdirSync(AGENTS_DIR)) {
+        if (!file.endsWith('.json'))
+            continue;
+        const name = file.slice(0, -5);
+        const record = loadAgent(name);
+        if (record)
+            out.push({ name, record });
+    }
+    out.sort((a, b) => a.name.localeCompare(b.name));
+    return out;
+}
+/** Remove a stored identity. Returns true if a file was deleted. */
+export function deleteAgent(name) {
+    if (!isValidAgentName(name))
+        return false;
+    const file = agentFilePath(name);
+    if (!existsSync(file))
+        return false;
+    try {
+        unlinkSync(file);
+        // Also remove the login-materialized context file (operating guide + memory
+        // snapshot written on `agent login`), so logout leaves nothing behind.
+        try {
+            const ctx = join(AGENTS_DIR, `${name}.context.md`);
+            if (existsSync(ctx))
+                unlinkSync(ctx);
+        }
+        catch {
+            /* best-effort */
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Local-first avatar collision guard: find a DIFFERENT stored agent that
+ * already claims the given avatarId. The durable guard is AgentRegistry's
+ * avatar pool; this covers the local 4-terminals demo without a cloud D1.
+ */
+export function findAgentByAvatar(avatarId, exceptName) {
+    for (const { name, record } of listAgents()) {
+        if (name === exceptName)
+            continue;
+        if (record.avatarId === avatarId)
+            return name;
+    }
+    return null;
+}
+/**
+ * ⚠⚠ THE PROCESS SCOPE AN AGENT WAS LOGGED IN FROM — the binding that unifies the three
+ * things this codebase calls "the agent".
+ *
+ * Before this there were three unrelated handles:
+ *   · the IDENTITY   — `~/.beehaven/agents/<name>.json` (agentId, userId, token)
+ *   · the SESSION    — an `agent_sessions` row inside a workspace, its id stored above
+ *   · the CURSOR     — `target-<scope>.json`, which decides WHICH workspace
+ *
+ * `BEEHAVEN_AGENT` tied the first and third together, but only if a human remembered to
+ * export it — and `agent login` ended by PRINTING that instruction rather than doing
+ * anything. An agent that logged in and did not export was fully authenticated and still
+ * calling as nobody.
+ *
+ * Binding the login to the PROCESS SCOPE (`deriveAgentScope()`, which needs no cooperation)
+ * closes it: log in once, and every later call from that same session resolves to that
+ * agent — identity, workspace session and cursor together, with no env var to forget.
+ *
+ * ⚠ A LIST, NOT A FIELD. One agent may legitimately be logged in from several places (a
+ * terminal, the in-app shell, a cron), and one process scope may only ever mean ONE agent —
+ * which is why the reverse lookup below refuses on ambiguity rather than picking.
+ */
+export function bindAgentScope(name, scope, opts = {}) {
+    try {
+        const rec = loadAgent(name);
+        if (!rec)
+            return;
+        const prev = Array.isArray(rec.boundScopes) ? rec.boundScopes : [];
+        /**
+         * ⚠⚠ THE FAMILY IS RECORDED ALONGSIDE THE EXACT SCOPE, AND IT IS WHAT SURVIVES.
+         * A Claude Code scope is `claude-<session id>`, so it dies with the conversation: logging in
+         * bound an identity to a handle that could never be presented again, and the NEXT session was
+         * "not logged in" while holding a stored, valid, unexpired identity. Measured on this machine —
+         * `jinri-claude` was bound to `claude-507a5e19c44a` while the live session derived
+         * `claude-f400ac603290`.
+         *
+         * ⚠ A human terminal derives `''` and used to bind NOTHING, so `agent login` at a prompt could
+         * never take effect at all. It has a family (`terminal`) and now binds like everything else.
+         */
+        /**
+         * ⚠ `family: false` binds THIS scope only. A login the workspace refused must still own the
+         * session it ran in (see `loginSessionOutcome`), but must not become the identity every
+         * future un-logged-in session of the same tool inherits. A human terminal (`''`) has no exact
+         * scope — its family IS its scope — so it keeps the family either way.
+         */
+        const fam = opts.family === false && scope ? null : scopeFamilyKey(scope);
+        const add = [scope, fam].filter((s) => !!s && !prev.includes(s));
+        // `lastLoginAt` is what breaks a tie between two identities in one family; without it the
+        // fallback would have to refuse, which is the state being fixed.
+        const next = add.length ? [...add, ...prev].slice(0, 20) : prev;
+        saveAgent(name, { ...rec, boundScopes: next, lastLoginAt: Date.now() });
+    }
+    catch { /* binding is a convenience; a failed write must not fail the login */ }
+}
+/**
+ * The stable half of a process scope — the TOOL rather than the conversation.
+ *
+ * ⚠ `pid-*` HAS NO FAMILY, deliberately. That scope is the "no marker, not a TTY" fallback, i.e.
+ * we do not know what is calling; pooling those would let two unrelated scripts inherit each
+ * other's identity, which is the misattribution the scope system exists to prevent.
+ */
+export function scopeFamilyKey(scope) {
+    if (!scope)
+        return 'family:terminal';
+    const m = /^(claude|codex|gemini)-/.exec(scope);
+    if (m)
+        return `family:${m[1]}`;
+    if (scope.startsWith('pid-'))
+        return null;
+    return null;
+}
+/**
+ * The agent bound to this process scope, or null.
+ *
+ * Exact scope first (refusing on ambiguity), then the tool FAMILY — see `bindAgentScope`.
+ */
+export function agentForScope(scope = '') {
+    try {
+        const all = listAgents();
+        const boundTo = (key) => all
+            .filter(({ record }) => Array.isArray(record.boundScopes)
+            && record.boundScopes.includes(key));
+        /**
+         * ⚠⚠ TWO AGENTS ON ONE SCOPE MEANS SOMEONE LOGGED IN TWICE, AND THE SECOND LOGIN IS THE
+         * ANSWER. This used to refuse outright — "silently picking one is how a call runs as the wrong
+         * principal" — and that reasoning was written when there was no `lastLoginAt` to pick BY, so
+         * refusing was the only honest option. It is not any more.
+         *
+         * ⚠ AND THE REFUSAL WAS REPRODUCING THE BUG THIS FILE EXISTS TO FIX. Measured: after logging
+         * in as `claude` and later as `jinri-claude` from one session, every call reported *"you are an
+         * agent and have not logged in"* while holding two valid identities, the second minted seconds
+         * earlier. "Log in as X, then as Y" means you are Y everywhere else; refusing left the caller
+         * as NOBODY, which is strictly worse than the ambiguity it was avoiding.
+         *
+         * ⚠ AN UNDATABLE TIE STILL REFUSES. Two pre-`lastLoginAt` records on one scope cannot be
+         * ordered, and picking whichever the filesystem returned first IS the arbitrary choice the
+         * original note warned about.
+         */
+        if (scope) {
+            const exact = boundTo(scope);
+            if (exact.length === 1)
+                return exact[0].name;
+            if (exact.length > 1) {
+                const byRecency = [...exact].sort((a, b) => Number(b.record.lastLoginAt || 0) - Number(a.record.lastLoginAt || 0));
+                const top = Number(byRecency[0].record.lastLoginAt || 0);
+                const second = Number(byRecency[1].record.lastLoginAt || 0);
+                return top > second ? byRecency[0].name : null;
+            }
+        }
+        /**
+         * ⚠⚠ THERE IS NO WORKSPACE-QUALIFIED BINDING, AND THAT IS A FINDING RATHER THAN AN OVERSIGHT.
+         * An identity IS per workspace — the token carries `agentId` + `userId` and NO workspace, the
+         * agent row lives in the workspace DO, and `_checkAgentScope` refuses a principal it has no row
+         * for. So keying the binding on the connected workspace is the obviously right design. It was
+         * built, and it deadlocks on an ordering constraint that already exists:
+         *
+         *     cli-state.targetFileFor() → effectiveScope() → agentForScope()
+         *
+         * The CURSOR is keyed BY the agent (`target-<agent>.json`, so concurrent agents do not fight
+         * over one file), so the agent cannot be keyed by the cursor. Calling `getTarget()` from here
+         * runs during that module's own initialisation and answers `home` for every workspace —
+         * silently disabling the qualification while looking like it works. Measured: every binding was
+         * written `@home`, and two different workspaces resolved to the same agent.
+         *
+         * ⚠ SO THE PER-WORKSPACE RULE IS ENFORCED WHERE IT CAN BE — on the SERVER, which owns the
+         * roster and already refuses correctly. What this side owes is a RECOVERABLE refusal:
+         * `workspace.ts` turns `unknown agent 'X'` into the login that fixes it, and `BOOTSTRAP_ACTIONS`
+         * is what makes logging in to a fresh workspace possible at all.
+         *
+         * ⚠ DO NOT "FIX" THIS BY CACHING THE TARGET AT IMPORT TIME. The target changes with
+         * `beehaven connect` inside one process tree, so a cached value is wrong exactly when someone
+         * is moving between workspaces — the only case it would exist for.
+         */
+        /**
+         * ⚠⚠ THE FAMILY FALLBACK RESOLVES AMBIGUITY BY RECENCY RATHER THAN REFUSING, and that is the
+         * opposite of the rule above ON PURPOSE. Refusing here would make the fallback useless the
+         * moment anyone has ever used two names from one tool — the ordinary case. It is safe because
+         * it can only ever apply to a session that has NOT logged in, which today resolves to nobody:
+         * the worst outcome is inheriting your own most recent identity instead of having none.
+         */
+        const fam = scopeFamilyKey(scope);
+        if (!fam)
+            return null;
+        const kin = boundTo(fam);
+        if (!kin.length)
+            return null;
+        if (kin.length === 1)
+            return kin[0].name;
+        return [...kin]
+            .sort((a, b) => Number(b.record.lastLoginAt || 0)
+            - Number(a.record.lastLoginAt || 0))[0].name;
+    }
+    catch {
+        return null;
+    }
+}
+export function loginSessionOutcome(started, thrown) {
+    if (thrown !== undefined) {
+        return { kind: 'unreachable', reason: String(thrown?.message ?? thrown) };
+    }
+    const payload = started?.result ?? started;
+    const id = payload?.session?.id;
+    if (typeof id === 'string' && id)
+        return { kind: 'started', sessionId: id, brief: payload?.brief };
+    const err = payload?.error ?? started?.error;
+    if (err) {
+        return {
+            kind: 'refused',
+            reason: typeof err === 'string' ? err : String(err?.message ?? JSON.stringify(err)),
+            code: String(payload?.code ?? started?.code ?? ''),
+            scope: String(payload?.scope ?? started?.scope ?? ''),
+        };
+    }
+    return { kind: 'refused', reason: 'the workspace returned no session', code: '', scope: '' };
+}
+/**
+ * The active agent name for this invocation: `--agent` flag, else $BEEHAVEN_AGENT, else the
+ * agent BOUND to this process scope by a previous `agent login`.
+ */
+export function activeAgentName(values) {
+    const fromFlag = values?.agent;
+    if (typeof fromFlag === 'string' && fromFlag.trim())
+        return fromFlag.trim();
+    const fromEnv = process.env.BEEHAVEN_AGENT;
+    if (fromEnv && fromEnv.trim())
+        return fromEnv.trim();
+    try {
+        return agentForScope(deriveAgentScope());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the active agent identity for this invocation, or null when no
+ * agent is selected. Used by the call path to attach the token + route the
+ * avatar instance.
+ */
+export function resolveActiveAgent(values) {
+    const name = activeAgentName(values);
+    if (!name)
+        return null;
+    const record = loadAgent(name);
+    if (!record)
+        return null;
+    return {
+        name,
+        token: record.token,
+        ...(record.localToken ? { localToken: record.localToken } : {}),
+        agentId: record.agentId,
+        avatarId: record.avatarId,
+        record,
+        expired: typeof record.expiresAt === 'number' && record.expiresAt <= Date.now(),
+    };
+}
+/**
+ * The agent's CURRENT session id, stored beside its identity.
+ *
+ * Without this the session id exists only in the login output — so resuming means an agent (or
+ * a person) copying a uuid out of scrollback, which is exactly the kind of friction that ends
+ * with everyone starting a fresh session every time and the history fragmenting into singles.
+ */
+export function saveAgentSession(name, sessionId) {
+    try {
+        const rec = loadAgent(name);
+        if (!rec)
+            return;
+        saveAgent(name, { ...rec, sessionId });
+    }
+    catch { /* the session is still live server-side; this is a convenience */ }
+}
+/** Clear active session metadata from disk when the agent logs out. */
+export function clearAgentSession(name) {
+    try {
+        const rec = loadAgent(name);
+        if (!rec)
+            return;
+        const raw = { ...rec };
+        delete raw.sessionId;
+        delete raw.session;
+        delete raw.lastLoginAt;
+        saveAgent(name, raw);
+    }
+    catch { /* best-effort cleanup */ }
+}
+/** The last session id we started for this agent, if any. */
+export function loadAgentSession(name) {
+    try {
+        return loadAgent(name)?.sessionId ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * WHICH AGENT THIS INSTALL ACTS AS — the desktop binding, read from disk.
+ *
+ * ⚠⚠ THIS IS A THIRD MIRROR OF ONE FILE FORMAT AND THAT IS THE HAZARD IT HAS TO ANSWER FOR.
+ * `apps/electron/electron/agent-binding.ts` OWNS the format and writes the file; the avatar
+ * building (`Avatar.ts:boundPrincipal`) reads it because it runs inside the daemon and cannot
+ * reach Electron's store; this exists for the same reason, one layer over — the daemon's own
+ * in-process MCP tools need the identity that the daemon's CLI spawns already carry.
+ *
+ * A reader pointed at the wrong path does not throw. It silently returns the fallback and every
+ * screen still looks right, while one install wears two identities in the activity log —
+ * `verify-agent-binding` reads all three files and fails when the path, the shape test or the
+ * fallback drift apart. Do not "simplify" any of the three in isolation.
+ *
+ * ⚠ IT NEVER THROWS. A missing file is the ordinary state of an install that has never opened the
+ * binding menu, and a settings read must not be able to fail a turn.
+ */
+export function desktopPrincipal() {
+    try {
+        const p = join(homedir(), '.beehaven', 'desktop-agent.json');
+        const id = String(JSON.parse(readFileSync(p, 'utf8'))?.agent ?? '').trim();
+        return /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/.test(id) ? id : 'clearly-desktop';
+    }
+    catch {
+        return 'clearly-desktop';
+    }
+}
+/**
+ * The identity the DAEMON's own tools should act as, or `null` if it has none usable.
+ *
+ * ⚠⚠ `null` MUST BE A REFUSAL AT THE CALL SITE, NEVER A FALL-THROUGH TO A RAW DISPATCH. That is
+ * the exact shape deleted from `beehaven call` on 2026-08-28, and the reason is worth repeating
+ * because it is counter-intuitive: an EXPIRED identity used to make privilege go **UP**. An agent
+ * bound by a read-only `tool_allowlist` whose token lapsed silently became the account owner and
+ * kept working — the one state where a credential must do LESS, it did more.
+ *
+ * ⚠ EXPIRY IS CHECKED HERE so a caller cannot forget to. `resolveActiveAgent` returns the record
+ * WITH an `expired` flag, which is right for a CLI that wants to print a specific message and
+ * wrong for a tool boundary that has one decision to make.
+ */
+export function daemonToolIdentity() {
+    const name = desktopPrincipal();
+    const record = loadAgent(name);
+    if (!record?.agentId)
+        return null;
+    if (typeof record.expiresAt === 'number' && record.expiresAt <= Date.now())
+        return null;
+    const sessionId = loadAgentSession(name);
+    return { agentId: record.agentId, name, ...(sessionId ? { sessionId } : {}) };
+}