@zhijiewang/openharness 2.9.0 → 2.11.0

package/README.md

@@ -366,6 +366,19 @@ mcpServers:
 
 MCP tools appear alongside built-in tools. `/status` shows connected servers.
 
+### Remote MCP servers (HTTP / SSE)
+
+```yaml
+mcpServers:
+  - name: linear
+    type: http
+    url: https://mcp.linear.app/mcp
+    headers:
+      Authorization: "Bearer ${LINEAR_API_KEY}"
+```
+
+See [docs/mcp-servers.md](docs/mcp-servers.md) for the full reference.
+
 **MCP Server Registry** — browse and install from a curated catalog:
 
 ```

package/dist/harness/config.d.ts

@@ -2,20 +2,47 @@
  * .oh/config.yaml — provider, model, permissionMode and other persisted settings.
  */
 import type { PermissionMode } from "../types/permissions.js";
-export type McpServerConfig = {
+export type McpCommonConfig = {
     name: string;
+    riskLevel?: "low" | "medium" | "high";
+    timeout?: number;
+};
+export type McpStdioConfig = McpCommonConfig & {
+    type?: "stdio";
     command: string;
     args?: string[];
     env?: Record<string, string>;
-    riskLevel?: "low" | "medium" | "high";
-    timeout?: number;
 };
+export type McpHttpConfig = McpCommonConfig & {
+    type: "http";
+    url: string;
+    headers?: Record<string, string>;
+};
+export type McpSseConfig = McpCommonConfig & {
+    type: "sse";
+    url: string;
+    headers?: Record<string, string>;
+};
+export type McpServerConfig = McpStdioConfig | McpHttpConfig | McpSseConfig;
 export type HookDef = {
     command?: string;
     http?: string;
     prompt?: string;
     match?: string;
     timeout?: number;
+    /**
+     * When true (and this hook has a `command`), OH sends a JSON envelope
+     * `{event, ...context}` on stdin and parses a JSON response from stdout.
+     * Response shape (Claude Code compatible):
+     *   { "decision": "allow" | "deny",
+     *     "reason"?: string,
+     *     "hookSpecificOutput"?: {...} }
+     *
+     * When false (default), OH passes context via `OH_EVENT` / `OH_TOOL_NAME`
+     * env vars and gates on the command's exit code (0 = allow). The env-var
+     * mode remains the default for backward compatibility.
+     */
+    jsonIO?: boolean;
 };
 export type HooksConfig = {
     sessionStart?: HookDef[];

package/dist/harness/hooks.js

@@ -141,6 +141,86 @@ function runCommandHookAsync(command, env, timeoutMs = 10_000) {
         });
     });
 }
+/**
+ * Run a JSON-mode command hook (Claude Code convention).
+ *
+ * Sends `{event, ...context}` as JSON on stdin. Parses stdout as JSON
+ * `{ decision: "allow" | "deny", reason?: string, hookSpecificOutput?: any }`.
+ *
+ * Gating logic:
+ *   - `decision: "deny"` → blocks (returns false).
+ *   - `decision: "allow"` or omitted decision → allow (returns true).
+ *   - Non-zero exit code → block.
+ *   - Invalid/empty JSON on stdout → fall back to exit code (0 = allow).
+ *   - Timeout or spawn error → block.
+ */
+function runJsonIoHookAsync(command, env, event, ctx, timeoutMs = 10_000) {
+    return new Promise((resolve) => {
+        const proc = spawn(command, {
+            shell: true,
+            timeout: timeoutMs,
+            stdio: ["pipe", "pipe", "pipe"],
+            env,
+        });
+        let settled = false;
+        let stdoutBuf = "";
+        const timer = setTimeout(() => {
+            if (!settled) {
+                settled = true;
+                proc.kill();
+                resolve(false);
+            }
+        }, timeoutMs);
+        proc.stdout?.on("data", (chunk) => {
+            stdoutBuf += chunk.toString();
+        });
+        // Write the event + context JSON envelope to stdin then close it so the
+        // hook knows there's no more input coming.
+        try {
+            const payload = JSON.stringify({ event, ...ctx });
+            proc.stdin?.end(payload);
+        }
+        catch {
+            /* stdin already closed — ignore */
+        }
+        proc.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            // Non-zero exit is always a block, regardless of stdout.
+            if ((code ?? 1) !== 0) {
+                resolve(false);
+                return;
+            }
+            // Empty stdout → treat exit code as the signal (allow for exit 0).
+            if (!stdoutBuf.trim()) {
+                resolve(true);
+                return;
+            }
+            try {
+                const parsed = JSON.parse(stdoutBuf);
+                if (parsed.decision === "deny") {
+                    resolve(false);
+                }
+                else {
+                    resolve(true); // "allow" or omitted → allow
+                }
+            }
+            catch {
+                // Malformed JSON with a zero exit — fail closed conservatively.
+                resolve(false);
+            }
+        });
+        proc.on("error", () => {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer);
+                resolve(false);
+            }
+        });
+    });
+}
 /** Run an HTTP hook. POSTs context as JSON, expects { allowed: true/false }. */
 async function runHttpHook(url, event, ctx, timeoutMs = 10_000) {
     try {
@@ -161,15 +241,63 @@ async function runHttpHook(url, event, ctx, timeoutMs = 10_000) {
     }
 }
 /**
- * Run a prompt hook. Uses LLM to make a yes/no decision.
+ * Run a prompt hook. Uses an LLM to make a yes/no allow/deny decision.
+ *
+ * The hook's `prompt:` field is the question posed to the model along with
+ * the event context. The response is parsed case-insensitively: responses
+ * starting with YES / ALLOW / TRUE / PASS / APPROVE allow; anything else
+ * (including explicit NO, DENY, errors, timeouts, empty) blocks.
  *
- * Currently a stub — prompt hooks always allow because the hook system
- * runs outside the query loop and has no access to a Provider instance.
- * Full implementation requires passing a Provider via HookContext so the
- * hook can call provider.complete() with the prompt text.
+ * Fail-closed semantics: if the provider isn't reachable or the response
+ * can't be parsed, the hook denies. This matches command hooks (non-zero
+ * exit = deny) and HTTP hooks (network error = deny).
+ *
+ * Provider selection: reads `.oh/config.yaml` to get the configured provider
+ * and model. A separate provider instance is created per call — no caching,
+ * since hooks are rare and cold-start cost is negligible compared to the
+ * LLM call itself.
  */
-async function runPromptHook(_promptText, _ctx) {
-    return true;
+async function runPromptHook(promptText, ctx, timeoutMs = 10_000) {
+    try {
+        const cfg = readOhConfig();
+        if (!cfg)
+            return false; // no config → no provider → fail closed
+        const { createProvider } = (await import("../providers/index.js"));
+        const modelArg = cfg.model ? `${cfg.provider}/${cfg.model}` : cfg.provider;
+        const overrides = {};
+        if (cfg.apiKey)
+            overrides.apiKey = cfg.apiKey;
+        if (cfg.baseUrl)
+            overrides.baseUrl = cfg.baseUrl;
+        const { provider, model } = await createProvider(modelArg, overrides);
+        const systemPrompt = "You are a policy gate. Read the question and the event context. Answer with a single word: YES to allow, NO to deny. Do not explain unless asked.";
+        const userContent = [
+            `Question: ${promptText}`,
+            "",
+            "Event context:",
+            JSON.stringify({ event: ctx }, null, 2),
+            "",
+            "Answer (YES or NO):",
+        ].join("\n");
+        const { createUserMessage } = (await import("../types/message.js"));
+        const messages = [createUserMessage(userContent)];
+        // Race the completion against a hard timeout so a hung provider doesn't
+        // block the agent loop indefinitely.
+        const completion = await Promise.race([
+            provider.complete(messages, systemPrompt, undefined, model),
+            new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs)),
+        ]);
+        if (!completion)
+            return false; // timeout → deny
+        const text = (completion.content ?? "").trim().toUpperCase();
+        if (!text)
+            return false;
+        // Accept multiple allow synonyms; default to deny on anything else.
+        return /^(YES|ALLOW|TRUE|PASS|APPROVE)\b/.test(text);
+    }
+    catch {
+        return false; // any error path → deny
+    }
 }
 // ── Hook Execution ──
 /** Execute a single hook definition. Returns true if allowed. */
@@ -177,6 +305,12 @@ async function executeHookDef(def, event, ctx) {
     const timeout = def.timeout ?? 10_000;
     if (def.command) {
         const env = buildEnv(event, ctx);
+        // JSON-mode (Claude Code convention): send `{event, ...ctx}` on stdin,
+        // parse `{decision}` from stdout. Env-var mode (legacy default): gate on
+        // exit code.
+        if (def.jsonIO) {
+            return runJsonIoHookAsync(def.command, env, event, ctx, timeout);
+        }
         const code = await runCommandHookAsync(def.command, env, timeout);
         return code === 0;
     }
@@ -206,14 +340,31 @@ export function emitHook(event, ctx = {}) {
             if (!matchesHook(def, ctx))
                 continue;
             if (def.command) {
+                const input = def.jsonIO ? JSON.stringify({ event, ...ctx }) : undefined;
                 const result = spawnSync(def.command, {
                     shell: true,
                     timeout: def.timeout ?? 10_000,
                     stdio: "pipe",
                     env,
+                    input,
                 });
                 if (result.status !== 0 || result.error)
                     return false;
+                // JSON mode: parse stdout for {decision: "deny"} → block. Allow on empty
+                // stdout (exit-code already gated above). Malformed JSON fails closed.
+                if (def.jsonIO) {
+                    const out = result.stdout?.toString() ?? "";
+                    if (out.trim()) {
+                        try {
+                            const parsed = JSON.parse(out);
+                            if (parsed.decision === "deny")
+                                return false;
+                        }
+                        catch {
+                            return false;
+                        }
+                    }
+                }
             }
             // HTTP and prompt hooks for preToolUse are handled in emitHookAsync
         }

package/dist/mcp/client.d.ts

@@ -1,18 +1,25 @@
+import type { Client as SdkClient } from "@modelcontextprotocol/sdk/client/index.js";
 import type { McpServerConfig } from "../harness/config.js";
 import type { McpToolDef } from "./types.js";
+type ForTestingOptions = {
+    name: string;
+    cfg: McpServerConfig;
+    sdk: SdkClient;
+    timeoutMs: number;
+    reconnect?: () => Promise<SdkClient>;
+};
 export declare class McpClient {
     readonly name: string;
-    private proc;
-    private nextId;
-    private pending;
-    private ready;
-    private dead;
+    instructions: string | null;
+    private sdk;
     private cfg;
     private timeoutMs;
+    private reconnectImpl;
     private constructor();
-    /** Server-provided instructions (from capabilities during init) */
-    instructions: string | null;
     static connect(cfg: McpServerConfig, timeoutMs?: number): Promise<McpClient>;
+    /** Test-only constructor. Not exported from the package's public API. */
+    static _forTesting(opts: ForTestingOptions): McpClient;
+    private defaultReconnect;
     listTools(): Promise<McpToolDef[]>;
     listResources(): Promise<Array<{
         uri: string;
@@ -21,8 +28,7 @@ export declare class McpClient {
     }>>;
     readResource(uri: string): Promise<string>;
     callTool(name: string, args: Record<string, unknown>): Promise<string>;
-    private callWithTimeout;
-    private call;
     disconnect(): void;
 }
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/mcp/client.js

@@ -1,150 +1,97 @@
-import { spawn } from "node:child_process";
-import { createInterface } from "node:readline";
-import { safeEnv } from "../utils/safe-env.js";
+import { normalizeMcpConfig } from "./config-normalize.js";
+import { buildClient, connectWithFallback } from "./transport.js";
+const DEFAULT_TIMEOUT_MS = 5_000;
 export class McpClient {
     name;
-    proc;
-    nextId = 1;
-    pending = new Map();
-    // biome-ignore lint/correctness/noUnusedPrivateClassMembers: set via Object.assign in static factory
-    ready = false;
-    dead = false;
+    instructions = null;
+    sdk;
     cfg;
     timeoutMs;
-    constructor(name, proc, cfg, timeoutMs) {
+    reconnectImpl;
+    constructor(name, cfg, sdk, timeoutMs, reconnect) {
         this.name = name;
-        this.proc = proc;
         this.cfg = cfg;
+        this.sdk = sdk;
         this.timeoutMs = timeoutMs;
-        const rl = createInterface({ input: proc.stdout });
-        rl.on("line", (line) => {
-            try {
-                const msg = JSON.parse(line);
-                const p = this.pending.get(msg.id);
-                if (p) {
-                    this.pending.delete(msg.id);
-                    p.resolve(msg);
-                }
-            }
-            catch {
-                // non-JSON line from server (e.g. startup noise) — ignore
-            }
-        });
-        proc.on("exit", () => {
-            this.dead = true;
-            for (const p of this.pending.values()) {
-                p.reject(new Error(`MCP server '${name}' exited`));
-            }
-            this.pending.clear();
-        });
+        this.reconnectImpl = reconnect ?? (() => this.defaultReconnect());
+        const instr = sdk.getInstructions?.();
+        if (instr && typeof instr === "string") {
+            this.instructions = instr;
+        }
     }
-    /** Server-provided instructions (from capabilities during init) */
-    instructions = null;
-    static async connect(cfg, timeoutMs = cfg.timeout ?? 5_000) {
-        const proc = spawn(cfg.command, cfg.args ?? [], {
-            stdio: ["pipe", "pipe", "pipe"],
-            env: safeEnv(cfg.env),
-        });
-        const client = new McpClient(cfg.name, proc, cfg, timeoutMs);
-        // Initialize handshake
-        const initResponse = await Promise.race([
-            client.call("initialize", {
-                protocolVersion: "2024-11-05",
-                clientInfo: { name: "openharness", version: "0.2.1" },
-                capabilities: {},
-            }),
-            new Promise((_, reject) => setTimeout(() => reject(new Error(`MCP '${cfg.name}' init timeout`)), timeoutMs)),
-        ]);
-        // Extract server instructions from init response
-        const serverInfo = initResponse?.result;
-        if (serverInfo?.instructions && typeof serverInfo.instructions === "string") {
-            client.instructions = serverInfo.instructions;
+    static async connect(cfg, timeoutMs = cfg.timeout ?? DEFAULT_TIMEOUT_MS) {
+        const normalized = normalizeMcpConfig(cfg, process.env);
+        if (normalized.kind === "error") {
+            throw new Error(normalized.message);
         }
-        await client.call("notifications/initialized", {});
-        client.ready = true;
-        return client;
+        const sdk = await connectWithFallback(normalized.cfg, (c) => buildClient(c));
+        return new McpClient(cfg.name, cfg, sdk, timeoutMs);
+    }
+    /** Test-only constructor. Not exported from the package's public API. */
+    static _forTesting(opts) {
+        return new McpClient(opts.name, opts.cfg, opts.sdk, opts.timeoutMs, opts.reconnect);
+    }
+    async defaultReconnect() {
+        const normalized = normalizeMcpConfig(this.cfg, process.env);
+        if (normalized.kind === "error")
+            throw new Error(normalized.message);
+        return connectWithFallback(normalized.cfg, (c) => buildClient(c));
     }
     async listTools() {
-        const res = await this.call("tools/list", {});
-        return (res.result?.tools ?? []);
+        const res = await this.sdk.listTools();
+        return (res?.tools ?? []);
     }
     async listResources() {
         try {
-            const res = await this.callWithTimeout("resources/list", {});
-            return (res.result?.resources ?? []);
+            const res = await this.sdk.listResources();
+            return (res?.resources ?? []);
         }
         catch {
             return []; // Server may not support resources
         }
     }
     async readResource(uri) {
-        const res = await this.callWithTimeout("resources/read", { uri });
-        if (res.error)
-            throw new Error(res.error.message);
-        const contents = res.result?.contents ?? [];
+        const res = await this.sdk.readResource({ uri });
+        const contents = res?.contents ?? [];
         return contents
-            .filter((c) => c.text)
+            .filter((c) => typeof c.text === "string")
             .map((c) => c.text)
             .join("\n");
     }
     async callTool(name, args) {
-        if (this.dead) {
-            try {
-                const fresh = await McpClient.connect(this.cfg, this.timeoutMs);
-                Object.assign(this, { proc: fresh.proc, dead: false, ready: true, nextId: 1, pending: new Map() });
-            }
-            catch {
-                throw new Error(`MCP server '${this.name}' died and restart failed`);
-            }
-        }
-        // Retry up to 2 times for transient failures
-        let lastError = null;
+        // Retry up to 2 times on transport-closed / timeout errors
+        let lastErr = null;
         for (let attempt = 0; attempt < 3; attempt++) {
             try {
-                const res = await this.callWithTimeout("tools/call", { name, arguments: args });
-                if (res.error)
-                    throw new Error(res.error.message);
-                const content = res.result?.content ?? [];
-                return content
-                    .filter((c) => c.type === "text")
+                const res = await this.sdk.callTool({ name, arguments: args });
+                const content = (res?.content ?? []);
+                const text = content
+                    .filter((c) => c.type === "text" && typeof c.text === "string")
                     .map((c) => c.text)
                     .join("\n");
+                if (res?.isError) {
+                    throw new Error(text || `MCP tool '${name}' returned an error`);
+                }
+                return text;
             }
             catch (err) {
-                lastError = err instanceof Error ? err : new Error(String(err));
-                // Only retry on timeout or server death — not on application errors
-                if (!lastError.message.includes("timeout") && !lastError.message.includes("exited")) {
-                    throw lastError;
+                lastErr = err instanceof Error ? err : new Error(String(err));
+                const msg = lastErr.message;
+                const retryable = /transport closed|timeout|ECONNRESET|stream closed|socket hang up/i.test(msg);
+                if (!retryable || attempt === 2)
+                    throw lastErr;
+                try {
+                    this.sdk = await this.reconnectImpl();
                 }
-                if (this.dead && attempt < 2) {
-                    try {
-                        const fresh = await McpClient.connect(this.cfg, this.timeoutMs);
-                        Object.assign(this, { proc: fresh.proc, dead: false, ready: true, nextId: 1, pending: new Map() });
-                    }
-                    catch {
-                        throw new Error(`MCP server '${this.name}' died and restart failed`);
-                    }
+                catch (reErr) {
+                    throw new Error(`MCP '${this.name}' died and reconnect failed: ${reErr instanceof Error ? reErr.message : String(reErr)}`);
                 }
             }
         }
-        throw lastError ?? new Error(`MCP '${this.name}' call failed after retries`);
-    }
-    callWithTimeout(method, params) {
-        return Promise.race([
-            this.call(method, params),
-            new Promise((_, reject) => setTimeout(() => reject(new Error(`MCP '${this.name}' call timeout (${this.timeoutMs}ms)`)), this.timeoutMs)),
-        ]);
-    }
-    call(method, params) {
-        return new Promise((resolve, reject) => {
-            const id = this.nextId++;
-            const req = { jsonrpc: "2.0", id, method, params };
-            this.pending.set(id, { resolve, reject });
-            this.proc.stdin.write(`${JSON.stringify(req)}\n`);
-        });
+        throw lastErr ?? new Error(`MCP '${this.name}' callTool failed after retries`);
     }
     disconnect() {
-        this.proc.kill();
+        void this.sdk.close?.();
     }
 }
 //# sourceMappingURL=client.js.map

package/dist/mcp/config-normalize.d.ts

@@ -0,0 +1,24 @@
+import type { McpHttpConfig, McpServerConfig, McpSseConfig, McpStdioConfig } from "../harness/config.js";
+/** Discriminated-union result: either a validated config or a human-readable error. */
+export type NormalizeResult = {
+    kind: "ok";
+    cfg: NormalizedConfig;
+} | {
+    kind: "error";
+    message: string;
+};
+export type NormalizedConfig = (McpStdioConfig & {
+    type: "stdio";
+}) | (McpHttpConfig & {
+    inferredFromUrl?: boolean;
+}) | (McpSseConfig & {
+    inferredFromUrl?: boolean;
+});
+/**
+ * Validate + normalize a raw MCP server config entry.
+ * - Infers missing `type` from `command`/`url`.
+ * - Interpolates ${ENV} in headers (http/sse only).
+ * - Returns {kind:"error"} with a reason for any invalid combination.
+ */
+export declare function normalizeMcpConfig(raw: McpServerConfig, env: Record<string, string | undefined>): NormalizeResult;
+//# sourceMappingURL=config-normalize.d.ts.map

package/dist/mcp/config-normalize.js

@@ -0,0 +1,72 @@
+const ENV_REF = /\$\{([A-Z_][A-Z0-9_]*)\}/g;
+/** Replace ${VAR} references in `value` from `env`. Returns the new string or a missing-var name. */
+function interpolate(value, env) {
+    let missing = null;
+    const out = value.replace(ENV_REF, (_match, varName) => {
+        const v = env[varName];
+        if (v === undefined) {
+            if (missing === null)
+                missing = varName;
+            return "";
+        }
+        return v;
+    });
+    if (missing !== null)
+        return { ok: false, missing };
+    return { ok: true, value: out };
+}
+function interpolateHeaders(headers, env) {
+    if (!headers)
+        return { ok: true, headers: undefined };
+    const out = {};
+    for (const [k, v] of Object.entries(headers)) {
+        const r = interpolate(v, env);
+        if (!r.ok)
+            return { ok: false, missing: r.missing };
+        out[k] = r.value;
+    }
+    return { ok: true, headers: out };
+}
+/**
+ * Validate + normalize a raw MCP server config entry.
+ * - Infers missing `type` from `command`/`url`.
+ * - Interpolates ${ENV} in headers (http/sse only).
+ * - Returns {kind:"error"} with a reason for any invalid combination.
+ */
+export function normalizeMcpConfig(raw, env) {
+    const hasCommand = "command" in raw && !!raw.command;
+    const hasUrl = "url" in raw && !!raw.url;
+    if (hasCommand && hasUrl) {
+        return { kind: "error", message: `MCP '${raw.name}': config sets both 'command' and 'url'` };
+    }
+    const declaredType = raw.type;
+    const effectiveType = declaredType ?? (hasCommand ? "stdio" : hasUrl ? "http" : undefined);
+    if (!effectiveType) {
+        return { kind: "error", message: `MCP '${raw.name}': must set 'command' (stdio) or 'url' (http/sse)` };
+    }
+    if (effectiveType === "stdio") {
+        if (!hasCommand) {
+            return { kind: "error", message: `MCP '${raw.name}': type='stdio' requires 'command'` };
+        }
+        return { kind: "ok", cfg: { ...raw, type: "stdio" } };
+    }
+    // http or sse
+    if (!hasUrl) {
+        return { kind: "error", message: `MCP '${raw.name}': type='${effectiveType}' requires 'url'` };
+    }
+    const headers = raw.headers;
+    const interp = interpolateHeaders(headers, env);
+    if (!interp.ok) {
+        return {
+            kind: "error",
+            message: `MCP '${raw.name}': env var '${interp.missing}' referenced in headers is not set`,
+        };
+    }
+    const inferred = declaredType === undefined;
+    const base = { ...raw, type: effectiveType, headers: interp.headers };
+    return {
+        kind: "ok",
+        cfg: inferred ? { ...base, inferredFromUrl: true } : base,
+    };
+}
+//# sourceMappingURL=config-normalize.js.map

package/dist/mcp/loader.js

@@ -3,10 +3,34 @@ import { McpClient } from "./client.js";
 import { DeferredMcpTool } from "./DeferredMcpTool.js";
 import { McpTool } from "./McpTool.js";
 const connectedClients = [];
+let exitHandlerInstalled = false;
+function installExitHandler() {
+    if (exitHandlerInstalled)
+        return;
+    exitHandlerInstalled = true;
+    const handler = () => {
+        try {
+            disconnectMcpClients();
+        }
+        catch {
+            /* shutdown best-effort */
+        }
+    };
+    process.once("exit", handler);
+    process.once("SIGINT", () => {
+        handler();
+        process.exit(130);
+    });
+    process.once("SIGTERM", () => {
+        handler();
+        process.exit(143);
+    });
+}
 /** 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() {
+    installExitHandler();
     const cfg = readOhConfig();
     const servers = cfg?.mcpServers ?? [];
     if (servers.length === 0)

package/dist/mcp/transport.d.ts

@@ -0,0 +1,38 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { NormalizedConfig } from "./config-normalize.js";
+export declare class RemoteAuthRequiredError extends Error {
+    readonly serverName: string;
+    readonly wwwAuthenticate: string | undefined;
+    constructor(serverName: string, wwwAuthenticate: string | undefined);
+}
+export declare class UnreachableError extends Error {
+    readonly serverName: string;
+    readonly cause: unknown;
+    constructor(serverName: string, cause: unknown);
+}
+export declare class ProtocolError extends Error {
+    readonly serverName: string;
+    readonly cause: unknown;
+    constructor(serverName: string, cause: unknown);
+}
+/**
+ * Construct an SDK Transport for a normalized config.
+ * Does NOT call .start() — caller (Client.connect) handles that.
+ */
+export declare function buildTransport(cfg: NormalizedConfig): Promise<Transport>;
+/**
+ * Connect to an MCP server, with auto-fallback from Streamable HTTP to
+ * legacy SSE when the config's type was INFERRED from url (not explicit).
+ *
+ * `doConnect` is the side-effecting step — build/connect a transport and
+ * return the opaque client. Kept injectable for tests; production call-site
+ * wires it to `buildClient` (Task 7).
+ */
+export declare function connectWithFallback<T>(cfg: NormalizedConfig, doConnect: (cfg: NormalizedConfig) => Promise<T>): Promise<T>;
+/**
+ * Build a connected SDK Client for a normalized config.
+ * Maps connect-time errors into OH's typed error taxonomy.
+ */
+export declare function buildClient(cfg: NormalizedConfig): Promise<Client>;
+//# sourceMappingURL=transport.d.ts.map

package/dist/mcp/transport.js

@@ -0,0 +1,159 @@
+import { createRequire } from "node:module";
+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";
+const pkg = createRequire(import.meta.url)("../../package.json");
+export class RemoteAuthRequiredError extends Error {
+    serverName;
+    wwwAuthenticate;
+    constructor(serverName, wwwAuthenticate) {
+        super(`MCP server '${serverName}' requires authentication. ` +
+            `Add headers.Authorization to your config (OAuth flow is not yet supported).`);
+        this.name = "RemoteAuthRequiredError";
+        this.serverName = serverName;
+        this.wwwAuthenticate = wwwAuthenticate;
+    }
+}
+export class UnreachableError extends Error {
+    serverName;
+    cause;
+    constructor(serverName, cause) {
+        const causeMsg = cause instanceof Error ? cause.message : String(cause);
+        super(`MCP server '${serverName}' unreachable: ${causeMsg}`);
+        this.name = "UnreachableError";
+        this.serverName = serverName;
+        this.cause = cause;
+    }
+}
+export class ProtocolError extends Error {
+    serverName;
+    cause;
+    constructor(serverName, cause) {
+        const causeMsg = cause instanceof Error ? cause.message : String(cause);
+        super(`MCP server '${serverName}' protocol error: ${causeMsg}`);
+        this.name = "ProtocolError";
+        this.serverName = serverName;
+        this.cause = cause;
+    }
+}
+/**
+ * Construct an SDK Transport for a normalized config.
+ * Does NOT call .start() — caller (Client.connect) handles that.
+ */
+export async function buildTransport(cfg) {
+    if (cfg.type === "stdio") {
+        return new StdioClientTransport({
+            command: cfg.command,
+            args: cfg.args,
+            env: cfg.env,
+        });
+    }
+    if (cfg.type === "http") {
+        return new StreamableHTTPClientTransport(new URL(cfg.url), {
+            requestInit: cfg.headers ? { headers: cfg.headers } : undefined,
+        });
+    }
+    if (cfg.type === "sse") {
+        return new SSEClientTransport(new URL(cfg.url), {
+            requestInit: cfg.headers ? { headers: cfg.headers } : undefined,
+        });
+    }
+    throw new Error(`unknown transport type: ${cfg.type}`);
+}
+/**
+ * Does this error indicate "try the legacy SSE transport instead"?
+ * Yes for 4xx OTHER than 401-with-WWW-Authenticate (which is a real auth challenge).
+ */
+function isFallbackCandidate(err) {
+    const code = err?.code;
+    if (typeof code !== "number")
+        return false;
+    if (code < 400 || code >= 500)
+        return false;
+    if (code === 401) {
+        const www = err?.headers?.["www-authenticate"];
+        if (typeof www === "string" && www.length > 0)
+            return false;
+    }
+    return true;
+}
+function extractWwwAuthenticate(err) {
+    const code = err?.code;
+    if (code !== 401)
+        return undefined;
+    const www = err?.headers?.["www-authenticate"];
+    return typeof www === "string" ? www : undefined;
+}
+/**
+ * Connect to an MCP server, with auto-fallback from Streamable HTTP to
+ * legacy SSE when the config's type was INFERRED from url (not explicit).
+ *
+ * `doConnect` is the side-effecting step — build/connect a transport and
+ * return the opaque client. Kept injectable for tests; production call-site
+ * wires it to `buildClient` (Task 7).
+ */
+export async function connectWithFallback(cfg, doConnect) {
+    try {
+        return await doConnect(cfg);
+    }
+    catch (err) {
+        // Auth challenge → surface immediately, never fall back
+        const www = extractWwwAuthenticate(err);
+        if (www !== undefined)
+            throw new RemoteAuthRequiredError(cfg.name, www);
+        // Explicit type → surface as-is
+        const inferred = cfg.inferredFromUrl === true;
+        if (!inferred)
+            throw err;
+        // Only http-was-inferred-first falls back to sse; other shapes surface
+        if (cfg.type !== "http")
+            throw err;
+        if (!isFallbackCandidate(err))
+            throw err;
+        // Log + retry
+        // biome-ignore lint/suspicious/noConsole: user-facing diagnostic
+        console.warn(`[mcp] ${cfg.name}: Streamable HTTP failed (${err.message}); trying legacy SSE`);
+        const sseCfg = { ...cfg, type: "sse" };
+        return await doConnect(sseCfg);
+    }
+}
+const DEFAULT_TIMEOUT_MS = 5_000;
+const CLIENT_INFO = { name: "openharness", version: pkg.version };
+/**
+ * Build a connected SDK Client for a normalized config.
+ * Maps connect-time errors into OH's typed error taxonomy.
+ */
+export async function buildClient(cfg) {
+    const transport = await buildTransport(cfg);
+    const client = new Client(CLIENT_INFO, { capabilities: {} });
+    const timeoutMs = cfg.timeout ?? DEFAULT_TIMEOUT_MS;
+    let timer = null;
+    try {
+        await Promise.race([
+            client.connect(transport),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`init timeout after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+        return client;
+    }
+    catch (err) {
+        // Leave RemoteAuthRequiredError / UnreachableError / ProtocolError as-is
+        if (err instanceof RemoteAuthRequiredError || err instanceof UnreachableError || err instanceof ProtocolError) {
+            throw err;
+        }
+        // Network-shaped errors (DNS, TCP, TLS, timeout) → Unreachable
+        const msg = err?.message ?? String(err);
+        if (/timeout|ECONNREFUSED|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|network|fetch failed/i.test(msg)) {
+            throw new UnreachableError(cfg.name, err);
+        }
+        // Otherwise protocol-shaped
+        throw new ProtocolError(cfg.name, err);
+    }
+    finally {
+        if (timer !== null)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/mcp/types.d.ts

@@ -1,19 +1,4 @@
-/** Minimal MCP protocol types (JSON-RPC 2.0 over stdio) */
-export interface JsonRpcRequest {
-    jsonrpc: "2.0";
-    id: number;
-    method: string;
-    params?: unknown;
-}
-export interface JsonRpcResponse {
-    jsonrpc: "2.0";
-    id: number;
-    result?: unknown;
-    error?: {
-        code: number;
-        message: string;
-    };
-}
+/** MCP tool definition as returned by `tools/list`. */
 export interface McpToolDef {
     name: string;
     description?: string;

package/dist/mcp/types.js

@@ -1,3 +1,2 @@
-/** Minimal MCP protocol types (JSON-RPC 2.0 over stdio) */
 export {};
 //# sourceMappingURL=types.js.map

package/dist/tools/MemoryTool/index.d.ts

@@ -12,16 +12,16 @@ declare const inputSchema: z.ZodObject<{
     action: "search" | "save" | "list";
     content?: string | undefined;
     type?: "user" | "convention" | "preference" | "project" | "debugging" | "feedback" | "reference" | undefined;
-    description?: string | undefined;
     name?: string | undefined;
+    description?: string | undefined;
     global?: boolean | undefined;
     query?: string | undefined;
 }, {
     action: "search" | "save" | "list";
     content?: string | undefined;
     type?: "user" | "convention" | "preference" | "project" | "debugging" | "feedback" | "reference" | undefined;
-    description?: string | undefined;
     name?: string | undefined;
+    description?: string | undefined;
     global?: boolean | undefined;
     query?: string | undefined;
 }>;

package/dist/tools/TaskUpdateTool/index.d.ts

@@ -12,7 +12,7 @@ declare const inputSchema: z.ZodObject<{
     addBlockedBy: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
 }, "strip", z.ZodTypeAny, {
     taskId: number;
-    status?: "completed" | "pending" | "cancelled" | "in_progress" | "deleted" | undefined;
+    status?: "completed" | "cancelled" | "pending" | "in_progress" | "deleted" | undefined;
     description?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     subject?: string | undefined;
@@ -22,7 +22,7 @@ declare const inputSchema: z.ZodObject<{
     addBlockedBy?: number[] | undefined;
 }, {
     taskId: number;
-    status?: "completed" | "pending" | "cancelled" | "in_progress" | "deleted" | undefined;
+    status?: "completed" | "cancelled" | "pending" | "in_progress" | "deleted" | undefined;
     description?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     subject?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {
@@ -36,6 +36,7 @@
     "start": "node dist/main.js"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "better-sqlite3": "^12.9.0",
     "chalk": "^5.4.1",
     "commander": "^13.0.0",