@zhijiewang/openharness 2.17.0 → 2.19.0

package/README.md

@@ -23,6 +23,8 @@ AI coding agent in your terminal. Works with any LLM -- free local models or clo
 
 [![npm version](https://img.shields.io/npm/v/@zhijiewang/openharness)](https://www.npmjs.com/package/@zhijiewang/openharness) [![npm downloads](https://img.shields.io/npm/dm/@zhijiewang/openharness)](https://www.npmjs.com/package/@zhijiewang/openharness) [![license](https://img.shields.io/npm/l/@zhijiewang/openharness)](LICENSE) ![tests](https://img.shields.io/badge/tests-890-brightgreen) ![tools](https://img.shields.io/badge/tools-42-blue) ![Node.js 18+](https://img.shields.io/badge/node-18%2B-green) ![TypeScript](https://img.shields.io/badge/typescript-strict-blue) [![GitHub stars](https://img.shields.io/github/stars/zhijiewong/openharness)](https://github.com/zhijiewong/openharness) [![GitHub issues](https://img.shields.io/github/issues-raw/zhijiewong/openharness)](https://github.com/zhijiewong/openharness/issues) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen)](https://github.com/zhijiewong/openharness/pulls)
 
+**English** | [简体中文](README.zh-CN.md)
+
 ---
 
 ## Table of Contents
@@ -30,8 +32,8 @@ AI coding agent in your terminal. Works with any LLM -- free local models or clo
 - [Quick Start](#quick-start)
 - [Why OpenHarness?](#why-openharness)
 - [Terminal UI](#terminal-ui)
-- [Tools (35)](#tools-35)
-- [Slash Commands (33)](#slash-commands-33)
+- [Tools (43)](#tools-43)
+- [Slash Commands](#slash-commands)
 - [Permission Modes](#permission-modes)
 - [Hooks](#hooks)
 - [Checkpoints & Rewind](#checkpoints--rewind)
@@ -57,7 +59,9 @@ 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).
+**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-sdk` after the npm install (the PyPI distribution is `openharness-sdk` because the unqualified name is taken), then `from openharness import query`. See [`python/README.md`](python/README.md).
+
+**TypeScript SDK:** drive `oh` from Node.js (VS Code extensions, Electron apps, build scripts) with `@zhijiewang/openharness-sdk` — `npm install @zhijiewang/openharness-sdk`, then `import { query, OpenHarnessClient, tool } from "@zhijiewang/openharness-sdk"`. Mirrors the Python SDK surface (streaming events, stateful sessions, custom tools, permission callback, session resume). See [`packages/sdk/README.md`](packages/sdk/README.md).
 
 ```bash
 oh init                               # interactive setup wizard (provider + cybergotchi)
@@ -82,26 +86,6 @@ Ctrl+O                                # flush transcript to scrollback for revie
 
 Most AI coding agents are locked to one provider or cost $20+/month. OpenHarness works with any LLM -- run it free with Ollama on your own machine, or connect to any cloud API. Every AI edit is git-committed and reversible with `/undo`.
 
-|  | OpenHarness | Claude Code | Aider | OpenCode |
-|---|---|---|---|---|
-| Any LLM | Yes (Ollama, OpenAI, Anthropic, OpenRouter, any OpenAI-compatible) | Anthropic only | Yes | Yes |
-| Free local models | Ollama native | No | Yes | Yes |
-| Tools | 41 with permission gates | 43+ | File-focused | 20+ |
-| Permission modes | 7 (ask, trust, deny, acceptEdits, plan, auto, bypass) | 7 | Basic | Basic |
-| Git integration | Auto-commit + /undo + /rewind checkpoints | Yes | Deep git | Basic |
-| Slash commands | 42+ built-in | 80+ | Some | Some |
-| Headless/CI mode | `oh -p "prompt"` or `oh run --json` | Yes | Yes | Yes |
-| GitHub Action | Built-in PR review action | Yes | No | No |
-| Agent roles | 6 specializations (reviewer, tester, debugger...) | Yes | No | No |
-| Vim mode | hjkl, w/b/e, 0/$, x, d, i/a/I/A/o | Full vim | No | No |
-| Prompt caching | Anthropic cache_control | Yes | No | No |
-| Bash security | AST-based command analysis | AST analysis | No | No |
-| Companion | Cybergotchi virtual pet | Basic | No | No |
-| Terminal UI | Sequential renderer (Ink pattern) | React + Ink | Basic | BubbleTea |
-| Language | TypeScript | TypeScript | Python | Go |
-| License | MIT | Proprietary | Apache 2.0 | MIT |
-| Price | Free (BYOK) | $20+/month | Free (BYOK) | Free (BYOK) |
-
 ## Terminal UI
 
 OpenHarness features a sequential terminal renderer inspired by Ink/Claude Code's default mode. Completed messages flush to native scrollback (scrollable), while the live area (streaming, spinner, input) rewrites in-place using relative cursor movement.
@@ -160,12 +144,13 @@ statusLineFormat: '{model} │ {tokens} │ {cost} │ {ctx}'
 
 Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XXXX), `{ctx}` (context usage bar). Empty sections are automatically collapsed.
 
-## Tools (35)
+## Tools (43)
 
 | Tool | Risk | Description |
 |------|------|-------------|
 | **Core** | | |
 | Bash | high | Execute shell commands with live streaming output (AST safety analysis) |
+| PowerShell | high | Execute PowerShell commands (Windows-native scripting) |
 | Read | low | Read files with line ranges, PDF support |
 | ImageRead | low | Read images/PDFs for multimodal analysis |
 | Write | medium | Create or overwrite files |
@@ -185,6 +170,7 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | TaskGet | low | Get task details |
 | TaskStop | low | Stop a running task |
 | TaskOutput | low | Get task output |
+| TodoWrite | low | Manage session task checklist (Claude Code-compatible) |
 | **Agents** | | |
 | Agent | medium | Spawn a sub-agent (with role specialization) |
 | ParallelAgent | medium | Dispatch multiple agents with DAG dependencies |
@@ -194,9 +180,12 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | CronCreate | medium | Schedule recurring tasks |
 | CronDelete | medium | Remove scheduled tasks |
 | CronList | low | List all scheduled tasks |
+| ScheduleWakeup | low | Self-pace the next /loop iteration (cache-aware) |
 | **Planning** | | |
 | EnterPlanMode | low | Enter structured planning mode |
 | ExitPlanMode | low | Exit planning mode |
+| **Pipelines** | | |
+| Pipeline | medium | Run a sequence of tasks with output passed between steps |
 | **Code Intelligence** | | |
 | Diagnostics | low | LSP-based code diagnostics |
 | NotebookEdit | medium | Edit Jupyter notebooks |
@@ -204,17 +193,22 @@ Available variables: `{model}`, `{tokens}` (input↑ output↓), `{cost}` ($X.XX
 | Memory | low | Save/list/search persistent memories |
 | Skill | low | Invoke a skill from .oh/skills/ |
 | ToolSearch | low | Find tools by description |
+| SessionSearch | low | Search prior sessions for relevant context |
+| **MCP** | | |
+| ListMcpResources | low | List resources from connected MCP servers |
+| ReadMcpResource | low | Read a specific MCP resource by URI |
 | **Git Worktrees** | | |
 | EnterWorktree | medium | Create isolated git worktree |
 | ExitWorktree | medium | Remove a git worktree |
 | **Process** | | |
 | KillProcess | high | Stop processes by PID or name |
+| Monitor | medium | Run a background command and stream each output line back to the agent |
 
 Low-risk read-only tools auto-approve. Medium and high risk tools require confirmation in `ask` mode. Use `--trust` or `--auto` to skip prompts.
 
-## Slash Commands (33)
+## Slash Commands
 
-Type these during a chat session. Aliases: `/q` exit, `/h` help, `/c` commit, `/m` model, `/s` status.
+Over 80 commands are registered. The most-used ones are grouped below; see `/help` in-session for the full list. Aliases: `/q` exit, `/h` help, `/c` commit, `/m` model, `/s` status.
 
 **Session:**
 | Command | Description |
@@ -245,6 +239,8 @@ Type these during a chat session. Aliases: `/q` exit, `/h` help, `/c` commit, `/
 | `/files` | List files in context |
 | `/model <name>` | Switch model mid-session |
 | `/memory` | View and search memories |
+| `/doctor` | Run diagnostic health checks |
+| `/hooks` | List loaded hooks grouped by event |
 
 **Settings:**
 | Command | Description |
@@ -302,11 +298,29 @@ hooks:
     command: "scripts/cleanup.sh"
 ```
 
-**Event types:**
-- `sessionStart` — fires once when the session begins
-- `preToolUse` — fires before each tool call; **exit code 1 blocks the tool** and returns an error to the model
-- `postToolUse` — fires after each tool call completes
-- `sessionEnd` — fires when the session ends
+**Event types** (17 total):
+
+| Event | When it fires | Can block? |
+|-------|---------------|------------|
+| `sessionStart` | Session begins | — |
+| `sessionEnd` | Session ends | — |
+| `turnStart` | Top-level agent turn begins (after user prompt accepted) | — |
+| `turnStop` | Top-level agent turn ends (mirrors Claude Code's `Stop`) | — |
+| `userPromptSubmit` | Before user prompt reaches the LLM | yes — `decision: deny` |
+| `preToolUse` | Before each tool call | yes — exit code 1 / `decision: deny` |
+| `postToolUse` | After successful tool execution | — |
+| `postToolUseFailure` | After tool throws or returns `isError: true` | — |
+| `permissionRequest` | When a tool needs approval (between `preToolUse` and the prompt) | yes — `decision: allow\|deny\|ask` |
+| `fileChanged` | After a tool modifies a file | — |
+| `cwdChanged` | After working directory changes | — |
+| `subagentStart` | A sub-agent is spawned | — |
+| `subagentStop` | A sub-agent completes | — |
+| `preCompact` | Before conversation compaction | — |
+| `postCompact` | After conversation compaction | — |
+| `configChange` | `.oh/config.yaml` is modified during the session | — |
+| `notification` | A notification is dispatched | — |
+
+Live introspection: run `/hooks` in-session to see exactly which hooks are loaded, grouped by event.
 
 **Environment variables** available to hook scripts:
 
@@ -316,10 +330,16 @@ hooks:
 | `OH_TOOL_NAME` | Name of the tool being called (tool events only) |
 | `OH_TOOL_ARGS` | JSON-encoded tool arguments (tool events only) |
 | `OH_TOOL_OUTPUT` | JSON-encoded tool output (`postToolUse` only) |
+| `OH_TOOL_INPUT_JSON` | Full JSON tool input (tool events only) |
+| `OH_SESSION_ID` / `OH_MODEL` / `OH_PROVIDER` / `OH_PERMISSION_MODE` | Current session context |
+| `OH_COST` / `OH_TOKENS` | Running cost and token totals |
+| `OH_FILE_PATH` | Path that changed (`fileChanged` only) |
+| `OH_NEW_CWD` | New working directory (`cwdChanged` only) |
+| `OH_TURN_NUMBER` / `OH_TURN_REASON` | Turn boundary context (`turnStart` / `turnStop`) |
 
-Use `match` to restrict a hook to a specific tool name (e.g., `match: Bash` only triggers for the Bash tool).
+Use `match` to restrict a hook to a specific tool name (e.g., `match: Bash` only triggers for the Bash tool). Substring, glob (`Cron*`), and `/regex/flags` patterns are all supported.
 
-See [docs/hooks.md](docs/hooks.md) for the full event reference including the new `userPromptSubmit`, `permissionRequest`, and `postToolUseFailure` events.
+Set `jsonIO: true` on a `command` hook to opt into structured JSON I/O — the harness sends `{event, ...context}` on stdin and reads `{decision, reason, hookSpecificOutput}` from stdout. HTTP hooks accept the same response shape. See [docs/hooks.md](docs/hooks.md) for the full reference.
 
 ## Cybergotchi
 
@@ -517,6 +537,24 @@ cat error.log | oh run "what's wrong here?"
 git diff | oh run "review these changes"
 ```
 
+### Structured output with `--json-schema`
+
+Constrain the model's output to a JSON Schema. Useful for CI scripts that
+parse model output programmatically without regex heuristics:
+
+```bash
+oh -p "output {\"ok\": true, \"count\": 3} as JSON" \
+  --trust \
+  --json-schema '{"type":"object","properties":{"ok":{"type":"boolean"},"count":{"type":"integer"}},"required":["ok","count"]}'
+```
+
+Behavior:
+- stdout: the validated JSON (single line), only when it passes the schema.
+- stderr: structured errors on failure, plus the raw model output for debugging.
+- Exit codes: **0** valid, **2** malformed schema, **3** model output was not JSON, **4** JSON didn't match the schema.
+
+Supported keywords: `type`, `properties`, `required`, `items`, `enum`. For richer validation, pipe the output through a dedicated validator.
+
 ### GitHub Action for PR Review
 
 OpenHarness includes a built-in GitHub Action for automated code review:
@@ -608,6 +646,8 @@ provider: ollama
 model: llama3
 permissionMode: ask
 theme: dark
+language: zh-CN        # optional — respond in this language (code stays as-is)
+outputStyle: default   # optional — "default", "explanatory", "learning", or a custom name
 ```
 
 Then per-project configs only need what's different:
@@ -617,6 +657,27 @@ Then per-project configs only need what's different:
 model: codellama   # override just the model
 ```
 
+### Output Styles
+
+Swap the agent's personality without touching its core instructions. Built-ins:
+
+- **`default`** — standard software engineering assistant (no preface)
+- **`explanatory`** — adds an `## Insights` section after each task explaining *why* the agent made its choices
+- **`learning`** — leaves 1–3 `TODO(human)` markers at strategic points so you write the instructive parts yourself
+
+Create your own styles as markdown files with YAML frontmatter. Save to `.oh/output-styles/<name>.md` (project) or `~/.oh/output-styles/<name>.md` (user). Project shadows user shadows built-in.
+
+````markdown
+---
+name: code-review
+description: Focused code review mode
+---
+
+Review rigorously. For every function, ask: is the logic correct, is error handling complete, are there edge cases ignored?
+````
+
+Activate with `outputStyle: code-review` in `.oh/config.yaml`.
+
 ## Project Rules
 
 Create `.oh/RULES.md` in any repo (or run `oh init`):
@@ -706,7 +767,7 @@ Yes. Use `oh -p "prompt" --auto` for headless execution, or the built-in GitHub
 Yes. OpenHarness is language-agnostic — it reads, writes, and executes code in any language. Syntax highlighting covers 20+ languages.
 
 **How does it compare to Claude Code?**
-~95% feature parity for CLI use cases. Main advantage: works with ANY LLM (not just Anthropic). See the [comparison table](#why-openharness) above.
+~95% feature parity for CLI use cases. Main advantage: works with ANY LLM (not just Anthropic) and is MIT-licensed. See [Why OpenHarness?](#why-openharness) above.
 
 ## Install