@zhijiewang/openharness 2.14.0 → 2.16.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/harness/config.d.ts

@@ -62,6 +62,10 @@ export type HooksConfig = {
     postCompact?: HookDef[];
     configChange?: HookDef[];
     notification?: HookDef[];
+    /** Fires at the start of each top-level agent turn (after a user prompt is accepted, before model call). */
+    turnStart?: HookDef[];
+    /** Fires at the end of each top-level agent turn (after the model either completes or errors). Matches Claude Code's Stop hook. */
+    turnStop?: HookDef[];
 };
 export type ToolPermissionRule = {
     tool: string;

package/dist/harness/hooks.d.ts

@@ -10,7 +10,7 @@
  * - prompt: LLM yes/no check via provider.complete()
  */
 import type { HookDef } from "./config.js";
-export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "postToolUseFailure" | "userPromptSubmit" | "permissionRequest" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification";
+export type HookEvent = "sessionStart" | "sessionEnd" | "preToolUse" | "postToolUse" | "postToolUseFailure" | "userPromptSubmit" | "permissionRequest" | "fileChanged" | "cwdChanged" | "subagentStart" | "subagentStop" | "preCompact" | "postCompact" | "configChange" | "notification" | "turnStart" | "turnStop";
 export type HookContext = {
     toolName?: string;
     toolArgs?: string;
@@ -38,6 +38,10 @@ export type HookContext = {
     errorMessage?: string;
     /** For permissionRequest: the decision OH would take absent the hook ("ask", "allow", "deny") — informational */
     permissionAction?: "ask" | "allow" | "deny";
+    /** For turnStart/turnStop: zero-indexed turn number within the current session */
+    turnNumber?: string;
+    /** For turnStop: reason the turn ended ("completed", "max_turns", "error", "interrupted") */
+    turnReason?: string;
 };
 /** Clear hook cache (call after config changes) */
 export declare function invalidateHookCache(): void;
@@ -92,4 +96,22 @@ export type HookOutcome = {
  *   from hooks is ignored — outcome.allowed is always true. additionalContext is still collected.
  */
 export declare function emitHookWithOutcome(event: HookEvent, ctx?: HookContext): Promise<HookOutcome>;
+export type HookDecisionNotification = {
+    event: HookEvent;
+    /** Present when the hook fired in a tool-specific context. */
+    tool?: string;
+    /** The effective decision. "ask" means defer to the user / default permission flow. */
+    decision: "allow" | "deny" | "ask";
+    /** Reason returned by the hook, if any. */
+    reason?: string;
+};
+type HookDecisionObserver = (n: HookDecisionNotification) => void;
+/**
+ * Register (or clear) a single observer that receives one notification per
+ * `emitHookWithOutcome` call that produces a decision. Used by
+ * `oh run --output-format stream-json` to emit `hook_decision` NDJSON events
+ * so the Python SDK can surface permission outcomes in real time.
+ */
+export declare function setHookDecisionObserver(cb: HookDecisionObserver | null): void;
+export {};
 //# sourceMappingURL=hooks.d.ts.map

package/dist/harness/hooks.js

@@ -67,6 +67,10 @@ function buildEnv(event, ctx) {
         env.OH_ERROR_MESSAGE = ctx.errorMessage;
     if (ctx.permissionAction !== undefined)
         env.OH_PERMISSION_ACTION = ctx.permissionAction;
+    if (ctx.turnNumber !== undefined)
+        env.OH_TURN_NUMBER = ctx.turnNumber;
+    if (ctx.turnReason !== undefined)
+        env.OH_TURN_REASON = ctx.turnReason;
     return env;
 }
 /**
@@ -263,6 +267,50 @@ async function runHttpHook(url, event, ctx, timeoutMs = 10_000) {
         return false;
     }
 }
+/**
+ * Run an HTTP hook and return its full structured response. POSTs `{event, ...ctx}`
+ * as JSON and parses the response body with the same jsonIO envelope shape used
+ * by command hooks:
+ *   { decision?: "allow" | "deny", reason?: string,
+ *     hookSpecificOutput?: { decision?: "allow" | "deny" | "ask", reason?, additionalContext? } }
+ *
+ * Also honors a legacy `{ allowed: boolean }` shape (downgrades to decision).
+ *
+ * Network errors / non-2xx responses / malformed JSON all return a "deny" outcome
+ * so the caller can fail closed.
+ */
+async function runHttpHookDetailed(url, event, ctx, timeoutMs = 10_000) {
+    try {
+        const body = JSON.stringify({ event, ...ctx });
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return { decision: "deny", reason: `hook HTTP ${res.status}` };
+        const text = await res.text();
+        if (!text.trim())
+            return {};
+        const parsed = parseJsonIoResponse(text);
+        // If the response only used the legacy `{ allowed: false }` shape, surface as deny.
+        if (!parsed.decision && !parsed.permissionDecision) {
+            try {
+                const legacy = JSON.parse(text);
+                if (legacy.allowed === false)
+                    return { decision: "deny", reason: "hook denied" };
+            }
+            catch {
+                // already handled by parseJsonIoResponse
+            }
+        }
+        return parsed;
+    }
+    catch {
+        return { decision: "deny", reason: "hook HTTP error" };
+    }
+}
 /**
  * Run a prompt hook. Uses an LLM to make a yes/no allow/deny decision.
  *
@@ -503,8 +551,7 @@ async function runHookForOutcome(def, event, ctx) {
         return mapEnvExitToOutcome(event, code === 0);
     }
     if (def.http) {
-        const allowed = await runHttpHook(def.http, event, ctx, def.timeout ?? 10_000);
-        return mapEnvExitToOutcome(event, allowed);
+        return await runHttpHookDetailed(def.http, event, ctx, def.timeout ?? 10_000);
     }
     if (def.prompt) {
         const allowed = await runPromptHook(def.prompt, ctx, def.timeout ?? 10_000);
@@ -537,20 +584,24 @@ export async function emitHookWithOutcome(event, ctx = {}) {
         const parsed = await runHookForOutcome(def, event, ctx);
         if (!notifyOnly) {
             if (parsed.decision === "deny" || parsed.permissionDecision === "deny") {
-                return {
+                const outcome = {
                     allowed: false,
                     reason: parsed.reason ?? reason,
                     permissionDecision: parsed.permissionDecision,
                 };
+                notifyHookDecision(event, ctx, outcome);
+                return outcome;
             }
             if (parsed.permissionDecision === "allow") {
                 if (parsed.additionalContext)
                     additionalContexts.push(parsed.additionalContext);
-                return {
+                const outcome = {
                     allowed: true,
                     permissionDecision: "allow",
                     additionalContext: additionalContexts.length ? additionalContexts.join("\n\n") : undefined,
                 };
+                notifyHookDecision(event, ctx, outcome);
+                return outcome;
             }
             if (parsed.permissionDecision === "ask")
                 askSeen = true;
@@ -560,11 +611,43 @@ export async function emitHookWithOutcome(event, ctx = {}) {
         if (!reason && parsed.reason)
             reason = parsed.reason;
     }
-    return {
+    const outcome = {
         allowed: true,
         additionalContext: additionalContexts.length ? additionalContexts.join("\n\n") : undefined,
         permissionDecision: askSeen ? "ask" : undefined,
         reason,
     };
+    notifyHookDecision(event, ctx, outcome);
+    return outcome;
+}
+let hookDecisionObserver = null;
+/**
+ * Register (or clear) a single observer that receives one notification per
+ * `emitHookWithOutcome` call that produces a decision. Used by
+ * `oh run --output-format stream-json` to emit `hook_decision` NDJSON events
+ * so the Python SDK can surface permission outcomes in real time.
+ */
+export function setHookDecisionObserver(cb) {
+    hookDecisionObserver = cb;
+}
+function notifyHookDecision(event, ctx, outcome) {
+    if (!hookDecisionObserver)
+        return;
+    // Prefer the richer permissionDecision when present; fall back to deny if the hook blocked.
+    let decision = outcome.permissionDecision;
+    if (!decision) {
+        if (!outcome.allowed)
+            decision = "deny";
+        else if (outcome.reason)
+            decision = "allow";
+    }
+    if (!decision)
+        return;
+    try {
+        hookDecisionObserver({ event, tool: ctx.toolName, decision, reason: outcome.reason });
+    }
+    catch {
+        // Observer errors must not break the hook pipeline.
+    }
 }
 //# sourceMappingURL=hooks.js.map

package/dist/main.js

@@ -16,7 +16,7 @@ import { join } from "node:path";
 import { Command, Option } from "commander";
 import { render } from "ink";
 import { readOhConfig } from "./harness/config.js";
-import { emitHook } from "./harness/hooks.js";
+import { emitHook, setHookDecisionObserver } from "./harness/hooks.js";
 import { loadActiveMemories, memoriesToPrompt, userProfileToPrompt } from "./harness/memory.js";
 import { detectProject, projectContextToPrompt } from "./harness/onboarding.js";
 import { discoverSkills, skillsToPrompt } from "./harness/plugins.js";
@@ -189,6 +189,26 @@ program
     let fullOutput = "";
     const toolResults = [];
     const callIdToName = {};
+    if (outputFormat === "stream-json") {
+        setHookDecisionObserver((n) => {
+            console.log(JSON.stringify({
+                type: "hook_decision",
+                event: n.event,
+                tool: n.tool,
+                decision: n.decision,
+                reason: n.reason,
+            }));
+        });
+    }
+    emitHook("turnStart", {
+        turnNumber: "0",
+        model,
+        provider: typeof config.provider === "string" ? config.provider : undefined,
+        permissionMode,
+    });
+    if (outputFormat === "stream-json") {
+        console.log(JSON.stringify({ type: "turnStart", turnNumber: 0 }));
+    }
     for await (const event of query(prompt, config)) {
         if (event.type === "text_delta") {
             fullOutput += event.content;
@@ -230,7 +250,25 @@ 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 }));
+            }
+            emitHook("turnStop", { turnNumber: "0", turnReason: event.reason, model, permissionMode });
+            if (outputFormat === "stream-json") {
+                console.log(JSON.stringify({ type: "turnStop", turnNumber: 0, reason: event.reason }));
+            }
             if (event.reason !== "completed") {
                 process.exitCode = 1;
             }
@@ -243,6 +281,164 @@ 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 = [];
+    let turnCounter = 0;
+    // Will be set to the current prompt id before each turn so hook_decision
+    // events can be demultiplexed by the client.
+    let activePromptId = "";
+    setHookDecisionObserver((n) => {
+        console.log(JSON.stringify({
+            id: activePromptId,
+            type: "hook_decision",
+            event: n.event,
+            tool: n.tool,
+            decision: n.decision,
+            reason: n.reason,
+        }));
+    });
+    // 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 = [];
+        const turnIdx = turnCounter++;
+        const turnNumber = String(turnIdx);
+        activePromptId = id;
+        emitHook("turnStart", {
+            turnNumber,
+            model,
+            provider: typeof config.provider === "string" ? config.provider : undefined,
+            permissionMode,
+        });
+        console.log(JSON.stringify({ id, type: "turnStart", turnNumber: turnIdx }));
+        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 }));
+                emitHook("turnStop", { turnNumber, turnReason: event.reason, model, permissionMode });
+                console.log(JSON.stringify({ id, type: "turnStop", turnNumber: turnIdx, 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 })

package/package.json

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