fix(pi): emit parameters and execute in the generated pi adapter

[musichen]

Problem

The generated Pi extension (~/.pi/agent/extensions/cbmem.ts) registers each MCP tool as:

pi.registerTool({ name: 'index_repository', run: (args, ctx) => call('index_repository', args, ctx?.signal) });

Pi's ToolDefinition requires label, description, parameters, and execute. The run-only shape is accepted by Pi's loader but produces tools that fail in two ways:

1. No parameters schema - strict providers such as xAI/Grok reject the request with 422 missing field parameters (OpenAI and other providers tolerate the omission, so it only surfaces on some providers).
2. No execute - the tool is uncallable, because Pi invokes execute, never run.

Once execute was wired up, a third problem surfaced: execute forwarded the raw MCP JSON (which has no content array) instead of Pi's required result shape, crashing the TUI's getTextOutput on result.content.filter(...).

Fix

The adapter now emits the full tool shape from the registry:

pi.registerTool({
  name: 'index_repository',
  label: 'Index repository',
  description: '...',
  parameters: { ...input_schema... },
  execute: async (args, ctx) => {
    const result = await call('index_repository', args, ctx?.signal);
    if (result && typeof result === 'object' && result.error) {
      throw new Error(String(result.error));
    }
    const content = result && Array.isArray(result.content)
      ? result.content
      : [{ type: 'text', text: JSON.stringify(result ?? null, null, 2) }];
    return { content, details: result ?? {} };
  },
});

Specifically:

• Added cbm_mcp_tool_title and cbm_mcp_tool_description accessors so the adapter reads metadata from the same registry that backs tools/list, instead of drifting.
• The input_schema is embedded directly as a JSON object literal (compact JSON is valid JavaScript), avoiding a JSON.parse indirection.
• Added a JS-string escaping helper so long descriptions with apostrophes/backslashes/newlines serialize safely.
• call now passes --json so the CLI emits the raw MCP result instead of human-readable text that JSON.parse cannot parse.
• execute returns Pi's required { content, details } shape: it passes the MCP content array through, throws on transport errors, and stringifies anything else.

Tests

• Added client_adapter_pi_emits_parameters_and_execute asserting execute/parameters are present, the legacy run: shape is gone, the schema is embedded, and --json is requested.
• Built the CLI and verified the generated cbmem.ts loads and returns a valid result shape for success, error, null, and plain-object results.
• agent_clients suite: 32/32 passing.

[github-actions]

Thanks for opening this — it has been seen, and it is queued.

This note is automated, but it is not a brush-off: it exists so you know where your PR stands instead of having to guess from silence.

Current review status: working through a backlog. 0.9.1-rc.1 is out, so the release freeze that held reviews is over — but it left a large queue of open pull requests behind it, and we are reading through them oldest-first. The background is in discussion #1144.

What that means for this PR, concretely:

• It will not be closed for inactivity. No stale bot touches pull requests here.
• It may still sit a while before a human reads it. That is on us, not on you.
• Older PRs are read first, so a recent one is not being skipped — it is behind a queue.

Things that will genuinely speed it up whenever review does happen:

• Keep it rebased on main — the tree is moving quickly right now, and a conflicting branch cannot be reviewed as the diff you intended.
• Get CI green, or say which failures you believe are pre-existing.
• Keep the change to one claim. Bundled features and refactors get split before they get merged, which costs you a round trip.
• Every commit needs a sign-off (git commit -s) — CI enforces DCO.

If this fixes a bug, a reproduction we can run is worth more than a description of the symptom.

Thanks for contributing, and sorry in advance for the wait.

[DeusData]

We took this to the plausibility gate's end-to-end step before merging, and the probe against the current published Pi (@mariozechner/pi 0.70.6, fresh npm install) found the contract has moved under the PR — sharing the specifics because your three diagnosed breakages are real and the fix direction is right:

1. pi.registerTool does not exist in 0.70.6 — the string appears nowhere in the installed package tree (pi, pi-agent-core, pi-ai), and dist/ contains no extension-path loading at all. Both our current adapter AND this PR's generated shape would fail to load there.
2. execute signature: pi-agent-core's AgentTool declares execute(toolCallId: string, params, signal?, onUpdate?) — the toolCall ID is the FIRST argument. The generated execute: async (args, ctx) would receive the ID string as the tool arguments.
3. Result shape {content, details}: ✓ this half matches AgentToolResult exactly.

