@sohampatwardhan/kiro-mcp-server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Soham Patwardhan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,218 @@
-# Temporary Holding Version
+# Kiro MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/@sohampatwardhan/kiro-mcp-server.svg)](https://www.npmjs.com/package/@sohampatwardhan/kiro-mcp-server)
+[![CI](https://github.com/sohampatwardhan/kiro-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/sohampatwardhan/kiro-mcp-server/actions/workflows/ci.yml)
+
+MCP server that lets AI agents with an always-on computer (Grok Bot, Claude, Cursor, Codex, and other MCP clients) orchestrate [Kiro CLI V3](https://kiro.dev/docs/cli/v3.md) coding sessions through typed tools instead of shell commands. It is the Kiro sibling of [`claude-code-mcp-server`](https://github.com/sohampatwardhan/claude-code-mcp-server).
+
+> **Requires `kiro-cli` with the V3 engine, installed and signed in, on the machine that runs this server.**
+>
+> 1. Install it: `curl -fsSL https://cli.kiro.dev/install | bash` (or `brew install kiro-cli` on macOS).
+> 2. Sign in: run `kiro-cli login` in a terminal (`kiro-cli login --use-device-flow` on a machine without a browser).
+> 3. Trust each workspace once: run `kiro-cli --v3` in the folder and choose **Trust, continue** (see [Workspace trust](#workspace-trust)).
+>
+> Without the CLI, tools return `CLI_NOT_FOUND` with the install command, and the server prints the same warning on stderr at startup. A signed-out CLI gives `CLI_NOT_SIGNED_IN`. This server never logs in for you.
+
+The server drives Kiro three ways: one long-lived ACP host (`kiro-cli acp --agent-engine=v3 --auth-method=cli`, newline-delimited JSON-RPC) for sessions, prompts, streaming, permissions, and Kiro's extension methods; headless runs (`kiro-cli chat --v3 --no-interactive --output-format stream-json`) for fire-and-forget work; and a few fixed-argv subcommands (`whoami`, `settings`, `agent`, `mcp`, `powers`). It exposes 32 tools and one subscribable transcript resource. The full feature-parity matrix, with what is exposed, composed, gated, withheld, or impossible and why, is in [`.kiro/specs/kiro-v3-orchestration/requirements.md`](.kiro/specs/kiro-v3-orchestration/requirements.md#feature-parity-matrix).
+
+## Design
+
+- **Strict schemas, typed results.** Every tool has a strict input schema (`additionalProperties: false`) and an `outputSchema`, and returns `structuredContent`. Errors are `{ "error": { "code", "message", "details" } }` with a code from the [error table](#errors).
+- **No escape hatch.** No shell tool, no raw argv, no field that forwards free-form CLI flags, and no "send any ACP method" tool. Kiro commands that only exist in the terminal UI are mapped to typed tools, or listed as not possible.
+- **Fixed argv.** The only place `kiro-cli` argv is built is `src/argv.ts`. Values are attached as `--flag=value` or follow `--`; prompts go on stdin. The v2-only `--agent`, `--model`, `--effort`, and `--trust-*` flags are never passed to `acp`: agent mode, model, and effort are set through session options.
+- **Operator policy.** Kiro runs only inside `KIRO_MCP_ROOTS` (checked with `realpath`). Shell approvals, persistent consent, headless trust flags, and config writes each need an explicit opt-in.
+- **Bounded processes.** Every child is spawned detached in its own process group and tracked. Closing stdin, SIGINT, SIGTERM, or SIGHUP cancels running turns, closes the host's stdin, and stops every process group.
+- **In memory.** Event feeds, jobs, tangent trees, pending permissions, and queued prompts live in memory. The server never writes Kiro's session files. No telemetry; no tokens, `KIRO_API_KEY`, or authorization URLs in output or logs.
+
+## Prerequisites
+
+- Node.js 20 or later.
+- `kiro-cli` 2.37 or later with the V3 engine (`kiro-cli acp --agent-engine=v3` must start), signed in. Set `KIRO_BIN` when `kiro-cli` is not on the server's `PATH`.
+
+## Install
+
+```bash
+npx -y @sohampatwardhan/kiro-mcp-server@latest
+```
+
+### Claude Code
+
+```bash
+claude mcp add kiro -e KIRO_MCP_ROOTS=$HOME/code -- npx -y @sohampatwardhan/kiro-mcp-server@latest
+```
+
+### Cursor, Claude Desktop, and other JSON configs
+
+```json
+{
+  "mcpServers": {
+    "kiro": {
+      "command": "npx",
+      "args": ["-y", "@sohampatwardhan/kiro-mcp-server@latest"],
+      "env": { "KIRO_MCP_ROOTS": "/Users/me/code" }
+    }
+  }
+}
+```
+
+### Codex
+
+```toml
+[mcp_servers.kiro]
+command = "npx"
+args = ["-y", "@sohampatwardhan/kiro-mcp-server@latest"]
+env = { KIRO_MCP_ROOTS = "/home/me/code" }
+```
+
+## Install the skills
+
+The repository ships agent skills that teach agents when and how to use these tools: delegating a task to Kiro, choosing mode, model, effort, and permission handling, following a run live, collecting results and patches, and recovering from failures. Install them with the [skills CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add sohampatwardhan/kiro-mcp-server -g
+```
+
+Install one skill, or only for some agents:
+
+```bash
+npx skills add sohampatwardhan/kiro-mcp-server -g --skill kiro-orchestration
+npx skills add sohampatwardhan/kiro-mcp-server -g -a claude-code -a codex
+```
+
+Each skill's `SKILL.md` carries a SemVer `metadata.version`, checked in CI by `scripts/check-skill-versions.mjs`, and CI installs the skills from the checkout into a throwaway `HOME` to test this exact path.
+
+## Environment variables
+
+All are optional. An invalid value makes the server print the variable name and reason on stderr and exit with code 2. Booleans accept `1`, `true`, `yes`, `0`, `false`, `no`.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `KIRO_BIN` | `kiro-cli` | CLI path or name |
+| `KIRO_MCP_CWD` | process cwd | Default root when `KIRO_MCP_ROOTS` is unset |
+| `KIRO_MCP_ROOTS` | `KIRO_MCP_CWD` | Comma-separated absolute directories Kiro may run in. `/` is refused. The first is the ACP host's cwd |
+| `KIRO_MCP_PERMISSIONS` | `ask` | `ask` (the calling agent answers), `deny` (reject all), or `allow` (approve once; shell still follows `KIRO_MCP_ALLOW_SHELL`) |
+| `KIRO_MCP_PERMISSION_TIMEOUT_MS` | `600000` | Unanswered permissions are rejected after this long |
+| `KIRO_MCP_ALLOW_SHELL` | off | Lets shell-command requests be approved. Off: they are rejected at once |
+| `KIRO_MCP_ALLOW_PERSISTENT_CONSENT` | off | Allows `allow_always` answers |
+| `KIRO_MCP_HEADLESS_TRUST` | `none` | `tools` allows headless `trust_tools`; `all` also allows `trust_all_tools` |
+| `KIRO_MCP_ALLOW_TRUST_WORKSPACE` | off | Allows headless `trust_workspace` |
+| `KIRO_MCP_ALLOW_CONFIG_WRITES` | off | Allows agent, MCP config, settings, and powers writes |
+| `KIRO_MCP_CLI_TIMEOUT_MS` | `120000` | Subcommand timeout |
+| `KIRO_MCP_REQUEST_TIMEOUT_MS` | `120000` | ACP request timeout (prompts have none) |
+| `KIRO_MCP_HEADLESS_TIMEOUT_MS` | `3600000` | Headless job timeout; `timeout_s` may lower it |
+
+`KIRO_API_KEY`, when set in the server's environment, is inherited by headless runs only. No tool can read or set it.
+
+### Workspace trust
+
+ACP has no method for trusting a workspace. Until a folder is trusted, Kiro does not load its custom agents, steering, MCP servers, skills, or workflows, and asks before every shell and MCP call. Trust each root once: run `kiro-cli --v3` in the folder and choose **Trust, continue**. `kiro_status` reports the saved trust for every root (read-only, from Kiro's per-workspace permissions file) and warns for each untrusted one. Kiro never saves trust for your home directory.
+
+### Shell approvals
+
+Shell approvals are off by default, as in `claude-code-mcp-server`: Kiro's requests to run commands (including tests and builds) are rejected at once and recorded as `policy: "shell_disabled"`. To let the calling agent approve them one at a time, set `KIRO_MCP_ALLOW_SHELL=1`. To approve every non-shell request automatically as well, add `KIRO_MCP_PERMISSIONS=allow`.
+
+## Typical flow
+
+1. `kiro_status` checks the CLI, sign-in, V3 engine, trust, and policy.
+2. `kiro_session_new` (or `kiro_session_load`) attaches a session; `kiro_session_configure` picks mode (`vibe`, `plan`, `spec`, `quick-spec`, `bug-fix`, `autonomous`, or a custom agent), model, and effort.
+3. `kiro_prompt` sends a prompt and waits up to `wait_s`. If the turn is still running, poll `kiro_events` (or `kiro_stream_session`) with the returned cursor until the status is `completed`, `cancelled`, or `failed`.
+4. Answer `pending_permissions` with `kiro_permission_respond`. When the client supports MCP elicitation, the request is also shown to its user.
+5. Steer with `kiro_steer`, stop with `kiro_cancel`, branch with `kiro_session_fork` or `kiro_tangent`, and close with `kiro_session_close`.
+
+## Tool reference
+
+| Tool | What it does |
+| --- | --- |
+| `kiro_status` | CLI path and version, V3 engine, capabilities, sign-in (account type, email, profile), roots and trust, policy, log paths, optional diagnostics |
+| `kiro_usage` | Plan usage and credits (`_kiro/account/getUsage`), plus credits observed for a session |
+| `kiro_session_new` | New local or cloud session, with mode, model, effort, title |
+| `kiro_session_list` | Saved sessions by workspace or user scope, with source, title, and limit filters |
+| `kiro_session_load` | Resume a session by id, or the latest for a workspace, with replay |
+| `kiro_session_configure` | Mode, model, effort, other advertised options, title |
+| `kiro_session_state` | MCP servers, tools, steering, skills, powers, governance, agent errors, commands, modes, config, context, `/config` panel, models |
+| `kiro_session_history` | Paged transcript and rewind points |
+| `kiro_session_fork` | Fork, optionally at a user message (`/rewind`) |
+| `kiro_session_export` | Export to a file inside the roots |
+| `kiro_session_compact` | Compact an idle session's context |
+| `kiro_session_close` | Close a session (cancels its turn, rejects its permissions) |
+| `kiro_session_delete` | Delete a session from Kiro's store (`confirm: true`) |
+| `kiro_prompt` | Prompt with text, files, images, or an advertised command; wait or queue |
+| `kiro_events` | Cursor-based event feed for a session or headless job, with long-poll |
+| `kiro_steer` | Steer a running turn |
+| `kiro_cancel` | Cancel a running turn, or stop a headless job |
+| `kiro_permissions` | Pending permission requests |
+| `kiro_permission_respond` | Answer one with an offered option |
+| `kiro_tangent` | Branch, merge, and list tangents |
+| `kiro_specs` | List and read `.kiro/specs` documents with parsed tasks |
+| `kiro_memory` | List, read, create, update, delete memories; sync status |
+| `kiro_knowledge` | Knowledge base subcommands |
+| `kiro_code_intelligence` | Code intelligence subcommands |
+| `kiro_workflow` | Workflow recipes and runs |
+| `kiro_cloud_sources` | Connected source providers and repositories |
+| `kiro_run_headless` | Headless run as a job |
+| `kiro_agents` | List and validate custom agents; create, set default, upgrade (gated) |
+| `kiro_mcp_config` | List and status of MCP config; add HTTP servers and remove (gated) |
+| `kiro_settings` | List and get settings; set and delete (gated, sensitive keys withheld) |
+| `kiro_powers` | List powers; install and uninstall (gated) |
+| `kiro_stream_session` | Follow any session's transcript live with a cursor |
+
+Resource: `kiro-session://<session_id>/transcript` returns a session's newest events as JSON. Subscribe with `resources/subscribe` to get `notifications/resources/updated` within a second of new events.
+
+## Errors
+
+| Code | Meaning |
+| --- | --- |
+| `CLI_NOT_FOUND` | `kiro-cli` (or `KIRO_BIN`) is missing; the message has the install command |
+| `CLI_NOT_SIGNED_IN` | Kiro reports a missing login; run `kiro-cli login` |
+| `ENGINE_V3_UNAVAILABLE` | `kiro-cli acp --agent-engine=v3` did not initialize; names the CLI version and reason |
+| `HOST_EXITED` | The ACP host exited during the call; the session re-attaches on next use and the prompt is not resent |
+| `UNSUPPORTED_BY_KIRO` | Kiro does not advertise or implement the method or target |
+| `KIRO_ERROR` | Other Kiro JSON-RPC error; `details.kiro` has Kiro's code, message, and error type |
+| `KIRO_REFUSED` | Kiro answered `success: false` or refused for trust or access level |
+| `OUTPUT_PARSE_FAILED` | CLI or Kiro output could not be parsed |
+| `TIMEOUT` | A subcommand, request, or job passed its timeout; its process group was stopped |
+| `CLI_EXIT` | A subcommand exited nonzero; `details.cli` has cleaned output tails |
+| `PATH_OUTSIDE_ROOTS` | A path resolves outside `KIRO_MCP_ROOTS` |
+| `PATH_EXISTS` | Export destination exists and `overwrite` is not true |
+| `CONTENT_TOO_LARGE` | A file or image is too large, not UTF-8, or not an allowed image type |
+| `SESSION_NOT_FOUND` | The session is unknown to Kiro or not attached here |
+| `TURN_ACTIVE` | The session already has a running turn |
+| `NO_ACTIVE_TURN` | Steering needs a running turn |
+| `QUEUE_FULL` | Five prompts already wait for this session |
+| `VALUE_NOT_ADVERTISED` | Mode, option, value, command, or recipe input is not advertised; lists the allowed values |
+| `PERMISSION_NOT_FOUND` | The permission is not pending |
+| `OPTION_NOT_OFFERED` | The option id was not offered |
+| `PERSISTENT_CONSENT_DISABLED` | `allow_always` needs `KIRO_MCP_ALLOW_PERSISTENT_CONSENT` |
+| `SHELL_APPROVAL_DISABLED` | Shell approvals need `KIRO_MCP_ALLOW_SHELL` |
+| `HEADLESS_TRUST_DISABLED` | A headless trust flag is not allowed by the operator |
+| `CONFIG_WRITES_DISABLED` | Config writes need `KIRO_MCP_ALLOW_CONFIG_WRITES` |
+| `STDIO_SERVER_WITHHELD` | Stdio MCP servers run arbitrary commands and cannot be added |
+| `SETTING_WITHHELD` | The setting key is withheld |
+| `CONFIRMATION_REQUIRED` | The call needs `confirm: true` |
+| `JOB_NOT_FOUND` | Unknown or expired headless job |
+| `SPEC_NOT_FOUND` | The spec or document does not exist |
+| `TANGENT_NOT_FOUND` | Not part of a tangent tree, or no tangent with that name |
+| `INVALID_MERGE_TARGET` | The merge destination resolves to the tangent itself or nothing |
+| `NOTHING_TO_BRANCH` | The session has no messages yet |
+
+## Development
+
+```bash
+npm ci
+npm run build   # strict tsc is the static check
+npm test        # builds, then node --test against the fake kiro-cli
+```
+
+Tests never run a real `kiro-cli`: `test/fixtures/fake-kiro.mjs` stands in for it through `KIRO_BIN`. See [AGENTS.md](AGENTS.md) for the architecture and rules.
+
+## Releasing
+
+Bump `version` in `package.json`, merge, then push a matching tag (`git tag v0.1.0 && git push origin v0.1.0`). The release workflow checks the tag against `package.json`, builds, tests, publishes to npm with provenance through trusted publishing (GitHub OIDC, no `NPM_TOKEN`), creates a GitHub release, and mirrors the package to GitHub Packages.
+
+## Credits
+
+Inspired by [vanphappi/kiro-cli-mcp](https://github.com/vanphappi/kiro-cli-mcp). No code was copied.
+
+## License
+
+MIT

package/dist/src/acp/host.js

@@ -0,0 +1,279 @@
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { acpArgv } from "../argv.js";
+import { KILL_GRACE_MS, killGroup, track } from "../children.js";
+import { runCli } from "../cli.js";
+import { LIMITS } from "../config.js";
+import { ToolError } from "../errors.js";
+import { cleanTerminalText, tail } from "../parse.js";
+import { cliNotFoundMessage, isSignInError, parseVersion, signInMessage } from "../prereq.js";
+import { JsonRpcPeer, METHOD_NOT_FOUND, RpcClosedError, RpcError, RpcTimeoutError } from "./jsonrpc.js";
+/**
+ * Optional methods that work on Kiro CLI 2.37.1 without being advertised in
+ * `extensionMethods` (design Decision 6).
+ */
+export const KNOWN_UNADVERTISED = ["_kiro/account/getUsage", "_kiro/session/rename", "_session/steer"];
+/**
+ * The long-lived `kiro-cli acp --agent-engine=v3` child. Only this module
+ * writes to the host process. Started lazily; restarted on the next call
+ * after it exits. Each start bumps `generation`, so sessions can tell that
+ * they must be re-attached.
+ */
+export class AcpHost extends EventEmitter {
+    opts;
+    state = "stopped";
+    generation = 0;
+    capabilities = null;
+    initResult = null;
+    lastError = null;
+    child = null;
+    peer = null;
+    starting = null;
+    lastDownAt = 0;
+    stderrText = "";
+    droppedBefore = 0;
+    notificationHandlers = [];
+    anyHandlers = [];
+    requestHandlers = [];
+    constructor(opts) {
+        super();
+        this.opts = opts;
+    }
+    /** `agentCapabilities._meta.kiro` from the last initialize. */
+    get kiro() {
+        return this.capabilities?._meta?.kiro ?? {};
+    }
+    /** Lines dropped across every host generation (Requirement 5.7). */
+    get droppedLines() {
+        return this.droppedBefore + (this.peer?.droppedLines ?? 0);
+    }
+    onNotification(method, handler) {
+        this.notificationHandlers.push([method, handler]);
+        this.peer?.onNotification(method, handler);
+    }
+    onAnyNotification(handler) {
+        this.anyHandlers.push(handler);
+        this.peer?.onAnyNotification(handler);
+    }
+    onRequest(method, handler) {
+        this.requestHandlers.push([method, handler]);
+        this.peer?.onRequest(method, handler);
+    }
+    /** True for core ACP methods, advertised extension methods, and KNOWN_UNADVERTISED. */
+    supports(method) {
+        if (!method.startsWith("_"))
+            return true;
+        if (KNOWN_UNADVERTISED.includes(method))
+            return true;
+        return (this.kiro.extensionMethods ?? []).includes(method);
+    }
+    /** Start the host if it is not running. Concurrent callers share one start. */
+    ensureStarted() {
+        if (this.state === "ready" && this.peer !== null && !this.peer.closed)
+            return Promise.resolve();
+        if (this.starting !== null)
+            return this.starting;
+        this.starting = this.start().finally(() => {
+            this.starting = null;
+        });
+        return this.starting;
+    }
+    async start() {
+        const backoff = this.opts.restartBackoffMs ?? 250;
+        const wait = this.lastDownAt + backoff - Date.now();
+        if (wait > 0)
+            await new Promise((r) => setTimeout(r, wait));
+        this.state = "starting";
+        this.stderrText = "";
+        this.generation++;
+        const generation = this.generation;
+        let child;
+        try {
+            child = spawn(this.opts.bin, acpArgv(), {
+                cwd: this.opts.cwd,
+                stdio: ["pipe", "pipe", "pipe"],
+                shell: false,
+                detached: true,
+                windowsHide: true,
+                env: { ...(this.opts.env ?? process.env), NO_COLOR: "1" },
+            });
+        }
+        catch (err) {
+            throw this.fail(new ToolError("CLI_NOT_FOUND", cliNotFoundMessage(this.opts.bin), { reason: String(err) }));
+        }
+        track(child);
+        this.child = child;
+        child.stderr.on("data", (chunk) => {
+            this.stderrText = tail(this.stderrText + chunk.toString("utf8"), LIMITS.outputTailChars);
+        });
+        child.stdin.on("error", () => undefined);
+        const peer = new JsonRpcPeer(child.stdout, child.stdin, { maxLineBytes: LIMITS.maxLineBytes });
+        this.peer = peer;
+        for (const [method, handler] of this.requestHandlers)
+            peer.onRequest(method, handler);
+        for (const [method, handler] of this.notificationHandlers)
+            peer.onNotification(method, handler);
+        for (const handler of this.anyHandlers)
+            peer.onAnyNotification(handler);
+        let spawnFailure = null;
+        const spawnError = new Promise((_, reject) => {
+            child.once("error", (err) => {
+                spawnFailure =
+                    err.code === "ENOENT" || err.code === "EACCES"
+                        ? new ToolError("CLI_NOT_FOUND", cliNotFoundMessage(this.opts.bin))
+                        : new ToolError("ENGINE_V3_UNAVAILABLE", `failed to start kiro-cli acp: ${err.message}`);
+                reject(spawnFailure);
+                peer.close("spawn error");
+            });
+        });
+        spawnError.catch(() => undefined);
+        let exitedEarly = false;
+        const onDown = (reason) => {
+            if (this.generation !== generation)
+                return;
+            exitedEarly = this.state === "starting";
+            if (this.state === "ready") {
+                this.state = "exited";
+                this.lastDownAt = Date.now();
+                this.droppedBefore += peer.droppedLines;
+                this.emit("exited", generation, reason);
+            }
+        };
+        child.once("exit", (code, signal) => {
+            peer.close(`host exited (${code ?? signal})`);
+            onDown(`host exited with ${code ?? signal}`);
+        });
+        peer.onClose((reason) => {
+            onDown(reason);
+            // stdout closed while the process lives on: stop it so it does not linger. During
+            // stop() the host gets to drain its stdin (a final session/cancel) and exit on its own.
+            if (this.state !== "stopping" && child.exitCode === null && child.signalCode === null)
+                killGroup(child, "SIGTERM");
+        });
+        try {
+            const init = (await Promise.race([
+                peer.request("initialize", {
+                    protocolVersion: 1,
+                    clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
+                    clientInfo: { name: "kiro-mcp-server", version: this.opts.clientVersion ?? "0.0.0" },
+                }, this.opts.requestTimeoutMs),
+                spawnError,
+            ]));
+            if (init === null || typeof init !== "object")
+                throw new RpcError(-32603, "initialize returned no result");
+            this.initResult = init;
+            this.capabilities = init.agentCapabilities ?? {};
+            this.state = "ready";
+            this.lastError = null;
+            this.emit("started", generation);
+        }
+        catch (err) {
+            if (spawnFailure !== null)
+                throw this.fail(spawnFailure);
+            if (err instanceof ToolError)
+                throw this.fail(err);
+            // Let the exit (or stderr) land so the message can name the reason.
+            await new Promise((r) => setTimeout(r, exitedEarly ? 0 : 50));
+            killGroup(child, "SIGKILL");
+            const version = await this.cliVersion();
+            const reason = cleanTerminalText(this.stderrText).trim().split("\n").slice(-3).join(" ") || (err instanceof Error ? err.message : String(err));
+            throw this.fail(new ToolError("ENGINE_V3_UNAVAILABLE", `kiro-cli ${version ?? "(unknown version)"} could not start the V3 ACP engine: ${reason}`, {
+                cliVersion: version,
+                stderrTail: tail(cleanTerminalText(this.stderrText), 2_000),
+            }));
+        }
+    }
+    fail(err) {
+        this.state = "failed";
+        this.lastDownAt = Date.now();
+        this.lastError = err;
+        return err;
+    }
+    async cliVersion() {
+        try {
+            const result = await runCli(this.opts.bin, ["--version"], { timeoutMs: 10_000, cwd: this.opts.cwd, env: this.opts.env });
+            return parseVersion(result.stdout);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Send a request and map failures to tool errors: UNSUPPORTED_BY_KIRO for
+     * an unsupported optional method or method-not-found, CLI_NOT_SIGNED_IN for
+     * authentication errors, HOST_EXITED when the host goes away, TIMEOUT, and
+     * KIRO_ERROR with `details.kiro` otherwise. Params never appear in errors.
+     */
+    async call(method, params, opts = {}) {
+        if (!this.supports(method)) {
+            throw new ToolError("UNSUPPORTED_BY_KIRO", `Kiro does not advertise ${method}`, { method });
+        }
+        await this.ensureStarted();
+        const peer = this.peer;
+        if (peer === null)
+            throw new ToolError("HOST_EXITED", "the Kiro ACP host is not running");
+        const timeoutMs = opts.timeoutMs === undefined ? this.opts.requestTimeoutMs : opts.timeoutMs ?? undefined;
+        try {
+            return await peer.request(method, params, timeoutMs);
+        }
+        catch (err) {
+            throw mapRpcError(method, err);
+        }
+    }
+    notify(method, params) {
+        this.peer?.notify(method, params);
+    }
+    /** Close the host's stdin, then stop its process group if it does not exit. */
+    async stop() {
+        const child = this.child;
+        if (child === null) {
+            this.state = "stopped";
+            return;
+        }
+        this.state = "stopping";
+        const exited = new Promise((resolve) => {
+            if (child.exitCode !== null || child.signalCode !== null)
+                resolve();
+            else
+                child.once("exit", () => resolve());
+        });
+        try {
+            child.stdin.end();
+        }
+        catch {
+            // already closed
+        }
+        const timer = setTimeout(() => killGroup(child, "SIGTERM"), 1_000);
+        const killTimer = setTimeout(() => killGroup(child, "SIGKILL"), 1_000 + KILL_GRACE_MS);
+        await exited;
+        clearTimeout(timer);
+        clearTimeout(killTimer);
+        this.generation++;
+        this.peer?.close("server stopping");
+        this.child = null;
+        this.peer = null;
+        this.state = "stopped";
+    }
+}
+export function mapRpcError(method, err) {
+    if (err instanceof ToolError)
+        return err;
+    if (err instanceof RpcClosedError)
+        return new ToolError("HOST_EXITED", `the Kiro ACP host exited before ${method} answered`);
+    if (err instanceof RpcTimeoutError)
+        return new ToolError("TIMEOUT", err.message, { method });
+    if (err instanceof RpcError) {
+        const data = (typeof err.data === "object" && err.data !== null ? err.data : {});
+        const errorType = typeof data.errorType === "string" ? data.errorType : undefined;
+        const detail = typeof data.details === "string" && data.details.length <= 500 ? data.details : undefined;
+        const message = detail !== undefined && /^internal error$/i.test(err.message) ? detail : err.message;
+        const kiro = { code: err.code, message, ...(errorType !== undefined ? { errorType } : {}) };
+        if (err.code === METHOD_NOT_FOUND)
+            return new ToolError("UNSUPPORTED_BY_KIRO", `Kiro does not implement ${method}`, { method, kiro });
+        if ((errorType !== undefined && /auth/i.test(errorType)) || isSignInError(message)) {
+            return new ToolError("CLI_NOT_SIGNED_IN", signInMessage(), { kiro });
+        }
+        return new ToolError("KIRO_ERROR", `${method} failed: ${message}`, { method, kiro });
+    }
+    return new ToolError("KIRO_ERROR", `${method} failed: ${err instanceof Error ? err.message : String(err)}`, { method });
+}