@zhijiewang/openharness 2.21.0 → 2.22.0

package/dist/mcp/elicitation.js

@@ -0,0 +1,88 @@
+/**
+ * MCP `elicitation/create` responder (audit B4).
+ *
+ * MCP servers can ask the client to elicit user input — for confirmations
+ * ("are you sure?"), for form fills, or for free-form text. The spec defines
+ * three response actions:
+ *   - `accept`   → user agreed; `content` may contain form values
+ *   - `decline`  → user explicitly said no
+ *   - `cancel`   → user dismissed without choosing (e.g. closed the prompt)
+ *
+ * Default behavior is **fail-safe decline** — when nothing decides, OH
+ * returns `{ action: "decline" }`. This keeps OH from accepting actions
+ * silently in headless / unattended mode. To accept, configure an
+ * `elicitation` hook that returns `permissionDecision: "allow"`, or wire an
+ * interactive handler via `setElicitationHandler` (the REPL will plug in
+ * when its UX support lands; until then the hook path is the supported
+ * extension point).
+ *
+ * Two hook events fire per elicitation:
+ *   - `elicitation`        — request received, before any decision
+ *   - `elicitationResult`  — final action + content, after decision is made
+ *
+ * Both carry the server name and message so audit hooks can log the
+ * full request/response pair.
+ */
+import { emitHook, emitHookWithOutcome } from "../harness/hooks.js";
+let interactiveHandler;
+/**
+ * Register / replace the interactive elicitation handler. Pass `undefined`
+ * to clear (for tests / REPL teardown). Idempotent.
+ */
+export function setElicitationHandler(handler) {
+    interactiveHandler = handler;
+}
+/**
+ * Resolve an MCP `elicitation/create` request into an `ElicitationResponse`.
+ *
+ * Decision priority:
+ *   1. `elicitation` hook returns a decision → honor it (allow → accept, deny → decline)
+ *   2. Interactive handler is registered → delegate to it
+ *   3. Default → `{ action: "decline" }`
+ *
+ * Always fires the symmetric `elicitationResult` hook last, so audit hooks
+ * see the full request/response pair regardless of which branch decided.
+ *
+ * @internal Exported for tests; transport.ts is the production caller.
+ */
+export async function resolveElicitation(req) {
+    const hookCtx = {
+        elicitationServer: req.serverName,
+        elicitationMessage: req.message.slice(0, 500),
+        // Schema can be large; cap at 2 KB so hooks don't OOM env vars.
+        elicitationSchema: JSON.stringify(req.requestedSchema).slice(0, 2_000),
+    };
+    let response;
+    const hookOutcome = await emitHookWithOutcome("elicitation", hookCtx);
+    if (hookOutcome.permissionDecision === "allow") {
+        response = { action: "accept", content: {} };
+    }
+    else if (hookOutcome.permissionDecision === "deny" || !hookOutcome.allowed) {
+        response = { action: "decline" };
+    }
+    else if (interactiveHandler) {
+        try {
+            response = await interactiveHandler(req);
+        }
+        catch {
+            // Interactive handler crashed — fail-safe decline rather than swallow.
+            response = { action: "cancel" };
+        }
+    }
+    else {
+        // Headless default — never accept silently.
+        response = { action: "decline" };
+    }
+    emitHook("elicitationResult", {
+        elicitationServer: req.serverName,
+        elicitationMessage: req.message.slice(0, 500),
+        elicitationAction: response.action,
+        elicitationContent: response.content ? JSON.stringify(response.content).slice(0, 2_000) : undefined,
+    });
+    return response;
+}
+/** @internal Test-only reset. */
+export function _resetElicitationForTest() {
+    interactiveHandler = undefined;
+}
+//# sourceMappingURL=elicitation.js.map

package/dist/mcp/roots.d.ts

