@hmharness/kernel 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,34 @@
+import type { HmhConfig } from './types.ts';
+export declare const STATE_DIRS: readonly ["sessions", "memory", "skills", "insights", "bench"];
+export declare function homeDir(): string;
+export declare function defaultConfig(): HmhConfig;
+export declare function loadConfig(): Promise<HmhConfig>;
+/**
+ * Point routing.chat at a named provider (`/model <name>` in the TUI/REPL,
+ * the model picker in the web UI). Preserves every other config field; the
+ * returned config reflects the new route (HMH_LOCALE override reapplied).
+ */
+export declare function setChatRoute(name: string): Promise<HmhConfig>;
+/**
+ * Persist the UI locale (TUI/REPL `/lang`) to config.json. Same
+ * read-mutate-write shape as setChatRoute; returns the refreshed config.
+ */
+export declare function setLocale(locale: 'zh' | 'en'): Promise<HmhConfig>;
+/**
+ * Merge detected providers into config.json (`hmh providers --scan`).
+ * Same-name entries never overwrite what is already configured; returns the
+ * refreshed config and the names actually added.
+ */
+export declare function addProviders(items: Array<{
+    name: string;
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+}>): Promise<{
+    cfg: HmhConfig;
+    added: string[];
+}>;
+export declare function initHome(): Promise<{
+    home: string;
+    created: string[];
+}>;

package/dist/config.js

@@ -0,0 +1,130 @@
+/**
+ * @hmharness/kernel - config
+ * HMH_HOME isolation: all hmharness state lives under one root
+ * (env HMH_HOME wins, default ~/.hmharness). Nothing is ever shared with
+ * any other harness on the machine - the lesson that motivated this
+ * clean-room project.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export const STATE_DIRS = ['sessions', 'memory', 'skills', 'insights', 'bench'];
+export function homeDir() {
+    return process.env.HMH_HOME ?? join(homedir(), '.hmharness');
+}
+export function defaultConfig() {
+    return {
+        // Point at any OpenAI-compatible endpoint via config.json or env vars.
+        provider: {
+            baseUrl: process.env.HMH_BASE_URL ?? '',
+            apiKey: process.env.HMH_API_KEY ?? '',
+            model: process.env.HMH_MODEL ?? '',
+        },
+        maxTurns: 25,
+    };
+}
+/** HMH_LOCALE env (zh|en) overrides the configured locale - used by --locale. */
+function applyLocaleOverride(cfg) {
+    const env = process.env.HMH_LOCALE;
+    return env === 'zh' || env === 'en' ? { ...cfg, locale: env } : cfg;
+}
+export async function loadConfig() {
+    const home = homeDir();
+    const file = join(home, 'config.json');
+    try {
+        const raw = JSON.parse(await readFile(file, 'utf8'));
+        return applyLocaleOverride({ ...defaultConfig(), ...raw, provider: { ...defaultConfig().provider, ...raw.provider } });
+    }
+    catch {
+        return applyLocaleOverride(defaultConfig());
+    }
+}
+/**
+ * Point routing.chat at a named provider (`/model <name>` in the TUI/REPL,
+ * the model picker in the web UI). Preserves every other config field; the
+ * returned config reflects the new route (HMH_LOCALE override reapplied).
+ */
+export async function setChatRoute(name) {
+    const home = homeDir();
+    const file = join(home, 'config.json');
+    let raw = {};
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        /* fresh config */
+    }
+    if (!raw.providers || !(name in raw.providers)) {
+        throw new Error(`unknown provider "${name}" - configure it under providers in config.json first`);
+    }
+    raw.routing = { ...(raw.routing ?? {}), chat: name };
+    await writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    return loadConfig();
+}
+/**
+ * Persist the UI locale (TUI/REPL `/lang`) to config.json. Same
+ * read-mutate-write shape as setChatRoute; returns the refreshed config.
+ */
+export async function setLocale(locale) {
+    const file = join(homeDir(), 'config.json');
+    let raw = {};
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        /* fresh config */
+    }
+    raw.locale = locale;
+    await writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    return loadConfig();
+}
+/**
+ * Merge detected providers into config.json (`hmh providers --scan`).
+ * Same-name entries never overwrite what is already configured; returns the
+ * refreshed config and the names actually added.
+ */
+export async function addProviders(items) {
+    const home = homeDir();
+    const file = join(home, 'config.json');
+    let raw = {};
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        /* fresh config */
+    }
+    const providers = (raw.providers ?? {});
+    const added = [];
+    for (const it of items) {
+        if (providers[it.name])
+            continue;
+        providers[it.name] = { baseUrl: it.baseUrl, model: it.model, ...(it.apiKey ? { apiKey: it.apiKey } : {}) };
+        added.push(it.name);
+    }
+    raw.providers = providers;
+    await writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    return { cfg: await loadConfig(), added };
+}
+export async function initHome() {
+    const home = homeDir();
+    const created = [];
+    await mkdir(home, { recursive: true });
+    for (const dir of STATE_DIRS) {
+        const p = join(home, dir);
+        try {
+            await mkdir(p, { recursive: true });
+        }
+        catch {
+            /* exists */
+        }
+    }
+    const configFile = join(home, 'config.json');
+    try {
+        await readFile(configFile, 'utf8');
+    }
+    catch {
+        await writeFile(configFile, JSON.stringify(defaultConfig(), null, 2) + '\n', 'utf8');
+        created.push('config.json');
+    }
+    return { home, created };
+}

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @hmharness/kernel - context
+ * Char-budget context compaction. Long agent runs are dominated by stale
+ * tool output; when the transcript exceeds its budget we replace the oldest
+ * tool results (never the system prompt, never the task itself, never the
+ * recent tail) with a tombstone. Deterministic, no model call, no surprise.
+ */
+import type { ChatMessage } from './types.ts';
+export declare const DEFAULT_CONTEXT_CHARS = 160000;
+export declare function transcriptChars(messages: ChatMessage[]): number;
+export declare function compactMessages(messages: ChatMessage[], budget?: number): ChatMessage[];

