pi-kiro-models

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

# pi-kiro-models

Bridge Kiro CLI's premium AI models into the [pi coding agent](https://github.com/earendil-works/pi-coding-agent) via the Agent Client Protocol (ACP).

![Status](https://img.shields.io/badge/status-chat%20%2B%20MCP%20passthrough-brightgreen)
![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux-lightgrey)
![Runtime](https://img.shields.io/badge/runtime-Node.js%2020%2B-green)

---

## Overview

[pi](https://github.com/earendil-works/pi-coding-agent) is a terminal-based AI coding agent. [Kiro](https://kiro.dev) is Amazon's AI coding agent that gives you access to 15 premium models (Claude Sonnet 5, Opus 4.8, DeepSeek V3.2, etc.) through a single subscription.

**This extension bridges Kiro's models into pi.** Once installed, you select a Kiro model in pi with `/model` and chat with it — token-by-token streaming, full conversation context, and the same workflow you use with any other provider.

### How it works

```
pi outer loop
  │ streamSimple + active extension catalog
  ├── loopback HTTP MCP (pi_host) ──► Kiro inner loop
  │                                  │ tools/call
  │                                  ▼
  └──── normal Pi tool call ◄── host handoff ──┘
```

1. pi loads the extension, which registers a `kiro` provider with the live model catalog.
2. On the first prompt, the extension writes the `pi-bridge` Kiro agent config, starts an authenticated `127.0.0.1` HTTP MCP adapter, and spawns `kiro-cli-chat acp`. The ACP `session/new` request retains configured stdio MCP servers and adds `pi_host`.
3. Each independent turn rebuilds the active extension-tool catalog. Catalog changes recreate only the internal Kiro session and replay Pi context.
4. Ordinary prompts render Pi's system prompt and transcript delta into `session/prompt`.
5. When Kiro calls a forwarded tool, the adapter suspends its HTTP request; Pi receives the original tool name as a normal tool call and runs its existing validation, hooks, UI, and result persistence.
6. The next Pi turn returns the recorded result to the waiting MCP request, so Kiro continues the original ACP prompt. Forwarded calls are serialized.

### Tools

Kiro still owns the inner agent loop, but forwarded extension calls execute through Pi's outer tool lifecycle. The bridged model sees three distinct tool classes:

1. **Kiro native tools** — `fs_read`, `fs_write`, `execute_bash`, `glob`, `grep`, `web_fetch`, and `web_search`.
2. **Configured Kiro MCP tools** — stdio servers from discovered `mcp.json` files remain direct Kiro MCP tools. See [MCP Tool Passthrough](#mcp-tool-passthrough).
3. **Host-executed Pi extension tools** — active extension-contributed tools are published through the authenticated `pi_host` loopback MCP adapter. Kiro calls the adapter, Pi executes the original tool with its normal validation, hooks, UI, and session recording, then the result returns to Kiro.

Pi built-in coding tools (`read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`) are intentionally excluded because Kiro already provides native equivalents. Forwarded calls are serialized. A blocked or failed Pi tool is returned to Kiro as an MCP error rather than a false success. Tool names that Kiro rejects receive deterministic aliases.

See [ADR 0001](https://github.com/yanralapdy/pi-kiro-models/blob/HEAD/docs/adr/0001-bridge-active-pi-extension-tools-through-host-execution.md) for the architecture decision.

---

## Features

- **15 models** from Kiro's catalog — Claude Sonnet 5, Opus 4.8/4.7/4.6/4.5, Sonnet 4.6/4.5/4, Haiku 4.5, DeepSeek V3.2, GLM-5, Qwen3 Coder Next, and more
- **Dynamic MCP tool passthrough** — every MCP server in your Kiro `mcp.json` is auto-forwarded to the bridged model. Add a server to `mcp.json`, restart pi, and its tools are callable — no bridge edits. See [MCP Tool Passthrough](#mcp-tool-passthrough).
- **Host-executed Pi extension tools** — active extension tools are discovered each turn and called through the authenticated loopback `pi_host` adapter.
- **Model routing via `session/set_model`** — pi's `/model` selection actually reaches Kiro (not just the `auto` default)
- **Token-by-token streaming** into pi's TUI
- **Full pi context passthrough** — `systemPrompt`, prior turns, tool calls, and tool results are rendered as a tagged transcript (`<pi-system-prompt>`, `<pi-transcript>`, `<user>`, `<assistant>`, `<tool_call>`, `<tool_result>`). Only the delta since the last send is forwarded per turn; Kiro's own session state persists prior turns.
- **Automatic process management** — spawns on first use, cleans up on pi exit, respawns if the child dies
- **Ctrl+C cancellation** — sends `session/cancel` to Kiro
- **No API key needed** — uses your existing Kiro CLI authentication (AWS IAM Identity Center)

---

## Stack

| Component | Technology |
|---|---|
| Runtime | Node.js 20+ (loaded by pi's jiti) |
| Language | TypeScript |
| Protocol | Agent Client Protocol (ACP) over stdio |
| Framing | NDJSON (newline-delimited JSON-RPC 2.0) |
| Transport | ACP NDJSON stdio plus authenticated loopback Streamable HTTP MCP |
| Authentication | Kiro CLI auth plus per-session random bearer token for `pi_host` |

---

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│ pi outer loop                                               │
│  streamKiro ── catalog + KiroToolCoordinator                │
│       │                                                     │
│       ├── 127.0.0.1:ephemeral /mcp (bearer token) ───────┐  │
│       │                                                    │  │
│       └── ACPClient NDJSON ── kiro-cli-chat acp             │  │
│                                      Kiro inner loop ◄──────┘  │
└─────────────────────────────────────────────────────────────┘
```

**Data flow per prompt:**

1. pi calls `streamSimple(model, context, options)`.
2. The extension discovers active extension metadata, excludes Pi built-ins, and starts/reuses the `pi_host` adapter plus Kiro ACP session.
3. The session retains configured stdio MCP servers and adds the adapter as an HTTP MCP server.
4. Text turns send only the transcript delta. A Kiro `tools/call` suspends its MCP HTTP response and emits a normal Pi `toolCall` event with the original Pi name.
5. Pi executes the tool and appends its authoritative `ToolResultMessage`. The next provider invocation resolves the suspended MCP request without sending another ACP prompt.
6. Kiro continues and streams `agent_message_chunk` notifications. Catalog changes recreate the disposable internal Kiro session before the next independent turn.
7. Kiro responds to `session/prompt` with `stopReason: "end_turn"`.
8. Extension pushes `done`, records `lastMessageCount` on the session, and ends the stream.

**Context passthrough limits:**

- pi's `systemPrompt` reaches the model as authoritative context (facts, conventions, project details) and is respected in the model's answers.
- Kiro's underlying agent has a fixed self-identity ("I'm Kiro") that its ACP `--agent` mode overlay does not override. Attempts to force identity change via pi's systemPrompt will be refused by the model. This is a Kiro-side limitation; pi's operational context still works.

---

## Models

All 15 models from the Kiro catalog:

| Model | Context | Notes |
|---|---|---|
| `auto` | 1M | Auto-routing |
| `claude-sonnet-5` | 1M | Experimental preview |
| `claude-opus-4.8` | 1M | |
| `claude-opus-4.7` | 1M | |
| `claude-opus-4.6` | 1M | |
| `claude-sonnet-4.6` | 1M | |
| `claude-opus-4.5` | 200K | |
| `claude-sonnet-4.5` | 200K | |
| `claude-sonnet-4` | 200K | |
| `claude-haiku-4.5` | 200K | Cheapest/fastest |
| `deepseek-3.2` | 164K | Experimental |
| `minimax-m2.5` | 196K | |
| `minimax-m2.1` | 196K | Experimental |
| `glm-5` | 200K | |
| `qwen3-coder-next` | 256K | Experimental, cheap |

---

## Prerequisites

- [pi coding agent](https://github.com/earendil-works/pi-coding-agent) installed (`pi` on PATH)
- [Kiro CLI](https://kiro.dev) installed (`kiro-cli-chat` available)
- Kiro CLI authenticated (`kiro-cli-chat whoami` shows your IAM user)
- An active Kiro subscription
- Node.js 20+ (bundled with pi's installer)

---

## Installation

### Method 1: Clone from GitHub

```bash
cd ~/.pi/agent/extensions/
git clone https://github.com/yanralapdy/pi-kiro-models.git kiro-provider
```

### Method 2: Symlink from a dev location

```bash
ln -s ~/sites/js/node/pi-kiro-models ~/.pi/agent/extensions/kiro-provider
```

### Method 3: Register in `settings.json`

If auto-discovery doesn't pick up the extension, add it explicitly to `~/.config/pi/agent/settings.json`:

```json
{
  "extensions": [
    "~/sites/js/node/pi-kiro-models/index.ts"
  ]
}
```

---

## Usage

```bash
pi
```

In pi, run:

```
/model
```

Scroll to the `kiro` provider. Select any model (e.g., `kiro/claude-haiku-4.5` for cheap/fast testing or `kiro/claude-sonnet-5` for premium quality).

Start chatting. Text streams token-by-token. Ctrl+C cancels.

---

## Host-executed Pi extension tools

The bridge advertises active extension-contributed tools through a short-lived `pi_host` Streamable HTTP MCP server. The server binds only to `127.0.0.1`, uses an ephemeral port and random bearer token, and accepts Kiro's missing `Origin` header while rejecting supplied untrusted origins.

On a forwarded call:

1. Kiro sends `tools/call` to `pi_host`.
2. Pi emits a normal `toolcall_start`/`toolcall_delta`/`toolcall_end` sequence using the original Pi name.
3. Pi's regular loop validates and executes the tool, including existing blockers and hooks.
4. The next Pi turn returns the recorded result to Kiro. Failures use MCP `isError: true`.

Only active extension tools are exposed. Built-in Pi coding tools are excluded, aliases are deterministic for incompatible names, and calls are serialized in v1. A changed active catalog is applied by recreating the internal Kiro session on the next independent turn.

## MCP Tool Passthrough

The bridge gives Kiro models access to [Model Context Protocol](https://modelcontextprotocol.io) servers. On each session it discovers the MCP servers configured for Kiro and forwards them two ways:

- **ACP `session/new` `mcpServers`** — connects the servers for the bridged ACP session (the mechanism that makes the tools callable).
- **`@server` entries in the generated `pi-bridge` agent config** — allows the servers' tools.

This is fully dynamic: add a server to any Kiro `mcp.json`, start a fresh pi session, and the model can call its tools. No changes to this extension are needed for new tools.

### Where servers are read from

Discovered and unioned by name (later overrides earlier, so a workspace entry overrides a global one):

1. `~/.config/kiro/settings/mcp.json` (global)
2. `~/.kiro/settings/mcp.json` (global)
3. `<cwd>/.kiro/settings/mcp.json` (per-project)

Only **stdio** (command-based) servers are forwarded. HTTP/SSE (`url`) servers are currently skipped.

### Register a server

Use the Kiro CLI (writes global config unless run inside a project, which writes the workspace config):

```bash
# stdio server on PATH or by absolute path
kiro-cli-chat mcp add --name my-tool --command /absolute/path/to/my-mcp-server

# with arguments and environment variables
kiro-cli-chat mcp add --name notion \
  --command npx --args "-y,@notionhq/notion-mcp-server" \
  --env NOTION_TOKEN=secret
```

Or edit `mcp.json` directly:

```json
{
  "mcpServers": {
    "my-tool": {
      "command": "/absolute/path/to/my-mcp-server",
      "args": [],
      "env": {}
    }
  }
}
```

Then start a fresh pi session. On startup you'll see the servers being forwarded:

```
[kiro-provider] Wrote Kiro agent config at ~/.config/kiro/agents/pi-bridge.json (mcp: notion, my-tool)
[kiro-provider] Forwarding 2 MCP server(s) to Kiro: notion, my-tool
```

Ask the model to call one of the server's tools to confirm.

### Verify

```
# in pi, with a Kiro model selected
call the list_projects tool          # example: codebase-memory-mcp
```

Or test the underlying agent directly, bypassing pi:

```bash
kiro-cli-chat chat --agent pi-bridge --no-interactive --trust-all-tools \
  "Call the list_projects tool and paste its output."
```

### Notes

- The `pi-bridge` agent config at `~/.config/kiro/agents/pi-bridge.json` is **generated** — it's regenerated each session from your `mcp.json`. Don't hand-edit it; edit `mcp.json` instead.
- Servers with `"disabled": true` in `mcp.json` are skipped.
- Server env values are copied into the ACP session config; treat the Kiro config tree as you would any file holding secrets.

---

## Testing

Test scripts in `test/`:

```bash
# ACP framing with a mock echo process
jiti test/framing.test.ts

# Active extension catalog and aliases
jiti test/catalog.test.ts

# Authenticated loopback MCP adapter
jiti test/tool-bridge.test.ts

# Existing configured stdio MCP discovery regression
jiti test/mcp-discovery.test.ts

# Suspended Kiro-to-Pi handoff state machine
jiti test/tool-coordinator.test.ts

# Text streaming + Ctrl+C abort
jiti test/stream.test.ts
jiti test/abort.test.ts

# Respawn after external kill
jiti test/lifecycle-cleanup.test.ts

# Transcript rendering + delta-send prompt building
jiti test/transcript.test.ts

# Authenticated Kiro HTTP MCP wire probe (requires Kiro auth)
KIRO_HTTP_MCP_PROBE=1 jiti test/http-mcp-probe.test.ts

# End-to-end multi-turn context passthrough (requires Kiro auth)
jiti test/context.test.ts
```

Run with pi's bundled jiti:

```bash
/Users/tnkapdy/.nvm/versions/node/v24.17.0/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/.bin/jiti test/framing.test.ts
```

---

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| `[kiro-provider] Extension loaded` not in output | Extension not discovered | Add path to `settings.json` → `extensions` |
| `baseUrl is required` error | Missing `baseUrl` in provider config | Update to latest version |
| `Provider kiro: "baseUrl" is required when defining models` | Same as above | Same |
| `spawn ~/.local/bin/kiro-cli-chat ENOENT` | Kiro CLI not installed or wrong path | Set `KIRO_CLI_CHAT` env var to absolute path |
| `Authentication failed` | Kiro not logged in | Run `kiro-cli-chat login` |
| Text doesn't stream, hangs for 30s | Kiro backend slow or network issue | Retry; check `kiro-cli-chat whoami` |
| Orphaned `kiro-cli-chat` processes after pi exit | Process exit handler not firing | Report an issue; manually `pkill -f kiro-cli-chat` |
| Model self-identifies as "Kiro" not pi | Kiro's built-in identity system prompt overrides `pi-bridge` mode overlay | Expected. pi's `systemPrompt` still delivers factual context (project name, tools, conventions). Identity swap is a Kiro-side limitation. |
| Selecting different `kiro/*` models has no effect | `session/set_model` failed silently | Check `stderr` for `session/set_model failed`; verify model id is in the [Kiro model list](#models); ensure Kiro subscription includes the model |
| pi's `systemPrompt` seems ignored | pi-bridge Kiro agent missing or stale | Delete `~/.config/kiro/agents/pi-bridge.json` and let the extension recreate it on the next run |
| MCP tool not available to the model | Server not in a discovered `mcp.json`, is `disabled`, or is a `url` (HTTP/SSE) server | Add it to a [discovered `mcp.json`](#where-servers-are-read-from) as a stdio (`command`) server; check startup log for `Forwarding N MCP server(s)`; start a fresh session |
| MCP server registered but tools still missing | Session started before the server was added | Restart pi — servers are forwarded at session creation |
| Host extension tool is missing | Tool is inactive, built-in, or catalog refresh is pending | Confirm the extension is active; start a new independent turn and check the catalog-change diagnostic |
| Forwarded call is blocked or fails | Pi's normal tool blocker/validation rejected it | Read the returned tool error; Kiro can recover, but the bridge never bypasses Pi policy |
| Kiro cannot connect to `pi_host` | Adapter stopped with the ACP child or the session was replaced | Retry the turn; the bridge recreates the adapter with a new token and port |

---

## Roadmap

- [x] V1: Chat-only bridge with all 15 models
- [x] MCP tool passthrough — dynamically forward configured stdio MCP servers to the bridged model
- [x] Host-executed active Pi extension tools via authenticated loopback HTTP MCP
- [ ] HTTP/SSE MCP servers in the user's `mcp.json` (the existing config reader remains stdio-only)
- [ ] Multi-session support (concurrent pi processes)
- [ ] Image input (Kiro ACP supports images; pi has ImageContent)

---

## Legal & Compliance

- This extension uses ACP, an official open protocol documented at [agentclientprotocol.com](https://agentclientprotocol.com)
- Kiro CLI explicitly supports ACP for third-party integrations (see [kiro.dev/docs/cli/acp](https://kiro.dev/docs/cli/acp))
- No reverse engineering or unofficial APIs used
- Requires valid Kiro subscription

---

## License

MIT

---

## Contributing

Issues and PRs welcome. Test with Kiro CLI v2.5.0+.

pi-kiro-models

Bridge Kiro CLI's premium AI models into the pi coding agent via the Agent Client Protocol (ACP).

Overview

pi is a terminal-based AI coding agent. Kiro is Amazon's AI coding agent that gives you access to 15 premium models (Claude Sonnet 5, Opus 4.8, DeepSeek V3.2, etc.) through a single subscription.

This extension bridges Kiro's models into pi. Once installed, you select a Kiro model in pi with /model and chat with it — token-by-token streaming, full conversation context, and the same workflow you use with any other provider.

How it works

pi outer loop
  │ streamSimple + active extension catalog
  ├── loopback HTTP MCP (pi_host) ──► Kiro inner loop
  │                                  │ tools/call
  │                                  ▼
  └──── normal Pi tool call ◄── host handoff ──┘

pi loads the extension, which registers a kiro provider with the live model catalog.
On the first prompt, the extension writes the pi-bridge Kiro agent config, starts an authenticated 127.0.0.1 HTTP MCP adapter, and spawns kiro-cli-chat acp. The ACP session/new request retains configured stdio MCP servers and adds pi_host.
Each independent turn rebuilds the active extension-tool catalog. Catalog changes recreate only the internal Kiro session and replay Pi context.
Ordinary prompts render Pi's system prompt and transcript delta into session/prompt.
When Kiro calls a forwarded tool, the adapter suspends its HTTP request; Pi receives the original tool name as a normal tool call and runs its existing validation, hooks, UI, and result persistence.
The next Pi turn returns the recorded result to the waiting MCP request, so Kiro continues the original ACP prompt. Forwarded calls are serialized.

Tools

Kiro still owns the inner agent loop, but forwarded extension calls execute through Pi's outer tool lifecycle. The bridged model sees three distinct tool classes:

Kiro native tools — fs_read, fs_write, execute_bash, glob, grep, web_fetch, and web_search.
Configured Kiro MCP tools — stdio servers from discovered mcp.json files remain direct Kiro MCP tools. See MCP Tool Passthrough.
Host-executed Pi extension tools — active extension-contributed tools are published through the authenticated pi_host loopback MCP adapter. Kiro calls the adapter, Pi executes the original tool with its normal validation, hooks, UI, and session recording, then the result returns to Kiro.

Pi built-in coding tools (read, write, edit, bash, grep, find, and ls) are intentionally excluded because Kiro already provides native equivalents. Forwarded calls are serialized. A blocked or failed Pi tool is returned to Kiro as an MCP error rather than a false success. Tool names that Kiro rejects receive deterministic aliases.

See ADR 0001 for the architecture decision.

Features

15 models from Kiro's catalog — Claude Sonnet 5, Opus 4.8/4.7/4.6/4.5, Sonnet 4.6/4.5/4, Haiku 4.5, DeepSeek V3.2, GLM-5, Qwen3 Coder Next, and more
Dynamic MCP tool passthrough — every MCP server in your Kiro mcp.json is auto-forwarded to the bridged model. Add a server to mcp.json, restart pi, and its tools are callable — no bridge edits. See MCP Tool Passthrough.
Host-executed Pi extension tools — active extension tools are discovered each turn and called through the authenticated loopback pi_host adapter.
Model routing via session/set_model — pi's /model selection actually reaches Kiro (not just the auto default)
Token-by-token streaming into pi's TUI
Full pi context passthrough — systemPrompt, prior turns, tool calls, and tool results are rendered as a tagged transcript (<pi-system-prompt>, <pi-transcript>, <user>, <assistant>, <tool_call>, <tool_result>). Only the delta since the last send is forwarded per turn; Kiro's own session state persists prior turns.
Automatic process management — spawns on first use, cleans up on pi exit, respawns if the child dies
Ctrl+C cancellation — sends session/cancel to Kiro
No API key needed — uses your existing Kiro CLI authentication (AWS IAM Identity Center)

Stack

Component	Technology
Runtime	Node.js 20+ (loaded by pi's jiti)
Language	TypeScript
Protocol	Agent Client Protocol (ACP) over stdio
Framing	NDJSON (newline-delimited JSON-RPC 2.0)
Transport	ACP NDJSON stdio plus authenticated loopback Streamable HTTP MCP
Authentication	Kiro CLI auth plus per-session random bearer token for `pi_host`

Architecture

┌─────────────────────────────────────────────────────────────┐
│ pi outer loop                                               │
│  streamKiro ── catalog + KiroToolCoordinator                │
│       │                                                     │
│       ├── 127.0.0.1:ephemeral /mcp (bearer token) ───────┐  │
│       │                                                    │  │
│       └── ACPClient NDJSON ── kiro-cli-chat acp             │  │
│                                      Kiro inner loop ◄──────┘  │
└─────────────────────────────────────────────────────────────┘

Data flow per prompt:

pi calls streamSimple(model, context, options).
The extension discovers active extension metadata, excludes Pi built-ins, and starts/reuses the pi_host adapter plus Kiro ACP session.
The session retains configured stdio MCP servers and adds the adapter as an HTTP MCP server.
Text turns send only the transcript delta. A Kiro tools/call suspends its MCP HTTP response and emits a normal Pi toolCall event with the original Pi name.
Pi executes the tool and appends its authoritative ToolResultMessage. The next provider invocation resolves the suspended MCP request without sending another ACP prompt.
Kiro continues and streams agent_message_chunk notifications. Catalog changes recreate the disposable internal Kiro session before the next independent turn.
Kiro responds to session/prompt with stopReason: "end_turn".
Extension pushes done, records lastMessageCount on the session, and ends the stream.

Context passthrough limits:

pi's systemPrompt reaches the model as authoritative context (facts, conventions, project details) and is respected in the model's answers.
Kiro's underlying agent has a fixed self-identity ("I'm Kiro") that its ACP --agent mode overlay does not override. Attempts to force identity change via pi's systemPrompt will be refused by the model. This is a Kiro-side limitation; pi's operational context still works.

Models

All 15 models from the Kiro catalog:

Model	Context	Notes
`auto`	1M	Auto-routing
`claude-sonnet-5`	1M	Experimental preview
`claude-opus-4.8`	1M
`claude-opus-4.7`	1M
`claude-opus-4.6`	1M
`claude-sonnet-4.6`	1M
`claude-opus-4.5`	200K
`claude-sonnet-4.5`	200K
`claude-sonnet-4`	200K
`claude-haiku-4.5`	200K	Cheapest/fastest
`deepseek-3.2`	164K	Experimental
`minimax-m2.5`	196K
`minimax-m2.1`	196K	Experimental
`glm-5`	200K
`qwen3-coder-next`	256K	Experimental, cheap

Prerequisites

pi coding agent installed (pi on PATH)
Kiro CLI installed (kiro-cli-chat available)
Kiro CLI authenticated (kiro-cli-chat whoami shows your IAM user)
An active Kiro subscription
Node.js 20+ (bundled with pi's installer)

Installation

Method 1: Clone from GitHub

cd ~/.pi/agent/extensions/
git clone https://github.com/yanralapdy/pi-kiro-models.git kiro-provider

Method 2: Symlink from a dev location

ln -s ~/sites/js/node/pi-kiro-models ~/.pi/agent/extensions/kiro-provider

Method 3: Register in `settings.json`

If auto-discovery doesn't pick up the extension, add it explicitly to ~/.config/pi/agent/settings.json:

{
  "extensions": [
    "~/sites/js/node/pi-kiro-models/index.ts"
  ]
}

Usage

pi

In pi, run:

/model

Scroll to the kiro provider. Select any model (e.g., kiro/claude-haiku-4.5 for cheap/fast testing or kiro/claude-sonnet-5 for premium quality).

Start chatting. Text streams token-by-token. Ctrl+C cancels.

Host-executed Pi extension tools

The bridge advertises active extension-contributed tools through a short-lived pi_host Streamable HTTP MCP server. The server binds only to 127.0.0.1, uses an ephemeral port and random bearer token, and accepts Kiro's missing Origin header while rejecting supplied untrusted origins.

On a forwarded call:

Kiro sends tools/call to pi_host.
Pi emits a normal toolcall_start/toolcall_delta/toolcall_end sequence using the original Pi name.
Pi's regular loop validates and executes the tool, including existing blockers and hooks.
The next Pi turn returns the recorded result to Kiro. Failures use MCP isError: true.

Only active extension tools are exposed. Built-in Pi coding tools are excluded, aliases are deterministic for incompatible names, and calls are serialized in v1. A changed active catalog is applied by recreating the internal Kiro session on the next independent turn.

MCP Tool Passthrough

The bridge gives Kiro models access to Model Context Protocol servers. On each session it discovers the MCP servers configured for Kiro and forwards them two ways:

ACP session/new mcpServers — connects the servers for the bridged ACP session (the mechanism that makes the tools callable).
@server entries in the generated pi-bridge agent config — allows the servers' tools.

This is fully dynamic: add a server to any Kiro mcp.json, start a fresh pi session, and the model can call its tools. No changes to this extension are needed for new tools.

Where servers are read from

Discovered and unioned by name (later overrides earlier, so a workspace entry overrides a global one):

~/.config/kiro/settings/mcp.json (global)
~/.kiro/settings/mcp.json (global)
<cwd>/.kiro/settings/mcp.json (per-project)

Only stdio (command-based) servers are forwarded. HTTP/SSE (url) servers are currently skipped.

Register a server

Use the Kiro CLI (writes global config unless run inside a project, which writes the workspace config):

# stdio server on PATH or by absolute path
kiro-cli-chat mcp add --name my-tool --command /absolute/path/to/my-mcp-server

# with arguments and environment variables
kiro-cli-chat mcp add --name notion \
  --command npx --args "-y,@notionhq/notion-mcp-server" \
  --env NOTION_TOKEN=secret

Or edit mcp.json directly:

{
  "mcpServers": {
    "my-tool": {
      "command": "/absolute/path/to/my-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Then start a fresh pi session. On startup you'll see the servers being forwarded:

[kiro-provider] Wrote Kiro agent config at ~/.config/kiro/agents/pi-bridge.json (mcp: notion, my-tool)
[kiro-provider] Forwarding 2 MCP server(s) to Kiro: notion, my-tool

Ask the model to call one of the server's tools to confirm.

Verify

# in pi, with a Kiro model selected
call the list_projects tool          # example: codebase-memory-mcp

Or test the underlying agent directly, bypassing pi:

kiro-cli-chat chat --agent pi-bridge --no-interactive --trust-all-tools \
  "Call the list_projects tool and paste its output."

Notes

The pi-bridge agent config at ~/.config/kiro/agents/pi-bridge.json is generated — it's regenerated each session from your mcp.json. Don't hand-edit it; edit mcp.json instead.
Servers with "disabled": true in mcp.json are skipped.
Server env values are copied into the ACP session config; treat the Kiro config tree as you would any file holding secrets.

Testing

Test scripts in test/:

# ACP framing with a mock echo process
jiti test/framing.test.ts

# Active extension catalog and aliases
jiti test/catalog.test.ts

# Authenticated loopback MCP adapter
jiti test/tool-bridge.test.ts

# Existing configured stdio MCP discovery regression
jiti test/mcp-discovery.test.ts

# Suspended Kiro-to-Pi handoff state machine
jiti test/tool-coordinator.test.ts

# Text streaming + Ctrl+C abort
jiti test/stream.test.ts
jiti test/abort.test.ts

# Respawn after external kill
jiti test/lifecycle-cleanup.test.ts

# Transcript rendering + delta-send prompt building
jiti test/transcript.test.ts

# Authenticated Kiro HTTP MCP wire probe (requires Kiro auth)
KIRO_HTTP_MCP_PROBE=1 jiti test/http-mcp-probe.test.ts

# End-to-end multi-turn context passthrough (requires Kiro auth)
jiti test/context.test.ts

Run with pi's bundled jiti:

/Users/tnkapdy/.nvm/versions/node/v24.17.0/lib/node_modules/@earendil-works/pi-coding-agent/node_modules/.bin/jiti test/framing.test.ts

Troubleshooting

Symptom	Cause	Fix
`[kiro-provider] Extension loaded` not in output	Extension not discovered	Add path to `settings.json` → `extensions`
`baseUrl is required` error	Missing `baseUrl` in provider config	Update to latest version
`Provider kiro: "baseUrl" is required when defining models`	Same as above	Same
`spawn ~/.local/bin/kiro-cli-chat ENOENT`	Kiro CLI not installed or wrong path	Set `KIRO_CLI_CHAT` env var to absolute path
`Authentication failed`	Kiro not logged in	Run `kiro-cli-chat login`
Text doesn't stream, hangs for 30s	Kiro backend slow or network issue	Retry; check `kiro-cli-chat whoami`
Orphaned `kiro-cli-chat` processes after pi exit	Process exit handler not firing	Report an issue; manually `pkill -f kiro-cli-chat`
Model self-identifies as "Kiro" not pi	Kiro's built-in identity system prompt overrides `pi-bridge` mode overlay	Expected. pi's `systemPrompt` still delivers factual context (project name, tools, conventions). Identity swap is a Kiro-side limitation.
Selecting different `kiro/*` models has no effect	`session/set_model` failed silently	Check `stderr` for `session/set_model failed`; verify model id is in the Kiro model list; ensure Kiro subscription includes the model
pi's `systemPrompt` seems ignored	pi-bridge Kiro agent missing or stale	Delete `~/.config/kiro/agents/pi-bridge.json` and let the extension recreate it on the next run
MCP tool not available to the model	Server not in a discovered `mcp.json`, is `disabled`, or is a `url` (HTTP/SSE) server	Add it to a discovered `mcp.json` as a stdio (`command`) server; check startup log for `Forwarding N MCP server(s)`; start a fresh session
MCP server registered but tools still missing	Session started before the server was added	Restart pi — servers are forwarded at session creation
Host extension tool is missing	Tool is inactive, built-in, or catalog refresh is pending	Confirm the extension is active; start a new independent turn and check the catalog-change diagnostic
Forwarded call is blocked or fails	Pi's normal tool blocker/validation rejected it	Read the returned tool error; Kiro can recover, but the bridge never bypasses Pi policy
Kiro cannot connect to `pi_host`	Adapter stopped with the ACP child or the session was replaced	Retry the turn; the bridge recreates the adapter with a new token and port

Roadmap

V1: Chat-only bridge with all 15 models
MCP tool passthrough — dynamically forward configured stdio MCP servers to the bridged model
Host-executed active Pi extension tools via authenticated loopback HTTP MCP
HTTP/SSE MCP servers in the user's mcp.json (the existing config reader remains stdio-only)
Multi-session support (concurrent pi processes)
Image input (Kiro ACP supports images; pi has ImageContent)

Legal & Compliance

This extension uses ACP, an official open protocol documented at agentclientprotocol.com
Kiro CLI explicitly supports ACP for third-party integrations (see kiro.dev/docs/cli/acp)
No reverse engineering or unofficial APIs used
Requires valid Kiro subscription

License

MIT

Contributing

Issues and PRs welcome. Test with Kiro CLI v2.5.0+.

pi-kiro-models

原始内容

pi-kiro-models

Overview

How it works

Tools

Features

Stack

Architecture

Models

Prerequisites

Installation

Method 1: Clone from GitHub

Method 2: Symlink from a dev location

Method 3: Register in settings.json

Usage

Host-executed Pi extension tools

MCP Tool Passthrough

Where servers are read from

Register a server

Verify

Notes

Testing

Troubleshooting

Roadmap

Legal & Compliance

License

Contributing

Method 3: Register in `settings.json`