@hmharness/kernel 0.9.0 → 0.9.1

package/dist/config.d.ts

@@ -28,6 +28,47 @@ export declare function addProviders(items: Array<{
     cfg: HmhConfig;
     added: string[];
 }>;
+/**
+ * Insert or fully replace one provider (web settings center: "保存即生效").
+ * apiKey omitted/empty keeps the existing key — the UI never round-trips
+ * secrets. Returns the refreshed config; throws on bad names.
+ */
+export declare function upsertProvider(input: {
+    name: string;
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    purposes?: string[];
+}): Promise<HmhConfig>;
+/**
+ * Save (upsert) one named provider for the web/TUI settings center.
+ * Semantics differ from upsertProvider on the secret key: `apiKey ===
+ * undefined` (form field left blank) KEEPS the existing key, while
+ * `apiKey === ''` DELETES it. Optional fields (authHeader, timeoutMs,
+ * contextWindow, supportsVision) are only written when provided. Returns
+ * the refreshed config; throws on invalid names/baseUrl/model.
+ */
+export declare function saveProvider(name: string, p: {
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    authHeader?: string;
+    timeoutMs?: number;
+    contextWindow?: number;
+    supportsVision?: boolean;
+}): Promise<HmhConfig>;
+/** Remove a provider (web settings center). Routing keys that pointed at it
+ *  (chat/vision/evolve/bench) are removed with it instead of being left
+ *  dangling. Returns the refreshed config. */
+export declare function deleteProvider(name: string): Promise<HmhConfig>;
+/**
+ * Generic in-place config patch (web settings center): read the raw JSON,
+ * Object.assign the top-level keys, shallow-merge `evolution` separately,
+ * write back and return loadConfig(). The CALLER is responsible for only
+ * passing whitelisted keys (this function validates nothing). `theme` is a
+ * plain top-level key and flows through the top-level assign.
+ */
+export declare function patchConfig(partial: Record<string, unknown>): Promise<HmhConfig>;
 export declare function initHome(): Promise<{
     home: string;
     created: string[];

package/dist/config.js

@@ -105,6 +105,143 @@ export async function addProviders(items) {
     await writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8');
     return { cfg: await loadConfig(), added };
 }
+/**
+ * Insert or fully replace one provider (web settings center: "保存即生效").
+ * apiKey omitted/empty keeps the existing key — the UI never round-trips
+ * secrets. Returns the refreshed config; throws on bad names.
+ */
+export async function upsertProvider(input) {
+    const name = String(input.name ?? '').trim();
+    const baseUrl = String(input.baseUrl ?? '').trim().replace(/\/+$/, '');
+    const model = String(input.model ?? '').trim();
+    if (!/^[a-zA-Z0-9_-]{1,48}$/.test(name))
+        throw new Error('provider name must be 1-48 chars of [a-zA-Z0-9_-]');
+    if (!/^https?:\/\//.test(baseUrl))
+        throw new Error('baseUrl must start with http(s)://');
+    if (!model)
+        throw new Error('model required');
+    const file = join(homeDir(), 'config.json');
+    let raw = {};
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        /* fresh config */
+    }
+    const providers = (raw.providers ?? {});
+    const existing = (providers[name] ?? {});
+    const next = {
+        baseUrl,
+        model,
+        // empty apiKey in the form = keep whatever was configured (never blank a key)
+        ...(input.apiKey ? { apiKey: input.apiKey } : existing.apiKey ? { apiKey: existing.apiKey } : {}),
+        ...(existing.authHeader ? { authHeader: existing.authHeader } : {}),
+        ...(existing.timeoutMs ? { timeoutMs: existing.timeoutMs } : {}),
+        ...(existing.supportsVision ? { supportsVision: existing.supportsVision } : {}),
+        ...(input.purposes?.length ? { purposes: input.purposes } : existing.purposes ? { purposes: existing.purposes } : {}),
+    };
+    providers[name] = next;
+    raw.providers = providers;
+    await writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    return loadConfig();
+}
+/**
+ * Save (upsert) one named provider for the web/TUI settings center.
+ * Semantics differ from upsertProvider on the secret key: `apiKey ===
+ * undefined` (form field left blank) KEEPS the existing key, while
+ * `apiKey === ''` DELETES it. Optional fields (authHeader, timeoutMs,
+ * contextWindow, supportsVision) are only written when provided. Returns
+ * the refreshed config; throws on invalid names/baseUrl/model.
+ */
+export async function saveProvider(name, p) {
+    if (!name || !/^[a-zA-Z0-9_-]+$/.test(name))
+        throw new Error('invalid provider name');
+    if (!/^https?:\/\//.test(p.baseUrl))
+        throw new Error('baseUrl must start with http:// or https://');
+    if (!p.model)
+        throw new Error('model must not be empty');
+    const file = join(homeDir(), 'config.json');
+    let raw = {};
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        /* fresh config */
+    }
+    const providers = (raw.providers ?? {});
+    const existing = (providers[name] ?? {});
+    const next = {
+        baseUrl: p.baseUrl,
+        model: p.model,
+        // apiKey === undefined: keep the existing key (edit form left blank).
+        // apiKey === '': explicitly clear it (delete the key).
+        ...(p.apiKey !== undefined
+            ? (p.apiKey !== '' ? { apiKey: p.apiKey } : {})
+            : existing.apiKey !== undefined ? { apiKey: existing.apiKey } : {}),
+        ...(p.authHeader ? { authHeader: p.authHeader } : {}),
+        ...(p.timeoutMs !== undefined ? { timeoutMs: p.timeoutMs } : {}),
+        ...(p.contextWindow !== undefined ? { contextWindow: p.contextWindow } : {}),
+        ...(p.supportsVision !== undefined ? { supportsVision: p.supportsVision } : {}),
+    };
+    providers[name] = next;
+    raw.providers = providers;
+    await writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    return loadConfig();
+}
+/** Remove a provider (web settings center). Routing keys that pointed at it
+ *  (chat/vision/evolve/bench) are removed with it instead of being left
+ *  dangling. Returns the refreshed config. */
+export async function deleteProvider(name) {
+    const file = join(homeDir(), 'config.json');
+    let raw = {};
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        /* fresh config */
+    }
+    const providers = (raw.providers ?? {});
+    if (!(name in providers))
+        throw new Error(`unknown provider "${name}"`);
+    delete providers[name];
+    raw.providers = providers;
+    const routing = (raw.routing ?? {});
+    let routingTouched = false;
+    for (const key of ['chat', 'vision', 'evolve', 'bench']) {
+        if (routing[key] === name) {
+            delete routing[key];
+            routingTouched = true;
+        }
+    }
+    if (routingTouched)
+        raw.routing = routing;
+    await writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    return loadConfig();
+}
+/**
+ * Generic in-place config patch (web settings center): read the raw JSON,
+ * Object.assign the top-level keys, shallow-merge `evolution` separately,
+ * write back and return loadConfig(). The CALLER is responsible for only
+ * passing whitelisted keys (this function validates nothing). `theme` is a
+ * plain top-level key and flows through the top-level assign.
+ */
+export async function patchConfig(partial) {
+    const file = join(homeDir(), 'config.json');
+    let raw = {};
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        /* fresh config */
+    }
+    const { evolution, ...top } = partial;
+    Object.assign(raw, top);
+    if (evolution !== undefined && typeof evolution === 'object' && evolution !== null) {
+        raw.evolution = { ...(raw.evolution ?? {}), ...evolution };
+    }
+    await writeFile(file, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+    return loadConfig();
+}
 export async function initHome() {
     const home = homeDir();
     const created = [];

package/dist/goal.d.ts

@@ -0,0 +1,12 @@
+export type GoalStore = {
+    [sessionId: string]: {
+        goal: string;
+        time: string;
+    };
+};
+/** The persisted goal for one session, or null when unset/unreadable. */
+export declare function getGoal(home: string, sessionId: string): Promise<string | null>;
+/** Persist (or, with an empty goal, clear) one session's goal. */
+export declare function setGoal(home: string, sessionId: string, goal: string): Promise<void>;
+/** Remove one session's goal (no-op when it has none). */
+export declare function clearGoal(home: string, sessionId: string): Promise<void>;

package/dist/goal.js

@@ -0,0 +1,47 @@
+/**
+ * @hmharness/kernel - goal
+ * Session-level goal store: HMH_HOME/goals.json maps sessionId -> goal
+ * ({ goal, time }). Web/TUI persist a goal when a session starts (or a run
+ * is forked); the agent runner reads it so the goal survives across turns,
+ * resumes and restarts. All IO is plain readFile/writeFile - a corrupt file
+ * degrades to null / an empty store rebuilt on the next write, never throws.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+async function readStore(file) {
+    try {
+        const parsed = JSON.parse(await readFile(file, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        // missing or corrupt file = empty store (rebuilt on the next write)
+        return {};
+    }
+}
+/** The persisted goal for one session, or null when unset/unreadable. */
+export async function getGoal(home, sessionId) {
+    const store = await readStore(join(home, 'goals.json'));
+    const entry = store[sessionId];
+    return typeof entry?.goal === 'string' ? entry.goal : null;
+}
+/** Persist (or, with an empty goal, clear) one session's goal. */
+export async function setGoal(home, sessionId, goal) {
+    const file = join(home, 'goals.json');
+    const store = await readStore(file);
+    if (!goal) {
+        delete store[sessionId];
+    }
+    else {
+        store[sessionId] = { goal, time: new Date().toISOString() };
+    }
+    await writeFile(file, JSON.stringify(store, null, 2) + '\n', 'utf8');
+}
+/** Remove one session's goal (no-op when it has none). */
+export async function clearGoal(home, sessionId) {
+    const file = join(home, 'goals.json');
+    const store = await readStore(file);
+    delete store[sessionId];
+    await writeFile(file, JSON.stringify(store, null, 2) + '\n', 'utf8');
+}

package/dist/index.d.ts

@@ -9,3 +9,4 @@ export * from './router.ts';
 export * from './config.ts';
 export * from './context.ts';
 export * from './mcp.ts';
+export * from './goal.ts';

package/dist/index.js

@@ -9,3 +9,4 @@ export * from "./router.js";
 export * from "./config.js";
 export * from "./context.js";
 export * from "./mcp.js";
+export * from "./goal.js";

package/dist/loop.d.ts

@@ -8,6 +8,10 @@ export interface LoopEvents {
     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;
+    /** Fired when an injected user message entered the working transcript
+     *  (web Ctrl+Enter / TUI Enter-while-running). The message is appended
+     *  after the previous tool batch, before the next model call. */
+    onInjected?(message: string): void;
     onFinal?(text: string, turns: number): void;
 }
 export interface LoopApproval {
@@ -61,4 +65,18 @@ export declare function runLoop(opts: {
     maxIdleTurns?: number;
     /** Hard total token spend cap (default: 50M — generous enough for days). */
     maxTotalTokens?: number;
+    /** Injected user messages (web Ctrl+Enter / TUI Enter-while-running):
+     *  called after every tool-result batch; the returned string (or null)
+     *  is appended to the working transcript as a user message before the
+     *  next model call. Absent -> no injection support (codex-style runtime
+     *  steering disabled). */
+    injectQueue?: () => string | null;
+    /** Polled at every turn boundary (and before the first model call): user
+     *  texts injected into the RUNNING loop (codex Enter-inject semantics).
+     *  poll() drains its pending queue; each entry becomes a user turn. */
+    injections?: {
+        poll(): Array<{
+            text: string;
+        }>;
+    };
 }): Promise<LoopResult>;

package/dist/loop.js

@@ -47,6 +47,14 @@ export async function runLoop(opts) {
             reason = 'interrupted';
             break;
         }
+        // Mid-run injection drain (codex Enter-inject semantics): entries queued
+        // while the previous round's model request / tool batch was in flight
+        // join the transcript here, so the NEXT model call sees them. An
+        // injection never affects a request already issued this round.
+        for (const inj of opts.injections?.poll() ?? []) {
+            working.push({ role: 'user', content: inj.text });
+            events?.onInjected?.(inj.text);
+        }
         const compacted = opts.summarizeContext
             ? await compactWithDigest(working, budget, opts.summarizeContext)
             : compactMessages(working, budget);
@@ -89,6 +97,15 @@ export async function runLoop(opts) {
         const calls = message.tool_calls ?? [];
         if (calls.length === 0) {
             const text = message.content ?? '';
+            // A runtime-steering injection may have arrived while this turn was in
+            // flight; honor it by continuing instead of ending (codex Enter while
+            // the last answer streams). Only end when the queue is empty.
+            const pending = opts.injectQueue?.();
+            if (pending) {
+                working.push({ role: 'user', content: pending });
+                events?.onInjected?.(pending);
+                continue;
+            }
             events?.onFinal?.(text, turn);
             return { text, turns: turn, toolUses, messages: working, usage, reason: 'final' };
         }
@@ -152,6 +169,14 @@ export async function runLoop(opts) {
                 content: p.output.length > 60_000 ? p.output.slice(0, 60_000) + '\n...[truncated]' : p.output,
             });
         }
+        // Runtime steering (codex Enter-while-running): a user message injected
+        // during the tool batch joins the transcript here, so the NEXT model call
+        // already sees it. Multiple pushes are drained in FIFO order.
+        const injected = opts.injectQueue?.();
+        if (injected) {
+            working.push({ role: 'user', content: injected });
+            events?.onInjected?.(injected);
+        }
         // Idle detection: count consecutive turns where NO tool succeeded. A
         // productive agent always has at least one successful call; N consecutive
         // all-fail/all-skip turns = the agent is stuck in a loop (this replaces

package/dist/types.d.ts

@@ -101,6 +101,8 @@ export interface HmhConfig {
     visionFallbacks?: ProviderConfig[];
     /** UI + system-prompt language. Default 'zh'. */
     locale?: 'zh' | 'en';
+    /** UI theme preference: 'dark' (default) | 'light' | 'system'. */
+    theme?: 'dark' | 'light' | 'system';
     /** 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/kernel",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "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",