@hmharness/agent 0.19.6 → 0.19.8

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export { mechanicalGate, parseVerdict, runPipeline, type PipelineOptions, type P
 export { buildSystemPrompt } from './prompt.js';
 export { strings, type Locale, type Strings } from './i18n.js';
 export { makeSpawnTool, MAX_SPAWN_DEPTH, type SpawnBase } from './spawn.js';
+export { withTopologyGovernance, mapRole, liveTopologySnapshot, teamLog } from './topology-live.js';
 export { buildRegistry, contextPack, makeApproval, liveYolo, nativeRegistry, runAgentTask, spawnBase, toServerConfig, type AgentTaskOptions, type RunnerEvents, } from './runner.js';
 export * from './skills-conformance.js';
 export * from './acp.js';

package/dist/index.js

@@ -5,6 +5,7 @@ export { mechanicalGate, parseVerdict, runPipeline, } from "./pipeline.js";
 export { buildSystemPrompt } from "./prompt.js";
 export { strings } from "./i18n.js";
 export { makeSpawnTool, MAX_SPAWN_DEPTH } from "./spawn.js";
+export { withTopologyGovernance, mapRole, liveTopologySnapshot, teamLog } from "./topology-live.js";
 export { buildRegistry, contextPack, makeApproval, liveYolo, nativeRegistry, runAgentTask, spawnBase, toServerConfig, } from "./runner.js";
 export * from "./skills-conformance.js";
 export * from "./acp.js";

package/dist/rlm-tool.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @hmharness/agent - RLM workspace tool (blueprint M5 / RLM-001..010 live)
+ *
+ * Gives the LIVE model a persistent, programmable cognitive workspace for
+ * the duration of a task: set/get variables, eval sandboxed code against
+ * them, checkpoint/restore, fork. The runtime enforces the budget and
+ * freezes its governance state — the model composes context, it can never
+ * rewrite the meter (no hidden unsafe self-modification, RLM-008).
+ *
+ * One workspace per session (spawned subagents share the parent's by home
+ * key — deliberately: delegation sees the same whiteboard).
+ */
+import type { Tool } from '@hmharness/kernel';
+export declare const rlmWorkspaceTool: Tool;

package/dist/rlm-tool.js

@@ -0,0 +1,89 @@
+import { RLMRuntime } from '@hmharness/cognitive';
+const workspaces = new Map();
+function wsFor(home) {
+    let ws = workspaces.get(home);
+    if (!ws) {
+        ws = new RLMRuntime({ maxEvals: 200, maxWallMs: 30 * 60_000, maxSubagents: 0 });
+        workspaces.set(home, ws);
+    }
+    return ws;
+}
+export const rlmWorkspaceTool = {
+    name: 'rlm_workspace',
+    description: 'Persistent structured workspace for THIS task: variables survive between calls (unlike your context window). ' +
+        'Actions: set(name,value) / get(name) / list() / eval(code — JS, `ctx.vars` holds the variables, return a value) / ' +
+        'checkpoint(label?) / restore(checkpointId) / reset(). Use it to accumulate findings, counts, plans, intermediate ' +
+        'results across many tool calls, then eval a composition over them. eval is sandboxed and budget-metered.',
+    parameters: {
+        type: 'object',
+        properties: {
+            action: { type: 'string', description: 'set | get | list | eval | checkpoint | restore | reset' },
+            name: { type: 'string', description: 'variable name (set/get)' },
+            value: { type: 'string', description: 'value to set (stored as string; eval can JSON.parse)' },
+            code: { type: 'string', description: 'eval body: `return ...` over ctx.vars' },
+            checkpointId: { type: 'string', description: 'restore target (from checkpoint result)' },
+            label: { type: 'string', description: 'checkpoint label' },
+        },
+        required: ['action'],
+    },
+    async execute(args, ctx) {
+        const action = String(args.action ?? '');
+        const ws = wsFor(ctx.home);
+        try {
+            switch (action) {
+                case 'set': {
+                    const name = String(args.name ?? '');
+                    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+                        return { output: `invalid variable name '${name}'`, isError: true };
+                    ws.set(name, String(args.value ?? ''));
+                    return { output: `set ${name} (${String(args.value ?? '').length} chars)` };
+                }
+                case 'get': {
+                    const v = ws.get(String(args.name ?? ''));
+                    if (v === undefined)
+                        return { output: `undefined`, isError: true };
+                    return { output: typeof v === 'string' ? v : JSON.stringify(v) };
+                }
+                case 'list':
+                    return { output: ws.names().length ? ws.names().join(', ') : '(empty)' };
+                case 'eval': {
+                    const code = String(args.code ?? '');
+                    if (!code.trim())
+                        return { output: 'code required', isError: true };
+                    const r = await ws.eval(code);
+                    if (!r.ok)
+                        return { output: `eval failed [${r.error?.code}]: ${r.error?.message}`, isError: true };
+                    const text = r.value === undefined ? 'undefined' : typeof r.value === 'string' ? r.value : JSON.stringify(r.value);
+                    return { output: text.length > 8_000 ? text.slice(0, 8_000) + '…[truncated]' : text };
+                }
+                case 'checkpoint': {
+                    const cp = ws.checkpoint(args.label ? String(args.label) : undefined);
+                    checkpoints.set(`${ctx.home}::${cp.id}`, cp);
+                    return { output: `checkpoint ${cp.id}${cp.label ? ` (${cp.label})` : ''} — restore with checkpointId=${cp.id}` };
+                }
+                case 'restore': {
+                    const id = String(args.checkpointId ?? '');
+                    if (!id)
+                        return { output: 'checkpointId required', isError: true };
+                    // restore needs the checkpoint object; keep an id->cp map on the tool side
+                    const cp = checkpoints.get(`${ctx.home}::${id}`);
+                    if (!cp)
+                        return { output: `unknown checkpoint ${id} (checkpoints live in-process)`, isError: true };
+                    ws.restore(cp);
+                    return { output: `restored ${id}` };
+                }
+                case 'reset': {
+                    workspaces.delete(ctx.home);
+                    checkpoints.delete(ctx.home);
+                    return { output: 'workspace cleared' };
+                }
+                default:
+                    return { output: `unknown action '${action}' (set|get|list|eval|checkpoint|restore|reset)`, isError: true };
+            }
+        }
+        catch (err) {
+            return { output: 'rlm_workspace failed: ' + String(err).slice(0, 200), isError: true };
+        }
+    },
+};
+const checkpoints = new Map();

package/dist/runner.js

@@ -21,6 +21,7 @@ import { baseTools } from "./tools.js";
 import { buildSystemPrompt } from "./prompt.js";
 import { strings } from "./i18n.js";
 import { makeSpawnTool, MAX_SPAWN_DEPTH } from "./spawn.js";
+import { withTopologyGovernance } from "./topology-live.js";
 /** Flatten the config.json shape into the runtime discriminated union. */
 export function toServerConfig(c) {
     if (c.type === 'http')
@@ -36,14 +37,17 @@ export function nativeRegistry(depth) {
     const reg = new Registry();
     reg.registerAll(baseTools).registerAll(harmonyTools).registerAll(opsTools);
     if (depth < MAX_SPAWN_DEPTH) {
-        reg.register(makeSpawnTool({
+        // blueprint M10: every spawn_agent is governed by the live topology
+        // (role contract + shared budget + immutable multi-agent.jsonl audit);
+        // governance failure falls back to the bare spawn (never blocks work)
+        reg.register(withTopologyGovernance(makeSpawnTool({
             depth,
             getBase: () => spawnBase.current ?? {
                 provider: { baseUrl: '', apiKey: '', model: '' },
                 ctx: { cwd: process.cwd(), home: homeDir() },
             },
             buildChildRegistry: nativeRegistry,
-        }));
+        })));
     }
     return reg;
 }

package/dist/tools.js

@@ -10,6 +10,7 @@ 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";
+import { rlmWorkspaceTool } from "./rlm-tool.js";
 const execCb = promisify(exec);
 const DENY_PATTERNS = [
     // recursive deletes aimed at ROOT/HOME/SYSTEM targets only - relative
@@ -663,5 +664,5 @@ export const seeImageTool = {
 export const baseTools = [
     readFileTool, editFileTool, writeFileTool, listDirTool, runCommandTool, rememberTool, seeImageTool,
     webSearchTool, webFetchTool, browserOpenTool, desktopScreenshotTool, desktopClickTool, desktopTypeTool, sshRunTool,
-    cognitiveQueryTool,
+    cognitiveQueryTool, rlmWorkspaceTool,
 ];

package/dist/topology-live.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @hmharness/agent - live multi-agent governance (blueprint §11 / MA-001..010)
+ *
+ * Wraps the REAL spawn_agent tool with blueprint-2.0 governance: every spawn
+ * becomes a topology node with a role contract (timeout/budget/heartbeat),
+ * spends from the shared blackboard budget, and appends an immutable event
+ * to cognitive/multi-agent.jsonl — process-agnostic, so the CLI and web
+ * panel can replay any run's team structure long after it finished.
+ *
+ * v1 heartbeat = start/finish stamps (subagents are short-lived); the
+ * watchdog threshold (3x the 30s role interval) only bites on stuck nodes.
+ */
+import type { Tool } from '@hmharness/kernel';
+import { type AgentRoleName } from '@hmharness/cognitive';
+/** map the tool-facing role vocabulary onto blueprint roles */
+export declare function mapRole(raw: string): AgentRoleName;
+export declare function liveTopologySnapshot(): {
+    goal: string;
+    createdAt: string;
+    nodes: Array<{
+        id: string;
+        role: string;
+        status: string;
+        startedAt?: string;
+        endedAt?: string;
+        failure?: {
+            code: string;
+            message: string;
+        };
+    }>;
+} | null;
+export declare function teamLog(limit?: number): Promise<Array<Record<string, unknown>>>;
+/** Wrap a spawn-like tool with topology governance. Non-fatal by contract:
+ *  governance failures never break the underlying spawn. */
+export declare function withTopologyGovernance(tool: Tool, opts?: {
+    task?: () => string;
+}): Tool;

package/dist/topology-live.js

@@ -0,0 +1,111 @@
+import { appendFile, mkdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homeDir } from '@hmharness/kernel';
+import { defineTopology, AgentTopology } from '@hmharness/cognitive';
+/** map the tool-facing role vocabulary onto blueprint roles */
+export function mapRole(raw) {
+    const r = raw.toLowerCase();
+    if (r.includes('plan'))
+        return 'planner';
+    if (r.includes('test') || r.includes('verif') || r.includes('judge'))
+        return 'verifier';
+    if (r.includes('review') || r.includes('critic'))
+        return 'critic';
+    if (r.includes('research') || r.includes('explore'))
+        return 'researcher';
+    if (r.includes('repair'))
+        return 'implementer';
+    return 'implementer';
+}
+/** one live topology per process, seeded from the first governed spawn */
+const live = {};
+export function liveTopologySnapshot() {
+    const t = live.current;
+    if (!t)
+        return null;
+    return {
+        goal: t.goal,
+        createdAt: t.createdAt,
+        nodes: t.topology.view().map((n) => ({ id: n.id, role: n.contract.role, status: n.status, startedAt: n.startedAt, endedAt: n.endedAt, failure: n.failure })),
+    };
+}
+async function auditTeam(event) {
+    try {
+        const home = homeDir();
+        const dir = join(home, 'cognitive');
+        await mkdir(dir, { recursive: true });
+        await appendFile(join(dir, 'multi-agent.jsonl'), JSON.stringify({ at: new Date().toISOString(), ...event }) + '\n', 'utf8');
+    }
+    catch { /* governance audit is best-effort, never blocks the spawn */ }
+}
+export async function teamLog(limit = 30) {
+    try {
+        const text = await readFile(join(homeDir(), 'cognitive', 'multi-agent.jsonl'), 'utf8');
+        return text.split('\n').filter((l) => l.trim()).slice(-limit).map((l) => JSON.parse(l));
+    }
+    catch {
+        return [];
+    }
+}
+/** Wrap a spawn-like tool with topology governance. Non-fatal by contract:
+ *  governance failures never break the underlying spawn. */
+export function withTopologyGovernance(tool, opts = {}) {
+    const original = tool.execute.bind(tool);
+    return {
+        ...tool,
+        async execute(args, ctx) {
+            const task = String(args.task ?? '').slice(0, 120);
+            const role = String(args.role ?? '');
+            const maxTurns = Math.min(Math.max(Number(args.max_turns ?? 8), 1), 12);
+            const blueprintRole = mapRole(role || 'implementer');
+            try {
+                if (!live.current) {
+                    const spec = defineTopology([blueprintRole, 'supervisor']);
+                    live.current = {
+                        topology: new AgentTopology(spec, {
+                            goalGraph: { nodes: [], edges: [] },
+                            worldDigest: { beliefs: [], uncertainty: {} },
+                            evidence: [],
+                            budget: { totalCostUnits: 400, spent: 0 },
+                            approvals: [],
+                            artifacts: [],
+                        }),
+                        createdAt: new Date().toISOString(),
+                        goal: opts.task?.() ?? task,
+                    };
+                    await auditTeam({ event: 'team.created', goal: live.current.goal.slice(0, 200) });
+                }
+                const t = live.current;
+                // a fresh node of this role per spawn (the topology grows with use)
+                const node = t.topology.addNode(blueprintRole);
+                // shared budget: each turn ~1 cost unit; over-budget spawns are denied
+                const spend = t.topology.trySpend(maxTurns);
+                if (!spend.ok) {
+                    return { output: `team budget exhausted (${spend.spent}/${spend.total} cost units) - do the work directly instead`, isError: true };
+                }
+                t.topology.start(node.id);
+                await auditTeam({ event: 'spawn.started', nodeId: node.id, role: blueprintRole, roleLabel: role, task, budgetUnits: maxTurns });
+                const started = Date.now();
+                try {
+                    const result = await original(args, ctx);
+                    const failed = Boolean(result.isError);
+                    if (failed)
+                        t.topology.fail(node.id, { code: 'E_SUBAGENT', message: String(result.output).slice(0, 200) });
+                    else
+                        t.topology.finish(node.id, { text: String(result.output).slice(0, 400) });
+                    await auditTeam({ event: failed ? 'spawn.failed' : 'spawn.done', nodeId: node.id, role: blueprintRole, turnsBudget: maxTurns, durationMs: Date.now() - started });
+                    return result;
+                }
+                catch (err) {
+                    t.topology.fail(node.id, { code: 'E_SUBAGENT_THREW', message: String(err).slice(0, 200) });
+                    await auditTeam({ event: 'spawn.failed', nodeId: node.id, role: blueprintRole, durationMs: Date.now() - started, error: String(err).slice(0, 200) });
+                    throw err;
+                }
+            }
+            catch {
+                // governance itself must never break the spawn — run it bare
+                return original(args, ctx);
+            }
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/agent",
-  "version": "0.19.6",
+  "version": "0.19.8",
   "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,13 +15,13 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/cognitive": "0.19.6",
-    "@hmharness/domain-harmony": "0.19.6",
-    "@hmharness/domain-ops": "0.19.6",
-    "@hmharness/evolution": "0.19.6",
-    "@hmharness/kernel": "0.19.6",
-    "@hmharness/observability": "0.19.6",
-    "@hmharness/sandbox": "0.19.6"
+    "@hmharness/cognitive": "0.19.8",
+    "@hmharness/domain-harmony": "0.19.8",
+    "@hmharness/domain-ops": "0.19.8",
+    "@hmharness/evolution": "0.19.8",
+    "@hmharness/kernel": "0.19.8",
+    "@hmharness/observability": "0.19.8",
+    "@hmharness/sandbox": "0.19.8"
   },
   "files": [
     "dist"