package/dist/context.js

@@ -0,0 +1,32 @@
+export const DEFAULT_CONTEXT_CHARS = 160_000;
+export function transcriptChars(messages) {
+    return messages.reduce((n, m) => n + (m.content?.length ?? 0) + (m.tool_calls?.length ?? 0) * 80, 0);
+}
+/** Messages too old to prune - keep the opening (system+task) and the tail. */
+function protectedRange(messages) {
+    const keep = new Set();
+    // system + first user message always survive
+    for (let i = 0; i < messages.length; i++) {
+        if (messages[i].role === 'system')
+            keep.add(i);
+        if (messages[i].role === 'user') {
+            keep.add(i);
+            break;
+        }
+    }
+    for (let i = Math.max(0, messages.length - 8); i < messages.length; i++)
+        keep.add(i);
+    return keep;
+}
+export function compactMessages(messages, budget = DEFAULT_CONTEXT_CHARS) {
+    if (transcriptChars(messages) <= budget)
+        return messages;
+    const keep = protectedRange(messages);
+    const out = messages.map((m) => ({ ...m }));
+    for (let i = 0; i < out.length && transcriptChars(out) > budget; i++) {
+        if (keep.has(i) || out[i].role !== 'tool')
+            continue;
+        out[i] = { ...out[i], content: '[context pruned: earlier tool output removed to fit budget]' };
+    }
+    return out;
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.ts';
+export * from './registry.ts';
+export * from './provider.ts';
+export * from './loop.ts';
+export * from './session.ts';
+export * from './config.ts';
+export * from './context.ts';
+export * from './mcp.ts';

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./types.js";
+export * from "./registry.js";
+export * from "./provider.js";
+export * from "./loop.js";
+export * from "./session.js";
+export * from "./config.js";
+export * from "./context.js";
+export * from "./mcp.js";

package/dist/loop-types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @hmharness/kernel - loop-types
+ * Structural typing for the registry the loop needs (avoids a hard import
+ * cycle and lets tests pass a stub registry).
+ */
+import type { Tool } from './types.ts';
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string | null;
+    tool_calls?: Array<{
+        id: string;
+        type: 'function';
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+    name?: string;
+}
+export interface RegistryLike {
+    get(name: string): Tool | undefined;
+    toOpenAITools(): Array<{
+        type: 'function';
+        function: {
+            name: string;
+            description: string;
+            parameters: unknown;
+        };
+    }>;
+}

package/dist/loop-types.js

@@ -0,0 +1 @@
+export {};

package/dist/loop.d.ts

@@ -0,0 +1,39 @@
+import type { ChatMessage, RegistryLike } from './loop-types.ts';
+import { chat, type DeltaKind } from './provider.ts';
+import type { ProviderConfig, ToolContext } from './types.ts';
+export interface LoopEvents {
+    onAssistant?(m: ChatMessage): void;
+    onDelta?(kind: DeltaKind, chunk: string): void;
+    onToolCall?(name: string, args: Record<string, unknown>): void;
+    onToolResult?(name: string, output: string, isError: boolean): void;
+    /** Called when a tool requested approval. granted=false means denied. */
+    onApproval?(name: string, args: Record<string, unknown>, granted: boolean): void;
+    onFinal?(text: string, turns: number): void;
+}
+export interface LoopApproval {
+    ask(toolName: string, args: Record<string, unknown>): Promise<boolean>;
+}
+export interface LoopResult {
+    text: string;
+    turns: number;
+    toolUses: number;
+    /** The full working transcript (system + task + all turns), uncompacted. */
+    messages: ChatMessage[];
+    /** Token usage summed across all model calls in this run (when reported). */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+}
+export declare function runLoop(opts: {
+    provider: ProviderConfig;
+    registry: RegistryLike;
+    messages: ChatMessage[];
+    ctx: ToolContext;
+    maxTurns?: number;
+    maxContextChars?: number;
+    approval?: LoopApproval;
+    events?: LoopEvents;
+    /** Injectable model call (tests pass a fake; production uses provider.chat). */
+    chatImpl?: typeof chat;
+}): Promise<LoopResult>;

package/dist/loop.js

@@ -0,0 +1,98 @@
+/**
+ * @hmharness/kernel - loop
+ * The agent loop: call the model, run the tools it asks for, feed results
+ * back, repeat until it answers without tool calls or the turn budget is
+ * spent. This is the "loop engineering" core - kept deliberately dull.
+ * Tools marked needsApproval pause here for a caller-provided ask() gate;
+ * no gate configured means deny (safe default). Between turns the
+ * transcript is compacted against the context budget.
+ */
+import { compactMessages } from "./context.js";
+import { chat } from "./provider.js";
+export async function runLoop(opts) {
+    const { provider, registry, ctx, events } = opts;
+    const modelCall = opts.chatImpl ?? chat;
+    const maxTurns = opts.maxTurns ?? 25;
+    const working = [...opts.messages];
+    let toolUses = 0;
+    const usage = { promptTokens: 0, completionTokens: 0 };
+    const tools = registry.toOpenAITools();
+    for (let turn = 1; turn <= maxTurns; turn++) {
+        const chatRes = await modelCall(provider, compactMessages(working, opts.maxContextChars), tools, {
+            onDelta: events?.onDelta,
+        });
+        usage.promptTokens += chatRes.usage?.prompt_tokens ?? 0;
+        usage.completionTokens += chatRes.usage?.completion_tokens ?? 0;
+        const { message } = chatRes;
+        events?.onAssistant?.(message);
+        const calls = message.tool_calls ?? [];
+        if (calls.length === 0) {
+            const text = message.content ?? '';
+            events?.onFinal?.(text, turn);
+            return { text, turns: turn, toolUses, messages: working, usage };
+        }
+        working.push({ role: 'assistant', content: message.content ?? null, tool_calls: calls });
+        const planned = [];
+        for (const call of calls) {
+            const name = call.function.name;
+            let args = {};
+            let badArgs = false;
+            try {
+                args = call.function.arguments ? JSON.parse(call.function.arguments) : {};
+            }
+            catch {
+                badArgs = true;
+            }
+            events?.onToolCall?.(name, args);
+            const tool = registry.get(name);
+            const p = { call, name, args, output: '', isError: false, skip: false };
+            if (!tool) {
+                p.output = `unknown tool: ${name}`;
+                p.isError = true;
+                p.skip = true;
+            }
+            else if (badArgs) {
+                p.output = `unparseable tool arguments for ${name}: ${call.function.arguments.slice(0, 200)}`;
+                p.isError = true;
+                p.skip = true;
+            }
+            else if (tool.needsApproval?.(args)) {
+                // Safe default: with no gate wired in, risky tools are denied.
+                const granted = opts.approval ? await opts.approval.ask(name, args) : false;
+                events?.onApproval?.(name, args, granted);
+                if (!granted) {
+                    p.output = 'User declined this action. Ask how to proceed or find a non-destructive alternative.';
+                    p.isError = true;
+                    p.skip = true;
+                }
+            }
+            planned.push(p);
+        }
+        await Promise.all(planned.map(async (p) => {
+            if (p.skip)
+                return;
+            try {
+                const r = await registry.get(p.name).execute(p.args, ctx);
+                p.output = r.output;
+                p.isError = r.isError === true;
+            }
+            catch (err) {
+                p.output = String(err);
+                p.isError = true;
+            }
+        }));
+        for (const p of planned) {
+            toolUses++;
+            events?.onToolResult?.(p.name, p.output, p.isError);
+            working.push({
+                role: 'tool',
+                tool_call_id: p.call.id,
+                name: p.name,
+                content: p.output.length > 60_000 ? p.output.slice(0, 60_000) + '\n...[truncated]' : p.output,
+            });
+        }
+    }
+    const text = `Turn budget exhausted (${maxTurns}). Last state preserved in the session log.`;
+    events?.onFinal?.(text, maxTurns);
+    return { text, turns: maxTurns, toolUses, messages: working, usage };
+}

package/dist/mcp.d.ts

@@ -0,0 +1,55 @@
+import type { Tool } from './types.ts';
+export type McpServerConfig = {
+    type: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    trusted?: boolean;
+} | {
+    type: 'http';
+    url: string;
+    headers?: Record<string, string>;
+    trusted?: boolean;
+};
+export declare class McpClient {
+    readonly serverName: string;
+    readonly config: McpServerConfig;
+    private proc;
+    private sessionId;
+    private buffer;
+    private stderrTail;
+    private pending;
+    private ready;
+    constructor(serverName: string, config: McpServerConfig);
+    /** initialize handshake. Must be called exactly once before use. */
+    connect(timeoutMs?: number): Promise<void>;
+    /** Fire-and-forget notification over HTTP (server answers 202). */
+    private notify;
+    private spawnStdio;
+    private onStdioChunk;
+    private onMessage;
+    /** One JSON-RPC round trip over whichever transport this server uses. */
+    private request;
+    /** Read an SSE body up to the first `data:` JSON message, then stop. */
+    private firstSseMessage;
+    listTools(): Promise<Array<{
+        name: string;
+        description?: string;
+        inputSchema?: unknown;
+    }>>;
+    callTool(name: string, args: Record<string, unknown>, timeoutMs?: number): Promise<{
+        output: string;
+        isError: boolean;
+    }>;
+    close(): void;
+}
+/** OpenAI function-name charset; MCP allows dots/dashes which it forbids. */
+export declare function sanitizeToolName(name: string): string;
+/**
+ * Connect + list + project. Separate from projectMcpTools so callers can
+ * distinguish "server down" from "server has no tools".
+ */
+export declare function mcpServerTools(serverName: string, config: McpServerConfig): Promise<{
+    client: McpClient;
+    tools: Tool[];
+}>;