@hmharness/agent 0.23.34 → 0.23.36

package/dist/gate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @hmharness/agent - gate (2026-10-15, v0.24 P2A research deploy)
+ *
+ * Production opt-in action gate. The 66-run live experiment arc proved the
+ * MECHANISM (WM -> kernel toolGate -> refusal -> model re-plans) and the
+ * SELECTIVITY (fires only on the corpus's genuinely divergent pair,
+ * read_file->edit_file 0.56 vs 0.83 baseline), but no synthetic task suite
+ * reproduces the real-session failures that produced the corpus signal.
+ * The next instrument is production A/B telemetry — this module makes that
+ * deployable: config `gate: { enabled: true, tau: 0.7 }` wires a
+ * sequence-conditioned gate into every run, default remains OFF.
+ *
+ * Policy (identical to scripts/p2a-intervention.mts arm C, extracted here
+ * so production and experiment share one implementation):
+ *   - pair (last-executed type -> this type) with support >= MIN_SUPPORT
+ *     decides, in BOTH directions (risky pair blocks, benign pair passes);
+ *   - else the per-type rate with support >= MIN_SUPPORT decides;
+ *   - else NO EVIDENCE = allow (the WM contract: knownUnknown is an explore
+ *     signal, never 0% success).
+ */
+import type { LoopToolGate } from '@hmharness/kernel';
+export declare const GATE_MIN_SUPPORT = 10;
+export interface Count {
+    s: number;
+    f: number;
+}
+export type StatTable = Map<string, Count>;
+/** Pure decision policy over precomputed tables — the single implementation
+ *  shared by the lab script and production (tested directly). */
+export declare function conditionedPolicy(typeStat: StatTable, pairStat: StatTable, tau: number): {
+    check(name: string): {
+        allowed: true;
+    } | {
+        allowed: false;
+        reason: string;
+    };
+    stats: () => {
+        consults: number;
+        refusals: number;
+        types: number;
+        pairs: number;
+        tau: number;
+    };
+};
+export interface GateStats {
+    consults: number;
+    refusals: number;
+    types: number;
+    pairs: number;
+    tau: number;
+}
+/** Build the gate from this home's terminal corpus (same train-split
+ *  protocol as the experiments: seed 1, 70/30). An empty corpus yields an
+ *  all-allow gate — no evidence never blocks. */
+export declare function buildConditionedGate(home: string, tau: number): Promise<LoopToolGate & {
+    stats(): GateStats;
+}>;

package/dist/gate.js

@@ -0,0 +1,91 @@
+import { loadTrajectories } from '@hmharness/cognitive';
+export const GATE_MIN_SUPPORT = 10;
+/** Pure decision policy over precomputed tables — the single implementation
+ *  shared by the lab script and production (tested directly). */
+export function conditionedPolicy(typeStat, pairStat, tau) {
+    let lastType = null; // last ALLOWED action (executions change the world, refusals do not)
+    let consults = 0;
+    let refusals = 0;
+    return {
+        check(name) {
+            consults++;
+            const pair = lastType !== null ? pairStat.get(`${lastType}->${name}`) : undefined;
+            const pairN = pair ? pair.s + pair.f : 0;
+            const type = typeStat.get(name);
+            const typeN = type ? type.s + type.f : 0;
+            let v;
+            if (pairN >= GATE_MIN_SUPPORT) {
+                const pr = pair.s / pairN;
+                v = pr < tau
+                    ? { allowed: false, reason: `the learned world model predicts ${lastType}->${name} fails often in similar contexts (pair success ${pr.toFixed(2)} < ${tau}, ${pairN} observations); choose a different approach or verify prerequisites first` }
+                    : { allowed: true };
+            }
+            else if (typeN >= GATE_MIN_SUPPORT) {
+                const tr = type.s / typeN;
+                v = tr < tau
+                    ? { allowed: false, reason: `the learned world model predicts this action type (${name}) tends to fail (success ${tr.toFixed(2)} < ${tau}, ${typeN} observations); choose a different approach or verify prerequisites first` }
+                    : { allowed: true };
+            }
+            else {
+                v = { allowed: true };
+            }
+            if (v.allowed)
+                lastType = name;
+            if (!v.allowed)
+                refusals++;
+            return v;
+        },
+        stats: () => ({ consults, refusals, types: typeStat.size, pairs: pairStat.size, tau }),
+    };
+}
+/** Build the gate from this home's terminal corpus (same train-split
+ *  protocol as the experiments: seed 1, 70/30). An empty corpus yields an
+ *  all-allow gate — no evidence never blocks. */
+export async function buildConditionedGate(home, tau) {
+    const typeStat = new Map();
+    const pairStat = new Map();
+    try {
+        const all = await loadTrajectories(home, 1000);
+        const usable = all.filter((t) => t.steps.length > 0 && t.environment.id === 'terminal');
+        // deterministic split (seed 1) — analysis-only, no decision leakage
+        const rng = mulberry32(hashSeed('p2a-intervention-1'));
+        const shuffled = [...usable].sort(() => rng() - 0.5);
+        const train = shuffled.slice(0, Math.floor(shuffled.length * 0.7));
+        const bump = (m, k, ok) => {
+            const e = m.get(k) ?? { s: 0, f: 0 };
+            if (ok)
+                e.s++;
+            else
+                e.f++;
+            m.set(k, e);
+        };
+        for (const t of train) {
+            let prev = null;
+            for (const s of t.steps) {
+                const type = String(s.action.type ?? '?');
+                if (s.outcome === 'success' || s.outcome === 'failure') {
+                    bump(typeStat, type, s.outcome === 'success');
+                    if (prev !== null)
+                        bump(pairStat, `${prev}->${type}`, s.outcome === 'success');
+                }
+                prev = type;
+            }
+        }
+    }
+    catch {
+        // unreadable corpus = no evidence = all-allow (the gate must never take
+        // the agent down; it is an advisor, not a dependency)
+    }
+    const policy = conditionedPolicy(typeStat, pairStat, tau);
+    return {
+        check: async (name) => policy.check(name),
+        stats: policy.stats,
+    };
+}
+function mulberry32(a) {
+    return () => { a |= 0; a = (a + 0x6d2b79f5) | 0; let t = Math.imul(a ^ (a >>> 15), 1 | a); t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; return ((t ^ (t >>> 14)) >>> 0) / 4294967296; };
+}
+function hashSeed(s) { let h = 2166136261; for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+} return h >>> 0; }

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 { pageReadSink } from './code-wm-recorder.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';

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 { pageReadSink } from "./code-wm-recorder.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";

package/dist/runner.js

@@ -25,6 +25,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 { buildConditionedGate } from "./gate.js";
 import { withTopologyGovernance } from "./topology-live.js";
 /** Flatten the config.json shape into the runtime discriminated union. */
 export function toServerConfig(c) {
@@ -433,6 +434,13 @@ export async function runAgentTask(opts) {
         ]);
         return r.message.content ?? '';
     };
+    // v0.24 P2A research: opt-in conditioned action gate (config gate.enabled,
+    // DEFAULT OFF — the 66-run live arc: mechanism + selectivity proven, task
+    // gain unproven, ~2x token cost on non-failing runs; production A/B only)
+    const gateTau = cfg.gate?.tau ?? 0.7;
+    const actionGate = cfg.gate?.enabled === true ? await buildConditionedGate(ctx.home, gateTau) : undefined;
+    if (actionGate)
+        traj.emit('gate.enabled', 'system', { tau: gateTau });
     const result = await runLoop({
         provider: chatProvider,
         registry: opts.registry,
@@ -449,6 +457,7 @@ export async function runAgentTask(opts) {
         // poll-shaped steering: drained at every turn boundary (codex semantics)
         injections: injectPoll,
         approval: spawnBase.current.approval,
+        toolGate: actionGate,
         events: {
             onDelta: (kind, chunk) => events.onDelta?.(kind, chunk),
             onInjected: (message) => {
@@ -481,6 +490,11 @@ export async function runAgentTask(opts) {
                 traj.emit(granted ? 'tool.approved' : 'tool.denied', 'system', { name });
                 events.onApproval?.(name, args, granted);
             },
+            onGate: (name, _args, allowed, reason) => {
+                // v0.24 P2A telemetry: every gate consult lands in the trajectory —
+                // production A/B reads these events, not lab reconstructions
+                traj.emit('gate.consulted', 'system', { name, allowed, reason: reason ? brief(reason, 200) : undefined });
+            },
             onAssistant: async (m) => {
                 // stamp the event when the message lands, not after the session
                 // write drains - awaiting first made model.responded land AFTER
@@ -502,6 +516,8 @@ export async function runAgentTask(opts) {
     // of silently vanishing into a channel nothing drains
     if (injectChannel)
         injectChannel.active = false;
+    if (actionGate)
+        traj.emit('gate.summary', 'system', actionGate.stats());
     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

package/package.json

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