@hmharness/agent 0.4.4 → 0.5.0

package/dist/prompt.d.ts

@@ -6,4 +6,5 @@ export declare function buildSystemPrompt(opts: {
     insights: string;
     model: string;
     locale?: string;
+    agentsMd?: string;
 }): string;

package/dist/prompt.js

@@ -4,9 +4,32 @@ export function buildSystemPrompt(opts) {
     const isWin = process.platform === 'win32';
     parts.push(`You are hmh, a coding agent powered by ${opts.model}, running on hmharness - a self-evolving agent framework designed for the full HarmonyOS development lifecycle. Working directory: ${opts.cwd}.`, '', opts.locale === 'en'
         ? 'Reply in the language the user writes in (English by default).'
-        : '回复语言跟随用户(默认使用中文)。', '', '## Host environment (facts - rely on these, do not guess)', `- OS: ${process.platform} (${process.arch}). The run_command tool executes through ${isWin ? 'cmd.exe (Windows cmd - NOT bash, NOT PowerShell)' : '/bin/sh'}.`, isWin
+        : '回复语言跟随用户(默认使用中文)。', 
+    // ---- [Codex] 持久执行 ----
+    '', '## Execution mandate', 'Persist until the task is fully handled end-to-end within the current turn: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes. Only stop when the user explicitly pauses, redirects, or when the turn budget is genuinely exhausted. For multi-step tasks: (1) outline your approach in 2-4 steps before acting; (2) after completing each step, confirm it succeeded before moving to the next; (3) if verification fails, diagnose and retry - do not skip forward. Skip planning only for trivial one-liners.', 
+    // ---- [Codex] 并行优先 ----
+    '', 'When multiple independent tool calls are needed (e.g. fetching several files, checking multiple paths, running unrelated diagnostics), invoke them in the same turn rather than one by one. The framework executes independent calls concurrently - this is the single biggest speed-up available to you.', 
+    // ---- [Codex + DeepSeek] 代码编辑纪律 ----
+    '', '## Code discipline', 'Prefer `edit_file` for surgical changes (search-replace of a specific string). Only use `write_file` for new files or complete rewrites. Never overwrite a file you have not read. You may be in a dirty git worktree: NEVER revert existing changes you did not make unless the user asks. If you notice unexpected changes in files you have not touched, STOP and ask the user. Never amend a commit unless explicitly requested. When asked for a "review", default to code review mindset: prioritize bugs, risks, regressions, missing tests - findings first, ordered by severity with file:line references.', 
+    // ---- [DeepSeek] 分段执行 + 合理质疑 ----
+    '', 'For tasks requiring reasoning across multiple steps, work in phases: search and list the key facts, plan the concrete steps, then execute. Do not skip planning to act directly.', 'If the user\'s requested approach carries risk or there is a clearly better alternative, raise it proactively - state the tradeoffs and let the user choose. Only execute confirmed plans.', 
+    // ---- [Codex] 用户反馈 ----
+    '', "When the user gives feedback saying something didn't work, treat it as ground truth. Use available tools to verify the current state, identify the root cause, fix it, and explain what changed.", 
+    // ---- 宿主环境 ----
+    '', '## Host environment (facts - rely on these, do not guess)', `- OS: ${process.platform} (${process.arch}). The run_command tool executes through ${isWin ? 'cmd.exe (Windows cmd - NOT bash, NOT PowerShell)' : '/bin/sh'}.`, isWin
         ? '- cmd.exe has NO grep/head/tail/ls/cat/$(...) and wmic may be absent. Use: findstr (search), "more" or node -e (head/text ops), dir /b (ls), type (cat), where (which). For anything richer: powershell -NoProfile -Command "..."'
-        : '- standard POSIX utilities are available.', `- npm workspaces monorepo; agent state lives in HMH_HOME (${opts.home}): config.json, memory, skills, insights, sessions.`, '- Investigate before asking the user: read environment variables (any *API_KEY), check listening ports (netstat -ano | findstr LISTENING) and probe http://127.0.0.1:<port>/v1/models to discover local services. Never scan a whole drive (dir /s /b from a root) - it times out; search specific directories instead.', '', '## Where tools and skills live on this machine (check these FIRST when asked "is X installed")', `Other agent frameworks share this machine; their skills/plugins/tools are at known paths under the home directory. When asked to check whether a tool/skill/package is installed, or to find/configure an existing one, probe these locations (in order) before concluding "not installed":`, `- ~/.zcode/skills/<name>/  (ZCode skills with SKILL.md, scripts/, .env)`, `- ~/.claude/skills/<name>/  (Claude Code skills with SKILL.md, scripts/)`, `- ~/.codex/skills/<name>/   (Codex skills with SKILL.md, scripts/)`, `- ~/.dsh/skills/<name>/ and ~/.dsh-hm/skills/<name>/  (deepseek-harness skills)`, `- ~/.jcode/skills/<name>/   (JCode skills)`, `- ~/.agent-reach-venv/ and ~/.agent-reach/tools/ (Agent Reach CLI + platform tools)`, `- ~/.local/bin/  (user-installed executables; PATH may not include it - check dir /b not just where)`, `Home directory: ${homedir()}`, 'When found, read the tool\'s SKILL.md or README.md for its usage; copy or reference its scripts rather than reinventing. If the user asks to "configure it for hmharness", check whether it exposes an MCP endpoint (add to config.json mcpServers), an HTTP API (add a provider), or a CLI (register as a skill via `hmh skills add <path>`).', '', 'HarmonyOS development is your home domain: DevEco Studio toolchain, hvigor builds, ohpm packages, hdc devices, ArkTS/ArkUI, OpenHarmony and Cangjie. When a task touches it, prefer the harmony_* tools and precise toolchain knowledge.', '', 'Working style: read before writing; prefer small focused commands; verify results; state tradeoffs briefly. For risky operations (deleting, overwriting, publishing) say what will happen first. When a command fails twice with the same error, switch strategy instead of repeating it. For multi-line/quoted logic, write a temp .cjs file and run it with node - never fight cmd.exe quoting with node -e one-liners.');
+        : '- standard POSIX utilities are available.', `- npm workspaces monorepo; agent state lives in HMH_HOME (${opts.home}): config.json, memory, skills, insights, sessions.`, '- Investigate before asking the user: read environment variables (any *API_KEY), check listening ports (netstat -ano | findstr LISTENING) and probe http://127.0.0.1:<port>/v1/models to discover local services. Never scan a whole drive (dir /s /b from a root) - it times out; search specific directories instead.', 
+    // ---- 跨框架技能路径 ----
+    '', '## Where tools and skills live on this machine (check these FIRST when asked "is X installed")', `Other agent frameworks share this machine; their skills/plugins/tools are at known paths under the home directory. When asked to check whether a tool/skill/package is installed, or to find/configure an existing one, probe these locations (in order) before concluding "not installed":`, `- ~/.zcode/skills/<name>/  (ZCode skills with SKILL.md, scripts/, .env)`, `- ~/.claude/skills/<name>/  (Claude Code skills with SKILL.md, scripts/)`, `- ~/.codex/skills/<name>/   (Codex skills with SKILL.md, scripts/)`, `- ~/.dsh/skills/<name>/ and ~/.dsh-hm/skills/<name>/  (deepseek-harness skills)`, `- ~/.jcode/skills/<name>/   (JCode skills)`, `- ~/.agent-reach-venv/ and ~/.agent-reach/tools/ (Agent Reach CLI + platform tools)`, `- ~/.local/bin/  (user-installed executables; PATH may not include it - check dir /b not just where)`, `Home directory: ${homedir()}`, 'When found, read the tool\'s SKILL.md or README.md for its usage; copy or reference its scripts rather than reinventing. If the user asks to "configure it for hmharness", check whether it exposes an MCP endpoint (add to config.json mcpServers), an HTTP API (add a provider), or a CLI (register as a skill via `hmh skills add <path>`).', 
+    // ---- 鸿蒙域 ----
+    '', 'HarmonyOS development is your home domain: DevEco Studio toolchain, hvigor builds, ohpm packages, hdc devices, ArkTS/ArkUI, OpenHarmony and Cangjie. When a task touches it, prefer the harmony_* tools and precise toolchain knowledge.', 
+    // ---- 通用工作风格 ----
+    '', 'Working style: read before writing; prefer small focused commands; verify results; state tradeoffs briefly. For risky operations (deleting, overwriting, publishing) say what will happen first. When a command fails twice with the same error, switch strategy instead of repeating it. For multi-line/quoted logic, write a temp .cjs file and run it with node - never fight cmd.exe quoting with node -e one-liners.');
+    // ---- AGENTS.md / CLAUDE.md / .cursorrules 注入（被动发现，不需模型主动调用） ----
+    if (opts.agentsMd?.trim()) {
+        parts.push('', '## Project-level instructions (AGENTS.md / CLAUDE.md / .cursorrules)', opts.agentsMd.trim());
+    }
+    // ---- 进化上下文注入 ----
     if (opts.memory.trim()) {
         parts.push('', '## Long-term memory', opts.memory.trim());
     }

package/dist/runner.d.ts

@@ -43,7 +43,19 @@ export declare function contextPack(task: string, sessionId?: string, opts?: {
  * Terminal approval gate: auto mode passes everything; a TTY gets a y/N
  * prompt (reusing a caller-provided readline); a pipe gets a safe deny.
  * The kernel loop denies by default when no gate is wired at all.
+ *
+ * Persistent approval (Codex's .rules pattern): once a user approves a
+ * command pattern (e.g. "hdc shell"), it is saved to
+ * HMH_HOME/approved-rules.json and auto-approved next time. Rules are
+ * matched by the tool name + args prefix. The hard-deny patterns in
+ * tools.ts always override rules - dangerous commands are never auto-approved.
  */
+export interface ApprovedRule {
+    tool: string;
+    argPrefix: string;
+    time: string;
+}
+export declare function loadApprovedRules(home: string): ApprovedRule[];
 export declare function makeApproval(cfg: HmhConfig, yes: boolean, sharedRl?: readline.Interface): LoopApproval;
 export interface RunnerEvents {
     onLine?(line: string): void;

package/dist/runner.js

@@ -6,6 +6,9 @@
  * approval gate construction.
  */
 import { homeDir, loadConfig, resolveProvider, mcpServerTools, Registry, runLoop, Session, } from '@hmharness/kernel';
+import { readFile } from 'node:fs/promises';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
 import { appendMemory, listSkills, readInsights, readNotes, recentInsights, recordInsight, retrieveMemory, skillsToPrompt, sessionGetsCanary, canaryWatermark, listCanary, workspaceForCwd } from '@hmharness/evolution';
 import { harmonyTools } from '@hmharness/domain-harmony';
 import { opsTools } from '@hmharness/domain-ops';
@@ -72,6 +75,26 @@ export async function buildRegistry(opts = {}) {
     }
     return { reg, clients };
 }
+/** Discover AGENTS.md / CLAUDE.md / .cursorrules by walking up from cwd to
+ *  the workspace root. Deeper files take precedence (Codex convention). Only
+ *  the first hit is returned; null when nothing found. */
+async function discoverAgentsMd(cwd) {
+    const NAMES = ['AGENTS.md', 'CLAUDE.md', '.cursorrules'];
+    let dir = cwd;
+    while (true) {
+        for (const name of NAMES) {
+            try {
+                return await readFile(join(dir, name), 'utf8');
+            }
+            catch { /* not here */ }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return null;
+}
 /** Retrieval-based context pack: task-relevant memories, not the whole file.
  *  P0 canary: ~20% of sessions (deterministic by session id) also receive
  *  the canary skill block, watermarked as experimental references - the
@@ -94,17 +117,34 @@ export async function contextPack(task, sessionId, opts = {}) {
     }
     return { memory, skills: skillsToPrompt(skills) + (canaryBlock ? '\n' + canaryBlock : ''), insights, skillsInjected: [...skills.map((s) => s.name), ...canaryNames] };
 }
-/**
- * Terminal approval gate: auto mode passes everything; a TTY gets a y/N
- * prompt (reusing a caller-provided readline); a pipe gets a safe deny.
- * The kernel loop denies by default when no gate is wired at all.
- */
+export function loadApprovedRules(home) {
+    try {
+        return JSON.parse(readFileSync(join(home, 'approved-rules.json'), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+function saveApprovedRules(home, rules) {
+    try {
+        writeFileSync(join(home, 'approved-rules.json'), JSON.stringify(rules, null, 2));
+    }
+    catch { /* best effort */ }
+}
+function matchesRule(rules, toolName, args) {
+    const argsStr = JSON.stringify(args);
+    return rules.some((r) => r.tool === toolName && argsStr.startsWith(r.argPrefix));
+}
 export function makeApproval(cfg, yes, sharedRl) {
     const t = strings(cfg.locale ?? 'zh');
+    const home = homeDir();
     return {
         async ask(toolName, args) {
             if (yes || cfg.approval === 'auto')
                 return true;
+            // Persistent rules: patterns the user previously approved are auto-passed
+            if (matchesRule(loadApprovedRules(home), toolName, args))
+                return true;
             const brief = JSON.stringify(args).slice(0, 120);
             if (!stdin.isTTY) {
                 process.stdout.write(`\x1b[33m${t.approvalDeniedNoTty(toolName, brief)}\x1b[0m\n`);
@@ -119,7 +159,17 @@ export function makeApproval(cfg, yes, sharedRl) {
                 if (!sharedRl)
                     rl.close();
             }
-            return answer === 'y' || answer === 'yes';
+            const granted = answer === 'y' || answer === 'yes';
+            // Save approved patterns for future auto-approval (skip simple argless tools)
+            if (granted && Object.keys(args).length > 0) {
+                const rules = loadApprovedRules(home);
+                const argsStr = JSON.stringify(args);
+                if (!rules.some((r) => r.tool === toolName && r.argPrefix === argsStr)) {
+                    rules.push({ tool: toolName, argPrefix: argsStr, time: new Date().toISOString() });
+                    saveApprovedRules(home, rules);
+                }
+            }
+            return granted;
         },
     };
 }
@@ -140,6 +190,7 @@ export async function runAgentTask(opts) {
     // contextPack needs the session id: canary injection is deterministic
     // per-session (stable attribution), decided before the prompt is built
     const pack = await contextPack(opts.task, session.id, { workspace, embedding });
+    const agentsMd = await discoverAgentsMd(ctx.cwd);
     const system = buildSystemPrompt({
         cwd: ctx.cwd,
         home: ctx.home,
@@ -148,6 +199,7 @@ export async function runAgentTask(opts) {
         insights: pack.insights,
         model: cfg.provider.model,
         locale: cfg.locale,
+        agentsMd: agentsMd ?? undefined,
     });
     await session.user(opts.task);
     const approval = opts.approvalAsk ? { ask: opts.approvalAsk } : makeApproval(cfg, opts.yes === true);

package/dist/tools.d.ts

@@ -1,6 +1,12 @@
 import { type Tool } from '@hmharness/kernel';
 export declare const readFileTool: Tool;
 export declare const writeFileTool: Tool;
+/** Surgical search-replace tool (adopted from Codex's apply_patch philosophy).
+ *  Safer than write_file for targeted edits: only changes the declared fragment,
+ *  refuses to run when old_string is not unique (prevents silent wrong-location
+ *  edits), and does NOT need approval - the blast radius is bounded to the
+ *  declared substring. The model must read the file first to know what to replace. */
+export declare const editFileTool: Tool;
 export declare const listDirTool: Tool;
 /** Host-shell pipe preflight: on Windows cmd, Unix-isms fail with cryptic
  *  mojibake and the model retries for many turns. Only the FIRST word of

package/dist/tools.js

@@ -73,6 +73,48 @@ export const writeFileTool = {
         }
     },
 };
+/** Surgical search-replace tool (adopted from Codex's apply_patch philosophy).
+ *  Safer than write_file for targeted edits: only changes the declared fragment,
+ *  refuses to run when old_string is not unique (prevents silent wrong-location
+ *  edits), and does NOT need approval - the blast radius is bounded to the
+ *  declared substring. The model must read the file first to know what to replace. */
+export const editFileTool = {
+    name: 'edit_file',
+    description: 'Surgical search-replace edit. Provide old_string (must appear exactly once in the file) and new_string to replace it. Prefer this over write_file for changes to existing files. old_string must be unique - if it appears more than once, the edit is refused (make it more specific).',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'file path' },
+            old_string: { type: 'string', description: 'the exact string to find and replace (must appear exactly once in the file)' },
+            new_string: { type: 'string', description: 'the replacement string' },
+        },
+        required: ['path', 'old_string', 'new_string'],
+    },
+    async execute(args, ctx) {
+        try {
+            const p = safePath(String(args.path), ctx.cwd);
+            const old = String(args.old_string ?? '');
+            const rep = String(args.new_string ?? '');
+            if (!old)
+                return { output: 'old_string is empty - provide the text to replace', isError: true };
+            if (old === rep)
+                return { output: 'old_string and new_string are identical - nothing to change', isError: true };
+            const content = await readFile(p, 'utf8');
+            const idx = content.indexOf(old);
+            if (idx < 0)
+                return { output: `old_string not found in ${p} - read the file first to find the exact text`, isError: true };
+            const second = content.indexOf(old, idx + 1);
+            if (second >= 0)
+                return { output: `old_string is not unique in ${p} (found at offset ${idx} and ${second}) - make it more specific by including surrounding context`, isError: true };
+            const out = content.slice(0, idx) + rep + content.slice(idx + old.length);
+            await writeFile(p, out, 'utf8');
+            return { output: `edited ${p}: replaced ${old.length} chars with ${rep.length} chars at offset ${idx}` };
+        }
+        catch (err) {
+            return { output: String(err), isError: true };
+        }
+    },
+};
 export const listDirTool = {
     name: 'list_dir',
     description: 'List a directory: names with d/- prefix and size.',
@@ -589,4 +631,4 @@ export const seeImageTool = {
         return { output: `all vision providers failed:\n${errors.join('\n')}`, isError: true };
     },
 };
-export const baseTools = [readFileTool, writeFileTool, listDirTool, runCommandTool, rememberTool, seeImageTool];
+export const baseTools = [readFileTool, editFileTool, writeFileTool, listDirTool, runCommandTool, rememberTool, seeImageTool];

package/package.json

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