@zhijiewang/openharness 2.21.0 → 2.22.1

package/dist/harness/api-key-helper.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Run the configured `apiKeyHelper` script and return its trimmed stdout as
+ * the API key (audit B8). Mirrors Claude Code's `apiKeyHelper`.
+ *
+ * Invocation:
+ *   - shell: true (so `helper-script.sh` and pipelines work without an explicit shell)
+ *   - 5s timeout (helper should be fast — it's invoked at credential-fetch time)
+ *   - OH_PROVIDER env var set so a single helper can dispatch by provider
+ *   - stderr captured and surfaced on failure
+ *
+ * Failure modes — all return undefined (caller falls through to legacy config):
+ *   - non-zero exit code
+ *   - timeout
+ *   - empty stdout
+ *   - spawn error (helper not found, permission denied, etc.)
+ *
+ * Failures are logged via `debug("config", ...)` so users can opt into
+ * visibility with `--debug config` without polluting normal output.
+ */
+export interface RunApiKeyHelperOptions {
+    /** Provider name passed to the helper as `OH_PROVIDER`. */
+    provider: string;
+    /** Spawn timeout in ms. Defaults to 5_000. */
+    timeoutMs?: number;
+}
+/**
+ * Execute `command` via the user's shell with `OH_PROVIDER` set, return the
+ * trimmed stdout on success, undefined on any failure. Pure side-effect-only —
+ * no caching here; resolveApiKey owns lifetime.
+ */
+export declare function runApiKeyHelper(command: string, opts: RunApiKeyHelperOptions): string | undefined;
+//# sourceMappingURL=api-key-helper.d.ts.map

package/dist/harness/api-key-helper.js

@@ -0,0 +1,70 @@
+/**
+ * Run the configured `apiKeyHelper` script and return its trimmed stdout as
+ * the API key (audit B8). Mirrors Claude Code's `apiKeyHelper`.
+ *
+ * Invocation:
+ *   - shell: true (so `helper-script.sh` and pipelines work without an explicit shell)
+ *   - 5s timeout (helper should be fast — it's invoked at credential-fetch time)
+ *   - OH_PROVIDER env var set so a single helper can dispatch by provider
+ *   - stderr captured and surfaced on failure
+ *
+ * Failure modes — all return undefined (caller falls through to legacy config):
+ *   - non-zero exit code
+ *   - timeout
+ *   - empty stdout
+ *   - spawn error (helper not found, permission denied, etc.)
+ *
+ * Failures are logged via `debug("config", ...)` so users can opt into
+ * visibility with `--debug config` without polluting normal output.
+ */
+import { spawnSync } from "node:child_process";
+import { debug } from "../utils/debug.js";
+/**
+ * Execute `command` via the user's shell with `OH_PROVIDER` set, return the
+ * trimmed stdout on success, undefined on any failure. Pure side-effect-only —
+ * no caching here; resolveApiKey owns lifetime.
+ */
+export function runApiKeyHelper(command, opts) {
+    const timeout = opts.timeoutMs ?? 5_000;
+    try {
+        const result = spawnSync(command, {
+            shell: true,
+            timeout,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: { ...process.env, OH_PROVIDER: opts.provider },
+            encoding: "utf8",
+        });
+        if (result.error) {
+            debug("config", "apiKeyHelper spawn failed", { provider: opts.provider, err: result.error.message });
+            return undefined;
+        }
+        if (result.signal === "SIGTERM") {
+            debug("config", "apiKeyHelper timed out", { provider: opts.provider, timeoutMs: timeout });
+            return undefined;
+        }
+        if (result.status !== 0) {
+            const stderr = (result.stderr ?? "").toString().trim().slice(0, 500);
+            debug("config", "apiKeyHelper non-zero exit", {
+                provider: opts.provider,
+                exit: result.status,
+                stderr,
+            });
+            return undefined;
+        }
+        const out = (result.stdout ?? "").toString().trim();
+        if (!out) {
+            debug("config", "apiKeyHelper produced empty stdout", { provider: opts.provider });
+            return undefined;
+        }
+        debug("config", "apiKeyHelper resolved", { provider: opts.provider, length: out.length });
+        return out;
+    }
+    catch (err) {
+        debug("config", "apiKeyHelper threw", {
+            provider: opts.provider,
+            err: err instanceof Error ? err.message : String(err),
+        });
+        return undefined;
+    }
+}
+//# sourceMappingURL=api-key-helper.js.map

package/dist/harness/config.d.ts

@@ -80,6 +80,19 @@ export type HooksConfig = {
     worktreeCreate?: HookDef[];
     /** Fires after ExitWorktreeTool successfully removes a git worktree. */
     worktreeRemove?: HookDef[];
+    /**
+     * Fires when an MCP server issues an `elicitation/create` request — before
+     * any decision is made. Hook can return `permissionDecision: "allow"` to
+     * accept (sends `{action: "accept", content: {}}` to the server) or `"deny"`
+     * to decline. No decision falls through to the interactive handler (REPL)
+     * or, if absent, to a fail-safe `decline`.
+     */
+    elicitation?: HookDef[];
+    /**
+     * Fires after the elicitation response has been decided — symmetric to
+     * `elicitation`. Useful for audit trails that want the request/response pair.
+     */
+    elicitationResult?: HookDef[];
     /** Fires once per system-prompt build after CLAUDE.md / global-rules / project RULES.md / user profile have been concatenated. Useful for audit trails. */
     instructionsLoaded?: HookDef[];
 };
@@ -124,6 +137,18 @@ export type OhConfig = {
      * Claude Code's `disableAllHooks` setting.
      */
     disableAllHooks?: boolean;
+    /**
+     * Script invoked at credential-fetch time to produce an API key on stdout.
+     * Avoids storing keys in plaintext config or the encrypted store. Inserted
+     * between the encrypted-store and legacy-config steps in `resolveApiKey`.
+     * Mirrors Claude Code's `apiKeyHelper`.
+     *
+     * The configured command runs through the user's shell with a 5s timeout;
+     * stderr is captured and surfaced on failure. The provider name is passed
+     * via the `OH_PROVIDER` env var so a single helper can dispatch by provider
+     * (`if [ "$OH_PROVIDER" = "anthropic" ]; then ... fi`).
+     */
+    apiKeyHelper?: string;
     toolPermissions?: ToolPermissionRule[];
     statusLineFormat?: string;
     /** Verification loops — auto-run lint/typecheck after file edits */

package/dist/harness/credentials.d.ts

@@ -15,10 +15,12 @@ export declare function deleteCredential(key: string): void;
 /** List credential keys (not values) */
 export declare function listCredentials(): string[];
 /**
- * Get API key for a provider, checking:
- * 1. Environment variable (highest priority)
- * 2. Encrypted credential store
- * 3. Config file (legacy plaintext, with migration prompt)
+ * Get API key for a provider, checking in priority order:
+ *   1. Environment variable
+ *   2. Encrypted credential store
+ *   3. `apiKeyHelper` config script (audit B8) — runs the configured command
+ *      with `OH_PROVIDER` set; trimmed stdout is the key. Failures fall through.
+ *   4. Config file (legacy plaintext, with migration into the encrypted store)
  */
 export declare function resolveApiKey(provider: string, configApiKey?: string): string | undefined;
 //# sourceMappingURL=credentials.d.ts.map

package/dist/harness/credentials.js

@@ -10,6 +10,8 @@ import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "node:
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname, userInfo } from "node:os";
 import { join } from "node:path";
+import { runApiKeyHelper } from "./api-key-helper.js";
+import { readOhConfig } from "./config.js";
 const CRED_DIR = join(homedir(), ".oh");
 const CRED_PATH = join(CRED_DIR, "credentials.enc");
 const ALGORITHM = "aes-256-gcm";
@@ -74,10 +76,12 @@ export function listCredentials() {
     return Object.keys(loadStore());
 }
 /**
- * Get API key for a provider, checking:
- * 1. Environment variable (highest priority)
- * 2. Encrypted credential store
- * 3. Config file (legacy plaintext, with migration prompt)
+ * Get API key for a provider, checking in priority order:
+ *   1. Environment variable
+ *   2. Encrypted credential store
+ *   3. `apiKeyHelper` config script (audit B8) — runs the configured command
+ *      with `OH_PROVIDER` set; trimmed stdout is the key. Failures fall through.
+ *   4. Config file (legacy plaintext, with migration into the encrypted store)
  */
 export function resolveApiKey(provider, configApiKey) {
     // Environment variable names by provider
@@ -93,6 +97,13 @@ export function resolveApiKey(provider, configApiKey) {
     const stored = getCredential(`${provider}-api-key`);
     if (stored)
         return stored;
+    // apiKeyHelper script — let users plug in 1Password / pass / vault / etc.
+    const cfg = readOhConfig();
+    if (cfg?.apiKeyHelper) {
+        const fromHelper = runApiKeyHelper(cfg.apiKeyHelper, { provider });
+        if (fromHelper)
+            return fromHelper;
+    }
     // Legacy config (migrate on use)
     if (configApiKey) {
         // Auto-migrate to encrypted store

package/dist/harness/hooks.d.ts

@@ -10,7 +10,7 @@
  * - prompt: LLM yes/no check via provider.complete()
  */
 import type { HookDef, HooksConfig } from "./config.js";
-export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "postToolUseFailure" | "postToolBatch" | "userPromptSubmit" | "userPromptExpansion" | "permissionRequest" | "permissionDenied" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification" | "turnStart" | "turnStop" | "taskCreated" | "taskCompleted" | "worktreeCreate" | "worktreeRemove" | "instructionsLoaded";
+export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "postToolUseFailure" | "postToolBatch" | "userPromptSubmit" | "userPromptExpansion" | "permissionRequest" | "permissionDenied" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification" | "turnStart" | "turnStop" | "taskCreated" | "taskCompleted" | "worktreeCreate" | "worktreeRemove" | "elicitation" | "elicitationResult" | "instructionsLoaded";
 export type HookContext = {
     toolName?: string;
     toolArgs?: string;
@@ -66,6 +66,16 @@ export type HookContext = {
     worktreeParent?: string;
     /** For worktreeRemove: whether `force: true` was passed to skip the dirty-state check */
     worktreeForced?: string;
+    /** For elicitation/elicitationResult: the MCP server that issued the elicitation request */
+    elicitationServer?: string;
+    /** For elicitation/elicitationResult: human-readable message the server wants to show (capped at 500 chars) */
+    elicitationMessage?: string;
+    /** For elicitation: JSON-stringified `requestedSchema` from the server (capped at 2000 chars) */
+    elicitationSchema?: string;
+    /** For elicitationResult: the final action ("accept" | "decline" | "cancel") */
+    elicitationAction?: string;
+    /** For elicitationResult: JSON-stringified content payload returned to the server (when action="accept") */
+    elicitationContent?: string;
     /** For instructionsLoaded: count of rules concatenated (as a string for env-var parity) */
     rulesCount?: string;
     /** For instructionsLoaded: total character length of the loaded rules */

package/dist/harness/hooks.js

@@ -90,6 +90,16 @@ function buildEnv(event, ctx) {
         env.OH_WORKTREE_PARENT = ctx.worktreeParent;
     if (ctx.worktreeForced !== undefined)
         env.OH_WORKTREE_FORCED = ctx.worktreeForced;
+    if (ctx.elicitationServer !== undefined)
+        env.OH_ELICITATION_SERVER = ctx.elicitationServer;
+    if (ctx.elicitationMessage !== undefined)
+        env.OH_ELICITATION_MESSAGE = ctx.elicitationMessage;
+    if (ctx.elicitationSchema !== undefined)
+        env.OH_ELICITATION_SCHEMA = ctx.elicitationSchema;
+    if (ctx.elicitationAction !== undefined)
+        env.OH_ELICITATION_ACTION = ctx.elicitationAction;
+    if (ctx.elicitationContent !== undefined)
+        env.OH_ELICITATION_CONTENT = ctx.elicitationContent;
     return env;
 }
 /**

package/dist/lsp/client.d.ts

@@ -51,7 +51,16 @@ export declare class LspClient {
     getDefinition(filePath: string, line: number, character: number): Promise<Location[]>;
     /** Find references */
     getReferences(filePath: string, line: number, character: number): Promise<Location[]>;
+    /**
+     * Hover at a position — returns the text content of the LSP hover response,
+     * or `null` if the server returned no hover information / doesn't support
+     * the `textDocument/hover` capability. The LSP `MarkupContent` envelope is
+     * unwrapped so callers see plain text or markdown.
+     */
+    getHover(filePath: string, line: number, character: number): Promise<string | null>;
     private guessLanguage;
+    /** @internal Exposed for unit tests of the hover-content unwrapper. */
+    static unwrapHoverContents(result: unknown): string | null;
     disconnect(): void;
 }
 export {};

package/dist/lsp/client.js

@@ -4,6 +4,38 @@
  */
 import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
+/**
+ * Unwrap a `textDocument/hover` result into a plain string. LSP allows three
+ * `contents` shapes: a bare string, a `{ kind, value }` envelope, or an
+ * array of either. Returns null when nothing is hoverable. Pure — exposed
+ * via `LspClient.unwrapHoverContents` for unit tests.
+ */
+function unwrapHoverContents(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const r = result;
+    if (!r.contents)
+        return null;
+    const c = r.contents;
+    if (typeof c === "string")
+        return c;
+    if (Array.isArray(c)) {
+        const parts = c.map((item) => {
+            if (typeof item === "string")
+                return item;
+            if (item && typeof item === "object" && typeof item.value === "string") {
+                return item.value;
+            }
+            return "";
+        });
+        const joined = parts.filter(Boolean).join("\n");
+        return joined || null;
+    }
+    if (typeof c === "object" && typeof c.value === "string") {
+        return c.value;
+    }
+    return null;
+}
 export class LspClient {
     proc;
     nextId = 1;
@@ -150,6 +182,20 @@ export class LspClient {
         });
         return result ?? [];
     }
+    /**
+     * Hover at a position — returns the text content of the LSP hover response,
+     * or `null` if the server returned no hover information / doesn't support
+     * the `textDocument/hover` capability. The LSP `MarkupContent` envelope is
+     * unwrapped so callers see plain text or markdown.
+     */
+    async getHover(filePath, line, character) {
+        const uri = `file://${filePath.replace(/\\/g, "/")}`;
+        const result = await this.send("textDocument/hover", {
+            textDocument: { uri },
+            position: { line, character },
+        });
+        return unwrapHoverContents(result);
+    }
     guessLanguage(path) {
         if (path.endsWith(".ts") || path.endsWith(".tsx"))
             return "typescript";
@@ -165,6 +211,10 @@ export class LspClient {
             return "java";
         return "plaintext";
     }
+    /** @internal Exposed for unit tests of the hover-content unwrapper. */
+    static unwrapHoverContents(result) {
+        return unwrapHoverContents(result);
+    }
     disconnect() {
         this.send("shutdown", {})
             .then(() => {