arcroom 0.0.1-beta

package/dist/index.js

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { codeSetup, forgetBlind, gitRoot, repoKey, writeSetup } from './blind.js';
+import { daemon } from './daemon.js';
+import { doctor, print } from './doctor.js';
+import { approveChecks, checksHash, isApproved, loadChecks, readApprovals } from './done.js';
+import { syncTree } from './tree.js';
+import { api, ARCROOM_HOME, loadConfig, setOff } from './home.js';
+import { hook } from './hook.js';
+import { init } from './init.js';
+import { mcp } from './mcp.js';
+import { readStats, statusText } from './signs.js';
+import { sessionUsage, tokensOf } from './usage.js';
+const [cmd, ...args] = process.argv.slice(2);
+if (cmd === 'init')
+    await init(args);
+else if (cmd === 'hook')
+    await hook();
+else if (cmd === 'daemon')
+    await daemon();
+else if (cmd === 'mcp')
+    await mcp();
+else if (cmd === 'doctor') {
+    if (!print(await doctor()))
+        process.exitCode = 1;
+}
+else if (cmd === 'whoami') {
+    const me = await api(loadConfig(), '/v1/me');
+    console.log(`${me.email ?? 'shared key (no person)'} in workspace "${me.workspace}" (key ${me.key_label ?? 'unlabelled'}, made ${me.key_created_at})`);
+}
+else if (cmd === 'status') {
+    // Claude Code status line: gets the session JSON on stdin, prints one line. Must be fast and never fail.
+    let input = '';
+    for await (const chunk of process.stdin)
+        input += chunk;
+    let session = '';
+    let used = 0;
+    try {
+        const raw = JSON.parse(input);
+        session = raw.session_id ?? '';
+        if (session)
+            used = tokensOf(sessionUsage(session, raw.transcript_path));
+    }
+    catch { }
+    console.log(statusText(session ? readStats(session) : readStats('none'), used));
+}
+else if (cmd === 'rule') {
+    // arcroom rule [--tag <tag>] [--max-hits N] [--idle-days D]   (no limits = remove the rule)
+    const opt = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+    const num = (name) => (opt(name) === undefined ? null : Number(opt(name)));
+    const res = await api(loadConfig(), '/v1/rules', { tag: opt('--tag') ?? null, max_hits: num('--max-hits'), idle_days: num('--idle-days') });
+    console.log(res.rule ? `rule set: ${JSON.stringify(res.rule)}` : 'rule removed');
+}
+else if (cmd === 'wrong' || cmd === 'share') {
+    // arcroom wrong [memo id] [reason]: the memory just handed over (or the one named) was wrong
+    // arcroom share [memo id]: share your new steps with the team before their second pass
+    const lastFile = join(ARCROOM_HOME, 'last-recall.json');
+    const named = /^[0-9a-f-]{36}$/i.test(args[0] ?? '') ? args.shift() : undefined;
+    const last = named ? { memo_id: named, intent: named } : existsSync(lastFile) ? JSON.parse(readFileSync(lastFile, 'utf8')) : undefined;
+    if (!last)
+        console.log('no memory was handed over yet; pass its id (see the Memory page)');
+    else if (cmd === 'share') {
+        await api(loadConfig(), '/v1/memory/share', { memo_id: last.memo_id });
+        console.log(`shared with the team: ${last.intent}`);
+    }
+    else {
+        const r = await api(loadConfig(), '/v1/memory/wrong', { memo_id: last.memo_id, reason: args.join(' ') || null });
+        const what = r.deleted
+            ? 'deleted (2 people said wrong)'
+            : r.steps_broken
+                ? 'steps broken, the last good version takes over'
+                : r.answer_thrown_away
+                    ? 'answer thrown away'
+                    : `noted (${r.reports} of 2 reports delete it)`;
+        console.log(`reported wrong: ${last.intent} · ${what}`);
+    }
+}
+else if (cmd === 'code') {
+    // arcroom code [status|sync|on|off]: the Code wing for the repo you are in (paths and git hashes, never code)
+    const s = codeSetup(process.cwd());
+    const sub = args[0] ?? 'status';
+    if (!s)
+        console.log('not inside a git repo');
+    else if (sub === 'off' || sub === 'on') {
+        writeSetup(s.root, { code: sub === 'off' ? 'off' : undefined });
+        forgetBlind(s.root); // the person here chose it: this laptop stops holding the repo to Blind
+        console.log(`Code wing ${sub} for ${s.root} (commit .arcroom.json so the team gets the same setting)`);
+    }
+    else if (s.mode !== 'standard')
+        console.log(`Code wing is ${s.mode} for this repo${s.mode === 'off' ? ': arcroom code on turns it on' : ''}`);
+    else if (sub === 'sync') {
+        const r = await syncTree(loadConfig(), s);
+        console.log(`sent ${r.nodes} folders and files (repo ${repoKey(s)})`);
+    }
+    else {
+        const repos = await api(loadConfig(), '/v1/code/tree');
+        const me = repos.find((x) => x.repo === repoKey(s));
+        console.log(me
+            ? `${me.repo}: ${me.folders} folders, ${me.files} files, ${me.editing} agent(s) editing now, default branch ${me.default_branch}`
+            : 'this repo has not sent its tree yet: arcroom code sync');
+    }
+}
+else if (cmd === 'off' || cmd === 'on') {
+    // arcroom off | on: ArcRoom for the repo you are in, on this laptop only (nothing traced or sent while off)
+    const root = gitRoot(process.cwd()) ?? process.cwd();
+    setOff(root, cmd === 'off');
+    console.log(cmd === 'off' ? `ArcRoom is off for ${root}: nothing from it is recorded or sent` : `ArcRoom is on again for ${root}`);
+}
+else if (cmd === 'checks') {
+    // arcroom checks [approve <code>]: the done-checks in this folder's .arcroom.json, and whether they may run.
+    // Approving needs the code printed next to the exact commands shown, so a later change to the file is never approved.
+    const checks = loadChecks(process.cwd());
+    const list = checks.map((c) => `  ${JSON.stringify(c)}`).join('\n');
+    const code = checksHash(checks).slice(0, 8);
+    if (!checks.length)
+        console.log('no doneChecks in .arcroom.json here');
+    else if (args[0] === 'approve' && !process.stdin.isTTY)
+        // an agent's shell has no terminal: approving stays a step the person takes themselves (N14)
+        console.log('not approved: run arcroom checks approve yourself, in a terminal (not through an agent)');
+    else if (args[0] === 'approve') {
+        const done = approveChecks(process.cwd(), args[1] ?? '');
+        console.log(done ? `approved for ${process.cwd()} (after editing files, the agent is asked to run them with its Bash tool before it stops):\n${list}` : 'not approved: run arcroom checks, read the commands, then arcroom checks approve <the code it prints>');
+    }
+    else if (isApproved(process.cwd(), checks, readApprovals()))
+        console.log(`${list}\napproved`);
+    else
+        console.log(`${list}\nnot approved: once approved, the agent is asked to run these with its Bash tool after it edits files (each run goes through its permission prompt).
+To allow them: arcroom checks approve ${code}`);
+}
+else if (cmd === 'decide') {
+    // arcroom decide "<what was chosen>" [--why ...] [--over "A, B"] [--context ...] [--by ...] [--source <url>] [--replaces <memo id>]
+    const opt = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+    const text = args[0];
+    if (!text || text.startsWith('--'))
+        console.log('usage: arcroom decide "<what was chosen>" [--why ...] [--over "A, B"] [--context ...] [--by ...] [--source <url>] [--replaces <memo id>]');
+    else {
+        const over = opt('--over')?.split(',').map((o) => o.trim()).filter(Boolean);
+        const url = opt('--source');
+        const r = await api(loadConfig(), '/v1/memory/remember', {
+            kind: 'decision',
+            text,
+            why: opt('--why') ?? null,
+            ...(over ? { options: [text, ...over] } : {}),
+            ...(opt('--context') ? { context: opt('--context') } : {}),
+            ...(opt('--by') ? { decided_by: opt('--by') } : {}),
+            ...(url ? { source: { kind: /\/pull\//.test(url) ? 'pr' : /\/issues\//.test(url) ? 'issue' : 'other', url } } : {}),
+            ...(opt('--replaces') ? { replaces: opt('--replaces') } : {}),
+        });
+        console.log(`${r.saved ? 'decision saved' : 'decision already saved; detail updated'}${r.replaced ? ', the earlier one is replaced' : ''} (${r.memo_id})`);
+    }
+}
+else
+    console.log('usage: arcroom init [--project <id>] (asks for the key; or set ARCROOM_API_KEY) [--url <arcroom api url>] | arcroom whoami | arcroom doctor | arcroom rule [--tag t] [--max-hits n] [--idle-days d] | arcroom wrong [memo id] [reason] | arcroom share [memo id] | arcroom decide "<choice>" [--why ...] [--over "A, B"] | arcroom code [status|sync|on|off] | arcroom checks [approve] | arcroom off | arcroom on');

package/dist/init.js

@@ -0,0 +1,190 @@
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import { AGENTS, CURSOR_HOOKS, opencodePlugin } from './agents.js';
+import { stopDaemon } from './daemon.js';
+import { onPath } from './git.js';
+import { apiUrl, ARCROOM_HOME, DEFAULT_URL } from './home.js';
+const EVENTS = ['SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop', 'SessionEnd'];
+const TOOL_EVENTS = new Set(['PreToolUse', 'PostToolUse']);
+const MARK = '.arcroom/runtime'; // identifies our hook entries in a settings file
+// node by its full path, never the word "node": an agent starting a hook inside a repo must not run a node.exe planted there
+const NODE = process.execPath;
+const nodeCmd = JSON.stringify(NODE);
+/** Puts ArcRoom's hook on every event: replaces an earlier ArcRoom entry, keeps everyone else's hooks. */
+export function withArcroomHooks(settings, command, anyTool = '*') {
+    const hooks = { ...settings.hooks };
+    for (const event of EVENTS) {
+        const others = (hooks[event] ?? []).filter((g) => !g.hooks.some((h) => h.command.includes(MARK)));
+        const ours = { hooks: [{ type: 'command', command }] };
+        if (TOOL_EVENTS.has(event))
+            ours.matcher = anyTool;
+        hooks[event] = [...others, ours];
+    }
+    return { ...settings, hooks };
+}
+/** Cursor's .cursor/hooks.json with ArcRoom on its six lifecycle events, keeping everyone else's hooks. */
+export function withCursorHooks(current, command) {
+    const hooks = { ...current.hooks };
+    for (const event of CURSOR_HOOKS)
+        hooks[event] = [...(hooks[event] ?? []).filter((h) => !h.command.includes(MARK)), { command }];
+    return { ...current, version: current.version ?? 1, hooks };
+}
+/** Codex's config.toml with an [mcp_servers.arcroom] table (an earlier one replaced, everything else kept). */
+export function withCodexMcp(toml, entry, node = NODE) {
+    const others = toml.replace(/\n?\[mcp_servers\.arcroom\][\s\S]*?(?=\n\[|$)/, '').trimEnd();
+    const ours = `[mcp_servers.arcroom]\ncommand = ${JSON.stringify(node)}\nargs = [${JSON.stringify(entry)}, "mcp"]\n`;
+    return (others ? `${others}\n\n` : '') + ours;
+}
+const readJson = (file) => (existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {});
+const writeJson = (file, value) => {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+};
+export async function init(args) {
+    const arg = (name) => (args.includes(name) ? args[args.indexOf(name) + 1] : undefined);
+    const agent = (arg('--agent') ?? 'claude');
+    if (!AGENTS.includes(agent)) {
+        console.error(`--agent takes one of: ${AGENTS.join(', ')}`);
+        process.exit(1);
+    }
+    const configFile = join(ARCROOM_HOME, 'config.json');
+    const saved = existsSync(configFile) ? JSON.parse(readFileSync(configFile, 'utf8')) : {}; // re-running init reuses saved values
+    let key = arg('--key') ?? process.env.ARCROOM_API_KEY ?? saved.apiKey;
+    if (arg('--key'))
+        console.error('Note: a key typed on the command line stays in your shell history. Next time run arcroom init and paste it when asked, or set ARCROOM_API_KEY.');
+    const url = arg('--url') ?? saved.url ?? DEFAULT_URL;
+    try {
+        apiUrl(url);
+    }
+    catch (e) {
+        console.error(`${e.message}.`);
+        process.exit(1);
+    }
+    if (!key) {
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        key = (await rl.question('ArcRoom API key: ')).trim();
+        rl.close();
+    }
+    if (!key?.startsWith('ark_')) {
+        console.error('That is not an ArcRoom key (it starts with ark_).');
+        process.exit(1);
+    }
+    // 1. Remember the key for this machine.
+    mkdirSync(ARCROOM_HOME, { recursive: true, mode: 0o700 });
+    writeFileSync(configFile, JSON.stringify({ apiKey: key, url }, null, 2), { mode: 0o600 });
+    stopDaemon(); // the next hook event starts the updated one
+    // 2. Copy the hook runtime to a stable place (npx's own copy is temporary).
+    const runtime = join(ARCROOM_HOME, 'runtime');
+    cpSync(dirname(fileURLToPath(import.meta.url)), runtime, {
+        recursive: true,
+        filter: (src) => !src.includes('.test.'),
+    });
+    writeFileSync(join(runtime, 'package.json'), '{ "type": "module" }\n');
+    // 3. Wire Claude Code's hooks in this project to it, and pre-approve our MCP server (local file: paths are per machine).
+    const entry = join(runtime, 'index.js').replaceAll('\\', '/');
+    const file = join(process.cwd(), '.claude', 'settings.local.json');
+    const current = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+    // The website's project for this folder (from "Connect a machine"); re-running init keeps the one set before.
+    const project = arg('--project') ?? JSON.stringify(current.hooks ?? {}).match(/--project ([0-9a-f-]{36})/)?.[1];
+    if (project && !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(project)) {
+        console.error('--project takes the project id the website shows.');
+        process.exit(1);
+    }
+    if (agent !== 'claude')
+        return initOther(agent, entry, project);
+    const settings = withArcroomHooks(current, `${nodeCmd} "${entry}" hook${project ? ` --project ${project}` : ''}`);
+    // never pre-approve a server from the shared .mcp.json by name: a pull request could change what that name runs
+    const approved = (current.enabledMcpjsonServers ?? []).filter((n) => n !== 'arcroom');
+    if (approved.length)
+        settings.enabledMcpjsonServers = approved;
+    else
+        delete settings.enabledMcpjsonServers;
+    // Live badge at the bottom of Claude Code ("ArcRoom · live · 2 reused"), unless the project has its own status line.
+    const theirs = current.statusLine;
+    if (!theirs || theirs.command?.includes(MARK))
+        settings.statusLine = { type: 'command', command: `${nodeCmd} "${entry}" status`, padding: 0 };
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+    // 4. Register the MCP server (find_task / claim_task / complete_task) for this project: in Claude Code's local scope
+    // (this person, this folder) rather than the shared .mcp.json. An entry an earlier init wrote there is taken out.
+    const mcpFile = join(process.cwd(), '.mcp.json');
+    const mcpConfig = existsSync(mcpFile) ? JSON.parse(readFileSync(mcpFile, 'utf8')) : {};
+    const local = addLocalMcp(entry);
+    if (local) {
+        if (String(mcpConfig.mcpServers?.arcroom?.args?.[0] ?? '').replaceAll('\\', '/').includes(MARK)) {
+            delete mcpConfig.mcpServers.arcroom;
+            writeFileSync(mcpFile, JSON.stringify(mcpConfig, null, 2) + '\n');
+        }
+    }
+    else {
+        // no claude command found: the shared file, which Claude Code asks about before running
+        mcpConfig.mcpServers = { ...mcpConfig.mcpServers, arcroom: { command: NODE, args: [entry, 'mcp'] } };
+        writeFileSync(mcpFile, JSON.stringify(mcpConfig, null, 2) + '\n');
+    }
+    console.log(`ArcRoom is on for this project.
+  key      ${join(ARCROOM_HOME, 'config.json')}
+  hooks    ${file}
+  tools    ${local ? 'Claude Code local scope (claude mcp list)' : `${mcpFile} (approve "arcroom" when Claude Code asks)`}
+Start a new Claude Code session here to begin capturing runs.`);
+}
+/** `claude mcp add --scope local arcroom`: false when the claude command is not on PATH or the add failed. */
+function addLocalMcp(entry) {
+    const claude = onPath(process.platform === 'win32' ? ['claude.exe', 'claude.cmd'] : ['claude']);
+    if (!claude)
+        return false;
+    const run = (args) => claude.endsWith('.cmd') // an npm install on Windows: a batch file runs through cmd, every argument quoted
+        ? spawnSync(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${[claude, ...args].map((a) => `"${a}"`).join(' ')}"`], {
+            windowsVerbatimArguments: true,
+            encoding: 'utf8',
+        })
+        : spawnSync(claude, args, { encoding: 'utf8' });
+    run(['mcp', 'remove', '--scope', 'local', 'arcroom']); // none yet is fine
+    return run(['mcp', 'add', '--scope', 'local', 'arcroom', '--', NODE, entry, 'mcp']).status === 0;
+}
+/** Steps 3 and 4 for Codex, Cursor and OpenCode: their own hook and MCP files, in this project. */
+function initOther(agent, entry, project) {
+    const cwd = process.cwd();
+    const command = `${nodeCmd} "${entry}" hook --agent ${agent}${project ? ` --project ${project}` : ''}`;
+    const written = [];
+    if (agent === 'codex') {
+        // same events and payloads as Claude Code; its matchers are regular expressions
+        const hooksFile = join(cwd, '.codex', 'hooks.json');
+        writeJson(hooksFile, withArcroomHooks(readJson(hooksFile), command, '.*'));
+        const configFile = join(cwd, '.codex', 'config.toml');
+        writeFileSync(configFile, withCodexMcp(existsSync(configFile) ? readFileSync(configFile, 'utf8') : '', entry));
+        written.push(hooksFile, configFile);
+    }
+    else if (agent === 'cursor') {
+        const hooksFile = join(cwd, '.cursor', 'hooks.json');
+        writeJson(hooksFile, withCursorHooks(readJson(hooksFile), command));
+        const mcpFile = join(cwd, '.cursor', 'mcp.json');
+        const mcp = readJson(mcpFile);
+        writeJson(mcpFile, { ...mcp, mcpServers: { ...mcp.mcpServers, arcroom: { type: 'stdio', command: NODE, args: [entry, 'mcp'] } } });
+        written.push(hooksFile, mcpFile);
+    }
+    else {
+        const configFile = join(cwd, 'opencode.json');
+        const config = readJson(configFile);
+        writeJson(configFile, {
+            $schema: 'https://opencode.ai/config.json',
+            ...config,
+            mcp: { ...config.mcp, arcroom: { type: 'local', command: [NODE, entry, 'mcp'], enabled: true } },
+        });
+        const pluginFile = join(cwd, '.opencode', 'plugins', 'arcroom.js');
+        mkdirSync(dirname(pluginFile), { recursive: true });
+        writeFileSync(pluginFile, opencodePlugin(entry, project, NODE));
+        written.push(configFile, pluginFile);
+    }
+    const next = {
+        codex: 'Trust this project in Codex, then approve the ArcRoom hooks once with /hooks.',
+        cursor: 'Restart Cursor. Cursor adds context only after a tool call, so team memory reaches the agent on its first tool use.',
+        opencode: "Restart OpenCode. Experimental: per-prompt recall rides OpenCode's experimental system-prompt hook, so it may change with OpenCode.",
+    };
+    console.log(`ArcRoom is on for ${agent} in this project.
+  key      ${join(ARCROOM_HOME, 'config.json')}
+${written.map((f) => `  wrote    ${f}`).join('\n')}
+${next[agent]}`);
+}

package/dist/logo.js

@@ -0,0 +1,13 @@
+// The ArcRoom shared-wall logo as MCP icons (spec: icons on serverInfo and tools; PNG must be supported, SVG should).
+// `theme` = the background the icon is meant for: dark stroke on light backgrounds, light stroke on dark ones.
+// PNGs are 64x64, rendered from the same paths as the website logo.
+const svg = (stroke) => 'data:image/svg+xml;base64,' +
+    Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="8 10 104 104"><path d="M18 104 V58 A21 21 0 0 1 60 58 A21 21 0 0 1 102 58 V104" fill="none" stroke="${stroke}" stroke-width="14" stroke-linejoin="round"/><path d="M60 60 V104" fill="none" stroke="#FF5B2E" stroke-width="14"/></svg>`).toString('base64');
+const PNG_LIGHT_BG = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAADqElEQVR4Aexau1LbQBS9K89Qg2Q8KVKYLn0KykCTfEbgSzBfAk3o06Q1+YWkSoXTZQw2LtIx1uYeWZLXQt5dWbKlWKvZa+/jPs+eXTyDPGr54wBoOQHIMcAxoOUIuCPQcgK4S9AdAXcEWo5AqSMQBMcXED/o3aTi9658lsNu9+zw8E2/CnwDjgOf/hbiFAYg4GSOguOhH/SkJHED4SIvUhE0IBZPekOvEz5AN2CbomDAxg96DyxRHPgkosrjWAMQcBE+J4SCBYkzsnwE68IGYATswwQEdPwYXA5hzSAlzjCwiMO+o2YEAAljF1EEW1gnxLqvGnwwEEP4zC5iTomTXS4y7iOO6Mxv4DNrmB1rAcA5RsJAN2tYYtxnnw/wnfhAH3NVxoEv9pkLdhIX32sBiJLic8xKpXad7XObx75xsYGu6OcqlZ9cgK25jHMBAHW2mNSyLL4sQdflxHZ6OibkAoDzs51UavMKJuQeh1cAgJY4PxumOtrQbhdmfc8LP2cDrQAA6sd/b7N6uWNJ8l6QvAzn3sl0MhYsJ6EIzzHHBrcsVbVb+FTiCMQhSQPkYB2Ej1xUo2KwAgCflStlTdtFQs+Tx/PJ5PF2NvuT7vzs6ekecwzGJXTYSbrG/cINhcIXfGbjTKfja+QAINixVZwsC1IAYmTwS4t9adsIO4GEtFq8CB3WPeeuVXKsp7YRFy4AqDqZ1wcQ1nEEDeJaI1cpAFlkotWcD96RS3UnclRWpqBrnZxiGdsoM/ou4jDjrvVai9VOZ57+kk0BWCwZPvnM2exI1guSY5ra3wmIoxyrrL91YzCO4wzWrSfzksSHpL8EQJCR/qAabfjEtjZHYRTrbhTJ0jaXAaZffDbJm5K+NylIklXEMflIa40YoF4KmgSNyWtsrZeEFFXEMfpIao4AsMpOkglVMj18SX036YReaNQx+eB7wDpXewCMUc0Kd+/9v6dHB6ST509vX8yeqtPYKQAfuwcv30590gnJebe68ohMvnYKgCmZOtYdAHWg3qSYjgFN2o06cnEMqAP1JsV0DGjSbtSRi2NAHag3KaZjQJN2o45cHAPqQL1JMfeOAUXBdQAURWzf9B0D9m1Hi9bjGFAUsX3TdwzYtx0tWo9jgIIY/p+2VoSQvxXdMt1fbKwTXq6kra2FvY+idxa4EzEAg+lkjBed1kr08gEblGni7udX8eXHO62wTpkYsMU7AqZ6oAeJAECnreIAaOvOJ3U7BiRI/K/fZfP+BwAA//+UjP8CAAAABklEQVQDAAelm5CWvAzJAAAAAElFTkSuQmCC';
+const PNG_DARK_BG = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAADqUlEQVR4AexbTXLaMBR+gk2YIXSc9ADJrrdoOEnDroseoLuQfZfdk0277wlINz1Am00XndADJEzBMyxSUL8nWx4wxpLAxC6WRs+2pPf76ZPDTKBBNW8egJoTgDwDPANqjoA/AjUngH8J+iPgj0DNEdjpCIST8WUkD4NwEsn0z8OVkun4YjYenxWBL8dgnzoG33msZMc4zgBwMuHkcQiRRHIQibgkikQI0Vci5XDelPfQg+740hWMUIH7yPYqDvvUMfjOYyU7xrEGQCcUFUwXZN+gKwcRGGYg4jiqaIRwYZCO4wS4EQDeuRA7HhfukhDyT3cFxJB9pld4bilOetlljBxVnAH7TBumx7kATHG+sHNDGAFdXIvpZ/B5z761O37mOYyLjHMBn5lgI07SNwLASQmcL2gCUVwL7uybX2Ihzjo/F+xeu1Ng5zEhEwA22GNSOjnil1h8tJK5fTzkMSETABjg7b6PVErzyUzIPA5rADAtkea2Z3EE26r2s7+NxZt0cisAKOrj73haKWd8SyR6zbk4b3dOBORcCtHlOVD7hgprEr5W4giOI6XsIwRywNWiC9Q2G69+OFsBYN5cXFn4iVVEDwV3253gphUEyc4fHwe3PNfunPYI4BBRskZbNC6UfbHPdJzjF6fX7c5JV0ZAWMVJsyABYKaQEfhEZ8xyFO14gF3J1+WkoQtGkFVytNpGKE4woKvT6yMGwjaOSLEgASCNzHqYaAY70mst7Xg0u/nKurbJLXuJbZancp85DpG4Jos2b1LyjksAIIsmQTWbHUm7agEw2BoZo+2g22cbPba9M+PY1qy/eK11EgCEMNOfqaYNXe+xrc1RGMW6riGUvp2tyGSA6ROfTfIqic0XafPGLiAOmXwktSoGzNQLkAzNKnmDD/OylEXEMfuYxTUrAMxpEUlJJlTJ3BpfjToNCx2DE5dcrQEwxLRaPvr4Pmz+uqM8ab/tPlk5K0jpWQFo3n17OvrwjvKE5PxlQbUpN6bLswJgSqaMdQ9AGahXKaZnQJV2o4xcPAPKQL1KMT0DqrQbZeTiGVAG6lWK6RlQpd0oIxfPgDJQr1LMg2OAK7geAFfEDk3fM+DQdtS1Hs8AV8QOTd8z4NB21LUez4AlxPh/fxtFiMbvJd1dHn/COE+wXEjfWAu8j1pBwOvRL0Z40O6c8BedciSw/oIDAmR28fnHF/Hp+6tcgU6mscMkf0fAVI9254+ARqKud8+Auu68rvu/Z4AuZNv7PwAAAP//+WPCTQAAAAZJREFUAwCt5dOQ/FC9ZQAAAABJRU5ErkJggg==';
+export const ICONS = [
+    { src: PNG_LIGHT_BG, mimeType: 'image/png', sizes: ['64x64'], theme: 'light' },
+    { src: PNG_DARK_BG, mimeType: 'image/png', sizes: ['64x64'], theme: 'dark' },
+    { src: svg('#121316'), mimeType: 'image/svg+xml', sizes: ['any'], theme: 'light' },
+    { src: svg('#F4F2EE'), mimeType: 'image/svg+xml', sizes: ['any'], theme: 'dark' },
+];

package/dist/lookup.js

@@ -0,0 +1,98 @@
+import { createHmac, randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { join } from 'node:path';
+import { codeContext } from './code.js';
+import { ARCROOM_HOME, loadConfig } from './home.js';
+import { recall } from './recall.js';
+import { projectOf } from './session.js';
+const PORT_FILE = join(ARCROOM_HOME, 'daemon.port'); // "<port> <secret>"
+// A hung API costs the full wait on every prompt. After a failure, prompts skip the lookup for a minute:
+// an outage then costs that wait once a minute, not every prompt.
+const DOWN = join(ARCROOM_HOME, 'api-down');
+const COOL_MS = 60_000;
+const OFFLINE = { recall: {}, offline: true };
+const markDown = () => {
+    try {
+        writeFileSync(DOWN, new Date().toISOString(), { mode: 0o600 });
+    }
+    catch {
+        // no cool-down this time: the next prompt waits again
+    }
+};
+const recentlyDown = () => {
+    try {
+        return Date.now() - statSync(DOWN).mtimeMs < COOL_MS;
+    }
+    catch {
+        return false;
+    }
+};
+// Inside the hook's 3 s wait (lookupFast): the lookup itself must finish well before it, or its answer arrives after
+// the hook gave up and every prompt reads "memory offline" (seen from India to the Ashburn API: 3.1 s each time).
+const RECALL_MS = 2200;
+const CODE_MS = 1200; // the code map is the extra: it never holds recall up
+/** Recall and the code map for one prompt, at the same time; a failure of either is an empty answer, never an error. */
+export async function lookup(prompt, cwd, session, given) {
+    const [r, code] = await Promise.all([
+        recall(prompt, cwd, projectOf(cwd), given, RECALL_MS).catch(() => undefined),
+        codeContext(loadConfig(), cwd, session, prompt, CODE_MS).catch(() => undefined),
+    ]);
+    if (!r)
+        markDown();
+    return { recall: r ?? {}, ...(code ? { code } : {}), ...(r ? {} : { offline: true }) };
+}
+/** The warm daemon's lookup; the hook's own when no daemon answers. A daemon that is there but slow is not asked twice. */
+export async function lookupFast(prompt, cwd, session, given, timeoutMs = 3000) {
+    if (recentlyDown())
+        return OFFLINE;
+    const [port, secret] = existsSync(PORT_FILE) ? readFileSync(PORT_FILE, 'utf8').trim().split(' ') : [];
+    if (!port)
+        return lookup(prompt, cwd, session, given);
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/lookup`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', 'x-arcroom': secret },
+            body: JSON.stringify({ prompt, cwd, session, given: [...given] }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            throw new Error(`daemon ${res.status}`);
+        // only our daemon knows the secret: an answer without its signature (whatever took the port after the daemon
+        // stopped) is never handed to the agent (L8)
+        const text = await res.text();
+        if (res.headers.get('x-arcroom-proof') !== proof(secret, text))
+            throw new Error('daemon answer not signed');
+        return JSON.parse(text);
+    }
+    catch (err) {
+        if (err.name === 'TimeoutError') {
+            markDown();
+            return OFFLINE; // the time is spent: no hand-over this prompt
+        }
+        return lookup(prompt, cwd, session, given); // no daemon on that port (it stopped): do it here
+    }
+}
+/** The daemon's side: serves lookups on a free port of 127.0.0.1 and writes the port and a fresh secret. */
+export function serveLookups() {
+    const secret = randomBytes(16).toString('hex');
+    const server = createServer(async (req, res) => {
+        try {
+            if (req.method !== 'POST' || req.url !== '/lookup' || req.headers['x-arcroom'] !== secret)
+                return void res.writeHead(404).end();
+            let body = '';
+            for await (const chunk of req)
+                body += chunk;
+            const a = JSON.parse(body);
+            const out = JSON.stringify(await lookup(String(a.prompt ?? ''), String(a.cwd ?? ''), String(a.session ?? ''), new Set(a.given ?? [])));
+            res.writeHead(200, { 'content-type': 'application/json', 'x-arcroom-proof': proof(secret, out) }).end(out);
+        }
+        catch (err) {
+            res.writeHead(500).end(String(err));
+        }
+    });
+    server.listen(0, '127.0.0.1', () => writeFileSync(PORT_FILE, `${server.address().port} ${secret}`, { mode: 0o600 }));
+    process.on('exit', () => rmSync(PORT_FILE, { force: true })); // a stopped daemon leaves no port to take over
+}
+/** The daemon's signature on an answer: an HMAC with the secret only it and this user can read. */
+export const proof = (secret, body) => createHmac('sha256', secret).update(body).digest('hex');

package/dist/loop.js

@@ -0,0 +1,35 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ARCROOM_HOME } from './home.js';
+export const LOOP_LIMIT = 3; // the 3rd identical call in a row is blocked
+const stable = (v) => Array.isArray(v)
+    ? `[${v.map(stable).join(',')}]`
+    : v && typeof v === 'object'
+        ? `{${Object.keys(v).sort().map((k) => `${JSON.stringify(k)}:${stable(v[k])}`).join(',')}}`
+        : JSON.stringify(v) ?? 'null';
+/** Same tool + same input (in any key order) = same signature. */
+export function signature(tool, input) {
+    return createHash('sha256').update(`${tool}\0${stable(input)}`).digest('hex').slice(0, 16);
+}
+/** True when the last LOOP_LIMIT-1 calls were all this same call. */
+export function isLoop(recent, sig) {
+    return recent.length >= LOOP_LIMIT - 1 && recent.slice(-(LOOP_LIMIT - 1)).every((s) => s === sig);
+}
+/** Path of a per-session state file under ~/.arcroom/sessions. */
+export function sessionFile(session, suffix = '') {
+    const dir = join(ARCROOM_HOME, 'sessions'); // ponytail: tiny files per session, never cleaned up; prune old ones if it matters
+    mkdirSync(dir, { recursive: true });
+    return join(dir, `${session.replace(/[^\w-]/g, '_')}${suffix}.json`);
+}
+/** Returns a block reason for a looping call; otherwise records the call and returns undefined. */
+export function checkLoop(session, tool, input) {
+    const file = sessionFile(session);
+    const recent = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : [];
+    const sig = signature(tool, input);
+    if (isLoop(recent, sig)) {
+        return `ArcRoom loop guard: this exact ${tool} call already ran ${LOOP_LIMIT - 1} times in a row. Don't repeat it; try a different approach.`;
+    }
+    writeFileSync(file, JSON.stringify([...recent, sig].slice(-(LOOP_LIMIT - 1))));
+    return undefined;
+}