@hmharness/agent 0.7.0 → 0.8.1

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/roles.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @hmharness/agent - team roles (V2 blueprint M7).
+ *
+ * spawn_agent already accepts a free-text role label with a success-rate
+ * leaderboard; this adds the canonical engineering-team CHARTERS. When a
+ * spawn names a canonical role, the child's system prompt carries that
+ * role's discipline text (what it always does / never does), turning
+ * "role: a word" into "role: a contract".
+ */
+export interface TeamRole {
+    name: string;
+    charter: string;
+    /** typical delegation phrasing hints, for docs only */
+    goodFor: string;
+}
+export declare const TEAM_ROLES: Record<string, TeamRole>;
+/** Resolve a role label to its charter (canonical names only); '' when free-form. */
+export declare function roleCharter(role: string): string;
+/** The known-role list for tool descriptions. */
+export declare const TEAM_ROLE_NAMES: string[];

package/dist/roles.js

@@ -0,0 +1,39 @@
+export const TEAM_ROLES = {
+    planner: {
+        name: 'planner',
+        charter: 'PLANNER duty: decompose the goal into ordered, verifiable steps. Output a numbered plan where every step names its verification (command/check). Never execute the steps yourself - plan only. Flag risks and unknowns explicitly.',
+        goodFor: 'task decomposition before implementation',
+    },
+    coder: {
+        name: 'coder',
+        charter: 'CODER duty: implement exactly the agreed step. Prefer surgical edits (edit_file) inside the workspace. Keep changes minimal and consistent with surrounding code. Run the cheapest verification that proves the change (build/lint/test) before answering.',
+        goodFor: 'focused implementation steps',
+    },
+    tester: {
+        name: 'tester',
+        charter: 'TESTER duty: try to BREAK the thing under test. Probe edge cases, empty inputs, wrong types, boundary values. Report each probe as input -> actual vs expected. A run with zero failures must say what WAS covered, never "all good".',
+        goodFor: 'adversarial verification',
+    },
+    reviewer: {
+        name: 'reviewer',
+        charter: 'REVIEWER duty: findings first, ordered by severity, each with file:line evidence. Prioritize bugs, regressions, and missing tests over style. No fixes - report only. If nothing significant, say so explicitly rather than inventing nits.',
+        goodFor: 'code review passes',
+    },
+    judge: {
+        name: 'judge',
+        charter: 'JUDGE duty: verdict from EVIDENCE, not from the executor\'s self-report. Cite what you actually observed (command outputs, file contents). Hard evidence (exit codes, tests) outranks your opinion; label opinion as opinion. End with VERDICT: PASS or VERDICT: FAIL plus one line why.',
+        goodFor: 'independent evaluation of a finished step',
+    },
+    repairer: {
+        name: 'repairer',
+        charter: 'REPAIRER duty: reproduce the failure first, state the root cause in one sentence, then apply the smallest fix that removes it, then re-run the reproduction to prove it is gone. Report before/after outputs.',
+        goodFor: 'fixing broken builds/tests',
+    },
+};
+/** Resolve a role label to its charter (canonical names only); '' when free-form. */
+export function roleCharter(role) {
+    const r = TEAM_ROLES[String(role ?? '').trim().toLowerCase()];
+    return r ? r.charter : '';
+}
+/** The known-role list for tool descriptions. */
+export const TEAM_ROLE_NAMES = Object.keys(TEAM_ROLES);

package/dist/spawn.js

@@ -16,6 +16,7 @@
 import { appendFile, mkdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { runLoop } from '@hmharness/kernel';
+import { roleCharter } from "./roles.js";
 export const MAX_SPAWN_DEPTH = 2;
 export async function recordRole(home, role, ok) {
     try {
@@ -62,7 +63,7 @@ export function makeSpawnTool(deps) {
             type: 'object',
             properties: {
                 task: { type: 'string', description: 'complete, self-contained instructions for the sub-agent' },
-                role: { type: 'string', description: 'optional label for this delegation, e.g. "explorer", "reviewer", "build-fixer" - roles accumulate success rates you will see next time' },
+                role: { type: 'string', description: 'optional role label; canonical roles carry a duty charter: planner / coder / tester / reviewer / judge / repairer (plus any custom label - roles accumulate success rates you will see next time)' },
                 max_turns: { type: 'number', description: 'turn budget for the sub-agent (default 8, max 12)' },
             },
             required: ['task'],
@@ -92,7 +93,7 @@ export function makeSpawnTool(deps) {
             }
             const system = [
                 `You are a hmh sub-agent (depth ${childDepth}${role ? `, role: ${role}` : ''}). You have no conversation history beyond this task.`,
-                role ? `Perform the ${role} duty with that specialty's discipline.` : '',
+                role ? roleCharter(role) || `Perform the ${role} duty with that specialty's discipline.` : '',
                 'Do exactly what the task asks, use tools as needed, verify before answering, and reply with a concise result (the caller only sees your final answer).',
             ].filter(Boolean).join('\n');
             base.onLine?.(`[${tag}] start: ${task.slice(0, 80)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hmharness/agent",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "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.1",
+    "@hmharness/domain-harmony": "0.8.0",
+    "@hmharness/domain-ops": "0.8.0"
   },
   "files": [
     "dist"