@hmharness/agent 0.1.0

package/dist/runner.js

@@ -0,0 +1,311 @@
+/**
+ * @hmharness/agent - runner
+ * The shared agent-task execution layer. CLI maps its events to terminal
+ * output; the web frontend maps them to SSE - one behavior, two frontends.
+ * Also owns the native registry factory (spawn_agent recursion) and the
+ * approval gate construction.
+ */
+import { homeDir, loadConfig, resolveProvider, mcpServerTools, Registry, runLoop, Session, } from '@hmharness/kernel';
+import { appendMemory, listSkills, readInsights, readNotes, recentInsights, recordInsight, retrieveMemory, skillsToPrompt, sessionGetsCanary, canaryWatermark, listCanary } from '@hmharness/evolution';
+import { harmonyTools } from '@hmharness/domain-harmony';
+import { opsTools } from '@hmharness/domain-ops';
+import * as readline from 'node:readline/promises';
+import { stdin } from 'node:process';
+import { baseTools } from "./tools.js";
+import { buildSystemPrompt } from "./prompt.js";
+import { strings } from "./i18n.js";
+import { makeSpawnTool, MAX_SPAWN_DEPTH } from "./spawn.js";
+/** Flatten the config.json shape into the runtime discriminated union. */
+export function toServerConfig(c) {
+    if (c.type === 'http')
+        return { type: 'http', url: c.url ?? '', headers: c.headers, trusted: c.trusted };
+    return { type: 'stdio', command: c.command ?? '', args: c.args, env: c.env, trusted: c.trusted };
+}
+/**
+ * Current spawn base, set per task so a long-lived registry (REPL, web
+ * server) always routes sub-agents to the CURRENT session and gate.
+ */
+export const spawnBase = {};
+export function nativeRegistry(depth) {
+    const reg = new Registry();
+    reg.registerAll(baseTools).registerAll(harmonyTools).registerAll(opsTools);
+    if (depth < MAX_SPAWN_DEPTH) {
+        reg.register(makeSpawnTool({
+            depth,
+            getBase: () => spawnBase.current ?? {
+                provider: { baseUrl: '', apiKey: '', model: '' },
+                ctx: { cwd: process.cwd(), home: homeDir() },
+            },
+            buildChildRegistry: nativeRegistry,
+        }));
+    }
+    return reg;
+}
+export async function buildRegistry(opts = {}) {
+    const reg = nativeRegistry(0);
+    const clients = [];
+    if (opts.mcp !== false) {
+        const cfg = await loadConfig();
+        const servers = Object.entries(cfg.mcpServers ?? {});
+        if (servers.length > 0) {
+            await Promise.all(servers.map(async ([name, raw]) => {
+                try {
+                    const { client, tools } = await mcpServerTools(name, toServerConfig(raw));
+                    for (const t of tools) {
+                        try {
+                            reg.register(t);
+                        }
+                        catch {
+                            /* name collision after sanitization - first server wins */
+                        }
+                    }
+                    clients.push(client);
+                    if (opts.announce !== false)
+                        console.log(`  [mcp] ${name}: ${tools.length} tools attached`);
+                }
+                catch (err) {
+                    if (opts.announce !== false)
+                        console.log(`  [mcp] ${name}: unavailable (${String(err).slice(0, 140)})`);
+                }
+            }));
+        }
+    }
+    return { reg, clients };
+}
+/** Retrieval-based context pack: task-relevant memories, not the whole file.
+ *  P0 canary: ~20% of sessions (deterministic by session id) also receive
+ *  the canary skill block, watermarked as experimental references - the
+ *  impact loop compares these sessions against the rest. */
+export async function contextPack(task, sessionId) {
+    const home = homeDir();
+    const [memory, skills, insights] = await Promise.all([
+        retrieveMemory(home, task),
+        listSkills(home),
+        recentInsights(home),
+    ]);
+    let canaryBlock = '';
+    let canaryNames = [];
+    if (sessionId && sessionGetsCanary(sessionId)) {
+        const canary = await listCanary(home);
+        if (canary.length > 0) {
+            canaryNames = canary.map((s) => s.name);
+            canaryBlock = canaryWatermark(canaryNames) + '\n' + skillsToPrompt(canary);
+        }
+    }
+    return { memory, skills: skillsToPrompt(skills) + (canaryBlock ? '\n' + canaryBlock : ''), insights, skillsInjected: [...skills.map((s) => s.name), ...canaryNames] };
+}
+/**
+ * Terminal approval gate: auto mode passes everything; a TTY gets a y/N
+ * prompt (reusing a caller-provided readline); a pipe gets a safe deny.
+ * The kernel loop denies by default when no gate is wired at all.
+ */
+export function makeApproval(cfg, yes, sharedRl) {
+    const t = strings(cfg.locale ?? 'zh');
+    return {
+        async ask(toolName, args) {
+            if (yes || cfg.approval === 'auto')
+                return true;
+            const brief = JSON.stringify(args).slice(0, 120);
+            if (!stdin.isTTY) {
+                process.stdout.write(`\x1b[33m${t.approvalDeniedNoTty(toolName, brief)}\x1b[0m\n`);
+                return false;
+            }
+            const rl = sharedRl ?? readline.createInterface({ input: stdin, output: process.stdout });
+            let answer;
+            try {
+                answer = (await rl.question(`\x1b[33m${t.approvalPrompt(toolName, brief)}\x1b[0m`)).trim().toLowerCase();
+            }
+            finally {
+                if (!sharedRl)
+                    rl.close();
+            }
+            return answer === 'y' || answer === 'yes';
+        },
+    };
+}
+/** Run one full agent task end-to-end; audit + insight recording included. */
+export async function runAgentTask(opts) {
+    const cfg = opts.cfg ?? (await loadConfig());
+    const ctx = opts.ctx ?? { cwd: process.cwd(), home: homeDir() };
+    const events = opts.events ?? {};
+    const session = new Session(ctx.home, ctx.cwd, cfg.provider.model);
+    // contextPack needs the session id: canary injection is deterministic
+    // per-session (stable attribution), decided before the prompt is built
+    const pack = await contextPack(opts.task, session.id);
+    const system = buildSystemPrompt({
+        cwd: ctx.cwd,
+        home: ctx.home,
+        memory: pack.memory,
+        skills: pack.skills,
+        insights: pack.insights,
+        model: cfg.provider.model,
+        locale: cfg.locale,
+    });
+    await session.user(opts.task);
+    const approval = opts.approvalAsk ? { ask: opts.approvalAsk } : makeApproval(cfg, opts.yes === true);
+    spawnBase.current = {
+        provider: resolveProvider(cfg, 'chat'),
+        ctx,
+        approval,
+        session,
+        onLine: (l) => events.onLine?.(l),
+    };
+    const messages = [
+        { role: 'system', content: system },
+        ...(opts.resumeMessages ?? []),
+        { role: 'user', content: opts.task },
+    ];
+    const toolsUsed = [];
+    // self-noted failure patterns: 2+ errors from one tool become a memory
+    // note, so the NEXT session starts knowing what broke this one (the
+    // self-evolution loop's missing per-session feedback channel)
+    const toolErrors = new Map();
+    const result = await runLoop({
+        provider: resolveProvider(cfg, 'chat'),
+        registry: opts.registry,
+        messages,
+        ctx,
+        maxTurns: cfg.maxTurns,
+        maxContextChars: cfg.maxContextChars,
+        approval: spawnBase.current.approval,
+        events: {
+            onDelta: (kind, chunk) => events.onDelta?.(kind, chunk),
+            onToolCall: (name, args) => {
+                toolsUsed.push(name);
+                events.onToolCall?.(name, args);
+            },
+            onToolResult: (name, output, isError) => {
+                if (isError) {
+                    const list = toolErrors.get(name) ?? [];
+                    list.push(output.split('\n')[0].slice(0, 120));
+                    toolErrors.set(name, list);
+                }
+                void session.tool(name, output, isError);
+                events.onToolResult?.(name, output, isError);
+            },
+            onApproval: (name, args, granted) => {
+                void session.approval(name, granted);
+                events.onApproval?.(name, args, granted);
+            },
+            onAssistant: async (m) => {
+                await session.assistant(m.content ?? null, m.tool_calls);
+            },
+        },
+    });
+    // ---- instant feedback: learn from THIS task's mistakes, not 8 tasks later ----
+    // Tier 1 (always, zero cost): raw error pattern → memory self-note. Lowered
+    // to 1 failure for system-level patterns (shell incompat, auth, missing
+    // binary) - those never self-correct on retry; 2 for generic errors.
+    try {
+        const SYSTEM_ERR = /not (recognized|found|exist)|ENOENT|EACCES|ECONN|HTTP 4\d\d|authentication|unauthorized|command not found|is not an? (internal|external)/i;
+        for (const [name, errs] of toolErrors) {
+            const systemLevel = errs.some((e) => SYSTEM_ERR.test(e));
+            const threshold = systemLevel ? 1 : 2;
+            if (errs.length < threshold)
+                continue;
+            const notes = await readNotes(ctx.home);
+            const last = notes.slice(-40).map((n) => n.text).join('\n');
+            if (last.includes(`[self-note] tool ${name}`))
+                continue;
+            await appendMemory(ctx.home, `[self-note] tool ${name} failed ${errs.length}x in one session; samples: ${[...new Set(errs)].slice(0, 2).join(' | ')}`);
+        }
+    }
+    catch {
+        /* memory is best-effort; never fail the task on it */
+    }
+    // Tier 2 (if errors occurred): one quick model call - "what went wrong,
+    // what to do differently" - written to memory immediately. This is the
+    // per-session reflection the user asked for: mistakes corrected in real
+    // time, not batched 8 sessions later.
+    if (toolErrors.size > 0) {
+        void (async () => {
+            try {
+                const { chat: chatFn } = await import('@hmharness/kernel');
+                const provider = resolveProvider(cfg, 'evolve');
+                if (!provider.apiKey)
+                    return;
+                const errSummary = [...toolErrors.entries()].map(([n, e]) => `${n}: ${[...new Set(e)].slice(0, 2).join('; ')}`).join('\n').slice(0, 600);
+                const task = opts.task.slice(0, 150);
+                const r = await chatFn(provider, [
+                    { role: 'system', content: 'You distill agent failure lessons. Given a task and its tool errors, output ONE actionable note (max 180 chars) starting with a verb: what to do differently next time on THIS machine/environment. If the errors are trivial/transient, output exactly NONE.' },
+                    { role: 'user', content: `Task: ${task}\nTool errors:\n${errSummary}` },
+                ]);
+                const lesson = (r.message.content ?? '').trim();
+                if (lesson && lesson.toUpperCase() !== 'NONE' && lesson.length < 300) {
+                    await appendMemory(ctx.home, `[lesson] ${lesson}`);
+                }
+            }
+            catch {
+                /* reflection is best-effort */
+            }
+        })();
+    }
+    await session.final(result.text, result.turns, result.toolUses);
+    await recordInsight(ctx.home, {
+        time: new Date().toISOString(),
+        session: session.id,
+        task: opts.task.slice(0, 120),
+        outcome: result.turns >= cfg.maxTurns ? 'turn-budget' : 'ok',
+        turns: result.turns,
+        toolUses: result.toolUses,
+        toolsUsed: [...new Set(toolsUsed)],
+        skillsInjected: pack.skillsInjected,
+    });
+    // daily self-evolution: every N insights, one background cycle fires
+    // (default on; autoEvolveEvery: 0 disables). Fire-and-forget - it never
+    // blocks the reply, and its own guards (bench gate, holdout, poison
+    // screen, skills/+memory/ only) apply unchanged.
+    const every = cfg.autoEvolveEvery ?? 3;
+    if (every > 0) {
+        try {
+            const count = (await readInsights(ctx.home, 10_000)).length;
+            if (count > 0 && count % every === 0)
+                void triggerBackgroundEvolve(ctx.home);
+        }
+        catch {
+            /* insight count is best-effort */
+        }
+    }
+    events.onFinal?.({ text: result.text, turns: result.turns, toolUses: result.toolUses, sessionId: session.id, usage: result.usage });
+    return { ...result, sessionId: session.id, toolsUsed: [...new Set(toolsUsed)] };
+}
+/** One background evolution cycle (auto-triggered). Logs to the evolution
+ *  journal only; failures never surface into the user's chat. */
+async function triggerBackgroundEvolve(home) {
+    try {
+        const { runEvolution } = await import('@hmharness/evolution');
+        const { defaultConfig, loadConfig, resolveProvider, chat } = await import('@hmharness/kernel');
+        const cfg = await loadConfig();
+        const provider = resolveProvider(cfg, 'evolve');
+        if (!provider.apiKey)
+            return; // no provider configured - stay quiet
+        const reg = nativeRegistry(0);
+        await runEvolution({
+            home,
+            provider,
+            runCase: async (c) => {
+                if (c.tools) {
+                    const { buildSystemPrompt } = await import("./prompt.js");
+                    const res2 = await runLoop({
+                        provider,
+                        registry: reg,
+                        messages: [
+                            { role: 'system', content: buildSystemPrompt({ cwd: process.cwd(), home, memory: '', skills: '', insights: '', model: provider.model }) },
+                            { role: 'user', content: c.prompt },
+                        ],
+                        ctx: { cwd: process.cwd(), home },
+                        maxTurns: 6,
+                    });
+                    return res2.text;
+                }
+                const r = await chat(provider, [{ role: 'user', content: c.prompt }]);
+                return r.message.content ?? '';
+            },
+            log: () => undefined,
+        });
+        void defaultConfig; // referenced for type stability of the dynamic import
+    }
+    catch {
+        /* background cycle failures are recorded by runEvolution itself or stay silent */
+    }
+}

