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.