@zhijiewang/openharness 2.21.0 → 2.22.1

package/dist/main.js

@@ -207,6 +207,10 @@ program
     .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline. Useful for fast CI / SDK invocations.")
     .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
     .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
+    .option("--fallback-model <model>", "One-shot fallback model used when the primary fails with a retriable error (429/5xx/network/timeout). Format: provider/model or just model. REPLACES .oh/config.yaml fallbackProviders for this run. Mirrors Claude Code's --fallback-model.")
+    .option("--init", "Run the interactive `oh init` setup wizard before starting the command. Useful for first-run on a fresh project.")
+    .option("--init-only", "Run `oh init` and exit, without proceeding to the run/session.")
+    .option("--permission-prompt-tool <mcp_tool>", 'Delegate per-tool permission decisions to a configured MCP tool (e.g. "mcp__myperm__check"). The tool is invoked when a tool needs approval and no permission hook decided. Mirrors Claude Code\'s --permission-prompt-tool.')
     .action(async (promptArg, opts) => {
     configureDebug({
         categories: opts.debug,
@@ -214,6 +218,11 @@ program
     });
     const bare = opts.bare === true;
     debug("startup", "oh run", { bare, model: opts.model });
+    // --init / --init-only run the setup wizard before (or instead of) the
+    // actual run. --init-only exits after the wizard; --init falls through.
+    if (opts.init === true || opts.initOnly === true) {
+        await runInitWizard({ exitOnDone: opts.initOnly === true });
+    }
     // Read from stdin if prompt is "-" or omitted and stdin is not a TTY
     let prompt;
     if (!promptArg || promptArg === "-" || !process.stdin.isTTY) {
@@ -248,7 +257,7 @@ program
         overrides.apiKey = savedConfig.apiKey;
     if (savedConfig?.baseUrl)
         overrides.baseUrl = savedConfig.baseUrl;
-    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined);
+    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined, opts.fallbackModel ? { fallbackModel: opts.fallbackModel } : {});
     const { query } = await import("./query.js");
     // Tool list = built-ins + MCP server tools (project config + --mcp-config).
     // Previously oh run skipped MCP entirely, which silently broke the SDK
@@ -294,6 +303,7 @@ program
         maxTurns: parseInt(opts.maxTurns, 10),
         model,
         ...(opts.maxBudgetUsd !== undefined ? { maxCost: parseMaxBudgetUsdOrExit(opts.maxBudgetUsd) } : {}),
+        ...(opts.permissionPromptTool ? { permissionPromptTool: opts.permissionPromptTool } : {}),
     };
     const outputFormat = opts.json ? "json" : (opts.outputFormat ?? "text");
     let fullOutput = "";
@@ -469,6 +479,10 @@ program
     .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline.")
     .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
     .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
+    .option("--fallback-model <model>", "One-shot fallback model used when the primary fails with a retriable error. Format: provider/model or just model. REPLACES .oh/config.yaml fallbackProviders for this run.")
+    .option("--init", "Run the interactive setup wizard before starting the session.")
+    .option("--init-only", "Run `oh init` and exit, without proceeding to the session.")
+    .option("--permission-prompt-tool <mcp_tool>", 'Delegate per-tool permission decisions to a configured MCP tool (e.g. "mcp__myperm__check"). Invoked when a tool needs approval and no permission hook decided.')
     .action(async (opts) => {
     configureDebug({
         categories: opts.debug,
@@ -476,6 +490,9 @@ program
     });
     const bare = opts.bare === true;
     debug("startup", "oh session", { bare, model: opts.model });
+    if (opts.init === true || opts.initOnly === true) {
+        await runInitWizard({ exitOnDone: opts.initOnly === true });
+    }
     const settingSources = parseSettingSources(opts.settingSources);
     const savedConfig = readOhConfig(undefined, settingSources);
     const permissionMode = (opts.permissionMode ??
@@ -488,7 +505,7 @@ program
         overrides.apiKey = savedConfig.apiKey;
     if (savedConfig?.baseUrl)
         overrides.baseUrl = savedConfig.baseUrl;
-    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined);
+    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined, opts.fallbackModel ? { fallbackModel: opts.fallbackModel } : {});
     const { query } = await import("./query.js");
     const { createAssistantMessage, createToolResultMessage, createUserMessage } = await import("./types/message.js");
     // Tool list = built-ins + MCP server tools (project config + --mcp-config).
@@ -532,6 +549,7 @@ program
         maxTurns: parseInt(opts.maxTurns, 10),
         model,
         ...(opts.maxBudgetUsd !== undefined ? { maxCost: parseMaxBudgetUsdOrExit(opts.maxBudgetUsd) } : {}),
+        ...(opts.permissionPromptTool ? { permissionPromptTool: opts.permissionPromptTool } : {}),
     };
     // Conversation history, shared across all prompts for this process.
     // Seeded from a prior session when --resume <id> is passed; otherwise a
