@clearlysh/beehaven 0.8.16

package/dist/commands/tool.js

@@ -0,0 +1,312 @@
+/**
+ * beehaven tool — Local tool registry for Claude (and other agents).
+ *
+ * Tools live under ~/.beehaven/tools/<name>/ as either:
+ *   - run.sh / run.mjs / run.ts / run.js  (executable script)
+ *   - manifest.json (optional metadata + input schema)
+ *
+ * Each tool is a self-contained script that takes JSON on stdin (or a single
+ * positional arg) and prints to stdout. Tools are discoverable, runnable, and
+ * persistent across Claude sessions — the user's workspace DO already gives Claude
+ * persistent memory; this gives Claude persistent CAPABILITIES.
+ *
+ * Subcommands:
+ *   beehaven tool list                    # list all installed tools
+ *   beehaven tool show <name>             # show one tool's manifest + script path
+ *   beehaven tool run <name> [<json>]     # execute a tool, json passed on stdin
+ *   beehaven tool create <name>           # scaffold a new tool dir
+ *   beehaven tool remove <name>           # delete a tool
+ *
+ * Example: install an elevenlabs transcription tool
+ *
+ *   beehaven tool create elevenlabs-transcribe
+ *   # writes ~/.beehaven/tools/elevenlabs-transcribe/run.mjs and manifest.json
+ *   # Claude edits run.mjs to call the ElevenLabs API
+ *
+ *   beehaven tool run elevenlabs-transcribe '{"audioFile":"/tmp/note.webm"}'
+ *   # Output: {"transcript":"...","duration":12.3,"language":"en"}
+ *
+ * The tool runs in the local shell with the user's environment. The daemon
+ * is NOT involved for local tool execution — this is intentional. Daemon
+ * RPCs are for talking to cloud DOs; local tools are for talking to APIs,
+ * the filesystem, the user's environment.
+ *
+ * Tools can call `beehaven rpc <action>` internally to compose with cloud
+ * data, including `beehaven rpc admin:store-rpc '{"storeId":"...","action":"...","input":{...}}'`
+ * to talk to a specific building DO.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, rmSync, statSync, chmodSync, } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import { spawn } from 'child_process';
+const TOOLS_DIR = join(homedir(), '.beehaven', 'tools');
+function ensureToolsDir() {
+    if (!existsSync(TOOLS_DIR))
+        mkdirSync(TOOLS_DIR, { recursive: true });
+}
+function listToolDirs() {
+    ensureToolsDir();
+    try {
+        return readdirSync(TOOLS_DIR).filter((name) => {
+            const p = join(TOOLS_DIR, name);
+            try {
+                return statSync(p).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function findEntry(dir) {
+    const candidates = [
+        { file: 'run.mjs', runtime: 'node' },
+        { file: 'run.js', runtime: 'node' },
+        { file: 'run.ts', runtime: 'node' },
+        { file: 'run.sh', runtime: 'bash' },
+        { file: 'run.py', runtime: 'python' },
+    ];
+    for (const c of candidates) {
+        const p = join(dir, c.file);
+        if (existsSync(p))
+            return { entry: p, runtime: c.runtime };
+    }
+    return null;
+}
+function loadTool(name) {
+    const dir = join(TOOLS_DIR, name);
+    if (!existsSync(dir))
+        return null;
+    let manifest = { name };
+    const manifestPath = join(dir, 'manifest.json');
+    if (existsSync(manifestPath)) {
+        try {
+            manifest = { name, ...JSON.parse(readFileSync(manifestPath, 'utf8')) };
+        }
+        catch (e) {
+            console.warn(`[tool] ${name}/manifest.json parse error: ${e.message}`);
+        }
+    }
+    let entry;
+    let runtime;
+    if (manifest.entry) {
+        entry = join(dir, manifest.entry);
+        runtime =
+            manifest.runtime && manifest.runtime !== 'auto'
+                ? manifest.runtime
+                : entry.endsWith('.sh')
+                    ? 'bash'
+                    : entry.endsWith('.py')
+                        ? 'python'
+                        : 'node';
+    }
+    else {
+        const found = findEntry(dir);
+        if (!found) {
+            console.warn(`[tool] ${name}: no run.{mjs,js,ts,sh,py} found in ${dir}`);
+            return null;
+        }
+        entry = found.entry;
+        runtime = found.runtime;
+    }
+    return { name, dir, entry, runtime, manifest };
+}
+function runTool(tool, input) {
+    return new Promise((resolve) => {
+        const interpreter = tool.runtime === 'node' ? 'node' : tool.runtime === 'python' ? 'python3' : 'bash';
+        const args = tool.runtime === 'node' && tool.entry.endsWith('.ts')
+            ? ['--experimental-strip-types', tool.entry]
+            : [tool.entry];
+        const env = { ...process.env };
+        const timeout = tool.manifest.timeout ?? 60_000;
+        const child = spawn(interpreter, args, {
+            cwd: tool.dir,
+            env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+        }, timeout);
+        child.stdout.on('data', (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({ stdout, stderr, exitCode: code ?? 1 });
+        });
+        // Pass input via stdin
+        if (input !== undefined && input !== null) {
+            child.stdin.write(typeof input === 'string' ? input : JSON.stringify(input));
+        }
+        child.stdin.end();
+    });
+}
+// ── Subcommand handlers ─────────────────────────────────────────────────
+export async function listTools() {
+    ensureToolsDir();
+    const dirs = listToolDirs();
+    if (dirs.length === 0) {
+        console.log(`No tools installed. Create one with:`);
+        console.log(`  beehaven tool create <name>`);
+        return;
+    }
+    console.log(`Tools (${dirs.length}):`);
+    for (const name of dirs) {
+        const tool = loadTool(name);
+        if (!tool) {
+            console.log(`  ${name}  (broken — no entry script)`);
+            continue;
+        }
+        const desc = tool.manifest.description ? `  — ${tool.manifest.description}` : '';
+        console.log(`  ${name}  [${tool.runtime}]${desc}`);
+    }
+    console.log(`\nTools dir: ${TOOLS_DIR}`);
+}
+export async function showTool(name) {
+    if (!name) {
+        console.error('Usage: beehaven tool show <name>');
+        process.exit(1);
+    }
+    const tool = loadTool(name);
+    if (!tool) {
+        console.error(`Tool not found: ${name}`);
+        process.exit(1);
+    }
+    console.log(`Name:        ${tool.name}`);
+    console.log(`Dir:         ${tool.dir}`);
+    console.log(`Entry:       ${tool.entry}`);
+    console.log(`Runtime:     ${tool.runtime}`);
+    if (tool.manifest.description)
+        console.log(`Description: ${tool.manifest.description}`);
+    if (tool.manifest.timeout)
+        console.log(`Timeout:     ${tool.manifest.timeout}ms`);
+    if (tool.manifest.input) {
+        console.log(`Input schema:`);
+        for (const [key, param] of Object.entries(tool.manifest.input)) {
+            const req = param.required === false ? ' (optional)' : '';
+            const desc = param.description ? ` — ${param.description}` : '';
+            console.log(`  ${key}: ${param.type}${req}${desc}`);
+        }
+    }
+}
+export async function runToolCmd(name, inputJson) {
+    if (!name) {
+        console.error('Usage: beehaven tool run <name> [<json-input>]');
+        process.exit(1);
+    }
+    const tool = loadTool(name);
+    if (!tool) {
+        console.error(`Tool not found: ${name}`);
+        process.exit(1);
+    }
+    let input = undefined;
+    if (inputJson) {
+        try {
+            input = JSON.parse(inputJson);
+        }
+        catch (e) {
+            console.error(`Invalid JSON input: ${e.message}`);
+            process.exit(1);
+        }
+    }
+    const result = await runTool(tool, input);
+    if (result.stdout)
+        process.stdout.write(result.stdout);
+    if (result.stderr)
+        process.stderr.write(result.stderr);
+    process.exit(result.exitCode);
+}
+export async function createTool(name) {
+    if (!name) {
+        console.error('Usage: beehaven tool create <name>');
+        process.exit(1);
+    }
+    if (!/^[a-z0-9-]+$/.test(name)) {
+        console.error(`Tool name must be lowercase letters/digits/hyphens only: ${name}`);
+        process.exit(1);
+    }
+    const dir = join(TOOLS_DIR, name);
+    if (existsSync(dir)) {
+        console.error(`Tool already exists: ${name}`);
+        process.exit(1);
+    }
+    mkdirSync(dir, { recursive: true });
+    // Write a starter run.mjs — a working echo with timestamp so the
+    // scaffolded tool is immediately runnable. Replace the `transform`
+    // function with real logic.
+    const runScript = `#!/usr/bin/env node
+/**
+ * ${name} — local tool for Claude / agents.
+ *
+ * Reads JSON from stdin, writes JSON to stdout.
+ * Compose with: beehaven rpc <action> '<json>' for cloud DO calls.
+ */
+let input = '';
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  let payload = {};
+  try { payload = input.trim() ? JSON.parse(input) : {}; } catch (e) {
+    process.stderr.write('Invalid JSON input\\n');
+    process.exit(1);
+  }
+
+  const result = transform(payload);
+  process.stdout.write(JSON.stringify(result, null, 2) + '\\n');
+});
+
+function transform(payload) {
+  // Your tool logic here. Return any JSON-serializable value.
+  // Examples:
+  //   - Call a local binary:  execSync('ffmpeg -i ...')
+  //   - Read a local file:    readFileSync('/tmp/x.json', 'utf-8')
+  //   - Call an API:          await fetch('https://api.example.com/...')
+  return {
+    tool: '${name}',
+    echoed: payload,
+    receivedAt: new Date().toISOString(),
+  };
+}
+`;
+    const runPath = join(dir, 'run.mjs');
+    writeFileSync(runPath, runScript);
+    chmodSync(runPath, 0o755);
+    // Write a starter manifest.json — input map describes payload fields
+    // the tool accepts (for agents + docs). Replace with your real fields.
+    const manifest = {
+        name,
+        description: `Local tool: ${name}`,
+        runtime: 'node',
+        entry: 'run.mjs',
+        timeout: 60_000,
+        input: {
+            message: { type: 'string', description: 'Example input field' },
+        },
+    };
+    writeFileSync(join(dir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n');
+    console.log(`Created: ${dir}`);
+    console.log(`  ├── run.mjs        ← edit this`);
+    console.log(`  └── manifest.json  ← edit this`);
+    console.log('');
+    console.log(`Run with: beehaven tool run ${name} '{}'`);
+}
+export async function removeTool(name) {
+    if (!name) {
+        console.error('Usage: beehaven tool remove <name>');
+        process.exit(1);
+    }
+    const dir = join(TOOLS_DIR, name);
+    if (!existsSync(dir)) {
+        console.error(`Tool not found: ${name}`);
+        process.exit(1);
+    }
+    rmSync(dir, { recursive: true, force: true });
+    console.log(`Removed: ${name}`);
+}

package/dist/commands/trash.js

@@ -0,0 +1,106 @@
+/**
+ * `beehaven trash` / `beehaven restore` — the way BACK from `rm`.
+ *
+ * ⚠⚠ `rm` ARCHIVES, IT DOES NOT DESTROY (CBH2-34). Its help page says so now. What it did not have
+ * was a route back: `beehaven help | grep -iE 'restore|trash|undelete|unarchive'` returned nothing,
+ * so the everyday surface could put a document away and never get it out again. Undoing an `rm`
+ * meant knowing that `document-archive` takes `{ archived: false }` — i.e. reading the worker.
+ *
+ * ⚠ BOTH CAPABILITIES ALREADY EXISTED SERVER-SIDE. `document-list { archived: true }` lists them
+ * (145 on this workspace) and `document-archive { archived: false }` puts one back. This is a
+ * missing DOOR, not a missing feature — so it is two thin verbs over the existing RPCs, never a
+ * second implementation of archiving.
+ *
+ * ⚠ TWO VERBS, NOT ONE. `trash` answers "what did I delete" and `restore` answers "put that back".
+ * Folding restore into `trash --restore <ref>` reads as a flag on a listing, and the thing a person
+ * types when they have just deleted the wrong file is the verb, not the flag.
+ */
+import { agentRpc as rpcOnce } from './workspace.js';
+const c = {
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+};
+/** Matches the rest of the CLI: a page is a page, and the ceiling is stated rather than silent. */
+const LIST_DEFAULT = 50;
+const LIST_MAX = 500;
+function getTimeout(values) {
+    const t = values?.timeout ? parseInt(String(values.timeout), 10) : undefined;
+    return Number.isFinite(t) ? t : undefined;
+}
+function fail(msg, hint) {
+    console.error(`  ${msg}`);
+    if (hint)
+        console.error(c.dim(`  ${hint}`));
+    process.exitCode = 1;
+}
+export async function cmdTrash(rest, values) {
+    const t = getTimeout(values);
+    if (rest[0] === 'help') {
+        console.log(`
+  ${c.cyan('beehaven trash')} — documents ${c.bold('rm')} put away (it archives, it does not destroy)
+
+    trash                       List archived documents  (--limit <n>, max ${LIST_MAX})
+    ${c.dim(`restore <key|title>         Put one back — see \`beehaven restore\``)}
+`);
+        return;
+    }
+    const asked = values?.limit ? parseInt(String(values.limit), 10) : LIST_DEFAULT;
+    const limit = Math.max(1, Math.min(Number.isFinite(asked) ? asked : LIST_DEFAULT, LIST_MAX));
+    // ⚠ SAY SO WHEN THE ASK WAS CLAMPED. A silently reduced limit is the defect this sprint spent
+    //   most of its time on — the caller believes they saw everything.
+    if (Number.isFinite(asked) && asked > LIST_MAX) {
+        console.error(c.dim(`  --limit ${asked} exceeds the ceiling; using ${LIST_MAX}.`));
+    }
+    const res = await rpcOnce('document-list', { limit, archived: true }, t, values);
+    if (!res || res.ok === false)
+        return fail(res?.error || 'could not list the trash', res?.hint);
+    const docs = Array.isArray(res.documents) ? res.documents
+        : Array.isArray(res.notes) ? res.notes
+            : Array.isArray(res.items) ? res.items : [];
+    if (!docs.length) {
+        console.log(c.dim('\n  Nothing archived.\n'));
+        return;
+    }
+    console.log('');
+    for (const d of docs) {
+        const key = String(d.key ?? '');
+        const title = String(d.title ?? '(untitled)');
+        console.log(`  ${c.cyan(key.padEnd(10))} ${title}`);
+    }
+    // ⚠ A FULL PAGE IS NOT THE SAME AS THE WHOLE LIST, and it must not read like one.
+    console.log(c.dim(`\n  ${docs.length} archived`
+        + (docs.length >= limit ? ` — that is the whole page, there may be more (--limit, max ${LIST_MAX})` : '')));
+    console.log(c.dim(`  Put one back:  beehaven restore <key>\n`));
+}
+export async function cmdRestore(rest, values) {
+    const t = getTimeout(values);
+    const ref = (rest[0] ?? '').trim();
+    if (!ref || ref === 'help') {
+        console.log(`
+  ${c.cyan('beehaven restore')} — put an archived document back
+
+    restore <key|title|id>      Un-archive it and return it to \`ls\`
+
+  ${c.dim('See what is there first:  beehaven trash')}
+`);
+        if (!ref)
+            process.exitCode = 1;
+        return;
+    }
+    // ⚠ `archived: false` IS THE UN-ARCHIVE. `document-archive` defaults the field to TRUE when it is
+    //   omitted, so sending the verb with no flag would archive the thing the caller asked to restore.
+    const res = await rpcOnce('document-archive', { id: ref, archived: false }, t, values);
+    if (!res || res.ok === false) {
+        return fail(res?.error || 'could not restore that document', res?.code === 'not-found' ? 'Check the key with `beehaven trash`.' : res?.hint);
+    }
+    const title = String(res.title ?? ref);
+    // ⚠ REPORT THE NO-OP AS A NO-OP. The handler answers `unchanged: true` when the row was already
+    //   live, and printing "restored" there would claim work that did not happen — the exact shape
+    //   this sprint kept finding. Same reason `document-update` reports `unchanged`.
+    if (res.unchanged) {
+        console.log(c.dim(`\n  ${title} was not archived — nothing to do.\n`));
+        return;
+    }
+    console.log(`\n  Restored ${c.bold(title)}${res.key ? c.dim(`  (${res.key})`) : ''}\n`);
+}