The mixed match suggests you validated against a different Pi build (understandable — 313 published versions). Could you tell us which version you ran the TUI against, and whether current Pi still loads TS tool extensions at all (vs. having moved on)? If extensions are alive in some form, we'd take a revision targeting the current AgentTool contract with the version noted in the generated header; if Pi has effectively dropped this surface, the honest fix may be retiring the adapter in favor of whatever Pi consumes now — which we'd also want to know. Thank you for the careful three-part diagnosis either way; it's the reason this got a real probe instead of a rubber stamp.

[musichen]

The three breakages you listed were real on the coding-agent surface I was looking at.
The probe target is the mismatch.

I ran against @earendil-works/pi-coding-agent 0.84.2 (pi --version → 0.84.2). That is the coding-agent TUI.

Small local context, since this is easy to miss from outside: I am in Vienna, same city as Mario / the Pi community here. Around three months ago (May 2026) it was going around locally that Mario Zechner joined Earendil GmbH and that Earendil took on pi.dev. That matches the packaging cut I can actually point at: 0.73.1 / 0.74.0 on 2026-05-07 (CHANGELOG: self-update for the rename, then "Updated repository links and package references for the move to earendil-works/pi-mono and @earendil-works/*"). From 0.74.0 onward it ships from Earendil, not @mariozechner/*:

• GitHub: https://github.com/earendil-works/pi
• npm: npm i -g --ignore-scripts @earendil-works/pi-coding-agent
• Homebrew: brew install pi-coding-agent (homebrew-core, currently 0.84.2)
• installer: curl -fsSL https://pi.dev/install.sh | sh

Answers to the three points:

1. pi.registerTool does not exist in 0.70.6 — the string appears nowhere in the installed package tree (pi, pi-agent-core, pi-ai), and dist/ contains no extension-path loading at all. Both our current adapter AND this PR's generated shape would fail to load there.

That finding is correct for @mariozechner/pi 0.70.6, but that package is not the coding agent. npm describes it as "CLI tool for managing vLLM deployments on GPU pods" (badlogic/pi-mono, packages/pods). No registerTool and no extension loader there is expected.

The older coding-agent name on that scope is @mariozechner/pi-coding-agent (last I see is 0.73.1). Current published coding agent is @earendil-works/pi-coding-agent 0.84.2.

On 0.84.2, TS extensions are still a first-class surface:

• auto-load from ~/.pi/agent/extensions/*.ts and .pi/extensions/*.ts
• pi.registerTool() is on ExtensionAPI (dist/core/extensions/types.d.ts)
• docs + examples still show TS extensions (docs/extensions.md, examples/extensions/hello.ts)
• cbmem.ts loads that way here and the tools show up in the TUI

So I would not retire the adapter. The install target for a re-probe should be @earendil-works/pi-coding-agent, not @mariozechner/pi.

2. execute signature: pi-agent-core's AgentTool declares execute(toolCallId: string, params, signal?, onUpdate?) — the toolCall ID is the FIRST argument. The generated execute: async (args, ctx) would receive the ID string as the tool arguments.

Yes. That was a real bug in this PR, and it is still true one wrapper up on 0.84.2 ToolDefinition.execute:

execute(
  toolCallId: string,
  params: Static<TParams>,
  signal: AbortSignal | undefined,
  onUpdate: AgentToolUpdateCallback<TDetails> | undefined,
  ctx: ExtensionContext,
): Promise<AgentToolResult<TDetails>>

execute: async (args, ctx) would bind toolCallId as args. Pushed the follow-up on this PR (109299f): the generator now emits

async execute(toolCallId, params, signal, _onUpdate, ctx) {
  const result = await call(name, params, signal ?? ctx?.signal);
  ...
  return { content, details: result ?? {} };
}

and the generated header pins @earendil-works/pi-coding-agent >= 0.74.0 (verified 0.84.2). agent_clients is 32/32 including the 5-arg shape.

3. Result shape {content, details}: ✓ this half matches AgentToolResult exactly.

Agreed. That half was already correct and is unchanged.

A probe can be re-run against @earendil-works/pi-coding-agent 0.84.2.

[DeusData]

Thank you for correcting the package target and updating the execute arity after the maintainer probe. The distinction between the unrelated @mariozechner/pi package and the current @earendil-works/pi-coding-agent surface explains the earlier mismatch, while the result-shape finding remains valid.

We will re-probe the generated adapter against the exact coding-agent version and extension contract you identified before making a merge decision. The process-spawn path is an existing adapter boundary rather than a new service dependency, but its argument order, cancellation signal, result normalization, and generated-string escaping all need end-to-end verification. Thank you for answering the version question with enough detail to make that probe reproducible.

[musichen]

Thanks. Branch is synced with main.

Re-probe target I used, so the next run is on the same surface:

• @earendil-works/pi-coding-agent@0.84.2 (pi --version)
• not @mariozechner/pi
• generated header on this branch:
  Target: @earendil-works/pi-coding-agent >= 0.74.0 (verified 0.84.2)
ToolDefinition.execute(toolCallId, params, signal, onUpdate, ctx)
• result still { content, details }

String shape and path escaping are already in agent_clients. The four live checks you named (arity, abort → kill cli --json, result wrap, description/BIN escaping) are the ones that still need a real Pi process. Spawn is unchanged: cli --json.

An in-tree fixture for arity + wrap is easy to add if that is cheaper than a TUI session.

[DeusData]

Taking you up on the fixture offer — that is the right answer, and better than the re-probe I promised.

First, the correction deserves acknowledging properly rather than in passing. My plausibility probe ran against @mariozechner/pi, which is a different project entirely; the coding agent is @earendil-works/pi-coding-agent, renamed in the May 2026 org move. So the "contract has moved" report I gave you was measured against the wrong package, and you spent a round trip disproving something I should have got right. Thank you for correcting it precisely and without irritation — and for separating my mistake from the arity bug, which was real and which you fixed in 109299f.

On the offer: yes, please add the in-tree fixture, and let us not do the live re-probe at all. I said I would re-verify argument order, cancellation signal and result normalization against a running Pi. Having thought about it, that is the wrong instrument for this repo. A check that depends on a third-party agent being installed and behaving is not something we can gate CI on, and a one-off manual probe expires the moment either side moves — which is precisely how we ended up here, with a contract assertion nobody could reproduce. A fixture that pins the emitted shape is reproducible, runs on every leg, and fails loudly when the contract drifts. Cheaper for you and worth more to us.

Your existing assertions are already binding — main emits run: (args, ctx) =>, so

ASSERT_NOT_NULL(strstr(js, "execute: async (toolCallId, params, signal, _onUpdate, ctx) => {"));
ASSERT_NULL(strstr(js, "run: (args, ctx)"));

are red without the change. I also checked the flag you emit: cli_strip_flag(&argc, argv, "--json") in src/main.c strips positionally, so ['cli', '--json', tool, args] is valid ordering rather than accidentally working.

What I would like the fixture to cover beyond that is the result wrapping — the {content, details} shape and how a tool error is surfaced — since that is the half your current assertions do not reach and the half most likely to drift silently. Argument arity you have; cancellation via signal is worth a line if it is cheap.

One thing I want on the record, which is our problem rather than yours. The generated cbmem.ts is written into $HOME/.pi/agent/extensions/, which Pi auto-loads — so this file executes inside the user's agent. It is a deliberate exception to our "clients get MCP config and markdown, never a runtime artifact" rule, correctly documented at the call site because Pi has no MCP client and this is the only bridge to the graph. But the generated output is pinned only by whichever substrings someone thought to assert; there is no byte-identity or golden-file gate anywhere in tests/test_agent_clients.c. For a generated artifact that lands in an auto-load directory, that is a gap worth closing. Not your job in this PR — I am recording it so it does not stay invisible, and your fixture is a step toward it.

CI is 34/34 green and the branch is clean. Add the result-wrapping coverage and I will merge.

[musichen]

Result-wrapping fixture is in 2ae84e7f, including the cheap abort lines. agent_clients is 33/33 locally; CI is running.

[DeusData]

Merged as 010569fa. Thank you — this one took four rounds and most of the friction was mine.

I reported that Pi's contract had moved, having probed @mariozechner/pi, which is an unrelated project; the coding agent is @earendil-works/pi-coding-agent. You corrected that precisely, separated my mistake from the real arity bug, and fixed the real one. Then when I asked for result-wrapping coverage you had it pushed within hours.

I checked the new assertions rather than counting them: the result wrap, the error throw, the Array.isArray(result.content) branch and the JSON-stringify fallback are all absent from main, so they are genuinely red without your change. Two of the seven — the signal?.addEventListener('abort', …) and if (!child.killed) child.kill(); lines — pin code that already existed in the call() helper you did not touch, so they are regression pins rather than new evidence. That is not a problem; the cancellation contract is covered by the earlier test's ', params, signal ?? ctx?.signal)' assertion, which IS binding. Just so the ledger is accurate.

The byte-identity gap I mentioned stays open and stays ours, not yours. Your fixture makes it smaller.