@hmharness/kernel 0.1.0

package/dist/session.js

@@ -0,0 +1,111 @@
+/**
+ * @hmharness/kernel - session
+ * Append-only JSONL session log under HMH_HOME/sessions/. Every loop event
+ * is durably recorded - the audit trail the 2026 consensus calls
+ * non-negotiable, and the raw material the evolution subsystem learns from.
+ */
+import { appendFile, mkdir, readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export class Session {
+    id;
+    file;
+    /** Append chain: events serialize in call order, even fire-and-forget ones. */
+    tail = Promise.resolve();
+    constructor(home, cwd, model) {
+        const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+        this.id = `${stamp}-${Math.random().toString(36).slice(2, 8)}`;
+        this.file = join(home, 'sessions', `${this.id}.jsonl`);
+        this.append({ t: 'session/start', id: this.id, time: new Date().toISOString(), cwd, model }).catch(() => undefined);
+    }
+    async append(event) {
+        const write = this.tail.then(async () => {
+            const dir = join(this.file, '..');
+            await mkdir(dir, { recursive: true });
+            await appendFile(this.file, JSON.stringify(event) + '\n', 'utf8');
+        });
+        // keep the chain going even if this write fails
+        this.tail = write.catch(() => undefined);
+        await write;
+    }
+    user(text) {
+        return this.append({ t: 'user', time: new Date().toISOString(), text });
+    }
+    assistant(text, toolCalls) {
+        return this.append({ t: 'assistant', time: new Date().toISOString(), text, ...(toolCalls ? { tool_calls: toolCalls } : {}) });
+    }
+    tool(name, output, isError) {
+        return this.append({ t: 'tool', time: new Date().toISOString(), name, output, isError });
+    }
+    approval(tool, granted) {
+        return this.append({ t: 'approval', time: new Date().toISOString(), tool, granted });
+    }
+    final(text, turns, toolUses) {
+        return this.append({ t: 'final', time: new Date().toISOString(), text, turns, toolUses });
+    }
+}
+/** Find the newest session file under home/sessions matching an id prefix. */
+export async function latestSession(home, prefix = '') {
+    let files;
+    try {
+        files = (await readdir(join(home, 'sessions'))).filter((f) => f.endsWith('.jsonl') && f.startsWith(prefix));
+    }
+    catch {
+        return null;
+    }
+    files.sort();
+    return files.length > 0 ? join(home, 'sessions', files[files.length - 1]) : null;
+}
+/**
+ * Rebuild a chat transcript from a session log. Tool events don't record
+ * tool_call_id, but the loop executes calls sequentially, so ids pair with
+ * the tool events that follow their assistant message in order.
+ */
+export async function loadTranscript(file) {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const out = { id: '', model: '', cwd: '', messages: [] };
+    let pendingCallIds = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (ev.t === 'session/start') {
+            out.id = ev.id;
+            out.model = ev.model;
+            out.cwd = ev.cwd;
+        }
+        else if (ev.t === 'user') {
+            out.messages.push({ role: 'user', content: ev.text });
+        }
+        else if (ev.t === 'assistant') {
+            const calls = (ev.tool_calls ?? []);
+            out.messages.push({
+                role: 'assistant',
+                content: ev.text,
+                ...(calls.length > 0 ? { tool_calls: calls } : {}),
+            });
+            pendingCallIds = calls.map((c) => c.id);
+        }
+        else if (ev.t === 'tool') {
+            out.messages.push({
+                role: 'tool',
+                tool_call_id: pendingCallIds.shift() ?? '',
+                name: ev.name,
+                content: ev.output,
+            });
+        }
+        // approval / final events carry no chat turn
+    }
+    return out.id ? out : null;
+}

package/dist/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * @hmharness/kernel - types
+ * The kernel contract surface. Deliberately small: a Tool, a chat message,
+ * a provider config. Everything else in hmharness composes from these.
+ */
+/** A JSON-Schema-shaped parameter description (OpenAI tool-call format). */
+export interface JsonSchema {
+    type: string;
+    properties?: Record<string, unknown>;
+    required?: string[];
+    [key: string]: unknown;
+}
+/** Uniform tool execution result. */
+export interface ToolResult {
+    output: string;
+    isError?: boolean;
+}
+/** Per-invocation context handed to every tool. */
+export interface ToolContext {
+    /** Working directory for filesystem/shell tools. */
+    cwd: string;
+    /** hmharness home (isolated state root, e.g. ~/.hmharness). */
+    home: string;
+}
+/** A capability the agent may call. The entire extension surface. */
+export interface Tool {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+    /**
+     * Declarative risk marker: when this returns true the loop must obtain
+     * user approval before executing (see LoopOptions.approval). Absent or
+     * false means read-only / safe. Remote (MCP) tools default to needing
+     * approval unless their server is marked trusted.
+     */
+    needsApproval?(args: Record<string, unknown>): boolean;
+    execute(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+}
+/** OpenAI-style chat message, reused across provider adapters. */
+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;
+}
+/** Connection settings for an OpenAI-compatible endpoint. */
+export interface ProviderConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    /** Custom auth header name for gateways that reject Bearer (e.g. 'X-Api-Key'
+     *  for freellmapi). Omit for standard Authorization: Bearer; on 401 the
+     *  provider renegotiates with X-Api-Key automatically. */
+    authHeader?: string;
+}
+/** User-level configuration (HMH_HOME/config.json). */
+export interface HmhConfig {
+    provider: ProviderConfig;
+    maxTurns: number;
+    /** 'ask' (default) prompts before risky tools; 'auto' approves everything. */
+    approval?: 'ask' | 'auto';
+    /** Rough context budget in chars before old tool outputs get pruned. */
+    maxContextChars?: number;
+    /** MCP servers whose tools are projected into the registry at startup. */
+    mcpServers?: Record<string, McpServerImport>;
+    /** SSH hosts the agent may operate (name -> {host,user,port,keyPath}).
+     *  Secrets stay in HMH_HOME; the ssh_run tool reads them from here. */
+    sshHosts?: Record<string, {
+        host: string;
+        user: string;
+        port?: number;
+        keyPath?: string;
+    }>;
+    /** Vision-capable provider for see_image (any OpenAI-compatible endpoint). */
+    vision?: ProviderConfig;
+    /** Tried in order after `vision` fails (multi-provider resilience). */
+    visionFallbacks?: ProviderConfig[];
+    /** UI + system-prompt language. Default 'zh'. */
+    locale?: 'zh' | 'en';
+    /** Run a background evolution cycle after every N recorded insights
+     *  (default 3; 0 disables). Tier 3 of the feedback ladder: Tier 1 = raw
+     *  error self-notes (every task, zero cost), Tier 2 = one model-call
+     *  lesson per erroring task (instant reflection), Tier 3 = this - full
+     *  cycle with bench gate. Guards unchanged: double-gate, holdout, poison
+     *  screen, writes only under skills/ and memory/. */
+    autoEvolveEvery?: number;
+    /** Named vendor endpoints for multi-provider routing. */
+    providers?: Record<string, ProviderConfig>;
+    /** Per-purpose provider names resolved against `providers`. */
+    routing?: {
+        /** main chat loop (default: `provider`) */
+        chat?: string;
+        /** see_image (default: `vision`) */
+        vision?: string;
+        /** evolution meta-calls (default: chat) */
+        evolve?: string;
+        /** bench runner (default: chat) */
+        bench?: string;
+    };
+}
+/** Resolve a purpose to a concrete provider config (routing > legacy fields). */
+export declare function resolveProvider(cfg: HmhConfig, purpose: 'chat' | 'vision' | 'evolve' | 'bench'): ProviderConfig;
+/** One row of `/model` listings: a named provider and what it currently serves. */
+export interface ProviderView {
+    name: string;
+    model: string;
+    baseUrl: string;
+    /** purposes this provider resolves for right now (chat/vision/evolve/bench) */
+    purposes: string[];
+}
+export declare function listProviders(cfg: HmhConfig): ProviderView[];
+/** Built-in OpenAI-compatible presets (source of truth for docs/PROVIDERS.md). */
+export interface ProviderPreset {
+    name: string;
+    baseUrl: string;
+    envVar: string;
+    model: string;
+    /** auth header the gateway requires (freellmapi: X-Api-Key) */
+    authHeader?: string;
+}
+export declare const PROVIDER_PRESETS: ProviderPreset[];
+/**
+ * Detect locally available providers, dsh-style: presets whose env var is
+ * set, plus anything configured in ~/.opencode (opencode.json providers).
+ * Already-configured names are excluded. Read-only - callers decide whether
+ * to merge into config via addProviders().
+ */
+export declare function detectLocalProviders(cfg: HmhConfig, readFileFn: typeof import('node:fs/promises')['readFile']): Promise<ProviderPreset[]>;
+/** Shape used in config.json (kernel/src/mcp.ts has the runtime client). */
+export interface McpServerImport {
+    type: 'stdio' | 'http';
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    /** Skip the per-call approval prompt for this server's tools. */
+    trusted?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,131 @@
+/**
+ * @hmharness/kernel - types
+ * The kernel contract surface. Deliberately small: a Tool, a chat message,
+ * a provider config. Everything else in hmharness composes from these.
+ */
+/** Resolve a purpose to a concrete provider config (routing > legacy fields). */
+export function resolveProvider(cfg, purpose) {
+    const named = cfg.routing?.[purpose] ?? (purpose === 'vision' ? undefined : cfg.routing?.chat);
+    if (named && cfg.providers?.[named])
+        return cfg.providers[named];
+    if (purpose === 'vision')
+        return cfg.vision ?? cfg.provider;
+    return cfg.provider;
+}
+export function listProviders(cfg) {
+    const purposesOf = (n) => {
+        const out = [];
+        for (const p of ['chat', 'vision', 'evolve', 'bench']) {
+            const named = cfg.routing?.[p] ?? (p !== 'vision' ? cfg.routing?.chat : undefined);
+            if (named === n)
+                out.push(p);
+        }
+        return out;
+    };
+    if (cfg.providers && Object.keys(cfg.providers).length) {
+        return Object.entries(cfg.providers).map(([name, p]) => ({ name, model: p.model, baseUrl: p.baseUrl, purposes: purposesOf(name) }));
+    }
+    return [{ name: 'default', model: cfg.provider.model, baseUrl: cfg.provider.baseUrl, purposes: ['chat', 'vision', 'evolve', 'bench'] }];
+}
+export const PROVIDER_PRESETS = [
+    { name: 'deepseek', baseUrl: 'https://api.deepseek.com/v1', envVar: 'DEEPSEEK_API_KEY', model: 'deepseek-chat' },
+    { name: 'kimi', baseUrl: 'https://api.moonshot.cn/v1', envVar: 'MOONSHOT_API_KEY', model: 'kimi-latest' },
+    { name: 'glm', baseUrl: 'https://open.bigmodel.cn/api/paas/v4', envVar: 'ZHIPU_API_KEY', model: 'glm-4.7' },
+    { name: 'qwen', baseUrl: 'https://dashscope.aliyuncs.com/compatible-mode/v1', envVar: 'DASHSCOPE_API_KEY', model: 'qwen3-max' },
+    { name: 'openai', baseUrl: 'https://api.openai.com/v1', envVar: 'OPENAI_API_KEY', model: 'gpt-5' },
+    { name: 'siliconflow', baseUrl: 'https://api.siliconflow.cn/v1', envVar: 'SILICONFLOW_API_KEY', model: 'deepseek-ai/DeepSeek-V3.2-Exp' },
+    { name: 'openrouter', baseUrl: 'https://openrouter.ai/api/v1', envVar: 'OPENROUTER_API_KEY', model: 'openrouter/auto' },
+    { name: 'nvidia-nim', baseUrl: 'https://integrate.api.nvidia.com/v1', envVar: 'NVIDIA_API_KEY', model: 'meta/llama-3.2-90b-vision-instruct' },
+    { name: 'groq', baseUrl: 'https://api.groq.com/openai/v1', envVar: 'GROQ_API_KEY', model: 'llama-3.3-70b-versatile' },
+    { name: 'together', baseUrl: 'https://api.together.xyz/v1', envVar: 'TOGETHER_API_KEY', model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo' },
+    { name: 'xai', baseUrl: 'https://api.x.ai/v1', envVar: 'XAI_API_KEY', model: 'grok-4' },
+    { name: 'minimax', baseUrl: 'https://api.minimaxi.com/v1', envVar: 'MINIMAX_API_KEY', model: 'MiniMax-M2' },
+    { name: 'volc-ark', baseUrl: 'https://ark.cn-beijing.volces.com/api/v3', envVar: 'ARK_API_KEY', model: 'doubao-seed-1-6' },
+    { name: 'stepfun', baseUrl: 'https://api.stepfun.com/v1', envVar: 'STEPFUN_API_KEY', model: 'step-3' },
+    { name: 'hunyuan', baseUrl: 'https://api.hunyuan.cloud.tencent.com/v1', envVar: 'HUNYUAN_API_KEY', model: 'hunyuan-turbos-latest' },
+    { name: 'ollama', baseUrl: 'http://127.0.0.1:11434/v1', envVar: '', model: 'qwen3:8b' },
+    { name: 'lm-studio', baseUrl: 'http://127.0.0.1:1234/v1', envVar: '', model: 'local-model' },
+];
+/**
+ * Detect locally available providers, dsh-style: presets whose env var is
+ * set, plus anything configured in ~/.opencode (opencode.json providers).
+ * Already-configured names are excluded. Read-only - callers decide whether
+ * to merge into config via addProviders().
+ */
+export async function detectLocalProviders(cfg, readFileFn) {
+    const known = new Set(Object.keys(cfg.providers ?? {}));
+    const found = [];
+    for (const p of PROVIDER_PRESETS) {
+        if (known.has(p.name))
+            continue;
+        // cloud presets: available when their env var is set; local-inference
+        // presets are intentionally NOT auto-added (caller opts in by hand)
+        if (p.envVar && process.env[p.envVar])
+            found.push(p);
+    }
+    // local OpenAI-compatible gateways: an env key plus a live /v1/models on a
+    // common loopback port (e.g. freellmapi on 3002, ollama on 11434); the
+    // probe negotiates auth (Bearer, then X-Api-Key) and remembers the scheme
+    for (const [envVar, ports] of [
+        ['FREELLM_API_KEY', [3002, 8080]],
+        ['OPENAI_COMPAT_API_KEY', [8080, 3000]],
+    ]) {
+        if (!process.env[envVar] || found.some((x) => x.name === envVar.toLowerCase().replace('_api_key', '')))
+            continue;
+        for (const port of ports) {
+            try {
+                const key = process.env[envVar];
+                let r = await fetch(`http://127.0.0.1:${port}/v1/models`, {
+                    headers: { Authorization: `Bearer ${key}` },
+                    signal: AbortSignal.timeout(800),
+                });
+                let authHeader;
+                if (r.status === 401) {
+                    r = await fetch(`http://127.0.0.1:${port}/v1/models`, {
+                        headers: { 'X-Api-Key': key },
+                        signal: AbortSignal.timeout(800),
+                    });
+                    if (r.ok)
+                        authHeader = 'X-Api-Key';
+                }
+                if (!r.ok)
+                    continue;
+                const d = (await r.json());
+                const model = d.data?.[0]?.id ?? 'auto';
+                found.push({ name: envVar.toLowerCase().replace('_api_key', ''), baseUrl: `http://127.0.0.1:${port}/v1`, envVar: `(local gateway, key from ${envVar})`, model, ...(authHeader ? { authHeader } : {}) });
+                break;
+            }
+            catch {
+                /* port closed - try next */
+            }
+        }
+    }
+    // opencode config carries provider ids + baseURLs + models
+    try {
+        const { homedir } = await import('node:os');
+        const { join } = await import('node:path');
+        for (const f of [join(homedir(), '.opencode', 'opencode.json'), join(process.cwd(), '.opencode.json')]) {
+            let raw;
+            try {
+                raw = await readFileFn(f, 'utf8');
+            }
+            catch {
+                continue;
+            }
+            const oc = JSON.parse(raw);
+            for (const [id, def] of Object.entries(oc.provider ?? {})) {
+                if (known.has(id) || found.some((x) => x.name === id))
+                    continue;
+                const baseURL = def.options?.baseURL ?? '';
+                const firstModel = Object.keys(def.models ?? {})[0] ?? '';
+                if (baseURL && firstModel) {
+                    found.push({ name: id, baseUrl: baseURL, envVar: `(opencode: ${f.includes('.opencode.json') && !f.includes(homedir()) ? 'project' : 'user'})`, model: firstModel });
+                }
+            }
+        }
+    }
+    catch {
+        /* unreadable opencode config is fine */
+    }
+    return found;
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@hmharness/kernel",
+  "version": "0.1.0",
+  "description": "hmharness kernel: tool registry, provider adapters, the agent loop, session log, config. Zero runtime dependencies (Node >=22 native fetch).",
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swsgbl/hmharness.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  }
+}