@hmharness/cli 0.1.1 → 0.2.0

package/dist/main.js

@@ -326,13 +326,20 @@ usage:
   hmh tui [--no-web]      fullscreen terminal UI (slash palette, mouse wheel);
                            also starts the web UI in the background (--no-web skips)
   hmh ops [scan|brief|status]  ops keeper: ecosystem radar
+  hmh mcp-serve        run as an MCP stdio SERVER: expose harmony_* tools to
+                        Claude Code / Codex / any MCP host
+                        (host config: npx -y @hmharness/cli mcp-serve)
   hmh devices|check        direct tool run, no model
   hmh tools                list all registered tools (native + MCP)
   hmh mcp                  show configured MCP servers and their tools
   hmh evolve [--every=N]   self-evolution cycle (or resident loop)
-  hmh bench                run the evolution bench
+  hmh bench [--impact]     run the evolution bench / canary A/B report
   hmh skills [--promote|--rollback|--unpromote <name>]
   hmh skills add <git-url-or-local-dir>   install skills (multi-skill packs supported)
+  hmh state backup [--full] | restore [id] | remove <id|--all> | list
+                           snapshot / recover the evolution state (skills,
+                           memory, insights, logs); restore parks current
+                           state in a .pre-restore copy first
 
 flags:
   --yes / -y          auto-approve gated tools (else they prompt; non-TTY denies)
@@ -397,6 +404,14 @@ flags:
         }
         return;
     }
+    if (cmd === 'mcp-serve') {
+        // SERVER mode: expose the harmony_* tool surface over stdio MCP so
+        // Claude Code / Codex / any MCP host calls them natively. stdout is the
+        // protocol - run this exactly as the host's server command.
+        const { serveMcp } = await import("./mcp-server.js");
+        await serveMcp();
+        return; // serveMcp exits when stdin closes
+    }
     if (cmd === 'skills') {
         const home = homeDir();
         const flag = rest.find((a) => a.startsWith('--'));
@@ -568,6 +583,44 @@ flags:
         }
         return;
     }
