@zhijiewang/openharness 2.32.0 → 2.34.0

package/README.md

@@ -542,7 +542,8 @@ Dispatch specialized sub-agents for focused tasks:
 | `security-auditor` | OWASP, injection, secrets, CVE scanning | Read-only + Bash |
 | `evaluator` | Evaluate code quality and run tests (read-only) | Read-only + Bash + Diagnostics |
 | `planner` | Design step-by-step implementation plans | Read-only + Bash |
-| `architect` | Analyze architecture and design structural changes | Read-only |
+| `architect` | Analyze architecture and design structural changes (hands off to editor) | Read-only |
+| `editor` | Apply an architect's plan as code edits, no re-planning | Read + Edit + Write + MultiEdit + Bash |
 | `migrator` | Systematic codebase migrations and upgrades | All file tools + Bash |
 
 Each role restricts the sub-agent to only its suggested tools. You can also pass `allowed_tools` explicitly:
@@ -552,6 +553,16 @@ Agent({ subagent_type: 'evaluator', prompt: 'Run all tests and report results' }
 Agent({ allowed_tools: ['Read', 'Grep'], prompt: 'Search for all TODO comments' })
 ```
 
+### Architect → Editor (cost-saving multi-file edits)
+
+For larger changes that span multiple files, dispatch a two-pass `architect` → `editor` workflow. The architect (powerful model) reads the codebase and outputs a structured plan; the editor (fast model) applies it mechanically without re-planning. When `modelRouter` is configured, OH automatically routes the `architect` role to your `powerful` tier and the `editor` role to your `fast` tier — typical cost reduction is 30-50% on multi-file edits versus running both passes on the powerful model.
+
+```
+Agent({ subagent_type: 'architect', prompt: 'Plan a migration from option A to option B across src/' })
+# Hand the resulting plan to:
+Agent({ subagent_type: 'editor', prompt: '<paste plan>' })
+```
+
 ## Headless Mode
 
 Run a single prompt without interactive UI — perfect for CI/CD and scripting:

package/README.zh-CN.md

@@ -542,7 +542,8 @@ Cron 执行器每 60 秒检查一次到期任务，并通过子查询运行。
 | `security-auditor` | OWASP、注入、密钥、CVE 扫描 | 只读 + Bash |
 | `evaluator` | 评估代码质量并运行测试（只读） | 只读 + Bash + Diagnostics |
 | `planner` | 设计分步实现计划 | 只读 + Bash |
-| `architect` | 分析架构、设计结构性变更 | 只读 |
+| `architect` | 分析架构、设计结构性变更（移交给 editor 落地） | 只读 |
+| `editor` | 按 architect 给出的方案应用代码改动，不再重新规划 | Read + Edit + Write + MultiEdit + Bash |
 | `migrator` | 系统化的代码库迁移与升级 | 全部文件工具 + Bash |
 
 每个角色只会让子代理使用其推荐的工具。你也可以显式传入 `allowed_tools`：
@@ -552,6 +553,16 @@ Agent({ subagent_type: 'evaluator', prompt: 'Run all tests and report results' }
 Agent({ allowed_tools: ['Read', 'Grep'], prompt: 'Search for all TODO comments' })
 ```
 
+### Architect → Editor（多文件改动的省钱模式）
+
+对于跨多个文件的较大改动，使用 `architect` → `editor` 两遍式工作流：architect（强模型）读懂代码并产出结构化方案；editor（轻量模型）按方案机械落地，不再重新规划。当配置了 `modelRouter` 时，OH 会自动把 `architect` 角色路由到 `powerful` 档、把 `editor` 角色路由到 `fast` 档 —— 相比两遍都跑强模型，多文件改动通常省 30-50% 成本。
+
+```
+Agent({ subagent_type: 'architect', prompt: 'Plan a migration from option A to option B across src/' })
+# 把得到的方案再交给 editor：
+Agent({ subagent_type: 'editor', prompt: '<paste plan>' })
+```
+
 ## 无头模式
 
 跑一次提示词，不走交互 UI —— 适合 CI/CD 和脚本化：

package/dist/agents/roles.js

@@ -131,7 +131,7 @@ Do NOT implement anything. Your output is a plan document, not code. Read widely
     {
         id: "architect",
         name: "Architect",
-        description: "Analyzes system architecture and designs structural changes",
+        description: "Analyzes system architecture and designs structural changes (hands off to editor)",
         systemPromptSupplement: `You are an architecture agent. Your job is to:
 - Map the current system architecture (modules, dependencies, data flow)
 - Identify architectural patterns and conventions in use
@@ -139,9 +139,38 @@ Do NOT implement anything. Your output is a plan document, not code. Read widely
 - Evaluate trade-offs between approaches (performance, maintainability, complexity)
 - Document interfaces, contracts, and integration points
 
-Focus on the big picture: module boundaries, data flow, dependency graphs. Leave implementation details to other agents.`,
+Focus on the big picture: module boundaries, data flow, dependency graphs. Do NOT apply edits — leave implementation to the editor agent.
+
+When you've finished planning, output a structured "Plan" the editor can apply mechanically:
+
+## Plan
+1. **<file:line>** — <change description>
+   - **Before**: <current state, 1-line>
+   - **After**:  <target state, 1-line>
+   - **Why**:    <one-sentence rationale>
+2. <next change…>
+
+Keep each step small enough that an editor (a cheaper model) can apply it without re-deriving your reasoning. Group related edits together; surface dependencies between steps.`,
         suggestedTools: ["Read", "Glob", "Grep", "LS"],
     },
+    {
+        id: "editor",
+        name: "Editor",
+        description: "Applies an architect's plan as code edits — does not re-plan, no discovery",
+        systemPromptSupplement: `You are a code editor. You receive a plan from an architect agent and apply it as file edits.
+
+Rules:
+- DO apply the changes exactly as described in the plan.
+- DO read each file before editing it (Read → Edit), so your edit anchors land correctly.
+- DO run tests after each batch if test commands are available.
+- DO NOT re-plan, second-guess the architect, or expand scope. If the plan is ambiguous on a specific edit, follow the most literal interpretation; surface the ambiguity in your final summary, don't try to resolve it yourself.
+- DO NOT add features, refactor adjacent code, or change tests beyond what the plan specifies.
+
+This role is intentionally tuned for a cheaper/faster model — the architect already did the reasoning. Your job is mechanical accuracy.
+
+If the plan can't be applied (e.g. a referenced file doesn't exist, an anchor doesn't match the current code), STOP and report which step failed and why. Do not improvise.`,
+        suggestedTools: ["Read", "Edit", "Write", "MultiEdit", "Bash"],
+    },
     {
         id: "migrator",
         name: "Migrator",

package/dist/harness/config.d.ts

@@ -214,6 +214,34 @@ export type OhConfig = {
         rateLimit?: number;
         allowedTools?: string[];
     };
+    /**
+     * Opt-in OS-level sandbox via `@anthropic-ai/sandbox-runtime` (an optional
+     * dependency). When `enabled: true`, BashTool wraps every command in
+     * bubblewrap (Linux) or sandbox-exec (macOS) plus a domain-allowlist
+     * network proxy. Windows isn't supported by the package — the wrap is a
+     * silent passthrough there. Off by default; users opt in via config or the
+     * `--sandbox` CLI flag.
+     *
+     * `network.allowedDomains` is the proxy allowlist (e.g. `["github.com",
+     * "registry.npmjs.org"]`); `deniedDomains` blocks specific hosts before
+     * the allowlist applies. `filesystem.allowWrite` defaults to `[cwd]` —
+     * the sandbox can write to the project tree but nowhere else.
+     *
+     * See `src/harness/sandbox-runtime.ts` and SECURITY.md for the full
+     * threat-model boundary.
+     */
+    sandbox?: {
+        enabled?: boolean;
+        network?: {
+            allowedDomains?: string[];
+            deniedDomains?: string[];
+        };
+        filesystem?: {
+            allowWrite?: string[];
+            denyWrite?: string[];
+            denyRead?: string[];
+        };
+    };
     /**
      * Environment variables injected into child processes spawned by the harness —
      * Bash/Monitor/PowerShell tool executions and MCP server subprocesses. Useful

package/dist/harness/sandbox-runtime.d.ts

@@ -0,0 +1,47 @@
+/**
+ * OS-level sandbox integration via the optional `@anthropic-ai/sandbox-runtime`
+ * package. The package wraps a shell command in bubblewrap (Linux) or
+ * sandbox-exec (macOS) plus a network proxy that filters by domain allowlist.
+ *
+ * Boundaries:
+ * - **Linux + macOS**: real sandboxing via the package's static API.
+ * - **Windows**: not supported by the package — every wrap call returns null
+ *   (graceful passthrough; tools spawn unsandboxed). Documented in SECURITY.md.
+ * - **Package not installed**: same passthrough behavior — installs cleanly
+ *   without the optional dep on any platform.
+ *
+ * Lifecycle:
+ * - Initialized once per process on the first wrap request.
+ * - One `SandboxManager.initialize` covers all subsequent wrap calls.
+ * - No reset — the package documents auto-cleanup on process exit.
+ *
+ * Opt-in: callers pass `{ enabled: true }` (typically derived from
+ * `OhConfig.sandbox.enabled` or the `--sandbox` CLI flag). The default is
+ * off so existing users see no behavior change.
+ */
+import type { OhConfig } from "./config.js";
+export type SandboxConfig = NonNullable<OhConfig["sandbox"]>;
+/**
+ * Returns true on Linux/macOS where sandboxing is supported. Windows is
+ * unsupported by the underlying package, so we short-circuit there to avoid
+ * a misleading "tried to load and failed" log.
+ */
+export declare function isSandboxAvailable(): boolean;
+/**
+ * Wrap a shell command for sandboxed execution.
+ *
+ * Returns the wrapped command (a single shell string suitable for
+ * `spawn(cmd, { shell: "/bin/bash" })`) when sandboxing is enabled and
+ * available. Returns null in every other case — Windows, missing package,
+ * disabled config, init failure — so the caller falls through to the
+ * unsandboxed code path unchanged.
+ */
+export declare function wrapForSandbox(command: string, config: SandboxConfig): Promise<string | null>;
+/**
+ * Test-only: reset the cached init promise so unit tests can re-init with
+ * different configs.
+ *
+ * @internal
+ */
+export declare function _resetSandboxForTest(): void;
+//# sourceMappingURL=sandbox-runtime.d.ts.map

package/dist/harness/sandbox-runtime.js

@@ -0,0 +1,100 @@
+/**
+ * OS-level sandbox integration via the optional `@anthropic-ai/sandbox-runtime`
+ * package. The package wraps a shell command in bubblewrap (Linux) or
+ * sandbox-exec (macOS) plus a network proxy that filters by domain allowlist.
+ *
+ * Boundaries:
+ * - **Linux + macOS**: real sandboxing via the package's static API.
+ * - **Windows**: not supported by the package — every wrap call returns null
+ *   (graceful passthrough; tools spawn unsandboxed). Documented in SECURITY.md.
+ * - **Package not installed**: same passthrough behavior — installs cleanly
+ *   without the optional dep on any platform.
+ *
+ * Lifecycle:
+ * - Initialized once per process on the first wrap request.
+ * - One `SandboxManager.initialize` covers all subsequent wrap calls.
+ * - No reset — the package documents auto-cleanup on process exit.
+ *
+ * Opt-in: callers pass `{ enabled: true }` (typically derived from
+ * `OhConfig.sandbox.enabled` or the `--sandbox` CLI flag). The default is
+ * off so existing users see no behavior change.
+ */
+// Cached, lazy-initialized handle. We deliberately don't expose this — callers
+// only see `wrapForSandbox` / `isSandboxAvailable` / `resetSandboxForTest`.
+let _initPromise = null;
+/**
+ * Returns true on Linux/macOS where sandboxing is supported. Windows is
+ * unsupported by the underlying package, so we short-circuit there to avoid
+ * a misleading "tried to load and failed" log.
+ */
+export function isSandboxAvailable() {
+    return process.platform === "linux" || process.platform === "darwin";
+}
+async function loadAndInitialize(config) {
+    if (!isSandboxAvailable())
+        return null;
+    let mod;
+    try {
+        mod = (await import("@anthropic-ai/sandbox-runtime"));
+    }
+    catch {
+        // Optional dep not installed — graceful passthrough.
+        return null;
+    }
+    try {
+        await mod.SandboxManager.initialize({
+            network: {
+                allowedDomains: config.network?.allowedDomains ?? [],
+                deniedDomains: config.network?.deniedDomains ?? [],
+            },
+            filesystem: {
+                allowWrite: config.filesystem?.allowWrite ?? [process.cwd()],
+                denyWrite: config.filesystem?.denyWrite ?? [],
+                denyRead: config.filesystem?.denyRead ?? [],
+            },
+        });
+    }
+    catch {
+        // Init can fail when bubblewrap / sandbox-exec aren't installed, or when
+        // the user's profile rejects the proxy ports. Falling back to passthrough
+        // is correct — opting in promised "use sandbox if you can," not "fail
+        // closed" — that's a separate `requireSandbox` mode for a future revision.
+        return null;
+    }
+    return mod;
+}
+/**
+ * Wrap a shell command for sandboxed execution.
+ *
+ * Returns the wrapped command (a single shell string suitable for
+ * `spawn(cmd, { shell: "/bin/bash" })`) when sandboxing is enabled and
+ * available. Returns null in every other case — Windows, missing package,
+ * disabled config, init failure — so the caller falls through to the
+ * unsandboxed code path unchanged.
+ */
+export async function wrapForSandbox(command, config) {
+    if (!config.enabled)
+        return null;
+    if (!_initPromise) {
+        _initPromise = loadAndInitialize(config);
+    }
+    const mod = await _initPromise;
+    if (!mod)
+        return null;
+    try {
+        return await mod.SandboxManager.wrapWithSandbox(command);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Test-only: reset the cached init promise so unit tests can re-init with
+ * different configs.
+ *
+ * @internal
+ */
+export function _resetSandboxForTest() {
+    _initPromise = null;
+}
+//# sourceMappingURL=sandbox-runtime.js.map

package/dist/providers/router.js

@@ -26,6 +26,13 @@ export class ModelRouter {
         if (context.role && powerfulRoles.includes(context.role)) {
             return this.route("powerful", `role: ${context.role}`);
         }
+        // Roles that apply mechanical changes per a prior plan → fast (cost
+        // optimization for the architect → editor pattern; the planner has
+        // already done the reasoning, so the editor doesn't need a powerful model)
+        const cheapRoles = ["editor"];
+        if (context.role && cheapRoles.includes(context.role)) {
+            return this.route("fast", `role: ${context.role}`);
+        }
         // Early exploration turns (1-2) → fast
         if (context.turn <= 2 && context.hadToolCalls) {
             return this.route("fast", "early exploration");

package/dist/tools/BashTool/index.js

@@ -1,5 +1,7 @@
 import { spawn } from "node:child_process";
 import { z } from "zod";
+import { readOhConfig } from "../../harness/config.js";
+import { wrapForSandbox } from "../../harness/sandbox-runtime.js";
 import { safeEnv } from "../../utils/safe-env.js";
 const inputSchema = z.object({
     command: z.string(),
@@ -21,12 +23,30 @@ export const BashTool = {
     isConcurrencySafe() {
         return false;
     },
-    call(input, context) {
+    async call(input, context) {
         // input.timeout is in seconds; convert to ms. Default 120s.
         const timeoutMs = Math.min((input.timeout ?? 120) * 1000, MAX_TIMEOUT);
         const isWin = process.platform === "win32";
-        const shell = isWin ? "cmd.exe" : "/bin/bash";
-        const shellArgs = isWin ? ["/c", input.command] : ["-c", input.command];
+        // Optional OS-level sandbox via @anthropic-ai/sandbox-runtime. Returns null
+        // when disabled / on Windows / when the optional dep isn't installed —
+        // caller falls back to the existing unsandboxed spawn unchanged.
+        const sandboxCfg = readOhConfig()?.sandbox;
+        const wrappedCommand = sandboxCfg ? await wrapForSandbox(input.command, sandboxCfg) : null;
+        let shell;
+        let shellArgs;
+        let extraSpawnOpts = {};
+        if (wrappedCommand) {
+            // sandbox-runtime returns a shell-string. Pin the shell to /bin/bash so
+            // the surrounding command syntax (heredocs, $((...)) etc.) keeps working
+            // — `shell: true` would default to /bin/sh on Linux.
+            shell = wrappedCommand;
+            shellArgs = [];
+            extraSpawnOpts = { shell: "/bin/bash" };
+        }
+        else {
+            shell = isWin ? "cmd.exe" : "/bin/bash";
+            shellArgs = isWin ? ["/c", input.command] : ["-c", input.command];
+        }
         // Background execution: spawn and return immediately
         if (input.run_in_background) {
             const bgId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
@@ -35,9 +55,13 @@ export const BashTool = {
                 env: safeEnv(),
                 stdio: ["ignore", "pipe", "pipe"],
                 detached: false,
+                ...extraSpawnOpts,
             });
             let stdout = "";
             let stderr = "";
+            // stdio is fixed to ["ignore", "pipe", "pipe"] above, so stdout/stderr
+            // are always streams. Adding `...extraSpawnOpts` widens the spawn
+            // overload's return type to potentially-null pipes; assert non-null.
             proc.stdout.on("data", (chunk) => {
                 stdout += chunk.toString();
             });
@@ -76,11 +100,15 @@ export const BashTool = {
                 cwd: context.workingDir,
                 env: safeEnv(),
                 stdio: ["ignore", "pipe", "pipe"],
+                ...extraSpawnOpts,
             });
             const timer = setTimeout(() => {
                 killed = true;
                 proc.kill("SIGTERM");
             }, timeoutMs);
+            // stdio: ["ignore", "pipe", "pipe"] is set above — pipes are always
+            // present here; the spread of extraSpawnOpts just widens the return
+            // type. Non-null asserts are safe.
             proc.stdout.on("data", (chunk) => {
                 const text = chunk.toString();
                 stdout += text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.32.0",
+  "version": "2.34.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {
@@ -91,6 +91,7 @@
   },
   "homepage": "https://github.com/zhijiewong/openharness#readme",
   "optionalDependencies": {
+    "@anthropic-ai/sandbox-runtime": "^0.0.49",
     "@napi-rs/keyring": "^1.2.0",
     "sharp": "^0.34.5"
   }