@@ -0,0 +1,36 @@
+/**
+ * MCP `roots/list` responder (audit B3).
+ *
+ * The MCP spec lets a server ask the client "which file system roots are in
+ * scope?" via the `roots/list` request. This module owns OH's answer.
+ *
+ * Roots are computed at request time (no caching) so a `cd` inside the REPL
+ * or a future `--add-dir` flag flip is reflected immediately. The set is:
+ *   - process.cwd() — always included
+ *   - any directories supplied via `setExtraRoots()` — for `--add-dir` /
+ *     `/add-dir` integrations once they're properly wired (audit A7 deferred).
+ *
+ * Pure module with one mutable Set; the SDK handler in `transport.ts` calls
+ * `getRoots()` at request time. Exported `setExtraRoots` lets later wiring
+ * extend the set without restarting the MCP connection.
+ */
+export interface McpRoot {
+    uri: string;
+    name?: string;
+}
+/**
+ * Build the current root list. Always includes the process cwd. Extra roots
+ * (added via `setExtraRoots`) are deduplicated against the cwd. Each root is
+ * a `file://` URI per the MCP spec; `name` is the basename for readability.
+ */
+export declare function getRoots(): McpRoot[];
+/**
+ * Replace the extra-roots set. Empty array clears it. Idempotent — passing
+ * the same set twice is a no-op for downstream observers.
+ *
+ * @internal Public for tests + future `--add-dir` wiring.
+ */
+export declare function setExtraRoots(paths: readonly string[]): void;
+/** @internal Test-only reset. */
+export declare function _resetRootsForTest(): void;
+//# sourceMappingURL=roots.d.ts.map

package/dist/mcp/roots.js

@@ -0,0 +1,56 @@
+/**
+ * MCP `roots/list` responder (audit B3).
+ *
+ * The MCP spec lets a server ask the client "which file system roots are in
+ * scope?" via the `roots/list` request. This module owns OH's answer.
+ *
+ * Roots are computed at request time (no caching) so a `cd` inside the REPL
+ * or a future `--add-dir` flag flip is reflected immediately. The set is:
+ *   - process.cwd() — always included
+ *   - any directories supplied via `setExtraRoots()` — for `--add-dir` /
+ *     `/add-dir` integrations once they're properly wired (audit A7 deferred).
+ *
+ * Pure module with one mutable Set; the SDK handler in `transport.ts` calls
+ * `getRoots()` at request time. Exported `setExtraRoots` lets later wiring
+ * extend the set without restarting the MCP connection.
+ */
+import { pathToFileURL } from "node:url";
+const extraRoots = new Set();
+/**
+ * Build the current root list. Always includes the process cwd. Extra roots
+ * (added via `setExtraRoots`) are deduplicated against the cwd. Each root is
+ * a `file://` URI per the MCP spec; `name` is the basename for readability.
+ */
+export function getRoots() {
+    const seen = new Set();
+    const out = [];
+    const push = (path) => {
+        if (!path || seen.has(path))
+            return;
+        seen.add(path);
+        const uri = pathToFileURL(path).toString();
+        const segments = path.split(/[\\/]/).filter(Boolean);
+        const name = segments[segments.length - 1] ?? path;
+        out.push({ uri, name });
+    };
+    push(process.cwd());
+    for (const p of extraRoots)
+        push(p);
+    return out;
+}
+/**
+ * Replace the extra-roots set. Empty array clears it. Idempotent — passing
+ * the same set twice is a no-op for downstream observers.
+ *
+ * @internal Public for tests + future `--add-dir` wiring.
+ */
+export function setExtraRoots(paths) {
+    extraRoots.clear();
+    for (const p of paths)
+        extraRoots.add(p);
+}
+/** @internal Test-only reset. */
+export function _resetRootsForTest() {
+    extraRoots.clear();
+}
+//# sourceMappingURL=roots.js.map

package/dist/mcp/transport.js