package/dist/commands/treehouse.js

@@ -0,0 +1,120 @@
+/**
+ * beehaven treehouse — drive a BYOK room (claude/codex/gemini/pi) from the CLI.
+ *
+ * WHY THIS EXISTS. The four rooms the Clearly desktop app hosts ran behind
+ * `ipcMain.handle('treehouse:send')`, which means the only caller that could ever
+ * reach them was the chat window itself. No CLI, no script, no test, no agent
+ * could ask Gemini for anything — the sole way to send a room a message was for a
+ * human to type it. That is a strange shape for four agents that exist to be
+ * automated, and it is why this verb exists.
+ *
+ * DEVELOPER MODE ONLY, and deliberately so: a turn here spends the USER'S OWN
+ * Claude/Codex/Gemini subscription and runs with their ~/Clearly filesystem. The
+ * desktop app only mounts the route when developer mode is on (main.ts →
+ * isDeveloperModeEnabled), so on a consumer build this 404s — the endpoint isn't
+ * there to reject you.
+ *
+ * TRANSPORT. Loopback HTTP to the Electron main process (127.0.0.1:3456), the same
+ * bridge `browser-rpc.ts` already exposes for tab control, authorised with the
+ * token at ~/.beehaven/browser-token. NOT the daemon: the daemon is a different
+ * process and has no treehouse — it was never the thing holding these sessions.
+ */
+import { readFileSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { color as c, spinner } from '../spinner.js';
+const DEFAULT_PORT = 3456;
+const TOKEN_PATH = join(homedir(), '.beehaven', 'browser-token');
+/** A room turn can build a whole page — minutes, not seconds. Don't cut it off. */
+const DEFAULT_TIMEOUT_MS = 15 * 60_000;
+const ROOMS = ['claude', 'codex', 'gemini', 'pi'];
+function readToken() {
+    try {
+        return readFileSync(TOKEN_PATH, 'utf8').trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * `beehaven treehouse <room> "<message>"` — send one turn, print the reply.
+ *
+ * Synchronous: the desktop holds the connection until the agent's turn finishes,
+ * then returns the whole transcript at once. There is no streaming here on
+ * purpose — one JSON reply is what a script can actually consume, and the tool
+ * lines come back in `events` so `--verbose` can show the work.
+ */
+export async function treehouse(args, opts = {}) {
+    const room = (args[0] || '').trim().toLowerCase();
+    const message = args.slice(1).join(' ').trim();
+    if (!room || !message) {
+        console.error(`Usage: beehaven treehouse <${ROOMS.join('|')}> "<message>"`);
+        console.error('       beehaven treehouse gemini "design a landing page for a hair salon"');
+        process.exit(1);
+    }
+    if (!ROOMS.includes(room)) {
+        // Name the valid set rather than just refusing — the same reason
+        // canvas.create-node's error lists its types.
+        console.error(`Unknown room '${room}'. Rooms: ${ROOMS.join(', ')}`);
+        process.exit(1);
+    }
+    const token = readToken();
+    if (!token) {
+        console.error(c.red('✗') + ` no browser token at ${TOKEN_PATH}`);
+        console.error('  The Clearly desktop app writes it on launch — open the app, then retry.');
+        process.exit(1);
+    }
+    const port = opts.port ?? DEFAULT_PORT;
+    const s = spinner(`${room} is thinking…`).start();
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    let body;
+    try {
+        const r = await fetch(`http://127.0.0.1:${port}/treehouse`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-Clearly-Browser-Token': token },
+            body: JSON.stringify({ agent: room, message, model: opts.model, sessionId: opts.session }),
+            signal: ctl.signal,
+        });
+        body = await r.json().catch(() => ({ error: `HTTP ${r.status}` }));
+        if (r.status === 404) {
+            s.fail('the treehouse bridge is developer-mode only');
+            console.error('  Turn it on: HIVE_DEV_MODE=1 in the app\'s environment, or the tray\'s Settings entry, then relaunch.');
+            process.exit(1);
+        }
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if (err?.name === 'AbortError') {
+            s.fail(`timed out after ${(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS) / 1000}s`);
+            process.exit(1);
+        }
+        s.fail(`cannot reach the desktop app on 127.0.0.1:${port} — is it running?`);
+        process.exit(1);
+    }
+    clearTimeout(timer);
+    const events = body.events ?? [];
+    const tools = events.filter((e) => e.kind === 'tool_call' || e.kind === 'tool_result');
+    s.succeed(`${room} · ${tools.length} tool call(s)`);
+    if (opts.verbose) {
+        for (const e of events) {
+            if (e.kind === 'tool_call')
+                console.log(c.dim(`  → ${e.tool}${e.detail ? ' ' + e.detail : ''}`));
+            else if (e.kind === 'tool_result')
+                console.log(c.dim(`  ${e.ok ? '✓' : '✗'} ${e.tool}${e.preview ? ' ' + e.preview : ''}`));
+            else if (e.kind === 'error')
+                console.log(c.red(`  ✗ ${e.message}`));
+        }
+        if (events.length)
+            console.log('');
+    }
+    // An error is worth surfacing even when some text came back: a room that hit an
+    // auth wall halfway still returns prose, and printing only the prose would read
+    // as success.
+    if (body.error)
+        console.error(c.red('✗ ') + body.error);
+    if (body.finalText)
+        console.log(body.finalText);
+    if (!body.ok)
+        process.exit(1);
+}