Skip to content

feat(agent-host): add Pi as an agent: permission gate, accounts, MCP, packages - #196

Merged
deymosh merged 8 commits into
masterfrom
feat/pi-driver
Nov 17, 2026
Merged

deymosh merged 8 commits into
masterfrom
feat/pi-driver

Conversation

@deymosh

@deymosh deymosh commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Adds Pi (@earendil-works/pi-coding-agent, pinned 1.5.2) as a fifth agent, driven over its RPC mode (pi --mode rpc, JSON lines on stdio), one Pi process per session, with the phone's accounts, MCP and plugin screens working for it.

Permissions: a gate extension, the policy in the driver

Pi has no permission system: it runs every tool call it decides on. Pi extensions can hold a tool_call and open a dialog that, in RPC mode, Pi forwards as an extension_ui_request and waits on. Verified live before writing the driver: a call held 3 s for our answer; Deny blocked it before it ran (no file written, Pi told the model it was denied), Allow ran it.

So the driver writes one self-contained extension (drivers/pi/extension.ts, serialised with Function.prototype.toString()) into Pi's home and loads it with -e. It is pinned with the host, so no separate npm package is needed. The extension asks about every call; the policy is the driver's, with three tiers:

  • Ask (default): a card for everything except Pi's read-only read/grep/find/ls, with Allow / Allow <tool> for this session / Deny.
  • Auto edit: Pi's own edit/write also run without a card. Shells, and any tool an extension or MCP server adds, still ask.
  • YOLO: no cards.

The extension also registers a bound provider profile as an openai-completions provider. The token goes in its own env var, named via Pi's $NAME interpolation, so it never touches the file. Verified live: the endpoint received Bearer <token>.

Accounts (supports.accounts)

Keys and subscription sign-ins for Pi's providers, managed with Pi's own code. A short-lived helper (authHelper.ts, serialised like the extension) loads the installed Pi's bundle and drives its ModelRuntime: getProviders, login, logout. A key or sign-in therefore lands exactly where Pi's /login puts it, in auth.json under Pi's own lock (which a running Pi also takes when refreshing a token).

  • Verified on 1.5.2: 43 providers, nine with a sign-in (Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot, xAI and others). A key login is a single secret prompt, after which a fresh runtime reports the key as stored.
  • The key reaches the helper on stdin, never in its argv or environment. Errors are redacted of the key and of a pasted sign-in address, and the helper's stderr is not logged.
  • Sign-in: Pi's auth_url becomes a paste-back attempt, and the pasted address answers Pi's manual_code prompt. A device_code becomes a code to enter. A login that asks anything else is refused with Pi's own question.
  • Keys from the bridge's environment show as the machine's, and cannot be removed from the phone.

MCP servers (supports.mcp)

The mcpServers of mcp.json in Pi's home, the file pi mcp add and /mcp edit. enabled: false switches a server off. Pi rejects SSE and names other than [A-Za-z0-9_-] (verified with pi mcp list --json), so both are refused before anything is written. Writes are serialised, staged and renamed, owner-only. A session's panel reports what its Pi loaded at start, as the DeepSeek driver does. --offline does not affect MCP (it covers catalog refreshes and package installs only).

Plugins (supports.plugins) = Pi packages

Install, update and remove go through Pi's own pi install|update|remove <source>; none of them prompts without a terminal. The list comes from settings.json. Packages are how Pi gains subagents, LSP diagnostics and other tools, without CodeDeck maintaining a harness.

  • The commands run in Pi's home, because Pi records a local path relative to it.
  • An npm source needs npm: the image has it, a release archive does not, and Pi's raw spawn npm ENOENT becomes a sentence that says so. CODEDECK_NPM_REGISTRY is passed on as npm_config_registry.
  • No toggles: Pi could only turn a package off by rewriting the user's resource filters.

Sessions

  • rpc.ts is a total LF-only JSONL codec: not readline, which splits on U+2028/2029. It finishes on close, and close() cannot hang on a Pi that stopped reading.
  • resumeLost is set only on Pi's No session found matching …. A crash or a failed install keeps the conversation.
  • Retries: Pi retries rate limits and overloads itself. Recorded live with a server answering 429, an attempt's error is followed by auto_retry_start, by auto_retry_end{success:false}, or by agent_settled. The driver holds each attempt's error: a retry becomes one short status line, and only an error Pi gives up on, or never retries, becomes an error row. Before this, one real turn through a rate-limited gateway showed four error rows.
  • Effort and model changes made while Pi is still starting wait for it. Steer, abort, commands, thinking levels, the model probe and deleting a conversation are as described in docs/PI.md.

Shared change: sdk/tools.ts reads an edits: [...] list as a file change (Pi's edit, and Claude Code's MultiEdit).