@@ -706,6 +724,9 @@ program
     .option("--bare", "Skip optional startup work (project detection, plugins, memory, skills, MCP). System prompt is just the tool-use baseline.")
     .option("--debug [categories]", "Enable categorized debug logs to stderr. Pass comma-separated categories (e.g. 'mcp,hooks') or no value for all. Also reads OH_DEBUG.")
     .option("--debug-file <path>", "When --debug is set, append debug lines to this file instead of stderr.")
+    .option("--fallback-model <model>", "One-shot fallback model used when the primary fails with a retriable error. Format: provider/model or just model. REPLACES .oh/config.yaml fallbackProviders for this run.")
+    .option("--init", "Run the interactive setup wizard before starting the chat session.")
+    .option("--init-only", "Run `oh init` and exit, without proceeding to the chat session.")
     .action(async (opts) => {
     configureDebug({
         categories: opts.debug,
@@ -713,6 +734,9 @@ program
     });
     const bare = opts.bare === true;
     debug("startup", "oh chat", { bare, model: opts.model, print: !!opts.print });
+    if (opts.init === true || opts.initOnly === true) {
+        await runInitWizard({ exitOnDone: opts.initOnly === true });
+    }
     // Load saved config as defaults (env vars + CLI flags override)
     const savedConfig = readOhConfig();
     const effectiveModel = opts.model ?? savedConfig?.model;
@@ -737,7 +761,7 @@ program
         if (fresh?.baseUrl)
             overrides.baseUrl = fresh.baseUrl;
         const targetModel = fresh?.model ?? effectiveModel;
-        return createProvider(targetModel, Object.keys(overrides).length ? overrides : undefined);
+        return createProvider(targetModel, Object.keys(overrides).length ? overrides : undefined, opts.fallbackModel ? { fallbackModel: opts.fallbackModel } : {});
     };
     try {
         const result = await tryCreateProvider();
@@ -1054,11 +1078,17 @@ program
     }
     console.log();
 });
