@hmharness/agent 0.19.0 → 0.19.2

package/dist/cognitive-recorder.d.ts

@@ -0,0 +1,23 @@
+export declare class CognitiveRunRecorder {
+    private home;
+    private cwd;
+    private rec;
+    private store;
+    private open;
+    private seq;
+    private failures;
+    private successes;
+    constructor(home: string, task: string, sessionId: string, cwd: string);
+    /** loop onToolCall: open a step for this tool invocation */
+    call(toolName: string, args: Record<string, unknown>): void;
+    /** loop onToolResult: close the matching step (same tool, FIFO) */
+    result(toolName: string, _output: string, isError: boolean): void;
+    /** task end: persist trajectory + episodic memory index entry */
+    finish(success: boolean, meta: {
+        turns: number;
+        toolUses: number;
+        task: string;
+    }): Promise<{
+        trajectoryId: string;
+    } | null>;
+}

package/dist/cognitive-recorder.js

@@ -0,0 +1,97 @@
+/**
+ * @hmharness/agent - cognitive run recorder (blueprint CL-001 / MEM-002)
+ *
+ * Bridges the LIVE agent loop into the Cognitive OS: every tool call becomes
+ * a cognitive trajectory step (action type = tool name, reason = the loop's
+ * own event context), and at task end the trajectory lands in the episodic
+ * store (HMH_HOME/cognitive/trajectories/) PLUS an episodic memory index
+ * entry with full provenance (source/provenance/confidence/timestamp/
+ * environment/session — MEM-007). Everything here is best-effort: cognitive
+ * recording must never break a task run.
+ */
+import { TrajectoryStore, TrajectoryRecorder, CognitiveMemory } from '@hmharness/cognitive';
+export class CognitiveRunRecorder {
+    home;
+    cwd;
+    rec;
+    store;
+    open = new Map();
+    seq = 0;
+    failures = 0;
+    successes = 0;
+    constructor(home, task, sessionId, cwd) {
+        this.home = home;
+        this.cwd = cwd;
+        this.store = new TrajectoryStore(home);
+        this.rec = new TrajectoryRecorder(`trj-${sessionId}-${Date.now().toString(36)}`, sessionId, { id: 'terminal', version: '1.0.0' }, { id: `goal-${sessionId}`, description: task });
+    }
+    /** loop onToolCall: open a step for this tool invocation */
+    call(toolName, args) {
+        const key = `${toolName}#${++this.seq}`;
+        this.open.set(key, {
+            action: { id: key, type: toolName, args: clip(args), reason: 'agent loop tool call' },
+            startedAt: Date.now(),
+        });
+    }
+    /** loop onToolResult: close the matching step (same tool, FIFO) */
+    result(toolName, _output, isError) {
+        for (const [key, open] of this.open) {
+            if (!key.startsWith(`${toolName}#`))
+                continue;
+            this.open.delete(key);
+            if (isError)
+                this.failures += 1;
+            else
+                this.successes += 1;
+            this.rec.record({
+                action: open.action,
+                outcome: isError ? 'failure' : 'success',
+                evidence: [],
+                durationMs: Date.now() - open.startedAt,
+            });
+            return;
+        }
+        // result without a matching open call (e.g. preflight rejection): still
+        // record it so denials are visible in the trajectory
+        this.rec.record({
+            action: { id: `${toolName}#${++this.seq}`, type: toolName, args: {}, reason: 'tool result without recorded call' },
+            outcome: isError ? 'failure' : 'success',
+            evidence: [],
+        });
+    }
+    /** task end: persist trajectory + episodic memory index entry */
+    async finish(success, meta) {
+        try {
+            const traj = this.rec.finish(success);
+            // recovery heuristic: a success step that follows a failure step was
+            // already counted by TrajectoryRecorder; metrics carry it
+            const written = await this.store.append(traj);
+            if (!written.ok)
+                return null;
+            const mem = new CognitiveMemory(this.home);
+            await mem.load();
+            await mem.write({
+                layer: 'episodic',
+                content: `${success ? 'OK' : 'FAIL'} ${meta.toolUses} tools/${meta.turns} turns: ${meta.task.slice(0, 120)}`,
+                payload: { trajectoryId: traj.id, tools: meta.toolUses, turns: meta.turns, successes: this.successes, failures: this.failures },
+                source: 'agent-run',
+                provenance: `trajectory:${traj.id}`,
+                confidence: success ? 0.9 : 0.6,
+                environment: 'terminal',
+                session: traj.sessionId,
+                tags: ['run', success ? 'ok' : 'fail'],
+            });
+            return { trajectoryId: traj.id };
+        }
+        catch {
+            return null; // cognitive recording is best-effort, never fatal
+        }
+    }
+}
+function clip(args) {
+    const out = {};
+    for (const [k, v] of Object.entries(args ?? {}).slice(0, 12)) {
+        out[k] = typeof v === 'string' ? v.slice(0, 200) : v;
+    }
+    return out;
+}

