@diegopetrucci/pi-fast 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1 @@
1
+ 0.83.0
package/README.md ADDED
@@ -0,0 +1,119 @@
1
+ # fast
2
+
3
+ A pi extension that provides one `/fast` toggle for supported OpenAI Codex and Anthropic Claude models. It selects the provider-specific Fast-mode request shape from the currently selected model.
4
+
5
+ For eligible OpenAI Codex models it injects:
6
+
7
+ ```json
8
+ {
9
+ "service_tier": "priority"
10
+ }
11
+ ```
12
+
13
+ For eligible Anthropic Claude models it injects:
14
+
15
+ ```json
16
+ {
17
+ "speed": "fast"
18
+ }
19
+ ```
20
+
21
+ It also adds the required Anthropic beta header value:
22
+
23
+ ```text
24
+ anthropic-beta: fast-mode-2026-02-01
25
+ ```
26
+
27
+ ## Eligibility
28
+
29
+ OpenAI Fast mode requires all of the following:
30
+
31
+ - Provider `openai-codex`.
32
+ - API `openai-codex-responses`.
33
+ - Model `gpt-5.4`, `gpt-5.5`, `gpt-5.6-sol`, `gpt-5.6-terra`, or `gpt-5.6-luna`.
34
+ - ChatGPT OAuth/subscription auth, not API-key auth.
35
+ - No existing `service_tier` field in the request payload.
36
+
37
+ Anthropic Fast mode requires all of the following:
38
+
39
+ - Provider `anthropic`.
40
+ - API `anthropic-messages`.
41
+ - Model `claude-opus-4-6`, `claude-opus-4-7`, or `claude-opus-4-8`.
42
+ - No existing `speed` field in the request payload.
43
+
44
+ Anthropic Fast mode supports both API-key and Claude Code OAuth access when the account has access to the research preview.
45
+
46
+ ## Commands
47
+
48
+ ```text
49
+ /fast
50
+ ```
51
+
52
+ Run `/fast` to toggle Fast mode for the current session/runtime. The enabled state follows model changes: switching between eligible OpenAI and Anthropic models automatically changes the request format without resetting the toggle. The footer shows `fast` only while the selected model is eligible and Fast mode is enabled.
53
+
54
+ The extension defaults to off so installing the full collection does not accidentally spend Fast-mode credits.
55
+
56
+ ## Config
57
+
58
+ Optional global config:
59
+
60
+ ```text
61
+ ~/<pi-config-dir>/agent/extensions/fast.json
62
+ ```
63
+
64
+ Optional project config:
65
+
66
+ ```text
67
+ <project>/<pi-config-dir>/fast.json
68
+ ```
69
+
70
+ Here `<pi-config-dir>` is Pi's runtime config directory name (`CONFIG_DIR_NAME`; `.pi` by default). Project config overrides global config after Pi reports that the project is trusted.
71
+
72
+ ```json
73
+ {
74
+ "enabled": false,
75
+ "showStatus": true
76
+ }
77
+ ```
78
+
79
+ - `enabled`: default Fast-mode state when there is no session override.
80
+ - `showStatus`: show a compact `fast` status when Fast mode is active for the selected model.
81
+
82
+ The unified extension intentionally does not read `openai-fast.json` or `claude-fast.json`; those files belong to the provider-specific standalone packages and may contain conflicting defaults.
83
+
84
+ ## Install
85
+
86
+ ### Standalone npm package
87
+
88
+ ```bash
89
+ pi install npm:@diegopetrucci/pi-fast
90
+ ```
91
+
92
+ ### Collection package
93
+
94
+ ```bash
95
+ pi install npm:@diegopetrucci/pi-extensions
96
+ ```
97
+
98
+ ### GitHub package
99
+
100
+ ```bash
101
+ pi install git:github.com/diegopetrucci/pi-extensions
102
+ ```
103
+
104
+ Then reload pi:
105
+
106
+ ```text
107
+ /reload
108
+ ```
109
+
110
+ ## Legacy provider-specific packages
111
+
112
+ The collection package loads this unified extension instead of `openai-fast` and `claude-fast`. Both provider-specific packages remain available as standalone alternatives. Do not load them together with this extension: independent Fast-mode state and duplicate `/fast` registrations can produce conflicting behavior.
113
+
114
+ ## Notes
115
+
116
+ - Anthropic Fast mode has separate rate limits, costs more than standard speed, and does not share prompt-cache prefixes with standard-speed requests.
117
+ - OpenAI Fast mode intentionally does not affect API-key models.
118
+ - Existing `speed` and `service_tier` fields are never overwritten.
119
+ - Cost accounting still depends on the provider reporting the effective tier in its streamed response.
@@ -0,0 +1,4 @@
1
+ {
2
+ "enabled": false,
3
+ "showStatus": true
4
+ }
package/index.ts ADDED
@@ -0,0 +1,383 @@
1
+ import { existsSync, readFileSync } from "node:fs";
2
+ import { dirname, join } from "node:path";
3
+ import {
4
+ CONFIG_DIR_NAME,
5
+ getAgentDir,
6
+ type ExtensionAPI,
7
+ type ExtensionContext,
8
+ } from "@earendil-works/pi-coding-agent";
9
+
10
+ const EXTENSION_ID = "fast";
11
+ const ANTHROPIC_PROVIDER_ID = "anthropic";
12
+ const ANTHROPIC_API_ID = "anthropic-messages";
13
+ const ANTHROPIC_FAST_SPEED = "fast";
14
+ const ANTHROPIC_FAST_BETA = "fast-mode-2026-02-01";
15
+ const CLAUDE_CODE_OAUTH_BETAS = ["claude-code-20250219", "oauth-2025-04-20"];
16
+ const FINE_GRAINED_TOOL_STREAMING_BETA = "fine-grained-tool-streaming-2025-05-14";
17
+ const INTERLEAVED_THINKING_BETA = "interleaved-thinking-2025-05-14";
18
+ const ANTHROPIC_SUPPORTED_MODELS = new Set(["claude-opus-4-6", "claude-opus-4-7", "claude-opus-4-8"]);
19
+
20
+ const OPENAI_PROVIDER_ID = "openai-codex";
21
+ const OPENAI_API_ID = "openai-codex-responses";
22
+ const OPENAI_FAST_SERVICE_TIER = "priority";
23
+ const OPENAI_SUPPORTED_MODELS = new Set([
24
+ "gpt-5.4",
25
+ "gpt-5.5",
26
+ "gpt-5.6-sol",
27
+ "gpt-5.6-terra",
28
+ "gpt-5.6-luna",
29
+ ]);
30
+
31
+ const DEFAULT_CONFIG: FastConfig = {
32
+ enabled: false,
33
+ showStatus: true,
34
+ };
35
+
36
+ type FastOverride = "auto" | "on" | "off";
37
+ type FastProvider = "anthropic" | "openai";
38
+
39
+ type FastConfig = {
40
+ /** Default Fast-mode state when there is no session override. */
41
+ enabled: boolean;
42
+ /** Show a compact `fast` status when Fast mode is active for the current model. */
43
+ showStatus: boolean;
44
+ };
45
+
46
+ type SessionState = {
47
+ config: FastConfig;
48
+ override: FastOverride;
49
+ lastInjectedAt?: number;
50
+ lastInjectedModel?: string;
51
+ };
52
+
53
+ type ProjectConfigContext = {
54
+ cwd: string;
55
+ isProjectTrusted?: () => boolean;
56
+ };
57
+
58
+ type RecursivePartial<T> = {
59
+ [P in keyof T]?: T[P] extends object ? RecursivePartial<T[P]> : T[P];
60
+ };
61
+
62
+ type PayloadRecord = Record<string, unknown>;
63
+
64
+ type AnthropicHeaderCompat = {
65
+ forceAdaptiveThinking?: boolean;
66
+ supportsEagerToolInputStreaming?: boolean;
67
+ };
68
+
69
+ type Eligibility = {
70
+ eligible: boolean;
71
+ modelKey: string;
72
+ provider?: FastProvider;
73
+ reason?: string;
74
+ };
75
+
76
+ function readConfigFile(path: string): RecursivePartial<FastConfig> {
77
+ if (!existsSync(path)) return {};
78
+
79
+ try {
80
+ const parsed = JSON.parse(readFileSync(path, "utf-8"));
81
+ return isPayloadRecord(parsed) ? (parsed as RecursivePartial<FastConfig>) : {};
82
+ } catch (error) {
83
+ console.error(`Warning: Could not parse ${path}: ${error}`);
84
+ return {};
85
+ }
86
+ }
87
+
88
+ function normalizeBoolean(value: unknown, fallback: boolean): boolean {
89
+ return typeof value === "boolean" ? value : fallback;
90
+ }
91
+
92
+ function mergeConfig(base: FastConfig, overrides: RecursivePartial<FastConfig>): FastConfig {
93
+ return {
94
+ enabled: normalizeBoolean(overrides.enabled, base.enabled),
95
+ showStatus: normalizeBoolean(overrides.showStatus, base.showStatus),
96
+ };
97
+ }
98
+
99
+ function canReadProjectConfig(ctx: ProjectConfigContext): boolean {
100
+ return typeof ctx.isProjectTrusted === "function" && ctx.isProjectTrusted();
101
+ }
102
+
103
+ function findProjectConfigPath(cwd: string): string {
104
+ let current = cwd;
105
+ while (true) {
106
+ const candidate = join(current, CONFIG_DIR_NAME, "fast.json");
107
+ if (existsSync(candidate)) return candidate;
108
+
109
+ const parent = dirname(current);
110
+ if (parent === current) return join(cwd, CONFIG_DIR_NAME, "fast.json");
111
+ current = parent;
112
+ }
113
+ }
114
+
115
+ function loadConfig(ctx: ProjectConfigContext): FastConfig {
116
+ const globalConfig = readConfigFile(join(getAgentDir(), "extensions", "fast.json"));
117
+ const projectConfig = canReadProjectConfig(ctx) ? readConfigFile(findProjectConfigPath(ctx.cwd)) : {};
118
+ return mergeConfig(mergeConfig(DEFAULT_CONFIG, globalConfig), projectConfig);
119
+ }
120
+
121
+ function isPayloadRecord(payload: unknown): payload is PayloadRecord {
122
+ return typeof payload === "object" && payload !== null && !Array.isArray(payload);
123
+ }
124
+
125
+ function modelKey(ctx: ExtensionContext): string {
126
+ const model = ctx.model;
127
+ return model ? `${model.provider}/${model.id}` : "no-model";
128
+ }
129
+
130
+ function isFastEnabled(state: SessionState): boolean {
131
+ if (state.override === "on") return true;
132
+ if (state.override === "off") return false;
133
+ return state.config.enabled;
134
+ }
135
+
136
+ function describeMode(state: SessionState): string {
137
+ if (state.override === "on") return "on (session override)";
138
+ if (state.override === "off") return "off (session override)";
139
+ return state.config.enabled ? "on (config default)" : "off (config default)";
140
+ }
141
+
142
+ function getEligibility(ctx: ExtensionContext): Eligibility {
143
+ const model = ctx.model;
144
+ if (!model) {
145
+ return { eligible: false, modelKey: "no-model", reason: "no model is selected" };
146
+ }
147
+
148
+ const key = `${model.provider}/${model.id}`;
149
+ if (model.provider === ANTHROPIC_PROVIDER_ID) {
150
+ if (model.api !== ANTHROPIC_API_ID) {
151
+ return {
152
+ eligible: false,
153
+ modelKey: key,
154
+ reason: `current API is ${model.api}, not ${ANTHROPIC_API_ID}`,
155
+ };
156
+ }
157
+
158
+ if (!ANTHROPIC_SUPPORTED_MODELS.has(model.id)) {
159
+ return {
160
+ eligible: false,
161
+ modelKey: key,
162
+ reason: "Fast mode is only enabled for Claude Opus 4.6, 4.7, and 4.8",
163
+ };
164
+ }
165
+
166
+ return { eligible: true, modelKey: key, provider: "anthropic" };
167
+ }
168
+
169
+ if (model.provider === OPENAI_PROVIDER_ID) {
170
+ if (model.api !== OPENAI_API_ID) {
171
+ return {
172
+ eligible: false,
173
+ modelKey: key,
174
+ reason: `current API is ${model.api}, not ${OPENAI_API_ID}`,
175
+ };
176
+ }
177
+
178
+ if (!OPENAI_SUPPORTED_MODELS.has(model.id)) {
179
+ return {
180
+ eligible: false,
181
+ modelKey: key,
182
+ reason: "Fast mode is not enabled for this OpenAI Codex model",
183
+ };
184
+ }
185
+
186
+ if (!ctx.modelRegistry.isUsingOAuth(model)) {
187
+ return {
188
+ eligible: false,
189
+ modelKey: key,
190
+ reason: "ChatGPT OAuth auth is required; API-key auth is intentionally not used",
191
+ };
192
+ }
193
+
194
+ return { eligible: true, modelKey: key, provider: "openai" };
195
+ }
196
+
197
+ return {
198
+ eligible: false,
199
+ modelKey: key,
200
+ reason: `current provider ${model.provider} does not support this extension's Fast mode`,
201
+ };
202
+ }
203
+
204
+ function updateStatus(ctx: ExtensionContext, state: SessionState): void {
205
+ if (!ctx.hasUI) return;
206
+ if (!state.config.showStatus) {
207
+ ctx.ui.setStatus(EXTENSION_ID, undefined);
208
+ return;
209
+ }
210
+
211
+ const eligibility = getEligibility(ctx);
212
+ ctx.ui.setStatus(
213
+ EXTENSION_ID,
214
+ isFastEnabled(state) && eligibility.eligible ? "fast" : undefined,
215
+ );
216
+ }
217
+
218
+ function getStatusMessage(ctx: ExtensionContext, state: SessionState): string {
219
+ const enabled = isFastEnabled(state);
220
+ const eligibility = getEligibility(ctx);
221
+ const active = enabled && eligibility.eligible;
222
+ const injected = state.lastInjectedAt
223
+ ? ` Last injected for ${state.lastInjectedModel ?? "unknown model"} ${Math.max(0, Math.round((Date.now() - state.lastInjectedAt) / 1000))}s ago.`
224
+ : "";
225
+
226
+ if (active) {
227
+ const wireSetting =
228
+ eligibility.provider === "anthropic"
229
+ ? `speed=${ANTHROPIC_FAST_SPEED}`
230
+ : `service_tier=${OPENAI_FAST_SERVICE_TIER}`;
231
+ return `Fast mode is ${describeMode(state)} and active for ${eligibility.modelKey}; requests will use ${wireSetting}.${injected}`;
232
+ }
233
+
234
+ if (enabled) {
235
+ return `Fast mode is ${describeMode(state)}, but inactive for ${eligibility.modelKey}: ${eligibility.reason}.${injected}`;
236
+ }
237
+
238
+ return `Fast mode is ${describeMode(state)}. Current model: ${eligibility.modelKey}.${injected}`;
239
+ }
240
+
241
+ function splitBetaHeader(value: string | null | undefined): string[] {
242
+ return (value ?? "")
243
+ .split(",")
244
+ .map((part) => part.trim())
245
+ .filter(Boolean);
246
+ }
247
+
248
+ async function isAnthropicOAuth(ctx: ExtensionContext): Promise<boolean> {
249
+ try {
250
+ const resolution = await ctx.modelRegistry.getProviderAuth(ANTHROPIC_PROVIDER_ID);
251
+ const apiKey = resolution?.auth.apiKey;
252
+ if (typeof apiKey === "string") return apiKey.includes("sk-ant-oat");
253
+ } catch {
254
+ // Fall back to the synchronous registry snapshot below.
255
+ }
256
+
257
+ return ctx.model ? ctx.modelRegistry.isUsingOAuth(ctx.model) : false;
258
+ }
259
+
260
+ function getAnthropicProviderBetas(ctx: ExtensionContext, hasActiveTools: boolean): string[] {
261
+ const model = ctx.model;
262
+ if (!model) return [];
263
+ const compat = model.compat as AnthropicHeaderCompat | undefined;
264
+
265
+ const betas: string[] = [];
266
+ if (hasActiveTools && compat?.supportsEagerToolInputStreaming === false) {
267
+ betas.push(FINE_GRAINED_TOOL_STREAMING_BETA);
268
+ }
269
+ if (compat?.forceAdaptiveThinking !== true) {
270
+ betas.push(INTERLEAVED_THINKING_BETA);
271
+ }
272
+ return betas;
273
+ }
274
+
275
+ async function injectAnthropicFastHeader(
276
+ headers: Record<string, string | null>,
277
+ ctx: ExtensionContext,
278
+ state: SessionState,
279
+ hasActiveTools: boolean,
280
+ ): Promise<void> {
281
+ if (!isFastEnabled(state)) return;
282
+ const eligibility = getEligibility(ctx);
283
+ if (!eligibility.eligible || eligibility.provider !== "anthropic") return;
284
+
285
+ const matchingKeys = Object.keys(headers).filter((name) => name.toLowerCase() === "anthropic-beta");
286
+ const existing = matchingKeys.flatMap((name) => splitBetaHeader(headers[name]));
287
+ const matchingModelEntries = Object.entries(ctx.model?.headers ?? {}).filter(
288
+ ([name]) => name.toLowerCase() === "anthropic-beta",
289
+ );
290
+ const modelBetas = matchingModelEntries.flatMap(([, value]) => splitBetaHeader(value));
291
+ const providerBetas = getAnthropicProviderBetas(ctx, hasActiveTools);
292
+ const oauthBetas = (await isAnthropicOAuth(ctx)) ? CLAUDE_CODE_OAUTH_BETAS : [];
293
+ const next = Array.from(
294
+ new Set([...modelBetas, ...existing, ...oauthBetas, ...providerBetas, ANTHROPIC_FAST_BETA]),
295
+ );
296
+
297
+ for (const key of matchingKeys) delete headers[key];
298
+ const outputKey = matchingModelEntries.at(-1)?.[0] ?? "anthropic-beta";
299
+ headers[outputKey] = next.join(",");
300
+ }
301
+
302
+ function injectFastPayload(
303
+ payload: unknown,
304
+ ctx: ExtensionContext,
305
+ state: SessionState,
306
+ ): PayloadRecord | undefined {
307
+ if (!isFastEnabled(state)) return undefined;
308
+ const eligibility = getEligibility(ctx);
309
+ if (!eligibility.eligible || !eligibility.provider) return undefined;
310
+ if (!isPayloadRecord(payload)) return undefined;
311
+ if (payload.model !== ctx.model?.id) return undefined;
312
+
313
+ if (eligibility.provider === "anthropic") {
314
+ if ("speed" in payload) return undefined;
315
+ state.lastInjectedAt = Date.now();
316
+ state.lastInjectedModel = eligibility.modelKey;
317
+ return { ...payload, speed: ANTHROPIC_FAST_SPEED };
318
+ }
319
+
320
+ if ("service_tier" in payload) return undefined;
321
+ state.lastInjectedAt = Date.now();
322
+ state.lastInjectedModel = eligibility.modelKey;
323
+ return { ...payload, service_tier: OPENAI_FAST_SERVICE_TIER };
324
+ }
325
+
326
+ export default function fastExtension(pi: ExtensionAPI) {
327
+ const states = new WeakMap<object, SessionState>();
328
+
329
+ function getState(ctx: ExtensionContext): SessionState {
330
+ let state = states.get(ctx.sessionManager);
331
+ if (!state) {
332
+ state = {
333
+ config: loadConfig(ctx),
334
+ override: "auto",
335
+ };
336
+ states.set(ctx.sessionManager, state);
337
+ }
338
+ return state;
339
+ }
340
+
341
+ pi.on("session_start", (_event, ctx) => {
342
+ const state: SessionState = {
343
+ config: loadConfig(ctx),
344
+ override: "auto",
345
+ };
346
+ states.set(ctx.sessionManager, state);
347
+ updateStatus(ctx, state);
348
+ });
349
+
350
+ pi.on("model_select", (_event, ctx) => {
351
+ updateStatus(ctx, getState(ctx));
352
+ });
353
+
354
+ pi.on("before_provider_headers", async (event, ctx) => {
355
+ const hasActiveTools = typeof pi.getActiveTools === "function" && pi.getActiveTools().length > 0;
356
+ await injectAnthropicFastHeader(event.headers, ctx, getState(ctx), hasActiveTools);
357
+ });
358
+
359
+ pi.on("before_provider_request", (event, ctx) => {
360
+ const state = getState(ctx);
361
+ const nextPayload = injectFastPayload(event.payload, ctx, state);
362
+ updateStatus(ctx, state);
363
+ return nextPayload;
364
+ });
365
+
366
+ pi.registerCommand("fast", {
367
+ description: "Toggle Fast mode for supported OpenAI Codex and Anthropic Claude models",
368
+ getArgumentCompletions: () => null,
369
+ handler: async (args, ctx) => {
370
+ const state = getState(ctx);
371
+ const action = args.trim();
372
+
373
+ if (!action) {
374
+ state.override = isFastEnabled(state) ? "off" : "on";
375
+ updateStatus(ctx, state);
376
+ ctx.ui.notify(getStatusMessage(ctx, state), "info");
377
+ return;
378
+ }
379
+
380
+ ctx.ui.notify("Usage: /fast", "warning");
381
+ },
382
+ });
383
+ }
package/package.json ADDED
@@ -0,0 +1,39 @@
1
+ {
2
+ "name": "@diegopetrucci/pi-fast",
3
+ "version": "0.1.0",
4
+ "description": "A pi extension that enables Fast mode for supported OpenAI Codex and Anthropic Claude models based on the currently selected model.",
5
+ "keywords": [
6
+ "pi-package",
7
+ "pi",
8
+ "openai",
9
+ "anthropic",
10
+ "fast"
11
+ ],
12
+ "license": "MIT",
13
+ "repository": {
14
+ "type": "git",
15
+ "url": "git+https://github.com/diegopetrucci/pi-extensions.git",
16
+ "directory": "extensions/fast"
17
+ },
18
+ "files": [
19
+ "index.ts",
20
+ "fast.example.json",
21
+ "README.md",
22
+ ".pi-fleet-tested-version"
23
+ ],
24
+ "publishConfig": {
25
+ "access": "public"
26
+ },
27
+ "pi": {
28
+ "extensions": [
29
+ "index.ts"
30
+ ]
31
+ },
32
+ "peerDependencies": {
33
+ "@earendil-works/pi-coding-agent": "*"
34
+ },
35
+ "type": "module",
36
+ "engines": {
37
+ "node": ">=22.19.0"
38
+ }
39
+ }