+    if (cmd === 'state') {
+        // The evolution state (skills+memory+insights+logs) is a single-point
+        // asset; backup/restore/list keeps one bad JSONL from erasing the
+        // agent's whole learning history. Restore always parks the current
+        // state in a .pre-restore copy first (undoable by construction).
+        await initHome();
+        const { backupState, listBackups, restoreState, removeBackup } = await import("./state.js");
+        const sub = rest[0] ?? 'list';
+        if (sub === 'backup') {
+            const full = rest.includes('--full');
+            const r = await backupState(homeDir(), { full });
+            stdout.write(GREEN('✓') + ` backup ${r.id} (${r.items.length} items${full ? ', incl. sessions' : ''}) -> ${r.dir}\n`
+                + DIM('restore with: hmh state restore ' + r.id + '\n'));
+            return;
+        }
+        if (sub === 'restore') {
+            const id = rest.find((a) => !a.startsWith('-') && a !== 'restore');
+            const r = await restoreState(homeDir(), id);
+            stdout.write(GREEN('✓') + ` restored ${r.id} (${r.restored.length} items)\n`
+                + DIM(`current state parked at ${r.parked} (delete it if unwanted)\n`));
+            return;
+        }
+        if (sub === 'remove') {
+            const id = rest.find((a) => !a.startsWith('-') && a !== 'remove');
+            if (!id && !rest.includes('--all')) {
+                stdout.write('usage: hmh state remove <id | --all>\n');
+                return;
+            }
+            const removed = await removeBackup(homeDir(), id ?? '', { all: rest.includes('--all') });
+            stdout.write(`removed ${removed.length} backup(s)\n`);
+            return;
+        }
+        const list = await listBackups(homeDir());
+        stdout.write(list.length
+            ? list.map((b) => `  ${b.id}  ${b.items.length} items${b.full ? ' (full)' : ''}  ${b.time}`).join('\n') + '\n'
+            : DIM('  no backups yet - run "hmh state backup"\n'));
+        return;
+    }
     if (cmd === 'tui') {
         await initHome();
         // tui(yes, noWeb): inside the TTY check the TUI auto-links the web UI

package/dist/mcp-server.d.ts

@@ -0,0 +1 @@
+export declare function serveMcp(): Promise<void>;

package/dist/mcp-server.js

@@ -0,0 +1,134 @@
+/**
+ * @hmharness/cli - mcp-server (stdio MCP server mode)
+ * Turns hmharness into a native tool provider for MCP hosts (Claude Code,
+ * Codex, Cursor, ...): they call harmony_build / harmony_api_lookup / ... as
+ * first-class tools - no nested agent loop, no double context, and the host's
+ * per-tool permission UI becomes the approval gate.
+ *
+ * Security model in server mode (deliberate, documented):
+ *   - EXPOSED: only tools matching /^harmony_/ by default (the HarmonyOS
+ *     domain surface). Generic tools (run_command, write_file, ...) stay
+ *     private - the host already has bash/file tools of its own. Override
+ *     with HMH_MCP_TOOLS="name_or_prefix,name_or_prefix,...".
+ *   - APPROVAL: tool-level needsApproval is intentionally NOT consulted -
+ *     the host prompts its user per tool call. What still applies is the
+ *     hard walls INSIDE every tool (destructive-command deny, path red
+ *     lines): those never depended on interaction and stay server-side.
+ *   - OBSERVABILITY: every tools/call is appended to
+ *     insights/mcp-calls.jsonl (tool, ok, ms) - external agents' HarmonyOS
+ *     usage becomes visible to the radar/insight pipeline (observation only;
+ *     the skill gate stays exclusive to native hmh sessions).
+ *
+ * Protocol: line-delimited JSON-RPC 2.0 over stdio (initialize /
+ * notifications/initialized / tools/list / tools/call / ping), the same
+ * shape scripts/test-mcp-server.mjs proved in-repo. stdout belongs to the
+ * protocol - every stray console.log is redirected to stderr.
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import readline from 'node:readline';
+import { join } from 'node:path';
+import { homeDir } from '@hmharness/kernel';
+import { buildRegistry } from '@hmharness/agent';
+const VERSION = (() => {
+    try {
+        return createRequire(import.meta.url)('../package.json').version;
+    }
+    catch {
+        return '0.0.0';
+    }
+})();
+function exposedFilter() {
+    const raw = process.env.HMH_MCP_TOOLS;
+    if (raw && raw.trim()) {
+        const pats = raw.split(',').map((s) => s.trim()).filter(Boolean);
+        return (t) => pats.some((p) => t.name === p || t.name.startsWith(p.endsWith('_') || p.endsWith('-') ? p : p + '_'));
+    }
+    return (t) => t.name.startsWith('harmony_');
+}
+export async function serveMcp() {
+    // stdout is the protocol channel: silence any library prints.
+    const realLog = console.log;
+    console.log = (...a) => console.error(...a);
+    void realLog;
+    const { reg } = await buildRegistry({ mcp: false, announce: false });
+    const tools = reg.list().filter(exposedFilter());
+    const byName = new Map(tools.map((t) => [t.name, t]));
+    const ctx = { cwd: process.cwd(), home: homeDir() };
+    const logCall = async (tool, ok, ms) => {
+        try {
+            const dir = join(ctx.home, 'insights');
+            await mkdir(dir, { recursive: true });
+            await appendFile(join(dir, 'mcp-calls.jsonl'), JSON.stringify({ time: new Date().toISOString(), tool, ok, ms }) + '\n', 'utf8');
+        }
+        catch { /* observation is best-effort, never fails a call */ }
+    };
+    const reply = (id, result, error) => {
+        const out = { jsonrpc: '2.0', id };
+        if (error)
+            out.error = error;
+        else
+            out.result = result;
+        process.stdout.write(JSON.stringify(out) + '\n');
+    };
+    const rl = readline.createInterface({ input: process.stdin });
+    rl.on('line', (line) => {
+        line = line.trim();
+        if (!line)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (msg.id === undefined)
+            return; // notification (notifications/initialized etc.) - no reply
+        switch (msg.method) {
+            case 'initialize':
+                reply(msg.id, {
+                    protocolVersion: '2025-06-18',
+                    capabilities: { tools: {} },
+                    serverInfo: { name: 'hmharness', version: VERSION },
+                });
+                break;
+            case 'ping':
+                reply(msg.id, {});
+                break;
+            case 'tools/list':
+                reply(msg.id, {
+                    tools: tools.map((t) => ({
+                        name: t.name,
+                        description: t.description.slice(0, 1000),
+                        inputSchema: t.parameters,
+                    })),
+                });
+                break;
+            case 'tools/call': {
+                const name = msg.params?.name ?? '';
+                const tool = byName.get(name);
+                if (!tool) {
+                    void logCall(name, false, 0);
+                    reply(msg.id, { content: [{ type: 'text', text: `unknown or not exposed tool: ${name}` }], isError: true });
+                    break;
+                }
+                const t0 = Date.now();
+                tool.execute(msg.params?.arguments ?? {}, ctx)
+                    .then(async (r) => {
+                    await logCall(name, r.isError !== true, Date.now() - t0);
+                    reply(msg.id, { content: [{ type: 'text', text: r.output }], ...(r.isError === true ? { isError: true } : {}) });
+                })
+                    .catch(async (err) => {
+                    await logCall(name, false, Date.now() - t0);
+                    reply(msg.id, { content: [{ type: 'text', text: String(err) }], isError: true });
+                });
+                break;
+            }
+            default:
+                reply(msg.id, undefined, { code: -32601, message: `method not found: ${msg.method}` });
+        }
+    });
+    // stdin closed (host shut us down) - exit cleanly.
+    rl.on('close', () => process.exit(0));
+}