package/dist/cognitive-tools.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @hmharness/agent - cognitive query tool (blueprint §18/UX-004 seed)
+ *
+ * Gives the LIVE model read access to its own accumulated world model:
+ * which tool types historically succeed, how calibrated its predictions
+ * are, and what the diagnosis layer thinks is worth learning. Read-only by
+ * design — the model cannot write beliefs; those update only from real
+ * trajectories (no self-grading channel).
+ */
+import type { Tool } from '@hmharness/kernel';
+export declare const cognitiveQueryTool: Tool;

package/dist/cognitive-tools.js

@@ -0,0 +1,53 @@
+export const cognitiveQueryTool = {
+    name: 'cognitive_query',
+    description: 'Query the cognitive layer\'s accumulated knowledge about past runs: which action/tool types historically succeed (belief table with confidence and evidence counts), prediction calibration, planner-trusted action types, learning opportunities, and memory contradictions. Read-only. Args: focus=beliefs|calibration|diagnosis|memory (optional; omit for a summary).',
+    parameters: {
+        type: 'object',
+        properties: {
+            focus: { type: 'string', description: 'beliefs | calibration | diagnosis | memory (optional)' },
+        },
+    },
+    async execute(args, ctx) {
+        const focus = String(args.focus ?? 'summary');
+        try {
+            const { analyzeWorldModel, diagnoseOpportunities, CognitiveMemory } = await import('@hmharness/cognitive');
+            const lines = [];
+            if (focus === 'summary' || focus === 'beliefs') {
+                const wm = await analyzeWorldModel(ctx.home);
+                lines.push(`world model (${wm.trajectoriesReplayed} trajectories, ${wm.stepsReplayed} steps replayed):`);
+                if (wm.beliefs.length === 0)
+                    lines.push('  (no beliefs yet — run a few tasks first)');
+                for (const b of wm.beliefs.slice(0, 12)) {
+                    lines.push(`  ${b.actionType.padEnd(24)} conf=${b.confidence.toFixed(2)} n=${b.evidenceCount}`);
+                }
+                if (focus === 'beliefs') {
+                    lines.push(`planner gate: trusted=[${wm.plannerGate.trusted.join(',')}] untrusted=[${wm.plannerGate.untrusted.join(',')}] unknown=[${wm.plannerGate.unknown.join(',')}]`);
+                }
+            }
+            if (focus === 'summary' || focus === 'calibration') {
+                const wm = await analyzeWorldModel(ctx.home);
+                const cal = wm.calibration;
+                lines.push(`calibration: ${cal.resolved} resolved predictions${cal.meanError !== undefined ? `, mean |error|=${cal.meanError}` : ' (no predictions recorded yet — steps carry no confidence)'}`);
+            }
+            if (focus === 'summary' || focus === 'diagnosis') {
+                const d = await diagnoseOpportunities(ctx.home);
+                lines.push(`diagnosis (${d.trajectories} trajectories):`);
+                if (d.opportunities.length === 0)
+                    lines.push('  (no learning opportunity meets the evidence threshold yet)');
+                for (const o of d.opportunities.slice(0, 6)) {
+                    lines.push(`  [${o.suggestedTargets.join('/')}] ${o.signal}`);
+                }
+            }
+            if (focus === 'summary' || focus === 'memory') {
+                const mem = new CognitiveMemory(ctx.home);
+                await mem.load();
+                const stats = mem.stats();
+                lines.push(`memory: working:${stats.working} episodic:${stats.episodic} semantic:${stats.semantic} procedural:${stats.procedural} world:${stats.world}, contradictions pending: ${mem.detectContradictions().length}`);
+            }
+            return { output: lines.join('\n') };
+        }
+        catch (err) {
+            return { output: 'cognitive_query failed: ' + String(err).slice(0, 200), isError: true };
+        }
+    },
+};

package/dist/i18n.d.ts