@@ -4,6 +4,9 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { ElicitRequestSchema, ListRootsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { resolveElicitation } from "./elicitation.js";
+import { getRoots } from "./roots.js";
 const pkg = createRequire(import.meta.url)("../../package.json");
 export class RemoteAuthRequiredError extends Error {
     serverName;
@@ -136,7 +139,30 @@ function hasAwaitCallback(p) {
  */
 export async function buildClient(cfg, opts = {}) {
     const transport = await buildTransport(cfg, opts);
-    const client = new Client(CLIENT_INFO, { capabilities: {} });
+    // Advertise the `roots` capability (audit B3) so MCP servers know they
+    // can ask OH which file system roots are in scope, and the `elicitation`
+    // capability (audit B4) so they can request user input. listChanged on
+    // roots is false — OH doesn't push notifications when the cwd changes;
+    // servers re-query on demand.
+    const client = new Client(CLIENT_INFO, {
+        capabilities: { roots: { listChanged: false }, elicitation: {} },
+    });
+    client.setRequestHandler(ListRootsRequestSchema, () => ({ roots: getRoots() }));
+    // Elicitation handler — only the form-mode (requestedSchema) variant is
+    // supported. URL-mode elicitations decline by default — we don't open
+    // browsers from the MCP path. Cast `as never` lets the SDK's wide union
+    // accept our narrower response shape.
+    client.setRequestHandler(ElicitRequestSchema, async (request) => {
+        const params = request.params;
+        if (params.requestedSchema === undefined) {
+            return { action: "decline" };
+        }
+        return (await resolveElicitation({
+            serverName: cfg.name,
+            message: params.message,
+            requestedSchema: params.requestedSchema,
+        }));
+    });
     const timeoutMs = cfg.timeout ?? DEFAULT_TIMEOUT_MS;
     async function tryConnect() {
         let timer = null;
@@ -175,9 +201,25 @@ export async function buildClient(cfg, opts = {}) {
                 catch {
                     // best-effort
                 }
-                // Build a fresh transport + client for the authenticated retry
+                // Build a fresh transport + client for the authenticated retry — same
+                // capabilities + handlers as the initial client (audit B3 roots,
+                // audit B4 elicitation).
                 const freshTransport = await buildTransport(cfg, opts);
-                const freshClient = new Client(CLIENT_INFO, { capabilities: {} });
+                const freshClient = new Client(CLIENT_INFO, {
+                    capabilities: { roots: { listChanged: false }, elicitation: {} },
+                });
+                freshClient.setRequestHandler(ListRootsRequestSchema, () => ({ roots: getRoots() }));
+                freshClient.setRequestHandler(ElicitRequestSchema, async (request) => {
+                    const params = request.params;
+                    if (params.requestedSchema === undefined) {
+                        return { action: "decline" };
+                    }
+                    return (await resolveElicitation({
+                        serverName: cfg.name,
+                        message: params.message,
+                        requestedSchema: params.requestedSchema,
+                    }));
+                });
                 let freshTimer = null;
                 try {
                     await Promise.race([

package/dist/providers/index.d.ts

@@ -4,11 +4,35 @@
 import type { Provider, ProviderConfig } from "./base.js";
 /**
  * Create a provider from a model string like "ollama/llama3" or "gpt-4o".
+ *
+ * `opts.fallbackModel` (audit B2) is the CLI override path for the existing
+ * `fallbackProviders` config — when set, REPLACES the config-file fallbacks
+ * with a single entry derived from the model string. Mirrors Claude Code's
+ * `--fallback-model <model>` for one-shot CI runs that want a fallback
+ * without editing `.oh/config.yaml`. Format matches `modelArg`:
+ * `provider/model` or just `model` (provider guessed). When unset, the
+ * existing config-file path is unchanged.
  */
-export declare function createProvider(modelArg?: string, overrides?: Partial<ProviderConfig>): Promise<{
+export declare function createProvider(modelArg?: string, overrides?: Partial<ProviderConfig>, opts?: {
+    fallbackModel?: string;
+}): Promise<{
     provider: Provider;
     model: string;
 }>;
+/**
+ * Parse `--fallback-model <value>` into the same shape as a `fallbackProviders[]`
+ * entry. Accepts `provider/model` (explicit) or just `model` (provider guessed
+ * via `guessProviderFromModel`, same as the primary modelArg). Exposed for
+ * tests.
+ *
+ * @internal
+ */
+export declare function parseFallbackModel(raw: string): {
+    provider: string;
+    model?: string;
+    apiKey?: string;
+    baseUrl?: string;
+};
 export { createProviderInstance, guessProviderFromModel };
 declare function createProviderInstance(name: string, config: ProviderConfig): Provider;
 declare function guessProviderFromModel(model: string): string;

package/dist/providers/index.js

@@ -10,8 +10,16 @@ import { OpenAIProvider } from "./openai.js";
 import { OpenRouterProvider } from "./openrouter.js";
 /**
  * Create a provider from a model string like "ollama/llama3" or "gpt-4o".
+ *
+ * `opts.fallbackModel` (audit B2) is the CLI override path for the existing
+ * `fallbackProviders` config — when set, REPLACES the config-file fallbacks
+ * with a single entry derived from the model string. Mirrors Claude Code's
+ * `--fallback-model <model>` for one-shot CI runs that want a fallback
+ * without editing `.oh/config.yaml`. Format matches `modelArg`:
+ * `provider/model` or just `model` (provider guessed). When unset, the
+ * existing config-file path is unchanged.
  */
-export async function createProvider(modelArg, overrides) {
+export async function createProvider(modelArg, overrides, opts = {}) {
     let providerName = "ollama";
     let model = "llama3";
     if (modelArg) {
@@ -32,7 +40,9 @@ export async function createProvider(modelArg, overrides) {
         ...overrides,
     };
     const primary = createProviderInstance(providerName, config);
-    const fallbackCfgs = readOhConfig()?.fallbackProviders ?? [];
+    const fallbackCfgs = opts.fallbackModel
+        ? [parseFallbackModel(opts.fallbackModel)]
+        : (readOhConfig()?.fallbackProviders ?? []);
     if (fallbackCfgs.length === 0) {
         return { provider: primary, model };
     }
@@ -48,6 +58,21 @@ export async function createProvider(modelArg, overrides) {
     const wrapped = createFallbackProvider(primary, fallbacks);
     return { provider: wrapped, model };
 }
+/**
+ * Parse `--fallback-model <value>` into the same shape as a `fallbackProviders[]`
+ * entry. Accepts `provider/model` (explicit) or just `model` (provider guessed
+ * via `guessProviderFromModel`, same as the primary modelArg). Exposed for
+ * tests.
+ *
+ * @internal
+ */
+export function parseFallbackModel(raw) {
+    if (raw.includes("/")) {
+        const [p, m] = raw.split("/", 2);
+        return { provider: p, model: m };
+    }
+    return { provider: guessProviderFromModel(raw), model: raw };
+}
 export { createProviderInstance, guessProviderFromModel };
 function createProviderInstance(name, config) {
     switch (name) {

package/dist/query/index.js

@@ -311,7 +311,7 @@ export async function* query(userMessage, config, existingMessages = []) {
         // Execute remaining tools not started during streaming
         const remaining = toolCalls.filter((tc) => !executedIds.has(tc.id));
         if (remaining.length > 0) {
-            yield* executeToolCalls(remaining, config.tools, toolContext, config.permissionMode, config.askUser, state);
+            yield* executeToolCalls(remaining, config.tools, toolContext, config.permissionMode, config.askUser, state, config.permissionPromptTool);
         }
         state.lastTurnHadTools = toolCalls.length > 0;
         state.lastTurnToolCount = toolCalls.length;

package/dist/query/tools.d.ts

@@ -11,7 +11,7 @@ type Batch = {
     calls: ToolCall[];
 };
 export declare function partitionToolCalls(toolCalls: ToolCall[], tools: Tools): Batch[];
-export declare function executeSingleTool(toolCall: ToolCall, tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn): Promise<ToolResult>;
-export declare function executeToolCalls(toolCalls: ToolCall[], tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, state?: QueryLoopState): AsyncGenerator<StreamEvent, void>;
+export declare function executeSingleTool(toolCall: ToolCall, tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, permissionPromptTool?: string): Promise<ToolResult>;
+export declare function executeToolCalls(toolCalls: ToolCall[], tools: Tools, context: ToolContext, permissionMode: PermissionMode, askUser?: AskUserFn, state?: QueryLoopState, permissionPromptTool?: string): AsyncGenerator<StreamEvent, void>;
 export {};
 //# sourceMappingURL=tools.d.ts.map

package/dist/query/tools.js

@@ -8,6 +8,42 @@ import { createToolResultMessage } from "../types/message.js";
 import { checkPermission } from "../types/permissions.js";
 const MAX_TOOL_RESULT_CHARS = 100_000;
 const TOOL_TIMEOUT_MS = 120_000;
+/**
+ * Invoke the configured `--permission-prompt-tool` (audit B1). The tool is
+ * looked up by name in the active tool registry (so MCP tools wired through
+ * `loadMcpTools` are reachable). Failure modes — missing tool, exception
+ * during call, malformed JSON, unknown `behavior` — collapse into
+ * `behavior: "fallthrough"` so the caller can try the next branch
+ * (interactive prompt or headless deny). A broken permission tool must
+ * not lock the user out.
+ */
+async function callPermissionPromptTool(toolName, tools, context, permissionedToolName, permissionedInput) {
+    const promptTool = findToolByName(tools, toolName);
+    if (!promptTool)
+        return { behavior: "fallthrough" };
+    let raw;
+    try {
+        raw = await promptTool.call({ tool_name: permissionedToolName, input: permissionedInput }, context);
+    }
+    catch {
+        return { behavior: "fallthrough" };
+    }
+    if (raw.isError)
+        return { behavior: "fallthrough" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.output);
+    }
+    catch {
+        return { behavior: "fallthrough" };
+    }
+    if (parsed.behavior === "allow")
+        return { behavior: "allow" };
+    if (parsed.behavior === "deny") {
+        return parsed.message ? { behavior: "deny", message: parsed.message } : { behavior: "deny" };
+    }
+    return { behavior: "fallthrough" };
+}
 export function partitionToolCalls(toolCalls, tools) {
     const batches = [];
     let currentConcurrent = [];
@@ -30,7 +66,7 @@ export function partitionToolCalls(toolCalls, tools) {
     }
     return batches;
 }
-export async function executeSingleTool(toolCall, tools, context, permissionMode, askUser) {
+export async function executeSingleTool(toolCall, tools, context, permissionMode, askUser, permissionPromptTool) {
     const tool = findToolByName(tools, toolCall.toolName);
     if (!tool) {
         return { output: `Error: Unknown tool '${toolCall.toolName}'`, isError: true };
@@ -72,6 +108,34 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
                 const reason = hookOutcome.reason ? `: ${hookOutcome.reason}` : "";
                 return denyAndEmit("hook", hookOutcome.reason ?? "hook denied", `Permission denied by hook${reason}`);
             }
+            else if (permissionPromptTool) {
+                // No hook decision → consult the configured MCP permission tool
+                // (audit B1). Mirrors Claude Code's --permission-prompt-tool. The
+                // tool returns JSON: { "behavior": "allow" | "deny", "message"?: string }.
+                // On any failure (tool missing, throws, malformed JSON, unknown
+                // behavior) we fall through to askUser / headless deny so a broken
+                // permission tool doesn't lock the user out.
+                const promptDecision = await callPermissionPromptTool(permissionPromptTool, tools, context, tool.name, parsed.data);
+                if (promptDecision.behavior === "allow") {
+                    // Permission tool granted — proceed.
+                }
+                else if (promptDecision.behavior === "deny") {
+                    return denyAndEmit("permission-prompt-tool", promptDecision.message ?? "denied", `Permission denied by ${permissionPromptTool}${promptDecision.message ? `: ${promptDecision.message}` : ""}`);
+                }
+                else if (askUser) {
+                    // promptDecision.behavior === "fallthrough" — tool was unavailable
+                    // or its response was malformed. Try the interactive prompt next.
+                    const { formatToolArgs } = await import("../utils/tool-summary.js");
+                    const description = formatToolArgs(tool.name, toolCall.arguments);
+                    const allowed = await askUser(tool.name, description, tool.riskLevel);
+                    if (!allowed) {
+                        return denyAndEmit("user", "user declined", "Permission denied by user.");
+                    }
+                }
+                else {
+                    return denyAndEmit("headless", "permission-prompt-tool unavailable and no interactive prompt", `Permission denied: ${permissionPromptTool} did not produce a usable decision and no interactive prompt is available.`);
+                }
+            }
             else if (askUser) {
                 // "ask" or no decision → interactive prompt when available
                 const { formatToolArgs } = await import("../utils/tool-summary.js");
@@ -209,7 +273,7 @@ export async function executeSingleTool(toolCall, tools, context, permissionMode
         return { output: `Tool error: ${errMsg}`, isError: true };
     }
 }
-export async function* executeToolCalls(toolCalls, tools, context, permissionMode, askUser, state) {
+export async function* executeToolCalls(toolCalls, tools, context, permissionMode, askUser, state, permissionPromptTool) {
     const batches = partitionToolCalls(toolCalls, tools);
     const outputChunks = [];
     const onOutputChunk = (callId, chunk) => {
@@ -218,7 +282,7 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
     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)));
+            const results = await Promise.all(batch.calls.map((tc) => executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser, permissionPromptTool)));
             for (const chunk of outputChunks.splice(0))
                 yield chunk;
             for (let i = 0; i < batch.calls.length; i++) {
@@ -230,7 +294,7 @@ export async function* executeToolCalls(toolCalls, tools, context, permissionMod
         }
         else {
             for (const tc of batch.calls) {
-                const result = await executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser);
+                const result = await executeSingleTool(tc, tools, { ...context, callId: tc.id, onOutputChunk }, permissionMode, askUser, permissionPromptTool);
                 for (const chunk of outputChunks.splice(0))
                     yield chunk;
                 yield { type: "tool_call_end", callId: tc.id, output: result.output, isError: result.isError };

package/dist/query/types.d.ts

@@ -22,6 +22,16 @@ export type QueryConfig = {
     gitCommitPerTool?: boolean;
     /** For sub-agent invocations: the agent role name (feeds into the model router). */
     role?: string;
+    /**
+     * MCP tool name (e.g. `mcp__myperm__check`) consulted when a tool needs
+     * approval and no permission hook gave a decision (audit B1). Mirrors
+     * Claude Code's `--permission-prompt-tool`. The tool is invoked with
+     * `{ tool_name, input }` and is expected to return a JSON string with
+     * shape `{ "behavior": "allow" | "deny", "message"?: string }`. Falls
+     * through to the interactive `askUser` prompt (or headless deny) when
+     * the tool is missing, throws, or returns malformed JSON.
+     */
+    permissionPromptTool?: string;
 };
 export type TransitionReason = "next_turn" | "retry_network" | "retry_prompt_too_long" | "retry_max_output_tokens";
 export type QueryLoopState = {

package/dist/utils/install-method.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Detect how the running OH CLI was installed (audit B7) so `oh update` can
+ * print the appropriate upgrade command. Pure function — `detectInstallMethod`
+ * inspects the process's own filesystem path and current working directory;
+ * exported for unit testing and reuse.
+ *
+ * Detection rules, in order:
+ *   - "local-clone"   → `dist/main.js` lives inside a git repo whose root is
+ *                       the package itself (the user is running from a clone).
+ *                       Suggest `git pull && npm install && npm run build`.
+ *   - "npm-global"    → `dist/main.js` lives under a directory containing the
+ *                       segment `node_modules/@zhijiewang/openharness/`. This
+ *                       is the standard npm global install layout. Suggest
+ *                       `npm install -g @zhijiewang/openharness@latest`.
+ *   - "npx-cache"     → `dist/main.js` lives under a path containing
+ *                       `_npx/` (npx caches packages there). npx auto-fetches
+ *                       the latest by default; suggest re-running with
+ *                       `@latest` to bypass cache.
+ *   - "unknown"       → Couldn't classify. Print all three options and let
+ *                       the user choose.
+ */
+export type InstallMethod = "local-clone" | "npm-global" | "npx-cache" | "unknown";
+export interface InstallMethodResult {
+    method: InstallMethod;
+    /** The detected install root, mostly for diagnostics. */
+    root: string;
+    /** Multi-line user-facing message describing the upgrade command. */
+    message: string;
+}
+/**
+ * Classify the install method given the running script's filesystem path.
+ * `mainPath` defaults to `import.meta.url`-derived path in the CLI; tests
+ * override it.
+ */
+export declare function detectInstallMethod(mainPath: string): InstallMethodResult;
+/**
+ * Default `mainPath` resolver — walks up from `process.argv[1]` to find the
+ * package root. Exported so tests can stub it. Falls back to argv[1] verbatim
+ * when nothing matches.
+ */
+export declare function getDefaultMainPath(): string;
+//# sourceMappingURL=install-method.d.ts.map

package/dist/utils/install-method.js

@@ -0,0 +1,110 @@
+/**
+ * Detect how the running OH CLI was installed (audit B7) so `oh update` can
+ * print the appropriate upgrade command. Pure function — `detectInstallMethod`
+ * inspects the process's own filesystem path and current working directory;
+ * exported for unit testing and reuse.
+ *
+ * Detection rules, in order:
+ *   - "local-clone"   → `dist/main.js` lives inside a git repo whose root is
+ *                       the package itself (the user is running from a clone).
+ *                       Suggest `git pull && npm install && npm run build`.
+ *   - "npm-global"    → `dist/main.js` lives under a directory containing the
+ *                       segment `node_modules/@zhijiewang/openharness/`. This
+ *                       is the standard npm global install layout. Suggest
+ *                       `npm install -g @zhijiewang/openharness@latest`.
+ *   - "npx-cache"     → `dist/main.js` lives under a path containing
+ *                       `_npx/` (npx caches packages there). npx auto-fetches
+ *                       the latest by default; suggest re-running with
+ *                       `@latest` to bypass cache.
+ *   - "unknown"       → Couldn't classify. Print all three options and let
+ *                       the user choose.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
+/**
+ * Classify the install method given the running script's filesystem path.
+ * `mainPath` defaults to `import.meta.url`-derived path in the CLI; tests
+ * override it.
+ */
+export function detectInstallMethod(mainPath) {
+    // Normalize to forward slashes so the substring tests below work on Windows.
+    const normalized = mainPath.replace(/\\/g, "/");
+    // npx-cache: path contains `/_npx/` (Node's npx puts packages there)
+    if (normalized.includes("/_npx/")) {
+        return {
+            method: "npx-cache",
+            root: dirname(mainPath),
+            message: [
+                "You're running OH via npx (auto-fetched on each invocation).",
+                "To force the latest version on the next run, use:",
+                "",
+                "  npx @zhijiewang/openharness@latest",
+                "",
+                "Or install globally to avoid the npx cache entirely:",
+                "  npm install -g @zhijiewang/openharness@latest",
+            ].join("\n"),
+        };
+    }
+    // local-clone: walk up to find a package.json whose name matches AND a .git dir
+    let dir = dirname(mainPath);
+    while (dir && dir !== dirname(dir)) {
+        const pkgPath = join(dir, "package.json");
+        if (existsSync(pkgPath)) {
+            const isClone = existsSync(join(dir, ".git"));
+            if (isClone) {
+                return {
+                    method: "local-clone",
+                    root: dir,
+                    message: [
+                        `Detected a local clone at: ${dir}`,
+                        "Pull the latest and rebuild:",
+                        "",
+                        `  cd ${dir}`,
+                        "  git pull && npm install && npm run build",
+                    ].join("\n"),
+                };
+            }
+            // npm-global: the package.json belongs to OH and lives under a global
+            // node_modules directory.
+            if (normalized.includes("/node_modules/@zhijiewang/openharness/")) {
+                return {
+                    method: "npm-global",
+                    root: dir,
+                    message: [
+                        `Detected a global npm install at: ${dir}`,
+                        "Upgrade with:",
+                        "",
+                        "  npm install -g @zhijiewang/openharness@latest",
+                    ].join("\n"),
+                };
+            }
+            break;
+        }
+        dir = dirname(dir);
+    }
+    return {
+        method: "unknown",
+        root: dirname(mainPath),
+        message: [
+            "Could not determine how OH was installed. Pick the option that matches your setup:",
+            "",
+            "  Global npm install:  npm install -g @zhijiewang/openharness@latest",
+            "  npx (one-shot):      npx @zhijiewang/openharness@latest",
+            "  Local clone:         git pull && npm install && npm run build",
+        ].join("\n"),
+    };
+}
+/**
+ * Default `mainPath` resolver — walks up from `process.argv[1]` to find the
+ * package root. Exported so tests can stub it. Falls back to argv[1] verbatim
+ * when nothing matches.
+ */
+export function getDefaultMainPath() {
+    const entry = process.argv[1] ?? "";
+    if (!entry)
+        return "";
+    // If argv[1] points at a `dist/main.js`, that's already the right anchor.
+    // Otherwise return as-is and let `detectInstallMethod` figure it out.
+    return entry.split(sep).join("/");
+}
+//# sourceMappingURL=install-method.js.map

package/package.json

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