package/dist/spawn.d.ts

@@ -0,0 +1,32 @@
+import { type Session, type LoopApproval, type Registry, type Tool } from '@hmharness/kernel';
+export declare const MAX_SPAWN_DEPTH = 2;
+export interface SpawnBase {
+    provider: import('@hmharness/kernel').ProviderConfig;
+    ctx: import('@hmharness/kernel').ToolContext;
+    approval?: LoopApproval;
+    session?: Session;
+    /** Bubbled tool traffic for display: `[sub1] list_dir {...}`. */
+    onLine?(line: string): void;
+}
+/** Aggregated per-role outcomes from the spawn journal (HMH_HOME). */
+export interface RoleStat {
+    role: string;
+    spawns: number;
+    /** ok = finished within its turn budget without tool errors */
+    ok: number;
+}
+export declare function recordRole(home: string, role: string, ok: boolean): Promise<void>;
+export declare function roleStats(home: string, limit?: number): Promise<RoleStat[]>;
+/** One-line leaderboard the parent sees before it delegates (>=3 samples). */
+export declare function roleStatsLine(stats: RoleStat[]): string;
+/**
+ * Resolved lazily at each spawn so a long-lived REPL registry always sees the
+ * CURRENT task's session/approval, not the one from when it was built.
+ */
+export interface SpawnDeps {
+    depth: number;
+    getBase(): SpawnBase;
+    /** Build the registry for a child at the given depth (no spawn at the cap). */
+    buildChildRegistry(depth: number): Registry;
+}
+export declare function makeSpawnTool(deps: SpawnDeps): Tool;

package/dist/spawn.js

@@ -0,0 +1,129 @@
+/**
+ * @hmharness/cli - spawn
+ * The sub-agent tool: run a nested agent loop with a FRESH context on a
+ * self-contained subtask and return its final answer. Children share the
+ * tool registry (minus MCP - children stay fast and deterministic) and the
+ * approval gate, but never the parent's conversation - context isolation
+ * is the point. Depth-capped so a confused model can't fork-bomb itself.
+ *
+ * P3 role records: an optional `role` labels the sub-agent (e.g.
+ * "explorer", "reviewer"); outcome stats accumulate in HMH_HOME and are
+ * surfaced in the parent's next spawn - the honest minimal version of
+ * agent-topology evolution: no MARL, just per-role success rates the
+ * model can read before delegating. Weak roles get called out; the
+ * model (or user) stops asking them for that kind of work.
+ */
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { runLoop } from '@hmharness/kernel';
+export const MAX_SPAWN_DEPTH = 2;
+export async function recordRole(home, role, ok) {
+    try {
+        const dir = join(home, 'evolution');
+        await mkdir(dir, { recursive: true });
+        await appendFile(join(dir, 'spawn-roles.jsonl'), JSON.stringify({ time: new Date().toISOString(), role, ok }) + '\n', 'utf8');
+    }
+    catch { /* stats are best-effort */ }
+}
+export async function roleStats(home, limit = 200) {
+    try {
+        const text = await readFile(join(home, 'evolution', 'spawn-roles.jsonl'), 'utf8');
+        const lines = text.trim().split('\n').filter(Boolean).slice(-limit);
+        const by = new Map();
+        for (const l of lines) {
+            try {
+                const r = JSON.parse(l);
+                const s = by.get(r.role) ?? { role: r.role, spawns: 0, ok: 0 };
+                s.spawns++;
+                if (r.ok)
+                    s.ok++;
+                by.set(r.role, s);
+            }
+            catch { /* skip corrupt */ }
+        }
+        return [...by.values()].sort((a, b) => (b.ok / b.spawns) - (a.ok / a.spawns));
+    }
+    catch {
+        return [];
+    }
+}
+/** One-line leaderboard the parent sees before it delegates (>=3 samples). */
+export function roleStatsLine(stats) {
+    const shown = stats.filter((s) => s.spawns >= 3).slice(0, 5);
+    if (shown.length === 0)
+        return '';
+    return `Role track record (prefer roles with high ok-rates for similar work): ${shown.map((s) => `${s.role} ${(100 * s.ok / s.spawns).toFixed(0)}% (${s.spawns}x)`).join(', ')}.`;
+}
+export function makeSpawnTool(deps) {
+    return {
+        name: 'spawn_agent',
+        description: 'Run a sub-agent with a fresh context on a self-contained subtask (e.g. "explore the project layout and report module names", "find which file defines X"). Returns the sub-agent\'s final answer. The sub-agent has the same tools but NO conversation history and no MCP tools - include every detail it needs in the task. Use it to keep this conversation small: delegate exploration and focused lookups.',
+        parameters: {
+            type: 'object',
+            properties: {
+                task: { type: 'string', description: 'complete, self-contained instructions for the sub-agent' },
+                role: { type: 'string', description: 'optional label for this delegation, e.g. "explorer", "reviewer", "build-fixer" - roles accumulate success rates you will see next time' },
+                max_turns: { type: 'number', description: 'turn budget for the sub-agent (default 8, max 12)' },
+            },
+            required: ['task'],
+        },
+        async execute(args) {
+            const base = deps.getBase();
+            if (deps.depth >= MAX_SPAWN_DEPTH) {
+                return { output: `spawn depth cap (${MAX_SPAWN_DEPTH}) reached. Do the work directly instead.`, isError: true };
+            }
+            const task = String(args.task ?? '').trim();
+            if (!task)
+                return { output: 'spawn_agent requires a non-empty task.', isError: true };
+            const role = String(args.role ?? '').trim().toLowerCase().slice(0, 24);
+            const childDepth = deps.depth + 1;
+            const tag = role || `sub${childDepth}`;
+            const maxTurns = Math.min(Math.max(Number(args.max_turns ?? 8), 1), 12);
+            const registry = deps.buildChildRegistry(childDepth);
+            // P3 tournament signal: show the role leaderboard (if any) to the
+            // parent model in the delegation prompt when the child runs with a role
+            let roleLine = '';
+            if (role) {
+                try {
+                    const stats = await roleStats(base.ctx.home, 200);
+                    roleLine = roleStatsLine(stats) + '\n';
+                }
+                catch { /* best-effort */ }
+            }
+            const system = [
+                `You are a hmh sub-agent (depth ${childDepth}${role ? `, role: ${role}` : ''}). You have no conversation history beyond this task.`,
+                role ? `Perform the ${role} duty with that specialty's discipline.` : '',
+                'Do exactly what the task asks, use tools as needed, verify before answering, and reply with a concise result (the caller only sees your final answer).',
+            ].filter(Boolean).join('\n');
+            base.onLine?.(`[${tag}] start: ${task.slice(0, 80)}`);
+            let sawError = false;
+            const result = await runLoop({
+                provider: base.provider,
+                registry,
+                messages: [
+                    { role: 'system', content: roleLine + system },
+                    { role: 'user', content: task },
+                ],
+                ctx: base.ctx,
+                maxTurns,
+                approval: base.approval,
+                events: {
+                    onToolCall: (name, a) => base.onLine?.(`[${tag}] ${name} ${JSON.stringify(a).slice(0, 80)}`),
+                    onToolResult: (name, output, isError) => {
+                        if (isError) {
+                            sawError = true;
+                            base.onLine?.(`[${tag}] ${name} ERROR: ${output.slice(0, 100)}`);
+                        }
+                        void base.session?.tool(`${tag}>${name}`, output, isError);
+                    },
+                },
+            });
+            const text = result.text || '(sub-agent returned empty output)';
+            // P3 record: ok = answered within budget and no tool errored
+            if (role)
+                await recordRole(base.ctx.home, role, result.turns < maxTurns && !sawError);
+            base.onLine?.(`[${tag}] done (${result.turns} turns, ${result.toolUses} tool uses)`);
+            return { output: text.length > 20_000 ? text.slice(0, 20_000) + '\n...[truncated]' : text };
+        },
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,52 @@
+import { type Tool } from '@hmharness/kernel';
+export declare const readFileTool: Tool;
+export declare const writeFileTool: Tool;
+export declare const listDirTool: Tool;
+/** Host-shell pipe preflight: on Windows cmd, Unix-isms fail with cryptic
+ *  mojibake and the model retries for many turns. Only the FIRST word of
+ *  each host segment (split on | || && ;) is checked - Unix words inside
+ *  arguments (docker exec c ls /app) belong to the container and stay legal.
+ *  (Pure, testable.) */
+export declare function unixPipeOnWindows(command: string, platform?: string): string | null;
+export declare function commandPreflight(command: string, cwd: string): Promise<string | null>;
+export declare const runCommandTool: Tool;
+/** Zero-dependency web search: DuckDuckGo HTML endpoint, no API key. */
+export declare const webSearchTool: Tool;
+/** Fetch a URL and return readable text (tags stripped, entities decoded,
+ *  size-bounded). Pairs with web_search: search finds, fetch reads. */
+export declare const webFetchTool: Tool;
+/** Desktop automation, step 1 (first-class): screenshot the primary display
+ *  to a PNG and hand the path back - the agent then reads it with see_image
+ *  (vision chain). Windows via PowerShell System.Drawing; other platforms
+ *  report the gap honestly instead of failing silently. */
+export declare const desktopScreenshotTool: Tool;
+/** Desktop automation steps 2-3: click and type. PowerShell + Win32 for
+ *  mouse (SetCursorPos + mouse_event), SendKeys for keyboard. Pair with
+ *  desktop_screenshot + see_image: look → act → verify. */
+export declare const desktopClickTool: Tool;
+export declare const desktopTypeTool: Tool;
+/** Browser automation, first-class entry point: open a URL in the user's
+ *  default browser (visible window), then drive it with the desktop triad:
+ *  desktop_screenshot + see_image to LOOK, desktop_click/desktop_type to
+ *  ACT, desktop_screenshot again to VERIFY. This sees-plan-act loop works
+ *  with any browser and any page (full JS rendering, login states, CAPTCHAs
+ *  - everything a real user sees). Headless alternatives (--dump-dom etc)
+ *  are unreliable on Windows; the visible browser is the honest primitive.
+ */
+export declare const browserOpenTool: Tool;
+/** Remote command execution over SSH (zero-dep: OpenSSH binary).
+ *  Hosts come from config sshHosts (name/host/user/port/keyPath); secrets
+ *  never leave HMH_HOME. Read-only commands skip the approval card,
+ *  everything else is gated. */
+export interface SshHost {
+    name: string;
+    host: string;
+    user: string;
+    port?: number;
+    /** private-key path; defaults to the agent's own key resolution (~/.ssh) */
+    keyPath?: string;
+}
+export declare const sshRunTool: Tool;
+export declare const rememberTool: Tool;
+export declare const seeImageTool: Tool;
+export declare const baseTools: Tool[];