package/dist/state.d.ts

@@ -0,0 +1,28 @@
+/** Timestamped backup id: sorts lexicographically == chronologically. */
+export declare function backupState(home: string, opts?: {
+    full?: boolean;
+}): Promise<{
+    id: string;
+    items: string[];
+    dir: string;
+}>;
+export interface BackupInfo {
+    id: string;
+    time: string;
+    full: boolean;
+    items: string[];
+}
+export declare function listBackups(home: string): Promise<BackupInfo[]>;
+/** Restore by id (or the latest when omitted). The CURRENT state is parked
+ *  in backups/.pre-restore-<ts>/ before anything is copied back, so a wrong
+ *  pick is undoable. Only items present in the backup are restored. */
+export declare function restoreState(home: string, id?: string): Promise<{
+    id: string;
+    restored: string[];
+    parked: string;
+}>;
+/** Remove a backup by id (or all with --all). Refuses to touch anything
+ *  that is not under backups/, and refuses the newest backup unless --all. */
+export declare function removeBackup(home: string, id: string, opts?: {
+    all?: boolean;
+}): Promise<string[]>;

package/dist/state.js

@@ -0,0 +1,120 @@
+/**
+ * @hmharness/cli - state (HMH_HOME backup / restore / list)
+ * The evolution state (skills + memory + insights + evolution logs + bench
+ * cases + pareto archive) is a single-point asset: one corrupted JSONL and
+ * the agent's entire learning history is gone. `hmh state backup` snapshots
+ * the irreplaceable parts into HMH_HOME/backups/<timestamp>/ as plain files
+ * (no archive format - restorable by copy even with a broken toolchain);
+ * `hmh state restore` swaps one back AFTER parking the current state in a
+ * .pre-restore-<ts> safety copy, so a botched restore is itself restorable.
+ */
+import { cp, mkdir, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The irreplaceable set. `sessions/` (large, and evidence rather than
+ *  state) is only included with --full. */
+const STATE_ITEMS = [
+    'config.json',
+    'workspaces.json',
+    'memory.md',
+    'memory',
+    'skills',
+    'insights',
+    'evolution',
+    'bench',
+    'ops',
+];
+async function exists(p) {
+    try {
+        await stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function backupsDir(home) {
+    return join(home, 'backups');
+}
+/** Timestamped backup id: sorts lexicographically == chronologically. */
+export async function backupState(home, opts = {}) {
+    const id = new Date().toISOString().replace(/[:.]/g, '-');
+    const dir = join(backupsDir(home), id);
+    await mkdir(dir, { recursive: true });
+    const items = [...STATE_ITEMS];
+    if (opts.full)
+        items.push('sessions');
+    const copied = [];
+    for (const item of items) {
+        const src = join(home, item);
+        if (await exists(src)) {
+            await cp(src, join(dir, item), { recursive: true });
+            copied.push(item);
+        }
+    }
+    await writeFile(join(dir, 'manifest.json'), JSON.stringify({
+        time: new Date().toISOString(),
+        full: opts.full === true,
+        items: copied,
+    }, null, 2), 'utf8');
+    return { id, items: copied, dir };
+}
+export async function listBackups(home) {
+    const dir = backupsDir(home);
+    if (!await exists(dir))
+        return [];
+    const out = [];
+    for (const name of await readdir(dir)) {
+        if (name.startsWith('.'))
+            continue;
+        try {
+            const m = JSON.parse(await (await import('node:fs/promises')).readFile(join(dir, name, 'manifest.json'), 'utf8'));
+            out.push({ id: name, time: m.time, full: m.full === true, items: m.items ?? [] });
+        }
+        catch { /* not a backup dir - skip */ }
+    }
+    return out.sort((a, b) => b.id.localeCompare(a.id));
+}
+/** Restore by id (or the latest when omitted). The CURRENT state is parked
+ *  in backups/.pre-restore-<ts>/ before anything is copied back, so a wrong
+ *  pick is undoable. Only items present in the backup are restored. */
+export async function restoreState(home, id) {
+    const backups = await listBackups(home);
+    if (backups.length === 0)
+        throw new Error('no backups found - run "hmh state backup" first');
+    const chosen = id ? backups.find((b) => b.id === id) : backups[0];
+    if (!chosen)
+        throw new Error(`no backup matches "${id}" (available: ${backups.map((b) => b.id).join(', ')})`);
+    // 1. park the current state
+    const parkId = `.pre-restore-${new Date().toISOString().replace(/[:.]/g, '-')}`;
+    const parkDir = join(backupsDir(home), parkId);
+    await mkdir(parkDir, { recursive: true });
+    for (const item of chosen.items) {
+        const cur = join(home, item);
+        if (await exists(cur))
+            await rename(cur, join(parkDir, item));
+    }
+    // 2. copy the backup in
+    const src = join(backupsDir(home), chosen.id);
+    const restored = [];
+    for (const item of chosen.items) {
+        if (await exists(join(src, item))) {
+            await cp(join(src, item), join(home, item), { recursive: true });
+            restored.push(item);
+        }
+    }
+    return { id: chosen.id, restored, parked: parkDir };
+}
+/** Remove a backup by id (or all with --all). Refuses to touch anything
+ *  that is not under backups/, and refuses the newest backup unless --all. */
+export async function removeBackup(home, id, opts = {}) {
+    const backups = await listBackups(home);
+    const targets = opts.all ? backups : backups.filter((b) => b.id === id);
+    if (!opts.all && targets.length === 0)
+        throw new Error(`no backup matches "${id}"`);
+    const removed = [];
+    for (const t of targets) {
+        await rm(join(backupsDir(home), t.id), { recursive: true, force: true });
+        removed.push(t.id);
+    }
+    return removed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/cli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "hmharness command line: one-shot tasks, an interactive REPL, a fullscreen TUI, the web frontend, and direct tool invocation.",
   "type": "module",
   "main": "dist/main.js",
@@ -43,11 +43,11 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/kernel": "0.1.0",
-    "@hmharness/evolution": "0.1.0",
-    "@hmharness/domain-harmony": "0.1.0",
-    "@hmharness/domain-ops": "0.1.0",
-    "@hmharness/agent": "0.1.0",
-    "@hmharness/web": "0.1.0"
+    "@hmharness/kernel": "0.2.0",
+    "@hmharness/evolution": "0.2.0",
+    "@hmharness/domain-harmony": "0.2.0",
+    "@hmharness/domain-ops": "0.2.0",
+    "@hmharness/agent": "0.2.0",
+    "@hmharness/web": "0.2.0"
   }
 }