@@ -86,6 +86,7 @@ export interface Strings {
     cmdStatusline: string;
     cmdKeymap: string;
     cmdRemote: string;
+    cmdCognitive: string;
     cmdReview: string;
     cmdModelHint: string;
     /** palette footer key hint: how to drive the slash/model picker (TUI) */

package/dist/i18n.js

@@ -70,6 +70,7 @@ const zh = {
     cmdStatusline: '自定义底栏字段(/statusline "{model} · {cwd}")',
     cmdKeymap: '查看/重映射动作键(/keymap <action>=<key>)',
     cmdRemote: '手机配对二维码/远程连接(/remote lan|wan)',
+    cmdCognitive: '认知子系统状态面板(/cognitive)',
     cmdReview: '一键发起「审查当前工作树」任务',
     cmdModelHint: '切换 chat 路由: /model <name>',
     panelHint: '↑↓/滚轮/点击 选择 · Enter 确认 · Esc 关闭',
@@ -221,6 +222,7 @@ const en = {
     cmdStatusline: 'custom bottom-line fields (/statusline "{model} · {cwd}")',
     cmdKeymap: 'view/remap action keys (/keymap <action>=<key>)',
     cmdRemote: 'phone pairing QR / remote connect (/remote lan|wan)',
+    cmdCognitive: 'cognitive subsystem status panel (/cognitive)',
     cmdReview: 'one-click "review the current worktree" task',
     cmdModelHint: 'switch chat route: /model <name>',
     panelHint: '↑↓ / wheel / click to select · Enter confirms · Esc closes',

package/dist/runner.js

@@ -7,6 +7,7 @@
  */
 import { homeDir, loadConfig, resolveProvider, getGoal, mcpServerTools, Registry, runLoop, Session, } from '@hmharness/kernel';
 import { brief, createTrajectoryRecorder } from '@hmharness/observability';
+import { CognitiveRunRecorder } from "./cognitive-recorder.js";
 import { readFile } from 'node:fs/promises';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
@@ -259,6 +260,10 @@ export async function runAgentTask(opts) {
     // are swallowed inside the recorder and can never fail the task itself.
     const traj = createTrajectoryRecorder(ctx.home, { task: opts.task, model: cfg.provider.model, cwd: ctx.cwd });
     traj.emit('run.started', 'user', { task: brief(opts.task, 400) });
+    // Cognitive OS (blueprint 2026-09 CL-001): the same tool-call stream also
+    // feeds the COGNITIVE trajectory store + episodic memory index, so goal/
+    // exploration/learning layers have real data from day one. Best-effort.
+    const cogRec = new CognitiveRunRecorder(ctx.home, opts.task, session.id, ctx.cwd);
     // V2 M10 shadow router: log what the adaptive router WOULD pick vs the live
     // static route - data for a later, gated switch (never steers traffic now)
     {
@@ -381,6 +386,7 @@ export async function runAgentTask(opts) {
             onToolCall: (name, args) => {
                 toolsUsed.push(name);
                 traj.emit('tool.requested', 'tool', { name, args: brief(args, 120) });
+                cogRec.call(name, args);
                 events.onToolCall?.(name, args);
             },
             onToolResult: (name, output, isError) => {
@@ -392,6 +398,7 @@ export async function runAgentTask(opts) {
                 }
                 void session.tool(name, output, isError);
                 traj.emit('tool.completed', 'tool', { name, isError, preview: brief(output, 120) });
+                cogRec.result(name, output, isError);
                 events.onToolResult?.(name, output, isError);
             },
             onApproval: (name, args, granted) => {
@@ -416,6 +423,9 @@ export async function runAgentTask(opts) {
     if (injectChannel)
         injectChannel.active = false;
     traj.finish({ success: result.reason === 'final', reason: result.reason }, { turns: result.turns, toolUses: result.toolUses, promptTokens: result.usage.promptTokens, completionTokens: result.usage.completionTokens });
+    // cognitive trajectory + episodic index land AFTER the observability
+    // recorder settles, still before onFinal so callers can rely on both
+    await cogRec.finish(result.reason === 'final', { turns: result.turns, toolUses: result.toolUses, task: opts.task });
     // routing.outcome backfill: did the ACTUAL route succeed? (shadow stats)
     {
         const routing = cfg.routing ?? {};

package/dist/tools.js

@@ -9,6 +9,7 @@ import { copyFile, readFile, readdir, writeFile } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
 import { promisify } from 'node:util';
 import { chatVision, homeDir, isBareProbe, isVisionRefusal, loadConfig, visionProviderChain } from '@hmharness/kernel';
+import { cognitiveQueryTool } from "./cognitive-tools.js";
 const execCb = promisify(exec);
 const DENY_PATTERNS = [
     // recursive deletes aimed at ROOT/HOME/SYSTEM targets only - relative
@@ -662,4 +663,5 @@ export const seeImageTool = {
 export const baseTools = [
     readFileTool, editFileTool, writeFileTool, listDirTool, runCommandTool, rememberTool, seeImageTool,
     webSearchTool, webFetchTool, browserOpenTool, desktopScreenshotTool, desktopClickTool, desktopTypeTool, sshRunTool,
+    cognitiveQueryTool,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/agent",
-  "version": "0.19.0",
+  "version": "0.19.2",
   "description": "hmharness agent execution layer: base tools, system prompt, sub-agent spawn, and the shared task runner that frontends (cli, web) drive.",
   "type": "module",
   "main": "dist/index.js",
@@ -15,12 +15,13 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/domain-harmony": "0.19.0",
-    "@hmharness/domain-ops": "0.19.0",
-    "@hmharness/evolution": "0.19.0",
-    "@hmharness/kernel": "0.19.0",
-    "@hmharness/observability": "0.19.0",
-    "@hmharness/sandbox": "0.19.0"
+    "@hmharness/cognitive": "0.19.2",
+    "@hmharness/domain-harmony": "0.19.2",
+    "@hmharness/domain-ops": "0.19.2",
+    "@hmharness/evolution": "0.19.2",
+    "@hmharness/kernel": "0.19.2",
+    "@hmharness/observability": "0.19.2",
+    "@hmharness/sandbox": "0.19.2"
   },
   "files": [
     "dist"