-// ── init ──
-program
-    .command("init")
-    .description("Initialize OpenHarness for the current project (interactive setup wizard)")
-    .action(async () => {
+/**
+ * Run the interactive setup wizard. Used by both the `oh init` subcommand and
+ * the `--init` / `--init-only` flag added to chat / run / session (audit B5).
+ *
+ * `exitOnDone` controls the wizard's `onDone` behavior:
+ *   - true  → wizard exits the process when the user finishes (the standalone
+ *             `oh init` command path)
+ *   - false → wizard resolves and the caller continues (the `--init` flag path,
+ *             where the wizard is just a setup step before running the command)
+ */
+async function runInitWizard(opts) {
     const { default: InitWizard } = await import("./components/InitWizard.js");
     const rulesPath = createRulesFile();
     const ctx = detectProject();
@@ -1071,8 +1101,144 @@ program
     }
     console.log(`  Rules file: ${rulesPath}`);
     console.log();
-    const { waitUntilExit } = render(_jsx(InitWizard, { onDone: () => process.exit(0) }));
+    const { waitUntilExit } = render(_jsx(InitWizard, { onDone: () => (opts.exitOnDone ? process.exit(0) : undefined) }));
     await waitUntilExit();
+}
+// ── init ──
+program
+    .command("init")
+    .description("Initialize OpenHarness for the current project (interactive setup wizard)")
+    .action(async () => {
+    await runInitWizard({ exitOnDone: true });
+});
+// ── auth (audit B6) — provider-agnostic credential management ──
+//
+// `oh auth login [provider] --key <value>`  — set API key for a provider
+// `oh auth logout [provider]`              — clear API key for a provider
+// `oh auth status`                         — show which providers have keys
+//
+// `provider` defaults to the current `cfg.provider` so a bare `oh auth login`
+// works for the just-configured project. Mirrors Claude Code's `claude auth`.
+const authCmd = program.command("auth").description("Manage API keys for any provider (login / logout / status)");
+// Providers that run locally and don't use API keys — `oh auth login <local>`
+// is a no-op for these; redirect users to `oh init` which configures the
+// base URL and downloads / launches the model.
+const LOCAL_PROVIDERS = new Set(["ollama", "llamacpp", "llama.cpp", "lmstudio", "lm studio"]);
+authCmd
+    .command("login [provider]")
+    .description("Set the API key for a provider (defaults to the configured provider)")
+    .option("--key <value>", "API key value (omit to read from stdin)")
+    .action(async (providerArg, opts) => {
+    const { setCredential } = await import("./harness/credentials.js");
+    const cfg = readOhConfig();
+    const provider = providerArg ?? cfg?.provider;
+    if (!provider) {
+        process.stderr.write("Error: no provider specified and no default in .oh/config.yaml.\nRun `oh init` first to pick a provider — including local options (Ollama, llama.cpp, LM Studio) that don't need API keys.\n");
+        process.exit(2);
+    }
+    if (LOCAL_PROVIDERS.has(provider.toLowerCase())) {
+        console.log([
+            `${provider} runs locally and doesn't use an API key — nothing to log in.`,
+            "",
+            "To configure your local model and base URL, run:",
+            "  oh init",
+            "",
+            "Or skip the wizard and run directly:",
+            `  oh --model ${provider}/<model-name>`,
+        ].join("\n"));
+        return;
+    }
+    let key = opts.key;
+    if (!key) {
+        // TTY: prompt the user for a key (one line, hidden behavior is OS-dependent
+        // — we don't try to mask, callers wanting silent input should pipe).
+        // Non-TTY: read until EOF so `echo $KEY | oh auth login` works.
+        if (process.stdin.isTTY) {
+            const readline = await import("node:readline");
+            const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+            key = await new Promise((resolve) => {
+                rl.question(`Enter API key for ${provider}: `, (answer) => {
+                    rl.close();
+                    resolve(answer.trim());
+                });
+            });
+        }
+        else {
+            const chunks = [];
+            for await (const chunk of process.stdin)
+                chunks.push(chunk);
+            key = Buffer.concat(chunks).toString("utf8").trim();
+        }
+    }
+    if (!key) {
+        process.stderr.write("Error: no API key provided (pass --key <value> or pipe on stdin).\n");
+        process.exit(2);
+    }
+    setCredential(`${provider}-api-key`, key);
+    console.log(`Stored API key for ${provider} in ~/.oh/credentials.enc.`);
+});
+authCmd
+    .command("logout [provider]")
+    .description("Clear the stored API key for a provider")
+    .action(async (providerArg) => {
+    const { deleteCredential, getCredential } = await import("./harness/credentials.js");
+    const cfg = readOhConfig();
+    const provider = providerArg ?? cfg?.provider;
+    if (!provider) {
+        process.stderr.write("Error: no provider specified and no default in .oh/config.yaml.\n");
+        process.exit(2);
+    }
+    const key = `${provider}-api-key`;
+    if (!getCredential(key)) {
+        console.log(`No stored API key for ${provider}.`);
+        return;
+    }
+    deleteCredential(key);
+    console.log(`Cleared stored API key for ${provider}.`);
+});
+authCmd
+    .command("status")
+    .description("Show which providers have stored API keys")
+    .action(async () => {
+    const { listCredentials } = await import("./harness/credentials.js");
+    const keys = listCredentials();
+    const providerKeys = keys.filter((k) => k.endsWith("-api-key"));
+    if (providerKeys.length === 0) {
+        console.log("No stored API keys.");
+        console.log("");
+        console.log("To add one (cloud providers): oh auth login <provider>");
+        console.log("To use a local LLM (no key):  oh init   — picks Ollama / llama.cpp / LM Studio");
+        return;
+    }
+    console.log("Stored API keys:");
+    for (const k of providerKeys) {
+        const provider = k.replace(/-api-key$/, "");
+        console.log(`  ${provider}`);
+    }
+    // Also show env-var status — useful when debugging which path resolveApiKey takes.
+    const envProviders = ["anthropic", "openai", "openrouter"].filter((p) => process.env[`${p.toUpperCase()}_API_KEY`]);
+    if (envProviders.length > 0) {
+        console.log("");
+        console.log("Env-var keys (override stored):");
+        for (const p of envProviders)
+            console.log(`  ${p} (${p.toUpperCase()}_API_KEY)`);
+    }
+    console.log("");
+    console.log("Local LLMs (Ollama / llama.cpp / LM Studio) need no auth — configure via `oh init`.");
+});
+// ── update (audit B7) — provider-agnostic self-update guidance ──
+program
+    .command("update")
+    .description("Show the right upgrade command for how this CLI was installed")
+    .action(async () => {
+    const { detectInstallMethod, getDefaultMainPath } = await import("./utils/install-method.js");
+    const result = detectInstallMethod(getDefaultMainPath());
+    console.log();
+    console.log(`  Current version: ${VERSION}`);
+    console.log(`  Install method: ${result.method}`);
+    console.log();
+    console.log(result.message);
+    console.log();
 });
 // ── sessions ──
 program
@@ -1203,60 +1369,7 @@ program
         process.exit(0);
     });
 });
