@zhijiewang/openharness 2.19.0 → 2.21.0

package/dist/mcp/loader.js

@@ -1,7 +1,52 @@
+import { readFileSync } from "node:fs";
 import { readOhConfig } from "../harness/config.js";
+import { debug } from "../utils/debug.js";
 import { McpClient } from "./client.js";
 import { DeferredMcpTool } from "./DeferredMcpTool.js";
 import { McpTool } from "./McpTool.js";
+/**
+ * Parse a `--mcp-config <path>` file. Format:
+ *   - `{ "mcpServers": [...] }` — Claude Code convention (preferred)
+ *   - `[ ... ]` — bare array of server configs (also accepted)
+ *   - `{ "name": ..., ... }` — single-server object (also accepted)
+ *
+ * Validation is shape-only: each entry must be an object with a `name`.
+ * Connection-time validation happens in `McpClient.connect`. Throws on
+ * malformed JSON or unrecognised top-level shape.
+ */
+export function parseMcpConfigFile(path) {
+    const raw = readFileSync(path, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`--mcp-config '${path}' is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let servers;
+    if (Array.isArray(parsed)) {
+        servers = parsed;
+    }
+    else if (parsed && typeof parsed === "object" && "mcpServers" in parsed) {
+        const list = parsed.mcpServers;
+        if (!Array.isArray(list)) {
+            throw new Error(`--mcp-config '${path}': mcpServers must be an array`);
+        }
+        servers = list;
+    }
+    else if (parsed && typeof parsed === "object" && "name" in parsed) {
+        servers = [parsed];
+    }
+    else {
+        throw new Error(`--mcp-config '${path}': expected an mcpServers array, a bare array, or a single server object`);
+    }
+    for (const s of servers) {
+        if (!s || typeof s !== "object" || typeof s.name !== "string") {
+            throw new Error(`--mcp-config '${path}': every server entry must be an object with a 'name' string`);
+        }
+    }
+    return servers;
+}
 const connectedClients = [];
 let exitHandlerInstalled = false;
 function installExitHandler() {
@@ -28,11 +73,20 @@ function installExitHandler() {
 }
 /** Threshold: servers with more tools than this use deferred loading */
 const DEFERRED_THRESHOLD = 10;
-/** Load MCP tools from .oh/config.yaml mcpServers list. Returns empty array if none configured. */
-export async function loadMcpTools() {
+/** Load MCP tools from .oh/config.yaml mcpServers list (and/or `--mcp-config` overrides). Returns empty array if none configured. */
+export async function loadMcpTools(opts = {}) {
     installExitHandler();
     const cfg = readOhConfig();
-    const servers = cfg?.mcpServers ?? [];
+    const fromConfig = opts.strict ? [] : (cfg?.mcpServers ?? []);
+    const fromExtra = opts.extraServers ?? [];
+    // Dedup by name — extras win on conflict so --mcp-config can override a
+    // project-config entry without --strict.
+    const byName = new Map();
+    for (const s of fromConfig)
+        byName.set(s.name, s);
+    for (const s of fromExtra)
+        byName.set(s.name, s);
+    const servers = Array.from(byName.values());
     if (servers.length === 0)
         return [];
     const tools = [];
@@ -45,10 +99,12 @@ export async function loadMcpTools() {
     for (const result of results) {
         if (result.status === "rejected") {
             console.warn(`[mcp] Failed to connect: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
+            debug("mcp", "connect failed", result.reason);
             continue;
         }
         const { client, defs, server } = result.value;
         connectedClients.push(client);
+        debug("mcp", "connected", { server: server.name, tools: defs.length, deferred: defs.length > DEFERRED_THRESHOLD });
         if (defs.length > DEFERRED_THRESHOLD) {
             for (const def of defs) {
                 tools.push(new DeferredMcpTool(client, def.name, def.description ?? "", server.riskLevel));
@@ -78,6 +134,33 @@ export function disconnectMcpClients() {
 export function connectedMcpServers() {
     return connectedClients.map((c) => c.name);
 }
+/**
+ * Enumerate prompts on every already-connected MCP server. Servers that don't
+ * implement the `prompts/list` capability return an empty list (handled
+ * inside `client.listPrompts`). Call AFTER `loadMcpTools()` so the client
+ * connections are warm.
+ */
+export async function loadMcpPrompts() {
+    const handles = [];
+    for (const client of connectedClients) {
+        let prompts;
+        try {
+            prompts = await client.listPrompts();
+        }
+        catch {
+            continue; // Defensive — listPrompts already swallows method-not-found
+        }
+        for (const p of prompts) {
+            handles.push({
+                qualifiedName: `${client.name}:${p.name}`,
+                description: p.description ?? `MCP prompt from ${client.name}`,
+                ...(p.arguments ? { arguments: p.arguments } : {}),
+                render: (args = {}) => client.getPrompt(p.name, args),
+            });
+        }
+    }
+    return handles;
+}
 const MAX_MCP_INSTRUCTION_LENGTH = 2000;
 /** Get MCP server instructions to inject into system prompt (sandboxed with origin markers) */
 export function getMcpInstructions() {

package/dist/query/tools.js

@@ -55,12 +55,22 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 permissionMode,
                 permissionAction: "ask",
             });
+            const denyAndEmit = (source, reason, output) => {
+                emitHook("permissionDenied", {
+                    toolName: tool.name,
+                    toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
+                    permissionMode,
+                    denySource: source,
+                    denyReason: reason,
+                });
+                return { output, isError: true };
+            };
             if (hookOutcome.permissionDecision === "allow") {
                 // Hook granted permission — proceed to execution.
             }
             else if (hookOutcome.permissionDecision === "deny" || !hookOutcome.allowed) {
                 const reason = hookOutcome.reason ? `: ${hookOutcome.reason}` : "";
-                return { output: `Permission denied by hook${reason}`, isError: true };
+                return denyAndEmit("hook", hookOutcome.reason ?? "hook denied", `Permission denied by hook${reason}`);
             }
             else if (askUser) {
                 // "ask" or no decision → interactive prompt when available
@@ -68,20 +78,25 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 const description = formatToolArgs(tool.name, toolCall.arguments);
                 const allowed = await askUser(tool.name, description, tool.riskLevel);
                 if (!allowed) {
-                    return { output: "Permission denied by user.", isError: true };
+                    return denyAndEmit("user", "user declined", "Permission denied by user.");
                 }
             }
             else {
                 // Headless mode with no hook decision and no interactive prompt:
                 // fail-closed deny. SDK consumers should configure a permissionRequest
                 // hook (or use canUseTool) to make per-call decisions.
-                return {
-                    output: "Permission denied: needs-approval (no interactive prompt available; configure a permissionRequest hook to gate this tool)",
-                    isError: true,
-                };
+                return denyAndEmit("headless", "no hook decision and no interactive prompt available", "Permission denied: needs-approval (no interactive prompt available; configure a permissionRequest hook to gate this tool)");
             }
         }
         else {
+            // Auto-mode policy block (deny / acceptEdits / etc) — symmetric event.
+            emitHook("permissionDenied", {
+                toolName: tool.name,
+                toolArgs: JSON.stringify(toolCall.arguments).slice(0, 1000),
+                permissionMode,
+                denySource: "policy",
+                denyReason: perm.reason,
+            });
             return { output: `Permission denied: ${perm.reason}`, isError: true };
         }
     }
@@ -200,6 +215,7 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
     const onOutputChunk = (callId, chunk) => {
         outputChunks.push({ type: "tool_output_delta", callId, chunk });
     };
+    const allToolNames = toolCalls.map((tc) => tc.toolName);
     for (const batch of batches) {
         if (batch.concurrent) {
             const results = await Promise.all(batch.calls.map((tc) => executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser)));
@@ -222,5 +238,17 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
             }
         }
     }
