@hmharness/agent 0.6.8 → 0.8.0

package/dist/capability.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @hmharness/agent - capability plane (V2 blueprint M4).
+ *
+ * Projects every registered tool - native, MCP, domain - onto a
+ * CapabilityManifest: an auditable declaration of id, risk, permissions,
+ * approval requirement and side effects. The PolicyEngine then answers
+ * "may this capability run in this mode?" for lockdown/standard modes.
+ * This is the DECLARATION layer on top of the existing enforcement layer
+ * (kernel needsApproval + shellgate + DENY_PATTERNS stay authoritative);
+ * manifests make the security surface inspectable (`hmh capability list`).
+ */
+import type { Tool } from '@hmharness/kernel';
+export type CapabilityRisk = 'low' | 'medium' | 'high' | 'critical';
+export interface CapabilityManifest {
+    id: string;
+    version: string;
+    description: string;
+    risk: CapabilityRisk;
+    /** coarse permission buckets derived from the tool's nature */
+    permissions: string[];
+    requiresApproval: boolean;
+    network: boolean;
+    sideEffects: string[];
+}
+export declare function manifestFor(tool: Tool): CapabilityManifest;
+export declare function capabilityReport(registry: {
+    list(): Tool[];
+}): CapabilityManifest[];
+export type PolicyMode = 'standard' | 'lockdown';
+export interface PolicyDecision {
+    allow: boolean;
+    reason: string;
+}
+/** Lockdown mode: anything with host/device/process reach is denied outright;
+ *  approval-gated capabilities still require their gate. Standard mode:
+ *  mirrors the existing enforcement (declaration-only view). */
+export declare function authorize(manifest: CapabilityManifest, mode: PolicyMode, deniedIds?: ReadonlySet<string>): PolicyDecision;

package/dist/capability.js

