Skip to content

Commit a8ff6b1

Browse files
only21milclaude
andcommitted
fix(pi): let completion gateways opt out of eager T3 tool schemas
Pi instances can turn off "Load every T3 tool on completion gateways". The default keeps the eager catalog from pingdotgg#18643. With it off, an openai-completions request declares the orchestration tools, tool_search and T3 tools already called in the current branch, and re-adds those after model switches and tree restores. Refs pingdotgg#19190 Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent ca140c4 commit a8ff6b1

11 files changed

Lines changed: 150 additions & 10 deletions

‎docs/user/providers-pi.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ directory, endpoint, or model configuration. `--provider` must be paired with `-
2323
rejects launch arguments that change Pi's execution mode or select a session because T3 owns those
2424
parts of the process lifecycle.
2525

26+
Pi models on OpenAI-compatible chat completion gateways receive every T3 Code tool schema on each
27+
request, because some gateways drop calls to tools the request does not declare. If your gateway
28+
runs tools that Pi loads through `tool_search`, turn off **Load every T3 tool on completion
29+
gateways** in the Pi instance's settings to send smaller requests. Pi then declares the orchestration
30+
tools, `tool_search`, and T3 Code tools the conversation has already called.
31+
2632
On a remote or headless server, connect to that machine over SSH and run `pi`, then `/login`.
2733
Open the authorization URL on your own computer. If the callback cannot reach the server,
2834
paste the final redirect URL or authorization code back into Pi when prompted. You can also

‎packages/provider-pi/src/server/adapter.test.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -412,7 +412,13 @@ const makeAdapter = Effect.fnUntraced(function* (
412412
displayName: undefined,
413413
enabled: true,
414414
environment: [],
415-
config: { enabled: true, binaryPath: "pi", launchArgs, customModels: [] },
415+
config: {
416+
enabled: true,
417+
binaryPath: "pi",
418+
launchArgs,
419+
eagerCompletionGatewayTools: true,
420+
customModels: [],
421+
},
416422
}).pipe(
417423
Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
418424
Effect.provideService(HostProcess.Environment, {}),
@@ -424,7 +430,13 @@ const makeAdapter = Effect.fnUntraced(function* (
424430
}
425431
return yield* makePiAdapterV2({
426432
instanceId: PI_INSTANCE_ID,
427-
settings: { enabled: true, binaryPath: "pi", launchArgs, customModels: [] },
433+
settings: {
434+
enabled: true,
435+
binaryPath: "pi",
436+
launchArgs,
437+
eagerCompletionGatewayTools: true,
438+
customModels: [],
439+
},
428440
environment: {},
429441
}).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner));
430442
});

‎packages/provider-pi/src/server/adapter.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -473,6 +473,7 @@ export const makePiAdapterV2 = Effect.fn("makePiAdapterV2")(function* (
473473
mcpSession,
474474
extensionPath,
475475
runtimeMode: input.runtimePolicy.runtimeMode,
476+
eagerCompletionGatewayTools: options.settings.eagerCompletionGatewayTools,
476477
});
477478
const scopedLaunch = yield* agentScope.wrap({
478479
command: options.settings.binaryPath || "pi",

‎packages/provider-pi/src/server/mcpBridge.testkit.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,14 @@ type AgentStartHook = (
3535
},
3636
ctx: {
3737
model?: { api: string };
38+
sessionManager?: {
39+
buildSessionContext: () => {
40+
messages: ReadonlyArray<{
41+
role: string;
42+
content: ReadonlyArray<{ type: string; name?: string }>;
43+
}>;
44+
};
45+
};
3846
ui: { notify: (message: string, severity: string) => void };
3947
},
4048
) => Promise<{ systemPrompt: string } | undefined>;
@@ -47,6 +55,7 @@ export async function loadMcpBridge(
4755
readonly toolSearchDisabled?: boolean;
4856
readonly allowsTool?: (name: string) => boolean;
4957
readonly runtimeMode?: string;
58+
readonly gatewayTools?: string;
5059
} = {},
5160
) {
5261
const handlers = new Map<string, AgentStartHook>();
@@ -91,6 +100,7 @@ export async function loadMcpBridge(
91100
T3_MCP_BEARER_TOKEN: "fixture-token",
92101
T3_PI_MCP_EXTENSION_PATH: "/fixture/pi-t3-extension.ts",
93102
T3_PI_RUNTIME_MODE: options.runtimeMode,
103+
T3_PI_GATEWAY_TOOLS: options.gatewayTools,
94104
},
95105
},
96106
AbortSignal,

‎packages/provider-pi/src/server/mcpExtensionSource.test.ts‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,52 @@ describe("Pi MCP tool exposure", () => {
252252
assert.include(bridge.getActiveTools(), "mcp__t3-code__preview_snapshot");
253253
});
254254

255+
it("declares only called T3 tools for gateways that opt out of eager schemas", async () => {
256+
const bridge = await loadMcpBridge({
257+
modern: true,
258+
toolSearchAvailable: true,
259+
gatewayTools: "called",
260+
});
261+
const messages: Array<{
262+
role: string;
263+
content: Array<{ type: string; name?: string }>;
264+
}> = [];
265+
const event = { systemPrompt: "" };
266+
const gatewayContext = {
267+
model: { api: "openai-completions" },
268+
sessionManager: { buildSessionContext: () => ({ messages }) },
269+
ui: { notify: assert.fail },
270+
};
271+
await bridge.handlers.get("session_start")!(event, gatewayContext);
272+
await bridge.handlers.get("before_agent_start")!(event, gatewayContext);
273+
assert.deepEqual(bridge.getActiveTools(), ["read", "tool_search"]);
274+
275+
messages.push(
276+
{ role: "user", content: [{ type: "text" }] },
277+
{
278+
role: "assistant",
279+
content: [
280+
{ type: "text" },
281+
{ type: "toolCall", name: "mcp__t3-code__preview_snapshot" },
282+
{ type: "toolCall", name: "bash" },
283+
],
284+
},
285+
);
286+
await bridge.handlers.get("model_select")!(event, gatewayContext);
287+
assert.deepEqual(bridge.getActiveTools(), [
288+
"read",
289+
"tool_search",
290+
"mcp__t3-code__preview_snapshot",
291+
]);
292+
bridge.restoreActiveTools(["read"]);
293+
await bridge.handlers.get("session_tree")!(event, gatewayContext);
294+
assert.deepEqual(bridge.getActiveTools(), [
295+
"read",
296+
"tool_search",
297+
"mcp__t3-code__preview_snapshot",
298+
]);
299+
});
300+
255301
it.each(["legacy Pi", "disabled tool search"])(
256302
"keeps tool execution available with %s",
257303
async (mode) => {

‎packages/provider-pi/src/server/mcpExtensionSource.ts‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ export const T3_MCP_URL_ENV = "T3_MCP_URL";
1010
export const T3_MCP_BEARER_ENV = "T3_MCP_BEARER_TOKEN";
1111
export const T3_PI_RUNTIME_MODE_ENV = "T3_PI_RUNTIME_MODE";
1212
export const T3_PI_MCP_EXTENSION_PATH_ENV = "T3_PI_MCP_EXTENSION_PATH";
13+
export const T3_PI_GATEWAY_TOOLS_ENV = "T3_PI_GATEWAY_TOOLS";
1314

1415
/**
1516
* Pi tools whose confirmations the bridge raises as file-change approvals.
@@ -27,6 +28,7 @@ const URL_ENV = ${JSON.stringify(T3_MCP_URL_ENV)};
2728
const TOKEN_ENV = ${JSON.stringify(T3_MCP_BEARER_ENV)};
2829
const RUNTIME_MODE_ENV = ${JSON.stringify(T3_PI_RUNTIME_MODE_ENV)};
2930
const EXTENSION_PATH_ENV = ${JSON.stringify(T3_PI_MCP_EXTENSION_PATH_ENV)};
31+
const GATEWAY_TOOLS_ENV = ${JSON.stringify(T3_PI_GATEWAY_TOOLS_ENV)};
3032
const ORCHESTRATION_INSTRUCTIONS = ${JSON.stringify(T3_CODE_ORCHESTRATION_INSTRUCTIONS.trim())};
3133
const PROTOCOL = "2025-06-18";
3234
const READ_ONLY_TOOLS = new Set(["read", "grep", "find", "ls"]);
@@ -415,7 +417,21 @@ export default async function t3McpExtension(pi: ExtensionAPI) {
415417
// mcp.json configures it; retry a failed connection at session_start.
416418
await ensureStarted().catch(() => undefined);
417419
418-
const reconcileDiscovery = (ctx: Pick<ExtensionContext, "model">) => {
420+
// Instances whose gateway runs tools found through tool_search opt out of
421+
// the full catalog and keep only T3 tools already called in this branch.
422+
const eagerGatewayTools = env(GATEWAY_TOOLS_ENV) !== "called";
423+
const calledToolNames = (ctx: Pick<ExtensionContext, "sessionManager">) => {
424+
const names = new Set<string>();
425+
for (const message of ctx.sessionManager.buildSessionContext().messages) {
426+
if (message.role !== "assistant") continue;
427+
for (const part of message.content) {
428+
if (part.type === "toolCall") names.add(part.name);
429+
}
430+
}
431+
return names;
432+
};
433+
434+
const reconcileDiscovery = (ctx: Pick<ExtensionContext, "model" | "sessionManager">) => {
419435
if (!supportsExposure) return;
420436
// A disabled or replaced search builtin cannot discover deferred tools.
421437
const hasToolSearch = hasBuiltinToolSearch();
@@ -427,10 +443,15 @@ export default async function t3McpExtension(pi: ExtensionAPI) {
427443
// in history or guidance. Eagerly load T3 schemas, including after tree
428444
// restores, while retaining deferred exposure for Pi's allowlist rules.
429445
// Pi still applies --tools/--exclude-tools to this active loadout.
430-
const required = [
431-
...(hasToolSearch ? ["tool_search"] : []),
432-
...(ctx.model?.api === "openai-completions" ? catalog.map((tool) => "mcp__t3-code__" + tool.name) : []),
433-
];
446+
let gatewayTools: string[] = [];
447+
if (ctx.model?.api === "openai-completions") {
448+
gatewayTools = catalog.map((tool) => "mcp__t3-code__" + tool.name);
449+
if (!eagerGatewayTools) {
450+
const called = calledToolNames(ctx);
451+
gatewayTools = gatewayTools.filter((name) => called.has(name));
452+
}
453+
}
454+
const required = [...(hasToolSearch ? ["tool_search"] : []), ...gatewayTools];
434455
const missing = required.filter((name) => !active.includes(name));
435456
if (missing.length > 0) pi.setActiveTools([...active, ...missing]);
436457
};

‎packages/provider-pi/src/server/mcpInjection.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import {
88
PI_T3_MCP_EXTENSION_FILENAME,
99
T3_MCP_BEARER_ENV,
1010
T3_MCP_URL_ENV,
11+
T3_PI_GATEWAY_TOOLS_ENV,
1112
T3_PI_RUNTIME_MODE_ENV,
1213
T3_PI_MCP_EXTENSION_PATH_ENV,
1314
} from "./mcpExtensionSource.ts";
@@ -107,6 +108,21 @@ describe("pi T3 MCP injection", () => {
107108
assert.equal(launch.env[T3_PI_RUNTIME_MODE_ENV], "approval-required");
108109
});
109110

111+
it("passes the completion gateway tool opt-out only to the T3 bridge", () => {
112+
const launch = (options: { readonly eagerCompletionGatewayTools?: boolean }) =>
113+
buildPiRpcLaunch({
114+
launchArgs: [],
115+
environment: { [T3_PI_GATEWAY_TOOLS_ENV]: "called" },
116+
mcpSession,
117+
extensionPath: "/tmp/cache/pi-t3-mcp-extension.ts",
118+
...options,
119+
}).env[T3_PI_GATEWAY_TOOLS_ENV];
120+
121+
assert.isUndefined(launch({}));
122+
assert.isUndefined(launch({ eagerCompletionGatewayTools: true }));
123+
assert.equal(launch({ eagerCompletionGatewayTools: false }), "called");
124+
});
125+
110126
it("forces tools and user extensions off for unattended text generation", () => {
111127
const launch = buildPiRpcLaunch({
112128
launchArgs: [

‎packages/provider-pi/src/server/mcpInjection.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ import {
88
PI_T3_MCP_EXTENSION_SOURCE,
99
T3_MCP_BEARER_ENV,
1010
T3_MCP_URL_ENV,
11+
T3_PI_GATEWAY_TOOLS_ENV,
1112
T3_PI_RUNTIME_MODE_ENV,
1213
T3_PI_MCP_EXTENSION_PATH_ENV,
1314
} from "./mcpExtensionSource.ts";
@@ -250,6 +251,7 @@ export function buildPiRpcLaunch(input: {
250251
readonly disableExtensions?: boolean;
251252
readonly disableTools?: boolean;
252253
readonly runtimeMode?: "approval-required" | "auto-accept-edits" | "auto" | "full-access";
254+
readonly eagerCompletionGatewayTools?: boolean;
253255
}): {
254256
readonly args: ReadonlyArray<string>;
255257
readonly env: NodeJS.ProcessEnv;
@@ -290,6 +292,7 @@ export function buildPiRpcLaunch(input: {
290292
delete environment[T3_MCP_URL_ENV];
291293
delete environment[T3_MCP_BEARER_ENV];
292294
delete environment[T3_PI_MCP_EXTENSION_PATH_ENV];
295+
delete environment[T3_PI_GATEWAY_TOOLS_ENV];
293296

294297
return {
295298
args,
@@ -310,6 +313,9 @@ export function buildPiRpcLaunch(input: {
310313
[T3_MCP_BEARER_ENV]: bearerTokenFromAuthorizationHeader(
311314
input.mcpSession.authorizationHeader,
312315
),
316+
...(input.eagerCompletionGatewayTools === false
317+
? { [T3_PI_GATEWAY_TOOLS_ENV]: "called" }
318+
: {}),
313319
}
314320
: {}),
315321
},

‎packages/provider-pi/src/server/status.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@ const settings = {
115115
enabled: true,
116116
binaryPath: "pi",
117117
launchArgs: "",
118+
eagerCompletionGatewayTools: true,
118119
customModels: [],
119120
} as const;
120121

‎packages/provider-pi/src/server/textGeneration.test.ts‎

Lines changed: 14 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,13 @@ it.effect("puts linked source control context in the Pi thread title prompt", ()
6767
Effect.gen(function* () {
6868
const pi = yield* makeFakePi(encodeJsonLine({ title: "Route Reset Credits Through Hub" }));
6969
const textGeneration = yield* makePiTextGeneration(
70-
{ enabled: true, binaryPath: "pi", launchArgs: "", customModels: [] },
70+
{
71+
enabled: true,
72+
binaryPath: "pi",
73+
launchArgs: "",
74+
eagerCompletionGatewayTools: true,
75+
customModels: [],
76+
},
7177
{},
7278
).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, pi.spawner));
7379

@@ -90,7 +96,13 @@ it.effect("names the model and the disabled extensions when Pi cannot load it",
9096
Effect.gen(function* () {
9197
const pi = yield* makeFakePi("", "Model not found: demo/demo-model");
9298
const textGeneration = yield* makePiTextGeneration(
93-
{ enabled: true, binaryPath: "pi", launchArgs: "", customModels: [] },
99+
{
100+
enabled: true,
101+
binaryPath: "pi",
102+
launchArgs: "",
103+
eagerCompletionGatewayTools: true,
104+
customModels: [],
105+
},
94106
{},
95107
).pipe(Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, pi.spawner));
96108

0 commit comments

Comments
 (0)