+    // Hook: postToolBatch — fires once after the model's full set of tool
+    // calls for this turn have all resolved (across however many serial /
+    // concurrent batches partitionToolCalls produced), before the next model
+    // call. Per-tool postToolUse / postToolUseFailure still fire as before;
+    // this is the batch-level boundary for hooks that want to act once per
+    // turn instead of once per tool.
+    if (toolCalls.length > 0) {
+        emitHook("postToolBatch", {
+            batchSize: String(toolCalls.length),
+            batchTools: allToolNames.slice(0, 50).join(","),
+        });
+    }
 }
 //# sourceMappingURL=tools.js.map

package/dist/tools/EnterWorktreeTool/index.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { createWorktree, isGitRepo } from "../../git/index.js";
+import { emitHook } from "../../harness/hooks.js";
 const inputSchema = z.object({
     branch: z.string().optional().describe("Branch name for the worktree (auto-generated if omitted)"),
 });
@@ -22,6 +23,9 @@ export const EnterWorktreeTool = {
         if (!path) {
             return { output: "Failed to create worktree.", isError: true };
         }
+        // Symmetric to taskCreated — fire only on the success path so audit hooks
+        // can react to the new worktree (e.g. set up a per-worktree scratch dir).
+        emitHook("worktreeCreate", { worktreePath: path, worktreeParent: context.workingDir });
         return { output: `Worktree created at: ${path}\nUse ExitWorktree to clean up when done.`, isError: false };
     },
     prompt() {

package/dist/tools/ExitWorktreeTool/index.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { hasWorktreeChanges, removeWorktree } from "../../git/index.js";
+import { emitHook } from "../../harness/hooks.js";
 const inputSchema = z.object({
     path: z.string().describe("Path to the worktree to remove"),
     force: z.boolean().optional().describe("Force removal even with uncommitted changes"),
@@ -24,6 +25,12 @@ export const ExitWorktreeTool = {
         }
         try {
             removeWorktree(input.path);
+            // Fire after removeWorktree resolves so the hook only sees confirmed
+            // removals — symmetric to worktreeCreate firing on success.
+            emitHook("worktreeRemove", {
+                worktreePath: input.path,
+                worktreeForced: input.force ? "true" : "false",
+            });
             return { output: `Worktree removed: ${input.path}`, isError: false };
         }
         catch (err) {

package/dist/tools/TaskCreateTool/index.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { z } from "zod";
+import { emitHook } from "../../harness/hooks.js";
 const inputSchema = z.object({
     subject: z.string(),
     description: z.string(),
@@ -42,6 +43,10 @@ export const TaskCreateTool = {
             };
             tasks.push(newTask);
             await fs.writeFile(filePath, JSON.stringify(tasks, null, 2), "utf-8");
+            emitHook("taskCreated", {
+                taskId: String(newTask.id),
+                taskSubject: newTask.subject.slice(0, 200),
+            });
             return { output: `Task #${newTask.id} created: ${newTask.subject}`, isError: false };
         }
         catch (err) {

package/dist/tools/TaskUpdateTool/index.js

@@ -1,6 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { z } from "zod";
+import { emitHook } from "../../harness/hooks.js";
 const inputSchema = z.object({
     taskId: z.number(),
     status: z.enum(["pending", "in_progress", "completed", "cancelled", "deleted"]).optional(),
@@ -32,6 +33,7 @@ export const TaskUpdateTool = {
             if (!task) {
                 return { output: `Error: Task #${input.taskId} not found.`, isError: true };
             }
+            const previousStatus = task.status;
             // Handle deletion
             if (input.status === "deleted") {
                 const idx = tasks.indexOf(task);
@@ -69,6 +71,15 @@ export const TaskUpdateTool = {
                 task.blockedBy = [...new Set([...(task.blockedBy ?? []), ...input.addBlockedBy])];
             }
             await fs.writeFile(filePath, JSON.stringify(tasks, null, 2), "utf-8");
+            // Hook: taskCompleted — fires only on the pending|in_progress → completed
+            // transition. Re-saving an already-completed task is a no-op for the hook.
+            if (input.status === "completed" && previousStatus !== "completed") {
+                emitHook("taskCompleted", {
+                    taskId: String(task.id),
+                    taskSubject: task.subject.slice(0, 200),
+                    taskPreviousStatus: previousStatus,
+                });
+            }
             return { output: `Task #${task.id} updated. Status: ${task.status}`, isError: false };
         }
         catch (err) {

package/dist/utils/debug.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Categorized debug logger — gates verbose internal traces behind a runtime
+ * switch so they're silent by default but easy to flip on for support / CI.
+ *
+ * Activation precedence (highest first):
+ *   1. `configureDebug({ categories })` from a CLI flag (`--debug [cats]`)
+ *   2. `OH_DEBUG` env var
+ *
+ * Sink precedence:
+ *   1. `configureDebug({ file })` from `--debug-file <path>`
+ *   2. `OH_DEBUG_FILE` env var
+ *   3. `process.stderr` (default)
+ *
+ * Categories are arbitrary strings — call sites pick them. The CLI accepts a
+ * comma-separated list (`--debug mcp,hooks`) or `--debug` alone for "all".
+ *
+ * Wire pattern:
+ *   import { configureDebug, debug } from "./utils/debug.js";
+ *   configureDebug({ categories: opts.debug, file: opts.debugFile });
+ *   debug("mcp", "connected", server.name);
+ */
+/**
+ * Parse the raw flag value into a Set of enabled categories.
+ *
+ * Accepted values:
+ *   - `undefined` / empty / `false`     → no debug
+ *   - `true` / `"*"` / `"all"` / `"1"`  → all categories
+ *   - `"mcp,hooks,provider"`            → comma-separated explicit list
+ *
+ * Whitespace is trimmed and empty entries dropped, so `"mcp, ,hooks"` is
+ * equivalent to `"mcp,hooks"`. Pure function — exposed for testability.
+ */
+export declare function parseDebugCategories(raw: string | boolean | undefined): Set<string>;
+export interface ConfigureDebugOptions {
+    /** CLI flag value: `--debug` → true, `--debug mcp` → "mcp", absent → undefined. */
+    categories?: string | boolean | undefined;
+    /** CLI flag value: `--debug-file <path>` — appended to, never truncated. */
+    file?: string;
+    /** Test injection — overrides the file/stderr sink. Not used at runtime. */
+    sink?: NodeJS.WritableStream;
+}
+/**
+ * Apply debug configuration. Safe to call multiple times — later calls fully
+ * replace earlier state. When `categories` is undefined, falls back to
+ * `OH_DEBUG`; when `file` is undefined, falls back to `OH_DEBUG_FILE`.
+ *
+ * File output uses `appendFileSync` rather than a `WriteStream` so each
+ * `debug()` line lands on disk before the function returns. That trades a
+ * little throughput for ordering guarantees that matter when debugging
+ * crashes — a streamed sink could lose its tail buffer on `process.exit`.
+ */
+export declare function configureDebug(opts?: ConfigureDebugOptions): void;
+/** Whether the given category is currently emitting. Cheap — a Set lookup. */
+export declare function isDebugEnabled(category: string): boolean;
+/**
+ * Emit a debug line for the given category. Cheap no-op when the category is
+ * disabled — argument formatting is skipped entirely. Each line is prefixed
+ * with `[debug:<cat>] +<elapsed_ms>ms` so categories interleave readably.
+ */
+export declare function debug(category: string, ...args: unknown[]): void;
+/** @internal Test-only: reset module-level state between cases. */
+export declare function _resetDebugForTest(): void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/utils/debug.js

@@ -0,0 +1,122 @@
+/**
+ * Categorized debug logger — gates verbose internal traces behind a runtime
+ * switch so they're silent by default but easy to flip on for support / CI.
+ *
+ * Activation precedence (highest first):
+ *   1. `configureDebug({ categories })` from a CLI flag (`--debug [cats]`)
+ *   2. `OH_DEBUG` env var
+ *
+ * Sink precedence:
+ *   1. `configureDebug({ file })` from `--debug-file <path>`
+ *   2. `OH_DEBUG_FILE` env var
+ *   3. `process.stderr` (default)
+ *
+ * Categories are arbitrary strings — call sites pick them. The CLI accepts a
+ * comma-separated list (`--debug mcp,hooks`) or `--debug` alone for "all".
+ *
+ * Wire pattern:
+ *   import { configureDebug, debug } from "./utils/debug.js";
+ *   configureDebug({ categories: opts.debug, file: opts.debugFile });
+ *   debug("mcp", "connected", server.name);
+ */
+import { appendFileSync } from "node:fs";
+const ALL = "*";
+let enabledCategories = new Set();
+let debugFilePath;
+let sinkOverride;
+let started = Date.now();
+/**
+ * Parse the raw flag value into a Set of enabled categories.
+ *
+ * Accepted values:
+ *   - `undefined` / empty / `false`     → no debug
+ *   - `true` / `"*"` / `"all"` / `"1"`  → all categories
+ *   - `"mcp,hooks,provider"`            → comma-separated explicit list
+ *
+ * Whitespace is trimmed and empty entries dropped, so `"mcp, ,hooks"` is
+ * equivalent to `"mcp,hooks"`. Pure function — exposed for testability.
+ */
+export function parseDebugCategories(raw) {
+    if (raw === undefined || raw === false || raw === "")
+        return new Set();
+    if (raw === true)
+        return new Set([ALL]);
+    const lower = raw.toLowerCase();
+    if (lower === "*" || lower === "all" || lower === "true" || lower === "1")
+        return new Set([ALL]);
+    return new Set(raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean));
+}
+/**
+ * Apply debug configuration. Safe to call multiple times — later calls fully
+ * replace earlier state. When `categories` is undefined, falls back to
+ * `OH_DEBUG`; when `file` is undefined, falls back to `OH_DEBUG_FILE`.
+ *
+ * File output uses `appendFileSync` rather than a `WriteStream` so each
+ * `debug()` line lands on disk before the function returns. That trades a
+ * little throughput for ordering guarantees that matter when debugging
+ * crashes — a streamed sink could lose its tail buffer on `process.exit`.
+ */
+export function configureDebug(opts = {}) {
+    const rawCats = opts.categories !== undefined ? opts.categories : process.env.OH_DEBUG;
+    enabledCategories = parseDebugCategories(rawCats);
+    sinkOverride = opts.sink;
+    debugFilePath = opts.sink ? undefined : (opts.file ?? process.env.OH_DEBUG_FILE);
+    started = Date.now();
+}
+/** Whether the given category is currently emitting. Cheap — a Set lookup. */
+export function isDebugEnabled(category) {
+    return enabledCategories.has(ALL) || enabledCategories.has(category);
+}
+/**
+ * Emit a debug line for the given category. Cheap no-op when the category is
+ * disabled — argument formatting is skipped entirely. Each line is prefixed
+ * with `[debug:<cat>] +<elapsed_ms>ms` so categories interleave readably.
+ */
+export function debug(category, ...args) {
+    if (!isDebugEnabled(category))
+        return;
+    const elapsed = Date.now() - started;
+    const formatted = args
+        .map((a) => {
+        if (typeof a === "string")
+            return a;
+        if (a instanceof Error)
+            return a.stack ?? a.message;
+        try {
+            return JSON.stringify(a);
+        }
+        catch {
+            return String(a);
+        }
+    })
+        .join(" ");
+    const line = `[debug:${category}] +${elapsed}ms ${formatted}\n`;
+    if (sinkOverride) {
+        sinkOverride.write(line);
+    }
+    else if (debugFilePath) {
+        try {
+            appendFileSync(debugFilePath, line);
+        }
+        catch (err) {
+            // Fall back to stderr so a broken --debug-file doesn't swallow output.
+            process.stderr.write(`[debug] could not append to '${debugFilePath}': ${err instanceof Error ? err.message : String(err)}\n`);
+            process.stderr.write(line);
+            debugFilePath = undefined;
+        }
+    }
+    else {
+        process.stderr.write(line);
+    }
+}
+/** @internal Test-only: reset module-level state between cases. */
+export function _resetDebugForTest() {
+    enabledCategories = new Set();
+    debugFilePath = undefined;
+    sinkOverride = undefined;
+    started = Date.now();
+}
+//# sourceMappingURL=debug.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.19.0",
+  "version": "2.21.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {