@hmharness/agent 0.19.5 → 0.19.7

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/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/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.5",
+  "version": "0.19.7",
   "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.5",
-    "@hmharness/domain-harmony": "0.19.5",
-    "@hmharness/domain-ops": "0.19.5",
-    "@hmharness/evolution": "0.19.5",
-    "@hmharness/kernel": "0.19.5",
-    "@hmharness/observability": "0.19.5",
-    "@hmharness/sandbox": "0.19.5"
+    "@hmharness/cognitive": "0.19.7",
+    "@hmharness/domain-harmony": "0.19.7",
+    "@hmharness/domain-ops": "0.19.7",
+    "@hmharness/evolution": "0.19.7",
+    "@hmharness/kernel": "0.19.7",
+    "@hmharness/observability": "0.19.7",
+    "@hmharness/sandbox": "0.19.7"
   },
   "files": [
     "dist"