Tests

  • The real pinned Pi in CI:
    • piFakeModel.test.ts: a profile-bound session against tools/fake-model.mjs; /tool raises a card, Deny blocks the write, Allow runs it.
    • Accounts: list, store and remove keys through the real helper.
    • MCP: Pi itself validates the mcp.json we write.
    • Packages: install, update and uninstall a local package.
  • piDriver.test.ts runs on a shared scripted RPC fake whose header states only what was checked against Pi 1.5.2 (lifecycle, gate, retries and their recorded order).
  • Each guard was proven by breaking it once: the resumeLost cases, close-on-a-stuck-pipe, options before ready, key redaction, MCP format, the package working directory, retry folding and retry line length.

Verification

  • ./codedeck check --changed: host install, typecheck, test (972 passed), build; Android bindings and Gradle all ok. Every commit typechecks on its own.
  • ./codedeck e2e: driver protocol and bridge end to end ok.
  • ./codedeck live pi --fake-model on the built host, in Ask and Auto edit: the profile bound, a bash card raised in both tiers, the turn completed.
  • A real model through a gateway: the session reached it with the environment's key. Its upstreams were rate-limited at the time, so a model choosing its own tool call end to end is not verified yet. That run is what exposed the retry noise above.

Traffic cost

No wire change: cards and entries use the existing vocabulary. The gate's round trip is local stdio between host and Pi; in YOLO, Auto edit (for edits) and for read-only tools it never reaches the phone. A retry adds at most one short status line per attempt in place of an error row.

Repo docs touched

docs/PI.md (new: accounts, the tiers, MCP, packages, retries), plus the agent lists in README, BRIDGE.md, PROTOCOL.md ("ships five"), AGENT-CANDIDATES.md, .claude/CLAUDE.md (agent lists; the CI fake-model test now covers pi) and the verify-changes skill (a live pi --fake-model line).

Review changes

A first draft was reviewed before the PR, and two rounds of bug hunting followed. Fixed:

  • resumeLost was set on any failure while resuming;
  • the codec finished on exit instead of close, and close() could hang;
  • an effort or model change made before Pi was ready was dropped;
  • the base-URL rule existed twice;
  • every retry attempt showed as an error, and a retry line could quote a page of gateway JSON;
  • Stop during a retry wait could show the held provider error;
  • the account helper's stderr was logged unredacted;
  • the scripted fake skipped the third retry announcement that Pi sends;
  • a package recorded as a Windows path (..\pkg) kept its prefix as its name on a Linux bridge (path.basename splits on / only there). CI's Linux job caught it.

🤖 Generated with Claude Code

The Pi driver runs the pinned CLI from an install-on-demand tree, the way
the DeepSeek Harness and Qwen Code drivers do: nothing larger than one
binary is shipped, and the tree is downloaded at the version and sha512
pnpm-lock.yaml holds the first time a Pi session needs it.

The generated pins are the root package's full dependency closure, laid
out where Node resolves each package exactly as pnpm did. Pi is pure
JavaScript, so no platform binary is involved; the optional native
packages its closure carries are skipped where their gates do not match.

The DeepSeek Harness pins gain two entries: Pi's own undici pin hoists
that version, and the harness's openai optional dependency now resolves
its own nested copy, which is how pnpm laid the shared closure out.

Co-Authored-By: Claude Code <[email protected]>
deymosh and others added 5 commits November 17, 2026 13:28
Pi has no permission system of its own: its tool calls run as soon as the
model asks for them. CodeDeck's own Pi extension holds every tool_call and
asks the client through Pi's extension-UI protocol, which is what turns
those calls into the phone's permission cards. The extension is a single
self-contained function serialized into Pi's config directory at session
start, so it runs inside Pi's process with nothing of the host beside it.

Policy lives in the driver, where the card is built from the
tool_execution_start facts of the call: ask (the default) asks for every
tool except Pi's own read-only set, yolo answers everything, and "allow for
this session" is remembered per tool. Other extensions' dialogs reach the
phone as questions, and a session's end or an interrupt answers every open
dialog cancelled — Pi does not settle an agent while one waits.

Sessions are one Pi process each over RPC (JSONL on stdio, LF-only framing
so U+2028 inside a string is data, not a record boundary), with Pi's own
conversation ids resumed through --session and its context meter reported
as session info. A provider profile is bound through the environment and
registered by the same extension with Pi's OpenAI-completions API, the
token referenced by name so it never reaches the file on disk. Models are
listed from a short-lived probe process.

The shared tool reader now treats a path with a non-empty edits list as a
file change: Pi's editor and Claude Code's MultiEdit both spell their
changes that way, and a call from either was read as a read.

Co-Authored-By: Claude Code <[email protected]>
`live pi` binds the local fake model to the session as a provider profile,
which is exactly the shape the bridge gives a real one, and names its model
under the profile's id — the selector Pi's startup resolves after the
driver's extension has registered it. The probe's agent lists and the weekly
release watch know the package too.

Verified against Pi 1.5.2 with the fake model: the install-on-demand tree
boots, hello is echoed, the scripted tool call raises a permission card and
runs once allowed, and a /question prompt answers that the request offers no
question tool (Pi ships none).

