Integration on AIBussin — AI applications, systems and books

MCP Servers

Fri, 02 Oct 2026 09:00:00 +0100

The guard extension intercepts write and edit. It blocks those calls as intended. Then someone on the team installs a Jira MCP server, and the model closes a ticket through mcp__jira__transition_issue without that guard blocking the call. The MCP call has a different tool name, so a guard limited to write and edit does not match it.

It was not consulted because the guard never claimed that path was its responsibility — and, more importantly, because whether it is covered turns out to be a real question with a documented answer. This chapter is about registering MCP servers, controlling how their tools reach the model, and the one thing a permission extension can and cannot learn from them.

The Interface Is Not the Agent

Fri, 02 Oct 2026 09:00:00 +0100

You have spent thirty chapters mostly in a terminal, and it is easy to come away thinking the terminal is Pi. It is not. The terminal is one way to drive the agent, alongside print mode, JSON, RPC and the SDK. Switching interfaces preserves the underlying agent architecture, but can change how work is submitted, what a person can approve, and how results and failures are reported.

That is a claim about architecture, and this part of the book ends by testing it. Chapters 32 to 35 take the interfaces one at a time. This chapter states what they share, shows that the sharing is real, and names the one place where an interface does leak into what an extension is allowed to assume.

Headless Pi

Fri, 02 Oct 2026 09:00:00 +0100

A CI job needs to run a review over a diff. A pre-commit hook needs to summarise what just changed. Neither has a person, and neither wants a terminal.

pi already handles this, and the handling is almost entirely documented in one place: cli-integration.md. But the interesting question is not “how do I print the answer” — it is what is different when the agent has no person attached, because most of what you built in the previous twenty-nine chapters assumed one.

The JSON Event Stream

Fri, 02 Oct 2026 09:00:00 +0100

You piped pi --mode json into a log and now you have four thousand lines and a question: which ones are the answer?

The JSON event stream is the reference for the agent-session events that JSON and RPC mode share. It is a wire format, with deliberate differences from in-process SDK events; RPC also has command responses and protocol-specific events that JSON mode does not. If you build on the stream without understanding those differences, your reconstruction can drift. This chapter takes the JSON stream apart: the framing, the event vocabulary, and the rule that governs message reconstruction.

SDK Sessions

Fri, 02 Oct 2026 09:00:00 +0100

Your integration is written in TypeScript. It parses JSONL records and reconstructs streamed messages. If you use RPC, it also correlates command responses with requests. Much of that protocol handling exists because you chose to communicate with Pi across a subprocess boundary.

@earendil-works/pi-coding-agent embeds Pi directly, and sdk.md opens with the recommendation in its first two lines: use the SDK for in-process TypeScript integration; for a language-independent or isolated subprocess, use CLI integration instead. This chapter is about what the boundary buys you back and what it charges.

RPC

Fri, 02 Oct 2026 09:00:00 +0100

You want to drive Pi from an editor plugin, from a Python service, or from an IDE — without reimplementing the TypeScript SDK in another language or running Pi inside your host process. A subprocess gives the host a separate failure and lifecycle boundary. It does not sandbox the agent: Pi and its tools can still reach whatever files, credentials, and services the child process is permitted to access.

RPC is the fourth interface in this progression and the one that keeps the isolation. This chapter is about the protocol: what flows in each direction, how you correlate, and the subprotocol that almost nobody realises exists.