@@ -0,0 +1,43 @@
+/** Tool-name heuristics -> permission buckets and risk. Declaration only -
+ *  enforcement stays in kernel (needsApproval/shellgate/DENY_PATTERNS). */
+const RISK_RULES = [
+    { match: /^(run_command|ssh_run)$/, risk: 'high', permissions: ['process.spawn', 'fs.read', 'fs.write', 'net.remote'], network: true, sideEffects: ['host-process', 'remote-exec'] },
+    { match: /^(write_file|edit_file)$/, risk: 'medium', permissions: ['fs.write'], network: false, sideEffects: ['file-mutation'] },
+    { match: /^desktop_(click|type)$/, risk: 'high', permissions: ['desktop.control'], network: false, sideEffects: ['host-ui-input'] },
+    { match: /^desktop_screenshot$/, risk: 'medium', permissions: ['desktop.read'], network: false, sideEffects: [] },
+    { match: /^(browser_open|web_search|web_fetch)$/, risk: 'low', permissions: ['net.egress'], network: true, sideEffects: [] },
+    { match: /^(harmony_install|harmony_launch|harmony_uninstall|harmony_sign)$/, risk: 'high', permissions: ['device.write'], network: false, sideEffects: ['device-mutation'] },
+    { match: /^(harmony_emulator_(create|start|stop|delete))$/, risk: 'high', permissions: ['device.write', 'process.spawn'], network: true, sideEffects: ['device-mutation'] },
+    { match: /^(harmony_build|harmony_cjpm_build|harmony_cjpm_test|harmony_lint)$/, risk: 'medium', permissions: ['process.spawn', 'fs.write'], network: true, sideEffects: ['build-artifacts'] },
+    { match: /^spawn_agent$/, risk: 'high', permissions: ['agent.spawn'], network: false, sideEffects: ['subagent-run'] },
+];
+export function manifestFor(tool) {
+    const rule = RISK_RULES.find((r) => r.match.test(tool.name));
+    const requiresApproval = typeof tool.needsApproval === 'function';
+    return {
+        id: tool.name,
+        version: '1.0.0',
+        description: tool.description.split('\n')[0].slice(0, 160),
+        risk: rule?.risk ?? (requiresApproval ? 'medium' : 'low'),
+        permissions: rule?.permissions ?? (requiresApproval ? ['gated.unknown'] : ['fs.read']),
+        requiresApproval,
+        network: rule?.network ?? false,
+        sideEffects: rule?.sideEffects ?? [],
+    };
+}
+export function capabilityReport(registry) {
+    return registry.list().map(manifestFor).sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Lockdown mode: anything with host/device/process reach is denied outright;
+ *  approval-gated capabilities still require their gate. Standard mode:
+ *  mirrors the existing enforcement (declaration-only view). */
+export function authorize(manifest, mode, deniedIds = new Set()) {
+    if (deniedIds.has(manifest.id))
+        return { allow: false, reason: `capability revoked: ${manifest.id}` };
+    if (mode === 'lockdown') {
+        const dangerous = manifest.permissions.some((p) => p.startsWith('process.') || p.startsWith('device.write') || p.startsWith('desktop.control') || p.startsWith('net.remote') || p.startsWith('agent.'));
+        if (dangerous)
+            return { allow: false, reason: `lockdown: ${manifest.id} touches ${manifest.permissions.filter((p) => !p.startsWith('fs.')).join(', ')}` };
+    }
+    return { allow: true, reason: manifest.requiresApproval ? 'allowed, approval gate applies' : 'allowed' };
+}

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { baseTools, readFileTool, writeFileTool, listDirTool, runCommandTool, rememberTool, seeImageTool } from './tools.ts';
+export { manifestFor, capabilityReport, authorize, type CapabilityManifest, type CapabilityRisk, type PolicyMode } from './capability.ts';
 export { buildSystemPrompt } from './prompt.ts';
 export { strings, type Locale, type Strings } from './i18n.ts';
 export { makeSpawnTool, MAX_SPAWN_DEPTH, type SpawnBase } from './spawn.ts';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { baseTools, readFileTool, writeFileTool, listDirTool, runCommandTool, rememberTool, seeImageTool } from "./tools.js";
+export { manifestFor, capabilityReport, authorize } from "./capability.js";
 export { buildSystemPrompt } from "./prompt.js";
 export { strings } from "./i18n.js";
 export { makeSpawnTool, MAX_SPAWN_DEPTH } from "./spawn.js";

package/dist/runner.js

@@ -6,6 +6,7 @@
  * approval gate construction.
  */
 import { homeDir, loadConfig, resolveProvider, mcpServerTools, Registry, runLoop, Session, } from '@hmharness/kernel';
+import { brief, createTrajectoryRecorder } from '@hmharness/observability';
 import { readFile } from 'node:fs/promises';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
@@ -229,6 +230,11 @@ export async function runAgentTask(opts) {
     const ctx = opts.ctx ?? { cwd: process.cwd(), home: homeDir() };
     const events = opts.events ?? {};
     const session = new Session(ctx.home, ctx.cwd, cfg.provider.model);
+    // V2 M1 flight recorder: every run leaves a typed, replayable trajectory
+    // under <home>/runs/<run-id>/. Best-effort by contract - storage failures
+    // 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) });
     // workspace scoping + optional embedding hybrid for memory retrieval.
     // Embeddings only when routing.embedding is EXPLICITLY set - an inherited
     // chat route would 404 on /embeddings once per task for nothing.
@@ -256,6 +262,14 @@ export async function runAgentTask(opts) {
     // watches IT - this makes the size visible every run (review finding #5)
     const systemTokens = Math.ceil(system.length / 4);
     events.onLine?.(`  [prompt] system: ${system.length} chars (~${systemTokens} tokens) · ${agentsMd ? 'AGENTS.md: yes' : 'no AGENTS.md'}`);
+    traj.emit('context.assembled', 'system', {
+        systemChars: system.length,
+        systemTokens,
+        agentsMd: Boolean(agentsMd),
+        memoryChars: pack.memory.length,
+        skills: pack.skills.length,
+        insights: pack.insights.length,
+    });
     await session.user(opts.task);
     // YOLO fix: when yes=true the caller's approvalAsk (TUI dialog, web remote
     // gate) must NOT override the auto-approve gate - it used to take
@@ -306,6 +320,7 @@ export async function runAgentTask(opts) {
             onDelta: (kind, chunk) => events.onDelta?.(kind, chunk),
             onToolCall: (name, args) => {
                 toolsUsed.push(name);
+                traj.emit('tool.requested', 'tool', { name, args: brief(args, 120) });
                 events.onToolCall?.(name, args);
             },
             onToolResult: (name, output, isError) => {
@@ -313,19 +328,30 @@ export async function runAgentTask(opts) {
                     const list = toolErrors.get(name) ?? [];
                     list.push(output.split('\n')[0].slice(0, 120));
                     toolErrors.set(name, list);
+                    traj.emit('error.observed', 'tool', { name, preview: brief(output, 160) });
                 }
                 void session.tool(name, output, isError);
+                traj.emit('tool.completed', 'tool', { name, isError, preview: brief(output, 120) });
                 events.onToolResult?.(name, output, isError);
             },
             onApproval: (name, args, granted) => {
                 void session.approval(name, granted);
+                traj.emit(granted ? 'tool.approved' : 'tool.denied', 'system', { name });
                 events.onApproval?.(name, args, granted);
             },
             onAssistant: async (m) => {
+                // stamp the event when the message lands, not after the session
+                // write drains - awaiting first made model.responded land AFTER
+                // run.completed in the timeline
+                traj.emit('model.responded', 'agent', { contentChars: m.content?.length ?? 0, toolCalls: m.tool_calls?.length ?? 0 });
                 await session.assistant(m.content ?? null, m.tool_calls);
             },
         },
+    }).catch((err) => {
+        traj.finish({ success: false, reason: 'error', error: brief(String(err), 200) }, { toolUses: toolsUsed.length });
+        throw err;
     });
+    traj.finish({ success: result.reason === 'final', reason: result.reason }, { turns: result.turns, toolUses: result.toolUses, promptTokens: result.usage.promptTokens, completionTokens: result.usage.completionTokens });
     // ---- instant feedback: learn from THIS task's mistakes, not 8 tasks later ----
     // Tier 1 (always, zero cost): raw error pattern → memory self-note. Lowered
     // to 1 failure for system-level patterns (shell incompat, auth, missing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/agent",
-  "version": "0.6.8",
+  "version": "0.8.0",
   "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,10 +15,11 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@hmharness/kernel": "0.6.8",
-    "@hmharness/evolution": "0.6.8",
-    "@hmharness/domain-harmony": "0.6.8",
-    "@hmharness/domain-ops": "0.6.8"
+    "@hmharness/kernel": "0.8.0",
+    "@hmharness/observability": "0.7.0",
+    "@hmharness/evolution": "0.8.0",
+    "@hmharness/domain-harmony": "0.8.0",
+    "@hmharness/domain-ops": "0.8.0"
   },
   "files": [
     "dist"