Co-Authored-By: Claude Code <[email protected]>
docs/PI.md says how Pi gets installed and a model (a provider profile, or
Pi's own providers through the bridge's environment or its own login in
CODEDECK_PI_HOME), what the permission gate CodeDeck writes into every
session asks about in Ask and YOLO, how reasoning and mid-turn messages
map, and what Pi does not have. The agent lists in the README, BRIDGE.md,
PROTOCOL.md, AGENT-CANDIDATES.md, CLAUDE.md and the verify-changes skill
name Pi beside the others.

Co-Authored-By: Claude Code <[email protected]>
Pi had no way to get a key from the phone: a session needed a provider
profile, a key in the bridge's environment or Pi's own login on the
machine. The driver now advertises `supports.accounts` and manages them
with Pi's own code, so a key or a sign-in lands where Pi's /login keeps
it (auth.json in Pi's home, under Pi's own lock, which a running Pi that
refreshes a token also takes).

A short-lived helper process (authHelper.ts, serialised like the
extension and run with the host's node) loads the installed Pi's bundle
and drives its ModelRuntime: getProviders for the list (43 providers in
1.5.2, nine with a subscription sign-in) with each one's auth status,
login(api_key) with its secret prompt answered for a key, login(oauth)
for a sign-in, logout for a removal. The key reaches the helper on
stdin, never in its arguments or environment. A sign-in's page becomes a
paste-back attempt whose pasted address answers Pi's manual_code prompt;
a device code becomes a code to enter. A login that asks anything else
is refused with Pi's own question. Errors are redacted of the key and
the pasted address. After a change the model list is read again.

Tests: listing, storing and removing run the real helper against the
pinned Pi (local file operations only); the sign-in flow runs on a
scripted helper. The redaction test was proven by removing it once.

Co-Authored-By: Claude Code <[email protected]>
The driver now advertises `supports.mcp`: the MCP screen edits the
`mcpServers` map of mcp.json in Pi's home, the file `pi mcp add` and
/mcp edit, so a server added from the phone is also there for Pi in a
terminal on that home. Stdio servers take command/args/env, HTTP ones
url/headers, and switching one off writes Pi's own `enabled: false`.
Pi rejects the legacy SSE transport and names other than letters,
digits, `_` and `-` (verified with `pi mcp list --json` on 1.5.2), so
both are refused before anything is written. Edits are serialised and
written beside the file then renamed over it, owner-only, since env and
header values are kept there.

A session's MCP panel says what its Pi loaded as it started, as the
DeepSeek driver's does: Pi connects its servers at session start and
reports nothing about them over RPC, so a server changed afterwards is
shown as not loaded yet. `--offline` does not affect MCP connections
(it covers model catalog refreshes and package installs only).

Tests: the pinned Pi validates the file this writes (proven by writing
an HTTP server under the wrong key once); listing carries no argument,
env or header value; refusals change nothing; the session panel follows
changes made after the session started.

Co-Authored-By: Claude Code <[email protected]>
@deymosh deymosh changed the title feat(agent-host): add Pi as an agent, with a permission gate extension feat(agent-host): add Pi as an agent: permission gate, accounts, MCP, packages Nov 17, 2026
deymosh and others added 2 commits November 17, 2026 13:37
The driver now advertises `supports.plugins`: the phone's plugins are
Pi's packages, installed, updated and removed with Pi's own commands
(`pi install|update|remove <source>`, none of which asks anything
without a terminal, verified on 1.5.2) and listed from the `packages`
array of settings.json in Pi's home. A package bundles extensions,
skills, prompt templates and themes, which is how Pi gains what it
does not ship (subagents, LSP diagnostics, other tools) without
CodeDeck maintaining any of it.

The commands run in Pi's home: Pi records a local path relative to its
settings file, and only there does that record name the same directory
(outside it Pi answers "No matching package found"). An npm source
needs npm, which Pi runs: the image has it, a release archive does not,
and Pi's raw `spawn npm ENOENT` becomes a sentence that says so. The
bridge's CODEDECK_NPM_REGISTRY mirror is passed on as
npm_config_registry. Pi can only turn a package off by rewriting its
resource filters, which would discard the user's own, so there are no
toggles.

Tests: install, update and uninstall of a local package through the
pinned Pi (proven by running the commands outside Pi's home once);
parsing of Pi's records and the refusals that never reach Pi.

Co-Authored-By: Claude Code <[email protected]>
Between Ask and YOLO: Pi's own file writers (`edit`, `write`) run
without a card, while a shell command and every other tool still ask.
Only Pi's built-ins count, by name: a tool an extension or an MCP server
adds may look like an edit and do anything else besides, so it asks.
The tier is the driver's policy, like the other two; the extension
still holds every call until the driver answers.

Co-Authored-By: Claude Code <[email protected]>
@deymosh
deymosh merged commit 25f59bd into master Nov 17, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant