@zhijiewang/openharness 2.13.0 → 2.15.0

package/README.md

@@ -57,6 +57,8 @@ oh
 
 That's it. OpenHarness auto-detects Ollama and starts chatting. No API key needed.
 
+**Python SDK:** there's also an official Python SDK for driving `oh` from Python programs (notebooks, batch scripts, ML pipelines). Install with `pip install openharness` after the npm install, then `from openharness import query`. See [`python/README.md`](python/README.md).
+
 ```bash
 oh init                               # interactive setup wizard (provider + cybergotchi)
 oh                                    # auto-detect local model

package/dist/commands/session.js

@@ -7,6 +7,33 @@ import { dirname, join, resolve } from "node:path";
 import { getContextWindow } from "../harness/cost.js";
 import { createSession, listSessions, loadSession, saveSession } from "../harness/session.js";
 import { compressMessages } from "../query/index.js";
+function formatMessagesAsMarkdown(messages) {
+    const blocks = [];
+    for (const m of messages) {
+        if (m.role === "user") {
+            blocks.push(`## User\n\n${m.content}`);
+        }
+        else if (m.role === "assistant") {
+            const parts = [];
+            if (m.content)
+                parts.push(m.content);
+            if (m.toolCalls?.length) {
+                for (const tc of m.toolCalls) {
+                    parts.push(`**Tool call:** \`${tc.toolName}(${JSON.stringify(tc.arguments)})\``);
+                }
+            }
+            blocks.push(`## Assistant\n\n${parts.join("\n\n")}`);
+        }
+        else if (m.role === "tool") {
+            for (const tr of m.toolResults ?? []) {
+                const label = tr.isError ? "Tool error" : "Tool result";
+                blocks.push(`**${label}:**\n\n\`\`\`\n${tr.output}\n\`\`\``);
+            }
+        }
+        // system / info messages are skipped — they're OH-internal UX, not conversation
+    }
+    return blocks.join("\n\n");
+}
 function setPinned(args, ctx, pinned) {
     const idx = parseInt(args.trim(), 10);
     if (Number.isNaN(idx) || idx < 1 || idx > ctx.messages.length) {
@@ -59,20 +86,19 @@ export function registerSessionCommands(register) {
             compactedMessages: compacted,
         };
     });
-    register("export", "Export conversation to file", (_args, ctx) => {
-        const lines = ctx.messages
-            .filter((m) => m.role === "user" || m.role === "assistant")
-            .map((m) => `${m.role === "user" ? "User" : "Assistant"}: ${m.content}`)
-            .join("\n\n");
-        const filename = `.oh/export-${ctx.sessionId}.md`;
+    register("export", "Export conversation to file (args: 'json' for JSON format)", (args, ctx) => {
+        const asJson = args.trim().toLowerCase() === "json";
+        const ext = asJson ? "json" : "md";
+        const filename = `.oh/export-${ctx.sessionId}.${ext}`;
+        const body = asJson ? JSON.stringify(ctx.messages, null, 2) : formatMessagesAsMarkdown(ctx.messages);
         try {
             mkdirSync(dirname(filename), { recursive: true });
             const { writeFileSync } = require("node:fs");
-            writeFileSync(filename, lines);
-            return { output: `Exported to ${filename}`, handled: true };
+            writeFileSync(filename, body);
+            return { output: `Exported ${ctx.messages.length} messages to ${filename}`, handled: true };
         }
         catch {
-            return { output: `Export failed. Content:\n\n${lines.slice(0, 500)}`, handled: true };
+            return { output: `Export failed. Content:\n\n${body.slice(0, 500)}`, handled: true };
         }
     });
     register("history", "List recent sessions or search across them", (args) => {
@@ -106,7 +132,8 @@ export function registerSessionCommands(register) {
         const lines = sessions.map((s) => {
             const date = new Date(s.updatedAt).toLocaleDateString();
             const cost = s.cost > 0 ? ` $${s.cost.toFixed(4)}` : "";
-            return `  ${s.id}  ${date}  ${String(s.messages).padStart(3)} msgs  ${(s.model || "?").slice(0, 24)}${cost}`;
+            const parent = s.parentSessionId ? ` ⤴ forked from ${s.parentSessionId}` : "";
+            return `  ${s.id}  ${date}  ${String(s.messages).padStart(3)} msgs  ${(s.model || "?").slice(0, 24)}${cost}${parent}`;
         });
         return { output: `Recent sessions (use /resume <id> to continue):\n${lines.join("\n")}`, handled: true };
     });
@@ -127,11 +154,11 @@ export function registerSessionCommands(register) {
         }
     });
     register("fork", "Fork current session (create a branch you can resume later)", (_args, ctx) => {
-        const forked = createSession("", "");
+        const forked = createSession(ctx.providerName, ctx.model, { parentSessionId: ctx.sessionId });
         forked.messages = [...ctx.messages];
         saveSession(forked);
         return {
-            output: `Session forked as ${forked.id}. Resume later with: oh --resume ${forked.id}`,
+            output: `Session forked as ${forked.id} (from ${ctx.sessionId}). Resume later with: oh --resume ${forked.id}`,
             handled: true,
         };
     });

package/dist/harness/config.d.ts

@@ -107,6 +107,10 @@ export type OhConfig = {
         apiKey?: string;
         baseUrl?: string;
     }>;
+    /** MCP OAuth token storage backend. Default: "auto" — keychain when available, filesystem otherwise. */
+    credentials?: {
+        storage?: "filesystem" | "auto";
+    };
     /** Auto-commit after each file-modifying tool execution */
     gitCommitPerTool?: boolean;
     /** Effort level for LLM reasoning depth */

package/dist/harness/session.d.ts

@@ -13,6 +13,8 @@ export type Session = {
     gitBranch?: string;
     workingDir?: string;
     tools?: string[];
+    /** For forked sessions: the session this one was forked from. */
+    parentSessionId?: string;
     /** Hibernate state — saved on exit for wake reconstruction */
     hibernate?: {
         summary?: string;
@@ -26,6 +28,7 @@ export declare function createSession(provider: string, model: string, extras?:
     gitBranch?: string;
     workingDir?: string;
     tools?: string[];
+    parentSessionId?: string;
 }): Session;
 export declare function saveSession(session: Session, dir?: string): string;
 export declare function loadSession(id: string, dir?: string): Session;
@@ -35,6 +38,7 @@ export declare function listSessions(dir?: string): Array<{
     messages: number;
     cost: number;
     updatedAt: number;
+    parentSessionId?: string;
 }>;
 /** Returns the ID of the most recently updated session, or null if none exist. */
 export declare function getLastSessionId(dir?: string): string | null;

package/dist/harness/session.js

@@ -18,6 +18,7 @@ export function createSession(provider, model, extras) {
         ...(extras?.gitBranch ? { gitBranch: extras.gitBranch } : {}),
         ...(extras?.workingDir ? { workingDir: extras.workingDir } : {}),
         ...(extras?.tools ? { tools: extras.tools } : {}),
+        ...(extras?.parentSessionId ? { parentSessionId: extras.parentSessionId } : {}),
     };
 }
 let _evicting = false;
@@ -73,6 +74,7 @@ export function listSessions(dir) {
                 messages: data.messages?.length ?? 0,
                 cost: data.totalCost ?? 0,
                 updatedAt: data.updatedAt ?? 0,
+                ...(data.parentSessionId ? { parentSessionId: data.parentSessionId } : {}),
             };
         }
         catch {

package/dist/main.js

@@ -230,7 +230,21 @@ program
                 console.log(JSON.stringify({ type: "error", message: event.message }));
             }
         }
+        else if (event.type === "cost_update") {
+            if (outputFormat === "stream-json") {
+                console.log(JSON.stringify({
+                    type: "cost_update",
+                    inputTokens: event.inputTokens,
+                    outputTokens: event.outputTokens,
+                    cost: event.cost,
+                    model: event.model,
+                }));
+            }
+        }
         else if (event.type === "turn_complete") {
+            if (outputFormat === "stream-json") {
+                console.log(JSON.stringify({ type: "turn_complete", reason: event.reason }));
+            }
             if (event.reason !== "completed") {
                 process.exitCode = 1;
             }
@@ -243,6 +257,138 @@ program
         process.stdout.write("\n");
     }
 });
+// ── `oh session`: long-lived stateful session for the Python SDK ──
+program
+    .command("session")
+    .description("Long-lived session: read JSON prompts from stdin, stream NDJSON events on stdout (for the Python SDK)")
+    .option("-m, --model <model>", "Model to use")
+    .addOption(new Option("--permission-mode <mode>", "Permission mode")
+    .choices(["ask", "trust", "deny", "acceptEdits", "plan", "auto", "bypassPermissions"])
+    .default("trust"))
+    .option("--allowed-tools <tools>", "Comma-separated allowed tool names")
+    .option("--disallowed-tools <tools>", "Comma-separated disallowed tool names")
+    .option("--max-turns <n>", "Maximum turns per prompt", "20")
+    .option("--system-prompt <prompt>", "Override the system prompt")
+    .action(async (opts) => {
+    const savedConfig = readOhConfig();
+    const permissionMode = (opts.permissionMode ??
+        savedConfig?.permissionMode ??
+        "trust");
+    const { createProvider } = await import("./providers/index.js");
+    const effectiveModel = opts.model ?? savedConfig?.model;
+    const overrides = {};
+    if (savedConfig?.apiKey)
+        overrides.apiKey = savedConfig.apiKey;
+    if (savedConfig?.baseUrl)
+        overrides.baseUrl = savedConfig.baseUrl;
+    const { provider, model } = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined);
+    const { query } = await import("./query.js");
+    const { createAssistantMessage, createToolResultMessage, createUserMessage } = await import("./types/message.js");
+    let tools = getAllTools();
+    if (opts.allowedTools) {
+        const allowed = new Set(opts.allowedTools.split(",").map((s) => s.trim()));
+        tools = tools.filter((t) => allowed.has(t.name));
+    }
+    if (opts.disallowedTools) {
+        const disallowed = new Set(opts.disallowedTools.split(",").map((s) => s.trim()));
+        tools = tools.filter((t) => !disallowed.has(t.name));
+    }
+    const systemPrompt = opts.systemPrompt ?? buildSystemPrompt(model);
+    const config = {
+        provider,
+        tools,
+        systemPrompt,
+        permissionMode,
+        maxTurns: parseInt(opts.maxTurns, 10),
+        model,
+    };
+    // Conversation history, shared across all prompts for this process.
+    const conversation = [];
+    // Announce readiness so the client can send the first prompt.
+    console.log(JSON.stringify({ type: "ready" }));
+    const readline = await import("node:readline");
+    const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
+    for await (const rawLine of rl) {
+        const line = rawLine.trim();
+        if (!line)
+            continue;
+        let request;
+        try {
+            request = JSON.parse(line);
+        }
+        catch {
+            console.log(JSON.stringify({ id: "", type: "error", message: "invalid JSON on stdin" }));
+            continue;
+        }
+        if (request.command === "exit")
+            break;
+        const id = request.id ?? "";
+        const prompt = request.prompt;
+        if (!id || !prompt) {
+            console.log(JSON.stringify({ id, type: "error", message: "missing 'id' or 'prompt' field" }));
+            continue;
+        }
+        // Accumulate this turn's assistant output so we can push a full message at the end.
+        let assistantText = "";
+        const turnToolCalls = [];
+        const callIdToName = {};
+        const toolResults = [];
+        for await (const event of query(prompt, config, conversation)) {
+            if (event.type === "text_delta") {
+                assistantText += event.content;
+                console.log(JSON.stringify({ id, type: "text", content: event.content }));
+            }
+            else if (event.type === "tool_call_start") {
+                callIdToName[event.callId] = event.toolName;
+                console.log(JSON.stringify({ id, type: "tool_start", tool: event.toolName }));
+            }
+            else if (event.type === "tool_call_complete") {
+                turnToolCalls.push({
+                    id: event.callId,
+                    toolName: callIdToName[event.callId] ?? event.callId,
+                    arguments: event.arguments,
+                });
+            }
+            else if (event.type === "tool_call_end") {
+                toolResults.push({ callId: event.callId, output: event.output, isError: event.isError });
+                console.log(JSON.stringify({
+                    id,
+                    type: "tool_end",
+                    tool: callIdToName[event.callId],
+                    output: event.output,
+                    error: event.isError,
+                }));
+            }
+            else if (event.type === "error") {
+                console.log(JSON.stringify({ id, type: "error", message: event.message }));
+            }
+            else if (event.type === "cost_update") {
+                console.log(JSON.stringify({
+                    id,
+                    type: "cost_update",
+                    inputTokens: event.inputTokens,
+                    outputTokens: event.outputTokens,
+                    cost: event.cost,
+                    model: event.model,
+                }));
+            }
+            else if (event.type === "turn_complete") {
+                console.log(JSON.stringify({ id, type: "turn_complete", reason: event.reason }));
+            }
+        }
+        // Rebuild this turn's contribution to the conversation.
+        // The pattern mirrors query()'s internal accumulation at
+        // src/query/index.ts:119 (user msg pushed before turn) and 344 (assistant
+        // msg with tool calls pushed after each turn) — see the spec for detail.
+        conversation.push(createUserMessage(prompt));
+        if (assistantText || turnToolCalls.length > 0) {
+            conversation.push(createAssistantMessage(assistantText, turnToolCalls.length > 0 ? turnToolCalls : undefined));
+        }
+        for (const tr of toolResults) {
+            conversation.push(createToolResultMessage({ callId: tr.callId, output: tr.output, isError: tr.isError }));
+        }
+    }
+});
 // ── Default command: just run `openharness` to start chatting ──
 program
     .command("chat", { isDefault: true })
@@ -276,38 +422,62 @@ program
                 : opts.permissionMode !== "ask"
                     ? opts.permissionMode
                     : (savedConfig?.permissionMode ?? "ask");
-    // Auto-detect provider or prompt for setup
+    // Auto-detect provider or launch the setup wizard
     let provider;
     let resolvedModel;
-    try {
+    const tryCreateProvider = async () => {
         const { createProvider } = await import("./providers/index.js");
         const overrides = {};
-        if (savedConfig?.apiKey)
-            overrides.apiKey = savedConfig.apiKey;
-        if (savedConfig?.baseUrl)
-            overrides.baseUrl = savedConfig.baseUrl;
-        const result = await createProvider(effectiveModel, Object.keys(overrides).length ? overrides : undefined);
+        const fresh = readOhConfig();
+        if (fresh?.apiKey)
+            overrides.apiKey = fresh.apiKey;
+        if (fresh?.baseUrl)
+            overrides.baseUrl = fresh.baseUrl;
+        const targetModel = fresh?.model ?? effectiveModel;
+        return createProvider(targetModel, Object.keys(overrides).length ? overrides : undefined);
+    };
+    try {
+        const result = await tryCreateProvider();
         provider = result.provider;
         resolvedModel = result.model;
     }
     catch (_err) {
-        // First-run experience: guide the user
-        console.log();
-        console.log("  Welcome to OpenHarness!");
-        console.log();
-        console.log("  To get started, choose a provider:");
-        console.log();
-        console.log("  Local (free, no API key):");
-        console.log("    npx openharness --model ollama/llama3");
-        console.log("    npx openharness --model ollama/qwen2.5:7b-instruct");
-        console.log();
-        console.log("  Cloud (needs API key in env var):");
-        console.log("    OPENAI_API_KEY=sk-... npx openharness --model gpt-4o");
-        console.log("    ANTHROPIC_API_KEY=sk-ant-... npx openharness --model claude-sonnet-4-6");
-        console.log();
-        console.log("  Make sure Ollama is running: ollama serve");
-        console.log();
-        process.exit(0);
+        // First-run: launch the interactive wizard in TTY mode; fall back to
+        // static help text for non-TTY (CI, piped stdin, etc.).
+        if (process.stdout.isTTY && process.stdin.isTTY) {
+            const { default: InitWizard } = await import("./components/InitWizard.js");
+            const { waitUntilExit } = render(_jsx(InitWizard, { onDone: () => { } }));
+            await waitUntilExit();
+            try {
+                const result = await tryCreateProvider();
+                provider = result.provider;
+                resolvedModel = result.model;
+            }
+            catch {
+                console.log();
+                console.log("  Setup incomplete. Run 'oh init' to try again, or set a provider via --model.");
+                console.log();
+                process.exit(0);
+            }
+        }
+        else {
+            console.log();
+            console.log("  Welcome to OpenHarness!");
+            console.log();
+            console.log("  To get started, choose a provider:");
+            console.log();
+            console.log("  Local (free, no API key):");
+            console.log("    npx openharness --model ollama/llama3");
+            console.log("    npx openharness --model ollama/qwen2.5:7b-instruct");
+            console.log();
+            console.log("  Cloud (needs API key in env var):");
+            console.log("    OPENAI_API_KEY=sk-... npx openharness --model gpt-4o");
+            console.log("    ANTHROPIC_API_KEY=sk-ant-... npx openharness --model claude-sonnet-4-6");
+            console.log();
+            console.log("  Make sure Ollama is running: ollama serve");
+            console.log();
+            process.exit(0);
+        }
     }
     const mcpTools = await loadMcpTools();
     const mcpNames = connectedMcpServers();

package/dist/mcp/oauth-keychain.d.ts

@@ -0,0 +1,16 @@
+/**
+ * OS keychain backend for MCP OAuth tokens.
+ *
+ * Wraps @napi-rs/keyring (optional dependency). All functions catch every error
+ * and return an "unavailable" sentinel so the orchestrator in oauth-storage.ts
+ * can fall back to the filesystem store without any user-visible disruption.
+ */
+import type { OhCredentials } from "./oauth-storage-fs.js";
+/** Clear the cached module reference. For tests only. */
+export declare function _resetForTesting(): void;
+/** True iff @napi-rs/keyring loaded successfully AND the platform has an Entry class. */
+export declare function keychainAvailable(): boolean;
+export declare function saveCredentialsKeychain(name: string, creds: OhCredentials): boolean;
+export declare function loadCredentialsKeychain(name: string): OhCredentials | undefined;
+export declare function deleteCredentialsKeychain(name: string): boolean;
+//# sourceMappingURL=oauth-keychain.d.ts.map

package/dist/mcp/oauth-keychain.js

@@ -0,0 +1,70 @@
+/**
+ * OS keychain backend for MCP OAuth tokens.
+ *
+ * Wraps @napi-rs/keyring (optional dependency). All functions catch every error
+ * and return an "unavailable" sentinel so the orchestrator in oauth-storage.ts
+ * can fall back to the filesystem store without any user-visible disruption.
+ */
+import { createRequire } from "node:module";
+const SERVICE = "openharness-mcp";
+const nodeRequire = createRequire(import.meta.url);
+let entryCtorCache;
+function getEntryCtor() {
+    if (entryCtorCache !== undefined)
+        return entryCtorCache;
+    try {
+        const mod = nodeRequire("@napi-rs/keyring");
+        entryCtorCache = mod.Entry;
+    }
+    catch {
+        entryCtorCache = null;
+    }
+    return entryCtorCache;
+}
+/** Clear the cached module reference. For tests only. */
+export function _resetForTesting() {
+    entryCtorCache = undefined;
+}
+/** True iff @napi-rs/keyring loaded successfully AND the platform has an Entry class. */
+export function keychainAvailable() {
+    return getEntryCtor() !== null;
+}
+export function saveCredentialsKeychain(name, creds) {
+    const Ctor = getEntryCtor();
+    if (!Ctor)
+        return false;
+    try {
+        new Ctor(SERVICE, name).setPassword(JSON.stringify(creds));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function loadCredentialsKeychain(name) {
+    const Ctor = getEntryCtor();
+    if (!Ctor)
+        return undefined;
+    try {
+        const raw = new Ctor(SERVICE, name).getPassword();
+        if (!raw)
+            return undefined;
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function deleteCredentialsKeychain(name) {
+    const Ctor = getEntryCtor();
+    if (!Ctor)
+        return false;
+    try {
+        new Ctor(SERVICE, name).deletePassword();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=oauth-keychain.js.map

package/dist/mcp/oauth-storage-fs.d.ts

@@ -0,0 +1,23 @@
+export type OhCredentials = {
+    issuerUrl: string;
+    clientInformation: {
+        client_id: string;
+        client_secret?: string;
+    } & Record<string, unknown>;
+    tokens: {
+        access_token: string;
+        refresh_token?: string;
+        expires_at?: number;
+        token_type?: string;
+        scope?: string;
+    };
+    codeVerifier?: string;
+    updatedAt: string;
+};
+/** Atomically write credentials for one server. Creates the directory with 0o700 on first use. */
+export declare function saveCredentials(storageDir: string, name: string, creds: OhCredentials): Promise<void>;
+/** Load credentials. Returns undefined on missing file OR corrupt JSON. Warns on world/group-readable mode. */
+export declare function loadCredentials(storageDir: string, name: string): Promise<OhCredentials | undefined>;
+/** Idempotent delete — ENOENT is swallowed. */
+export declare function deleteCredentials(storageDir: string, name: string): Promise<void>;
+//# sourceMappingURL=oauth-storage-fs.d.ts.map

package/dist/mcp/oauth-storage-fs.js

@@ -0,0 +1,58 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+function pathFor(storageDir, name) {
+    return join(storageDir, `${name}.json`);
+}
+/** Atomically write credentials for one server. Creates the directory with 0o700 on first use. */
+export async function saveCredentials(storageDir, name, creds) {
+    const filePath = pathFor(storageDir, name);
+    const tmpPath = `${filePath}.tmp`;
+    await fs.mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
+    const body = JSON.stringify(creds, null, 2);
+    await fs.writeFile(tmpPath, body, { mode: 0o600 });
+    await fs.rename(tmpPath, filePath);
+}
+/** Load credentials. Returns undefined on missing file OR corrupt JSON. Warns on world/group-readable mode. */
+export async function loadCredentials(storageDir, name) {
+    const filePath = pathFor(storageDir, name);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    try {
+        if (process.platform !== "win32") {
+            const s = await fs.stat(filePath);
+            if ((s.mode & 0o077) !== 0) {
+                console.warn(`[mcp] credentials file for '${name}' is world/group-readable; run 'chmod 600 ${filePath}'`);
+            }
+        }
+    }
+    catch {
+        // stat failure is non-fatal for load
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        console.warn(`[mcp] credentials file for '${name}' is corrupt; ignoring`);
+        return undefined;
+    }
+}
+/** Idempotent delete — ENOENT is swallowed. */
+export async function deleteCredentials(storageDir, name) {
+    const filePath = pathFor(storageDir, name);
+    try {
+        await fs.unlink(filePath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
+//# sourceMappingURL=oauth-storage-fs.js.map

package/dist/mcp/oauth-storage.d.ts

@@ -1,23 +1,28 @@
-export type OhCredentials = {
-    issuerUrl: string;
-    clientInformation: {
-        client_id: string;
-        client_secret?: string;
-    } & Record<string, unknown>;
-    tokens: {
-        access_token: string;
-        refresh_token?: string;
-        expires_at?: number;
-        token_type?: string;
-        scope?: string;
-    };
-    codeVerifier?: string;
-    updatedAt: string;
-};
-/** Atomically write credentials for one server. Creates the directory with 0o700 on first use. */
+/**
+ * OAuth token storage orchestrator.
+ *
+ * Prefers the OS keychain via `oauth-keychain.ts` when available and not
+ * opted out via `credentials.storage: "filesystem"`. Falls back to the
+ * filesystem store in `oauth-storage-fs.ts` on any keychain failure.
+ *
+ * Public API unchanged: callers in oauth.ts and commands/mcp-auth.ts
+ * continue to import `saveCredentials` / `loadCredentials` /
+ * `deleteCredentials` / `OhCredentials` from this module.
+ */
+export type { OhCredentials } from "./oauth-storage-fs.js";
+import type { OhCredentials } from "./oauth-storage-fs.js";
+/**
+ * Save credentials. Tries keychain first when available; falls back to
+ * filesystem on any keychain failure.
+ */
 export declare function saveCredentials(storageDir: string, name: string, creds: OhCredentials): Promise<void>;
-/** Load credentials. Returns undefined on missing file OR corrupt JSON. Warns on world/group-readable mode. */
+/**
+ * Load credentials. Checks keychain first (when available), then filesystem.
+ * If both have entries for the same name, keychain wins.
+ */
 export declare function loadCredentials(storageDir: string, name: string): Promise<OhCredentials | undefined>;
-/** Idempotent delete — ENOENT is swallowed. */
+/**
+ * Delete credentials from BOTH keychain and filesystem. Idempotent.
+ */
 export declare function deleteCredentials(storageDir: string, name: string): Promise<void>;
 //# sourceMappingURL=oauth-storage.d.ts.map

package/dist/mcp/oauth-storage.js

@@ -1,58 +1,55 @@
-import { promises as fs } from "node:fs";
-import { dirname, join } from "node:path";
-function pathFor(storageDir, name) {
-    return join(storageDir, `${name}.json`);
+/**
+ * OAuth token storage orchestrator.
+ *
+ * Prefers the OS keychain via `oauth-keychain.ts` when available and not
+ * opted out via `credentials.storage: "filesystem"`. Falls back to the
+ * filesystem store in `oauth-storage-fs.ts` on any keychain failure.
+ *
+ * Public API unchanged: callers in oauth.ts and commands/mcp-auth.ts
+ * continue to import `saveCredentials` / `loadCredentials` /
+ * `deleteCredentials` / `OhCredentials` from this module.
+ */
+import { readOhConfig } from "../harness/config.js";
+import { deleteCredentialsKeychain, keychainAvailable, loadCredentialsKeychain, saveCredentialsKeychain, } from "./oauth-keychain.js";
+import { deleteCredentials as deleteFs, loadCredentials as loadFs, saveCredentials as saveFs, } from "./oauth-storage-fs.js";
+function shouldUseKeychain() {
+    // Explicit opt-out via env var (used by the test runner to isolate tests
+    // from the real OS keychain). Accepts "disabled", "false", "0", or "off".
+    const envOpt = (process.env.OH_KEYCHAIN ?? "").toLowerCase();
+    if (envOpt === "disabled" || envOpt === "false" || envOpt === "0" || envOpt === "off")
+        return false;
+    const cfg = readOhConfig();
+    if (cfg?.credentials?.storage === "filesystem")
+        return false;
+    return keychainAvailable();
 }
-/** Atomically write credentials for one server. Creates the directory with 0o700 on first use. */
+/**
+ * Save credentials. Tries keychain first when available; falls back to
+ * filesystem on any keychain failure.
+ */
 export async function saveCredentials(storageDir, name, creds) {
-    const filePath = pathFor(storageDir, name);
-    const tmpPath = `${filePath}.tmp`;
-    await fs.mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
-    const body = JSON.stringify(creds, null, 2);
-    await fs.writeFile(tmpPath, body, { mode: 0o600 });
-    await fs.rename(tmpPath, filePath);
+    if (shouldUseKeychain() && saveCredentialsKeychain(name, creds))
+        return;
+    await saveFs(storageDir, name, creds);
 }
-/** Load credentials. Returns undefined on missing file OR corrupt JSON. Warns on world/group-readable mode. */
+/**
+ * Load credentials. Checks keychain first (when available), then filesystem.
+ * If both have entries for the same name, keychain wins.
+ */
 export async function loadCredentials(storageDir, name) {
-    const filePath = pathFor(storageDir, name);
-    let raw;
-    try {
-        raw = await fs.readFile(filePath, "utf8");
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return undefined;
-        throw err;
-    }
-    try {
-        if (process.platform !== "win32") {
-            const s = await fs.stat(filePath);
-            if ((s.mode & 0o077) !== 0) {
-                console.warn(`[mcp] credentials file for '${name}' is world/group-readable; run 'chmod 600 ${filePath}'`);
-            }
-        }
-    }
-    catch {
-        // stat failure is non-fatal for load
-    }
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        console.warn(`[mcp] credentials file for '${name}' is corrupt; ignoring`);
-        return undefined;
+    if (shouldUseKeychain()) {
+        const fromKc = loadCredentialsKeychain(name);
+        if (fromKc)
+            return fromKc;
     }
+    return loadFs(storageDir, name);
 }
-/** Idempotent delete — ENOENT is swallowed. */
+/**
+ * Delete credentials from BOTH keychain and filesystem. Idempotent.
+ */
 export async function deleteCredentials(storageDir, name) {
-    const filePath = pathFor(storageDir, name);
-    try {
-        await fs.unlink(filePath);
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
-            return;
-        throw err;
-    }
+    if (keychainAvailable())
+        deleteCredentialsKeychain(name);
+    await deleteFs(storageDir, name);
 }
 //# sourceMappingURL=oauth-storage.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.13.0",
+  "version": "2.15.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {
@@ -84,5 +84,8 @@
   "bugs": {
     "url": "https://github.com/zhijiewong/openharness/issues"
   },
-  "homepage": "https://github.com/zhijiewong/openharness#readme"
+  "homepage": "https://github.com/zhijiewong/openharness#readme",
+  "optionalDependencies": {
+    "@napi-rs/keyring": "^1.2.0"
+  }
 }