@zhijiewang/openharness 2.34.0 → 2.35.0

package/README.md

@@ -695,6 +695,17 @@ oh --model llamacpp/my-model
 oh models                    # list available models
 ```
 
+## ACP (Agent Client Protocol)
+
+Speak [Agent Client Protocol](https://agentclientprotocol.com/) over stdin/stdout so editors that support ACP — Zed, JetBrains via the ACP plugin, Cline, OpenCode — can drive openHarness as the underlying agent. No bespoke IDE extension required:
+
+```bash
+oh acp                                          # uses provider/model from .oh/config.yaml
+oh acp --provider anthropic --model claude-sonnet-4-6
+```
+
+Configure your editor's ACP integration to launch `oh acp` as the agent command. The session-update events (text chunks, tool calls, tool results) are translated automatically from openHarness's stream protocol; permission prompts currently use openHarness's own flow rather than the ACP `requestPermission` path (filed for follow-up). The `@agentclientprotocol/sdk` package is an `optionalDependency` — if it didn't install, `oh acp` exits with a clear install hint rather than silently failing.
+
 ## Auth
 
 Provider-agnostic credential management. Local LLMs (Ollama / llama.cpp / LM Studio) need no auth — configure them via `oh init`.

package/README.zh-CN.md

@@ -694,6 +694,17 @@ oh --model llamacpp/my-model
 oh models                    # 列出可用模型
 ```
 
+## ACP（Agent Client Protocol）
+
+通过 stdin/stdout 讲 [Agent Client Protocol](https://agentclientprotocol.com/)，让支持 ACP 的编辑器 —— Zed、通过 ACP 插件接入的 JetBrains、Cline、OpenCode 等 —— 把 openHarness 当作底层 agent 来驱动，无需为每个 IDE 单独写扩展：
+
+```bash
+oh acp                                          # 读取 .oh/config.yaml 的 provider/model
+oh acp --provider anthropic --model claude-sonnet-4-6
+```
+
+在编辑器的 ACP 集成里把 `oh acp` 配成 agent 启动命令即可。session-update 事件（文本块、工具调用、工具结果）由 openHarness 的流式协议自动翻译过去；权限确认目前仍走 openHarness 自己的流程，没有走 ACP 的 `requestPermission`（已记入后续跟进）。`@agentclientprotocol/sdk` 是 `optionalDependency` —— 如果没装上，`oh acp` 会带着清楚的安装提示退出，不会静默失败。
+
 ## 鉴权（Auth）
 
 提供商无关的凭据管理。本地 LLM（Ollama / llama.cpp / LM Studio）无需鉴权 —— 通过 `oh init` 配置即可。

package/dist/acp/agent.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ACP (Agent Client Protocol) bridge — exposes openHarness as an agent that
+ * Zed / JetBrains / Cursor / Cline can talk to via JSON-RPC over stdio.
+ *
+ * Spec: https://agentclientprotocol.com/
+ * SDK:  @agentclientprotocol/sdk (optional dependency)
+ *
+ * Responsibility split:
+ *   - This module implements the `Agent` interface from the SDK.
+ *   - The SDK handles JSON-RPC framing, schema validation, and notification
+ *     dispatch; we only own the OH ↔ ACP event translation.
+ *
+ * Event translation (the only interesting part of this file):
+ *
+ *   OH StreamEvent          →  ACP session/update
+ *   --------------------------- ------------------------------------------------
+ *   text_delta              →  agent_message_chunk { content: { type: text } }
+ *   thinking_delta          →  agent_thought_chunk { content: { type: text } }
+ *   tool_call_start         →  tool_call { status: pending, kind: <derived> }
+ *   tool_call_end           →  tool_call_update { status: completed, content }
+ *   tool_output_delta       →  tool_call_update { content: <appended> }
+ *   error                   →  end-of-turn with stopReason: refusal (logged)
+ *   turn_complete           →  prompt response: { stopReason: end_turn }
+ *
+ * What's NOT bridged in v2.35:
+ *   - permission_request → ACP requestPermission (uses OH's own permission flow today)
+ *   - cost_update        → ACP _meta passthrough (filed for follow-up)
+ *   - rate_limited       → currently surfaced via stderr only; an ACP
+ *                          session/update with retry hint is filed for follow-up.
+ *
+ * Why optional dep: the SDK ships ~750KB of generated zod schemas. Most OH
+ * users never hit the ACP path; they shouldn't pay that disk + import cost.
+ */
+import type { StreamEvent } from "../types/events.js";
+type AcpConnection = {
+    sessionUpdate: (params: unknown) => Promise<void>;
+};
+export type AcpAgentConfig = {
+    /** OH provider name: "anthropic", "openai", "ollama", … */
+    provider: string;
+    /** OH model identifier (e.g. "claude-sonnet-4-6") */
+    model: string;
+    /** Working directory (defaults to process.cwd()) */
+    cwd?: string;
+    /** Inject API key (otherwise resolved via OH's normal credential chain) */
+    apiKey?: string;
+};
+/**
+ * Translate one OH StreamEvent into zero-or-more ACP `session/update`
+ * notifications. Pure function — no I/O, no SDK dependency. This is the
+ * load-bearing piece that the rest of the bridge orchestrates.
+ *
+ * Returns an array because some OH events map to no ACP update (cost_update,
+ * turn_complete) and we always want a uniform shape for callers.
+ */
+export declare function bridgeStreamEventToAcp(event: StreamEvent, sessionId: string): Array<{
+    sessionId: string;
+    update: Record<string, unknown>;
+}>;
+/**
+ * Concatenate the text blocks of an ACP PromptRequest's `prompt` array into
+ * the single string our `OhAgent.run/stream` expects. Resource-link blocks
+ * surface as `[resource: <uri>]` markers so the model is aware of them but
+ * doesn't try to inline-include the content (the spec wants us to optionally
+ * `readTextFile`-fetch them; that's a v2.36 follow-up).
+ */
+export declare function extractPromptText(prompt: ReadonlyArray<{
+    type: string;
+    [key: string]: unknown;
+}>): string;
+/**
+ * Construct an ACP Agent wired to OH's `OhAgent` SDK class.
+ *
+ * The connection is the AgentSideConnection from the SDK; we pass it in so
+ * tests can stub it without loading the SDK.
+ */
+export declare function createAcpAgent(connection: AcpConnection, config: AcpAgentConfig): {
+    initialize(_params: unknown): Promise<unknown>;
+    newSession(_params: unknown): Promise<unknown>;
+    authenticate(_params: unknown): Promise<Record<string, never>>;
+    setSessionMode(_params: unknown): Promise<Record<string, never>>;
+    prompt(params: {
+        sessionId: string;
+        prompt: ReadonlyArray<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+    }): Promise<{
+        stopReason: "end_turn" | "cancelled" | "refusal";
+    }>;
+    cancel(params: {
+        sessionId: string;
+    }): Promise<void>;
+};
+export {};
+//# sourceMappingURL=agent.d.ts.map

package/dist/acp/agent.js

@@ -0,0 +1,246 @@
+/**
+ * ACP (Agent Client Protocol) bridge — exposes openHarness as an agent that
+ * Zed / JetBrains / Cursor / Cline can talk to via JSON-RPC over stdio.
+ *
+ * Spec: https://agentclientprotocol.com/
+ * SDK:  @agentclientprotocol/sdk (optional dependency)
+ *
+ * Responsibility split:
+ *   - This module implements the `Agent` interface from the SDK.
+ *   - The SDK handles JSON-RPC framing, schema validation, and notification
+ *     dispatch; we only own the OH ↔ ACP event translation.
+ *
+ * Event translation (the only interesting part of this file):
+ *
+ *   OH StreamEvent          →  ACP session/update
+ *   --------------------------- ------------------------------------------------
+ *   text_delta              →  agent_message_chunk { content: { type: text } }
+ *   thinking_delta          →  agent_thought_chunk { content: { type: text } }
+ *   tool_call_start         →  tool_call { status: pending, kind: <derived> }
+ *   tool_call_end           →  tool_call_update { status: completed, content }
+ *   tool_output_delta       →  tool_call_update { content: <appended> }
+ *   error                   →  end-of-turn with stopReason: refusal (logged)
+ *   turn_complete           →  prompt response: { stopReason: end_turn }
+ *
+ * What's NOT bridged in v2.35:
+ *   - permission_request → ACP requestPermission (uses OH's own permission flow today)
+ *   - cost_update        → ACP _meta passthrough (filed for follow-up)
+ *   - rate_limited       → currently surfaced via stderr only; an ACP
+ *                          session/update with retry hint is filed for follow-up.
+ *
+ * Why optional dep: the SDK ships ~750KB of generated zod schemas. Most OH
+ * users never hit the ACP path; they shouldn't pay that disk + import cost.
+ */
+import { Agent as OhAgent } from "../sdk/index.js";
+/**
+ * Translate one OH StreamEvent into zero-or-more ACP `session/update`
+ * notifications. Pure function — no I/O, no SDK dependency. This is the
+ * load-bearing piece that the rest of the bridge orchestrates.
+ *
+ * Returns an array because some OH events map to no ACP update (cost_update,
+ * turn_complete) and we always want a uniform shape for callers.
+ */
+export function bridgeStreamEventToAcp(event, sessionId) {
+    switch (event.type) {
+        case "text_delta":
+            return [
+                {
+                    sessionId,
+                    update: {
+                        sessionUpdate: "agent_message_chunk",
+                        content: { type: "text", text: event.content },
+                    },
+                },
+            ];
+        case "thinking_delta":
+            return [
+                {
+                    sessionId,
+                    update: {
+                        sessionUpdate: "agent_thought_chunk",
+                        content: { type: "text", text: event.content },
+                    },
+                },
+            ];
+        case "tool_call_start":
+            return [
+                {
+                    sessionId,
+                    update: {
+                        sessionUpdate: "tool_call",
+                        toolCallId: event.callId,
+                        title: event.toolName,
+                        kind: deriveToolKind(event.toolName),
+                        status: "pending",
+                    },
+                },
+            ];
+        case "tool_call_complete":
+            // OH separates "args known" (tool_call_complete) from "result known"
+            // (tool_call_end). ACP folds both into tool_call_update. Surface the
+            // arguments now so editors can render them while the tool runs.
+            return [
+                {
+                    sessionId,
+                    update: {
+                        sessionUpdate: "tool_call_update",
+                        toolCallId: event.callId,
+                        status: "in_progress",
+                        rawInput: event.arguments,
+                    },
+                },
+            ];
+        case "tool_call_end":
+            return [
+                {
+                    sessionId,
+                    update: {
+                        sessionUpdate: "tool_call_update",
+                        toolCallId: event.callId,
+                        status: event.isError ? "failed" : "completed",
+                        content: [
+                            {
+                                type: "content",
+                                content: { type: "text", text: event.output },
+                            },
+                        ],
+                    },
+                },
+            ];
+        // Everything else has no ACP equivalent in the v2.35 surface.
+        case "tool_output_delta":
+        case "permission_request":
+        case "ask_user":
+        case "cost_update":
+        case "turn_complete":
+        case "error":
+        case "rate_limited":
+            return [];
+    }
+}
+/**
+ * Map an OH tool name to an ACP tool kind. The kind drives editor UX —
+ * Zed colors "edit" tools differently from "read" or "execute" — so getting
+ * this approximately right is worth the if-ladder. Unknown tools fall back
+ * to "other" rather than guessing.
+ */
+function deriveToolKind(toolName) {
+    const name = toolName.toLowerCase();
+    if (name === "read" || name.endsWith("read") || name === "imageread")
+        return "read";
+    if (name === "edit" || name === "write" || name === "multiedit" || name === "notebookedit")
+        return "edit";
+    if (name === "bash" || name === "powershell" || name === "killprocess")
+        return "execute";
+    if (name === "glob" || name === "grep" || name === "ls")
+        return "search";
+    if (name === "webfetch" || name === "websearch" || name === "exasearch")
+        return "fetch";
+    if (name === "todowrite" || name === "memory")
+        return "think";
+    return "other";
+}
+/**
+ * Concatenate the text blocks of an ACP PromptRequest's `prompt` array into
+ * the single string our `OhAgent.run/stream` expects. Resource-link blocks
+ * surface as `[resource: <uri>]` markers so the model is aware of them but
+ * doesn't try to inline-include the content (the spec wants us to optionally
+ * `readTextFile`-fetch them; that's a v2.36 follow-up).
+ */
+export function extractPromptText(prompt) {
+    const parts = [];
+    for (const block of prompt) {
+        if (block.type === "text" && typeof block.text === "string") {
+            parts.push(block.text);
+        }
+        else if (block.type === "resource_link" && typeof block.uri === "string") {
+            parts.push(`[resource: ${block.uri}]`);
+        }
+        else if (block.type === "resource") {
+            // Embedded resource — we don't fetch the content here; just surface
+            // a reference so the model doesn't ignore the attachment.
+            const uri = block.resource?.uri;
+            parts.push(uri ? `[resource: ${uri}]` : "[embedded resource]");
+        }
+    }
+    return parts.join("\n\n");
+}
+/**
+ * Construct an ACP Agent wired to OH's `OhAgent` SDK class.
+ *
+ * The connection is the AgentSideConnection from the SDK; we pass it in so
+ * tests can stub it without loading the SDK.
+ */
+export function createAcpAgent(connection, config) {
+    const sessions = new Map();
+    return {
+        async initialize(_params) {
+            return {
+                // SDK's PROTOCOL_VERSION constant is 1 today; hardcoded so this
+                // module doesn't import the SDK at type-check time.
+                protocolVersion: 1,
+                agentCapabilities: {
+                    loadSession: false,
+                },
+            };
+        },
+        async newSession(_params) {
+            const sessionId = crypto.randomUUID();
+            const agent = new OhAgent({
+                provider: config.provider,
+                model: config.model,
+                ...(config.apiKey ? { apiKey: config.apiKey } : {}),
+                ...(config.cwd ? { cwd: config.cwd } : {}),
+                permissionMode: "trust",
+            });
+            sessions.set(sessionId, { abort: new AbortController(), agent });
+            return { sessionId };
+        },
+        async authenticate(_params) {
+            // OH resolves credentials from its own chain (env vars / keychain / config);
+            // we don't gate session creation on an explicit ACP authenticate call.
+            return {};
+        },
+        async setSessionMode(_params) {
+            // Modes (ask/architect/code) aren't exposed yet — return success so
+            // editors that try to set one don't error.
+            return {};
+        },
+        async prompt(params) {
+            const session = sessions.get(params.sessionId);
+            if (!session)
+                throw new Error(`Session ${params.sessionId} not found`);
+            // A new prompt cancels any prior in-flight prompt for this session.
+            session.abort.abort();
+            session.abort = new AbortController();
+            const promptText = extractPromptText(params.prompt);
+            try {
+                for await (const event of session.agent.stream(promptText)) {
+                    if (session.abort.signal.aborted)
+                        return { stopReason: "cancelled" };
+                    for (const update of bridgeStreamEventToAcp(event, params.sessionId)) {
+                        await connection.sessionUpdate(update);
+                    }
+                }
+                return { stopReason: "end_turn" };
+            }
+            catch (err) {
+                if (session.abort.signal.aborted)
+                    return { stopReason: "cancelled" };
+                // Surface unexpected errors as a refusal so the editor stops the spinner.
+                await connection.sessionUpdate({
+                    sessionId: params.sessionId,
+                    update: {
+                        sessionUpdate: "agent_message_chunk",
+                        content: { type: "text", text: `[agent error] ${err.message}` },
+                    },
+                });
+                return { stopReason: "refusal" };
+            }
+        },
+        async cancel(params) {
+            sessions.get(params.sessionId)?.abort.abort();
+        },
+    };
+}
+//# sourceMappingURL=agent.js.map

package/dist/acp/server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ACP server entry point — `oh acp`.
+ *
+ * Loads the optional `@agentclientprotocol/sdk` package, wires stdin/stdout
+ * via its ndJsonStream to the bridge in `agent.ts`, and runs until the
+ * client disconnects.
+ *
+ * Dies cleanly with an install hint if the SDK isn't available — unlike
+ * sandbox-runtime where missing-dep is a silent no-op, here the user
+ * explicitly invoked `oh acp` so a clear error is the right UX.
+ */
+import { type AcpAgentConfig } from "./agent.js";
+export declare function runAcpServer(config: AcpAgentConfig): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/acp/server.js

@@ -0,0 +1,46 @@
+/**
+ * ACP server entry point — `oh acp`.
+ *
+ * Loads the optional `@agentclientprotocol/sdk` package, wires stdin/stdout
+ * via its ndJsonStream to the bridge in `agent.ts`, and runs until the
+ * client disconnects.
+ *
+ * Dies cleanly with an install hint if the SDK isn't available — unlike
+ * sandbox-runtime where missing-dep is a silent no-op, here the user
+ * explicitly invoked `oh acp` so a clear error is the right UX.
+ */
+import { Readable, Writable } from "node:stream";
+import { createAcpAgent } from "./agent.js";
+export async function runAcpServer(config) {
+    let acp;
+    try {
+        acp = await import("@agentclientprotocol/sdk");
+    }
+    catch (err) {
+        process.stderr.write("ACP server requires @agentclientprotocol/sdk. Install with:\n  npm install -g @agentclientprotocol/sdk\nor reinstall openHarness — the package ships as an optionalDependency.\n");
+        process.stderr.write(`Original error: ${err.message}\n`);
+        process.exit(1);
+    }
+    // ACP wire framing: NDJSON over stdio. The SDK gives us a ready-made stream
+    // adapter; we just hand it our process pipes.
+    // ndJsonStream(input, output) — input is the AGENT's input (= stdin), output
+    // is the AGENT's output (= stdout). Names are direction-from-the-stream's
+    // perspective, which inverts the Node convention (stdin/stdout are named
+    // from the process's perspective). That's why this looks backwards.
+    const input = Writable.toWeb(process.stdout);
+    const output = Readable.toWeb(process.stdin);
+    const stream = acp.ndJsonStream(input, output);
+    // The SDK constructs the connection and wires our handlers. We wrap our
+    // bridge in a factory because the SDK passes the connection into it; we
+    // need the connection to send sessionUpdate notifications back. The
+    // returned object retains the wiring internally — we don't need to keep
+    // a reference, but we still construct it so the side effects happen.
+    void new acp.AgentSideConnection((conn) => createAcpAgent(conn, config), stream);
+    // Block until stdin closes (client disconnected). Without this the process
+    // would exit immediately after wiring.
+    await new Promise((resolve) => {
+        process.stdin.on("end", resolve);
+        process.stdin.on("close", resolve);
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/main.js

@@ -1078,6 +1078,28 @@ program
     }
     console.log();
 });
+// ── acp (Agent Client Protocol server) ──
+//
+// Speaks ACP (https://agentclientprotocol.com/) over stdin/stdout so editors
+// like Zed and JetBrains can drive openHarness as a coding agent. The SDK is
+// an optional dependency to keep the default install footprint small —
+// `oh acp` exits cleanly with an install hint if the SDK isn't present.
+program
+    .command("acp")
+    .description("Start an ACP (Agent Client Protocol) server over stdio. Usage: configure your editor (Zed/JetBrains/Cline) to launch `oh acp` as the agent command.")
+    .option("-m, --model <model>", "Model to use (defaults to .oh/config.yaml's model)")
+    .option("-p, --provider <provider>", "Provider name (defaults to .oh/config.yaml's provider)")
+    .action(async (opts) => {
+    const cfg = readOhConfig();
+    const model = opts.model ?? cfg?.model;
+    const provider = opts.provider ?? cfg?.provider;
+    if (!model || !provider) {
+        process.stderr.write("ACP server needs both a model and a provider. Pass --model and --provider, or run `oh init` first.\n");
+        process.exit(1);
+    }
+    const { runAcpServer } = await import("./acp/server.js");
+    await runAcpServer({ provider, model, cwd: process.cwd() });
+});
 /**
  * Run the interactive setup wizard. Used by both the `oh init` subcommand and
  * the `--init` / `--init-only` flag added to chat / run / session (audit B5).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhijiewang/openharness",
-  "version": "2.34.0",
+  "version": "2.35.0",
   "description": "Open-source terminal coding agent. Works with any LLM.",
   "type": "module",
   "bin": {
@@ -91,6 +91,7 @@
   },
   "homepage": "https://github.com/zhijiewong/openharness#readme",
   "optionalDependencies": {
+    "@agentclientprotocol/sdk": "^0.21.0",
     "@anthropic-ai/sandbox-runtime": "^0.0.49",
     "@napi-rs/keyring": "^1.2.0",
     "sharp": "^0.34.5"