@hmharness/agent 0.7.0 → 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/package.json

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