-// ── auth ──
-program
-    .command("auth")
-    .description("Manage API key credentials")
-    .argument("<action>", "login | logout | status")
-    .argument("[provider]", "Provider name (anthropic, openai, openrouter)")
-    .action(async (action, providerName) => {
-    const { setCredential, deleteCredential, listCredentials, getCredential } = await import("./harness/credentials.js");
-    if (action === "status") {
-        const keys = listCredentials();
-        if (keys.length === 0) {
-            console.log("  No stored credentials. API keys come from environment variables or config.yaml.");
-            return;
-        }
-        console.log("\n  Stored credentials:");
-        for (const k of keys) {
-            const val = getCredential(k);
-            console.log(`  ${k}: ${val ? `****${val.slice(-4)}` : "(empty)"}`);
-        }
-        console.log();
-        return;
-    }
-    if (action === "login") {
-        if (!providerName) {
-            console.error("  Usage: oh auth login <provider>");
-            process.exit(1);
-        }
-        // Read key from stdin
-        process.stdout.write(`  Enter API key for ${providerName}: `);
-        const chunks = [];
-        for await (const chunk of process.stdin) {
-            chunks.push(chunk);
-            break;
-        }
-        const key = Buffer.concat(chunks).toString("utf-8").trim();
-        if (!key) {
-            console.error("  No key provided.");
-            process.exit(1);
-        }
-        setCredential(`${providerName}-api-key`, key);
-        console.log(`  ✓ API key saved securely for ${providerName}`);
-        return;
-    }
-    if (action === "logout") {
-        if (!providerName) {
-            console.error("  Usage: oh auth logout <provider>");
-            process.exit(1);
-        }
-        deleteCredential(`${providerName}-api-key`);
-        console.log(`  ✓ API key removed for ${providerName}`);
-        return;
-    }
-    console.error(`  Unknown action: ${action}. Use: login, logout, status`);
-});
+// (oh auth subcommand is registered above near the init command)
 // ── serve (MCP server) ──
 program
     .command("serve")

package/dist/mcp/elicitation.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ */
+export type ElicitationAction = "accept" | "decline" | "cancel";
+export interface ElicitationRequest {
+    /** Server name — for hook context. Not part of the MCP wire format. */
+    serverName: string;
+    /** Human-readable message the server wants to show the user. */
+    message: string;
+    /** JSON Schema describing the structured content the server expects on accept. */
+    requestedSchema: unknown;
+}
+export interface ElicitationResponse {
+    action: ElicitationAction;
+    content?: Record<string, unknown>;
+}
+/**
+ * Optional interactive handler — called when no hook decided. The REPL is
+ * the natural caller; until that lands, leaving this unset means OH falls
+ * straight from the hook to the auto-decline default.
+ */
+export type InteractiveElicitationHandler = (req: ElicitationRequest) => Promise<ElicitationResponse>;
+/**
+ * Register / replace the interactive elicitation handler. Pass `undefined`
+ * to clear (for tests / REPL teardown). Idempotent.
+ */
+export declare function setElicitationHandler(handler: InteractiveElicitationHandler | undefined): void;
+/**
+ * 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 declare function resolveElicitation(req: ElicitationRequest): Promise<ElicitationResponse>;
+/** @internal Test-only reset. */
+export declare function _resetElicitationForTest(): void;
+//# sourceMappingURL=elicitation.d.ts.map

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([