pi-fast-mode 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuri Huang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,302 @@
+# pi-fast-mode
+
+<p align="center">
+  <img src="./showcase.png" alt="pi-fast-mode showcase" width="960" />
+</p>
+
+`pi-fast-mode` is a pi extension/package that toggles fast mode for selected models by injecting `service_tier` into provider requests.
+
+It follows the same packaging approach as `pi-hodor`:
+
+- normal pi package structure
+- bundled default config
+- optional global config bootstrap command
+- project/global/bundled config resolution
+- persistent per-session and per-branch on/off state
+
+## What it does
+
+When fast mode is enabled and the current `provider/model` matches a configured target, the extension patches the outgoing provider payload to include:
+
+```json
+{
+  "service_tier": "priority"
+}
+```
+
+This is useful when you want a lightweight toggle in pi without changing your provider or model definitions.
+
+## Features
+
+- `/fast` toggle command
+- `/fast on|off|status|reload`
+- `Ctrl+Shift+F` keyboard shortcut
+- `--fast` CLI flag for starting a session with fast mode enabled
+- supports custom provider names and custom model ids
+- supports custom `serviceTier` values per target
+- remembers the last on/off state when the session is resumed
+- restores the saved state when navigating branches with `/tree`
+- shows status in the footer while fast mode is active
+- supports project-local, global, legacy-global, and bundled config files
+
+## Requirements
+
+- pi with extension support
+- Node.js 20+
+
+## Installation
+
+### Install from npm
+
+```bash
+pi install npm:pi-fast-mode
+```
+
+### Install from git
+
+```bash
+pi install git:github.com/vurihuang/pi-fast-mode
+```
+
+### Install from a local path
+
+```bash
+pi install /absolute/path/to/pi-fast-mode
+```
+
+Restart pi after installation so the extension is loaded.
+
+## Quick start
+
+### 1. Bootstrap the global config
+
+```text
+/pi-fast-mode:setup
+```
+
+This creates:
+
+```text
+~/.pi/agent/extensions/pi-fast-mode/config.json
+```
+
+if it does not already exist.
+
+### 2. Edit the config
+
+Example:
+
+```json
+{
+  "targets": [
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.4",
+      "serviceTier": "priority"
+    },
+    {
+      "provider": "my-proxy",
+      "model": "gpt-5-4",
+      "serviceTier": "priority"
+    }
+  ]
+}
+```
+
+### 3. Toggle fast mode
+
+```text
+/fast
+```
+
+## Usage
+
+### Slash command
+
+```text
+/fast
+```
+
+### Explicit control
+
+```text
+/fast on
+/fast off
+/fast status
+/fast reload
+```
+
+### Keyboard shortcut
+
+```text
+Ctrl+Shift+F
+```
+
+### CLI flag
+
+```bash
+pi --fast
+```
+
+`--fast` makes the current session start with fast mode enabled, regardless of the previously saved state.
+
+## Configuration
+
+Config is resolved in this order:
+
+1. `./.pi-fast-mode.json`
+2. `./.pi/pi-fast-mode.json`
+3. `~/.pi/agent/extensions/pi-fast-mode/config.json`
+4. legacy fallback: `~/.pi/agent/extensions/fast-mode.json`
+5. bundled `config.json`
+
+That means:
+
+- project config overrides global config
+- global config overrides the bundled defaults
+- the legacy single-file path still works as a compatibility fallback
+
+### Config schema
+
+```json
+{
+  "targets": [
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.4",
+      "serviceTier": "priority"
+    }
+  ]
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `targets` | `FastTarget[]` | Allowlist of provider/model pairs that should receive `service_tier`. |
+| `targets[].provider` | `string` | Exact pi provider name. Official and unofficial provider names are both supported. |
+| `targets[].model` | `string` | Exact pi model id. Official and unofficial model ids are both supported. |
+| `targets[].serviceTier` | `string` | Value written as `service_tier`. Defaults to `priority` when omitted. |
+
+### Matching behavior
+
+Matching is done with exact string equality against:
+
+- `ctx.model.provider`
+- `ctx.model.id`
+
+So this works with:
+
+- built-in providers and models
+- providers added via `models.json`
+- providers registered through other extensions
+- unofficial model names
+
+### Example configs
+
+#### Default Codex target
+
+```json
+{
+  "targets": [
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.4"
+    }
+  ]
+}
+```
+
+#### Multiple custom providers
+
+```json
+{
+  "targets": [
+    {
+      "provider": "my-proxy",
+      "model": "gpt-5.4",
+      "serviceTier": "priority"
+    },
+    {
+      "provider": "openrouter",
+      "model": "openai/gpt-5.4",
+      "serviceTier": "priority"
+    },
+    {
+      "provider": "local-gateway",
+      "model": "gpt-5.4",
+      "serviceTier": "priority"
+    }
+  ]
+}
+```
+
+## Persistence behavior
+
+Fast mode state is stored in the session as custom entries.
+
+That means:
+
+- if you turn fast mode on, quit pi, and resume the same session, it comes back on
+- if you turn it off and resume the same session, it stays off
+- if you switch branches with `/tree`, the extension restores the saved state for that branch
+
+This persistence is session-aware and branch-aware.
+
+## Notes and limitations
+
+- The extension only patches request payloads when fast mode is enabled.
+- It only patches requests for configured provider/model pairs.
+- It does not validate whether a provider actually supports `service_tier`.
+- If a provider ignores unknown fields, the request will continue normally.
+- `/fast reload` reloads config from disk without restarting pi.
+
+## Development
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run type-check:
+
+```bash
+npm run check
+```
+
+Run release verification:
+
+```bash
+npm run release:check
+```
+
+Preview the package contents:
+
+```bash
+npm run pack:check
+```
+
+## Publishing checklist
+
+Before publishing:
+
+1. update `version` in `package.json`
+2. verify `repository`, `homepage`, and `bugs` URLs
+3. run `npm run release:check`
+4. confirm the tarball only contains intended files
+5. publish with npm if desired
+
+## Package structure
+
+```text
+.
+├── config.json
+├── index.ts
+├── LICENSE
+├── README.md
+├── package.json
+├── package-lock.json
+└── tsconfig.json
+```

package/config.json

@@ -0,0 +1,9 @@
+{
+  "targets": [
+    {
+      "provider": "openai-codex",
+      "model": "gpt-5.4",
+      "serviceTier": "priority"
+    }
+  ]
+}

package/index.ts

@@ -0,0 +1,370 @@
+import { access, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { Key } from "@mariozechner/pi-tui";
+
+type NotifyLevel = "info" | "warning" | "error";
+type ActiveModel = ExtensionContext["model"];
+
+type FastModeState = {
+	enabled?: boolean;
+};
+
+type FastTarget = {
+	provider: string;
+	model: string;
+	serviceTier?: string;
+};
+
+type FastModeConfig = {
+	targets: FastTarget[];
+};
+
+const EXTENSION_NAME = "pi-fast-mode";
+const ENTRY_TYPE = "fast-mode";
+const STATUS_ID = "fast-mode";
+const BUNDLED_CONFIG_PATH = join(__dirname, "config.json");
+const GLOBAL_CONFIG_PATH = join(getAgentDir(), "extensions", EXTENSION_NAME, "config.json");
+const LEGACY_GLOBAL_CONFIG_PATH = join(getAgentDir(), "extensions", "fast-mode.json");
+const PROJECT_CONFIG_CANDIDATES = [
+	".pi-fast-mode.json",
+	join(".pi", "pi-fast-mode.json"),
+] as const;
+const DEFAULT_CONFIG: FastModeConfig = {
+	targets: [{ provider: "openai-codex", model: "gpt-5.4", serviceTier: "priority" }],
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function getModelLabel(model: ActiveModel): string {
+	return model ? `${model.provider}/${model.id}` : "no model selected";
+}
+
+function normalizeTarget(raw: unknown): FastTarget | undefined {
+	if (!isRecord(raw)) return undefined;
+
+	const provider = typeof raw.provider === "string" ? raw.provider.trim() : "";
+	const model = typeof raw.model === "string" ? raw.model.trim() : "";
+	const serviceTier =
+		typeof raw.serviceTier === "string"
+			? raw.serviceTier.trim()
+			: typeof raw.service_tier === "string"
+				? raw.service_tier.trim()
+				: "";
+
+	if (!provider || !model) return undefined;
+	return {
+		provider,
+		model,
+		...(serviceTier ? { serviceTier } : {}),
+	};
+}
+
+function normalizeConfig(raw: unknown): FastModeConfig {
+	if (!isRecord(raw) || !Array.isArray(raw.targets)) {
+		return { targets: [...DEFAULT_CONFIG.targets] };
+	}
+
+	const targets = raw.targets
+		.map((target) => normalizeTarget(target))
+		.filter((target): target is FastTarget => target !== undefined);
+
+	return { targets };
+}
+
+function dedupeTargets(targets: FastTarget[]): FastTarget[] {
+	const byKey = new Map<string, FastTarget>();
+	for (const target of targets) {
+		byKey.set(`${target.provider}/${target.model}`, target);
+	}
+	return [...byKey.values()];
+}
+
+function getMatchingTarget(model: ActiveModel, targets: FastTarget[]): FastTarget | undefined {
+	if (!model) return undefined;
+	return targets.find((target) => target.provider === model.provider && target.model === model.id);
+}
+
+function getSavedStateFromBranch(ctx: ExtensionContext): boolean | undefined {
+	const entries = ctx.sessionManager.getBranch();
+	for (let i = entries.length - 1; i >= 0; i -= 1) {
+		const entry = entries[i];
+		if (entry.type !== "custom" || entry.customType !== ENTRY_TYPE || !isRecord(entry.data)) continue;
+		const enabled = (entry.data as FastModeState).enabled;
+		if (typeof enabled === "boolean") return enabled;
+	}
+	return undefined;
+}
+
+function safeNotify(ctx: ExtensionContext, message: string, level: NotifyLevel): void {
+	if (!ctx.hasUI) return;
+	ctx.ui.notify(message, level);
+}
+
+async function pathExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function ensureBundledConfigFile(): Promise<void> {
+	try {
+		await access(BUNDLED_CONFIG_PATH);
+	} catch {
+		await writeFile(BUNDLED_CONFIG_PATH, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf8");
+	}
+}
+
+async function resolveConfigPath(cwd: string): Promise<string> {
+	for (const relativePath of PROJECT_CONFIG_CANDIDATES) {
+		const candidatePath = join(cwd, relativePath);
+		if (await pathExists(candidatePath)) return candidatePath;
+	}
+
+	if (await pathExists(GLOBAL_CONFIG_PATH)) return GLOBAL_CONFIG_PATH;
+	if (await pathExists(LEGACY_GLOBAL_CONFIG_PATH)) return LEGACY_GLOBAL_CONFIG_PATH;
+	return BUNDLED_CONFIG_PATH;
+}
+
+async function copyBundledConfig(destinationPath: string): Promise<void> {
+	await ensureBundledConfigFile();
+	await mkdir(dirname(destinationPath), { recursive: true });
+	await copyFile(BUNDLED_CONFIG_PATH, destinationPath);
+}
+
+export default function fastModeExtension(pi: ExtensionAPI): void {
+	let fastModeEnabled = false;
+	let currentModel: ActiveModel;
+	let configuredTargets: FastTarget[] = [...DEFAULT_CONFIG.targets];
+	let resolvedConfigPath = BUNDLED_CONFIG_PATH;
+	const lastConfigError: { value?: string } = {};
+
+	function activeModel(ctx?: ExtensionContext): ActiveModel {
+		return currentModel ?? ctx?.model;
+	}
+
+	function configuredTargetsText(): string {
+		return configuredTargets.length > 0
+			? configuredTargets.map((target) => `${target.provider}/${target.model}`).join(", ")
+			: "none";
+	}
+
+	async function refreshConfig(cwd: string, ctx?: ExtensionContext): Promise<void> {
+		await ensureBundledConfigFile();
+		const configPath = await resolveConfigPath(cwd);
+		resolvedConfigPath = configPath;
+
+		try {
+			const parsed = normalizeConfig(JSON.parse(await readFile(configPath, "utf8")));
+			configuredTargets = dedupeTargets(parsed.targets);
+			lastConfigError.value = undefined;
+		} catch (error) {
+			configuredTargets = [...DEFAULT_CONFIG.targets];
+			const message = error instanceof Error ? error.message : String(error);
+			const errorKey = `${configPath}:${message}`;
+			if (lastConfigError.value !== errorKey) {
+				lastConfigError.value = errorKey;
+				if (ctx) {
+					safeNotify(
+						ctx,
+						`[${EXTENSION_NAME}] Failed to read config from ${configPath}. Falling back to bundled defaults: ${message}`,
+						"warning",
+					);
+				}
+			}
+		}
+	}
+
+	function statusText(ctx?: ExtensionContext): string {
+		const model = activeModel(ctx);
+		if (!fastModeEnabled) {
+			return `Fast mode is OFF. Config: ${resolvedConfigPath}`;
+		}
+
+		const target = getMatchingTarget(model, configuredTargets);
+		if (target) {
+			return `Fast mode is ON for ${getModelLabel(model)} (service_tier=${target.serviceTier ?? "priority"}). Config: ${resolvedConfigPath}`;
+		}
+
+		if (configuredTargets.length === 0) {
+			return `Fast mode is ON, but no targets are configured in ${resolvedConfigPath}.`;
+		}
+
+		return `Fast mode is ON, but ${getModelLabel(model)} is not enabled in ${resolvedConfigPath}. Enabled targets: ${configuredTargetsText()}.`;
+	}
+
+	function updateStatus(ctx: ExtensionContext): void {
+		if (!ctx.hasUI) return;
+		if (!fastModeEnabled) {
+			ctx.ui.setStatus(STATUS_ID, undefined);
+			return;
+		}
+
+		const target = getMatchingTarget(activeModel(ctx), configuredTargets);
+		if (target) {
+			ctx.ui.setStatus(STATUS_ID, ctx.ui.theme.fg("accent", "⚡ fast"));
+			return;
+		}
+
+		ctx.ui.setStatus(STATUS_ID, ctx.ui.theme.fg("warning", "⚡ fast*"));
+	}
+
+	function persistState(): void {
+		pi.appendEntry<FastModeState>(ENTRY_TYPE, { enabled: fastModeEnabled });
+	}
+
+	function notifyState(ctx: ExtensionContext): void {
+		safeNotify(
+			ctx,
+			statusText(ctx),
+			fastModeEnabled && !getMatchingTarget(activeModel(ctx), configuredTargets) ? "warning" : "info",
+		);
+	}
+
+	function applyEnabledState(enabled: boolean, ctx: ExtensionContext, options?: { notify?: boolean; persist?: boolean }): void {
+		fastModeEnabled = enabled;
+		if (options?.persist !== false) persistState();
+		updateStatus(ctx);
+		if (options?.notify !== false) notifyState(ctx);
+	}
+
+	function restoreEnabledState(
+		ctx: ExtensionContext,
+		options?: { fallback?: boolean; preserveCurrentIfMissing?: boolean },
+	): void {
+		const savedState = getSavedStateFromBranch(ctx);
+		if (typeof savedState === "boolean") {
+			applyEnabledState(savedState, ctx, { notify: false, persist: false });
+			return;
+		}
+
+		if (!options?.preserveCurrentIfMissing && typeof options?.fallback === "boolean") {
+			applyEnabledState(options.fallback, ctx, { notify: false, persist: false });
+			return;
+		}
+
+		updateStatus(ctx);
+	}
+
+	function toggleFastMode(ctx: ExtensionContext): void {
+		applyEnabledState(!fastModeEnabled, ctx);
+	}
+
+	pi.registerFlag("fast", {
+		description: `Start with fast mode enabled. Targets are loaded from project config, ${GLOBAL_CONFIG_PATH}, or the bundled config.`,
+		type: "boolean",
+		default: false,
+	});
+
+	pi.registerCommand("pi-fast-mode:setup", {
+		description: `Copy the default ${EXTENSION_NAME} config to ${GLOBAL_CONFIG_PATH}`,
+		handler: async (_args, ctx) => {
+			if (await pathExists(GLOBAL_CONFIG_PATH)) {
+				safeNotify(ctx, `[${EXTENSION_NAME}] Config already exists at ${GLOBAL_CONFIG_PATH}`, "warning");
+				return;
+			}
+
+			await copyBundledConfig(GLOBAL_CONFIG_PATH);
+			safeNotify(ctx, `[${EXTENSION_NAME}] Config copied to ${GLOBAL_CONFIG_PATH}`, "info");
+		},
+	});
+
+	pi.registerCommand("fast", {
+		description: "Toggle fast mode. Usage: /fast [on|off|status|reload]",
+		handler: async (args, ctx) => {
+			const action = args.trim().toLowerCase();
+			switch (action) {
+				case "":
+				case "toggle":
+					toggleFastMode(ctx);
+					return;
+				case "on":
+				case "enable":
+					if (fastModeEnabled) {
+						notifyState(ctx);
+						return;
+					}
+					applyEnabledState(true, ctx);
+					return;
+				case "off":
+				case "disable":
+					if (!fastModeEnabled) {
+						notifyState(ctx);
+						return;
+					}
+					applyEnabledState(false, ctx);
+					return;
+				case "status":
+					notifyState(ctx);
+					return;
+				case "reload":
+					await refreshConfig(ctx.cwd, ctx);
+					updateStatus(ctx);
+					safeNotify(
+						ctx,
+						`[${EXTENSION_NAME}] Reloaded targets from ${resolvedConfigPath}. Enabled targets: ${configuredTargetsText()}.`,
+						"info",
+					);
+					return;
+				default:
+					safeNotify(ctx, "Usage: /fast [on|off|status|reload]", "warning");
+			}
+		},
+	});
+
+	pi.registerShortcut(Key.ctrlShift("f"), {
+		description: "Toggle fast mode",
+		handler: async (ctx) => {
+			toggleFastMode(ctx);
+		},
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		currentModel = ctx.model;
+		await refreshConfig(ctx.cwd, ctx);
+
+		if (pi.getFlag("fast") === true) {
+			applyEnabledState(true, ctx, { notify: false, persist: false });
+			return;
+		}
+
+		restoreEnabledState(ctx, { fallback: false, preserveCurrentIfMissing: false });
+	});
+
+	pi.on("session_tree", async (_event, ctx) => {
+		restoreEnabledState(ctx, { preserveCurrentIfMissing: true });
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		if (getSavedStateFromBranch(ctx) !== fastModeEnabled) {
+			persistState();
+		}
+		if (ctx.hasUI) ctx.ui.setStatus(STATUS_ID, undefined);
+	});
+
+	pi.on("model_select", async (event, ctx) => {
+		currentModel = event.model;
+		updateStatus(ctx);
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		if (!fastModeEnabled) return;
+		const target = getMatchingTarget(activeModel(ctx), configuredTargets);
+		if (!target) return;
+		if (!isRecord(event.payload)) return;
+		if (typeof event.payload.model !== "string") return;
+
+		const serviceTier = target.serviceTier ?? "priority";
+		if (event.payload.service_tier === serviceTier) return;
+		return {
+			...event.payload,
+			service_tier: serviceTier,
+		};
+	});
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "pi-fast-mode",
+  "version": "0.1.0",
+  "description": "Persistent fast-mode toggle for pi that injects service_tier for configured provider/model pairs.",
+  "type": "module",
+  "author": "Vuri Huang",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "extension",
+    "fast-mode",
+    "service-tier",
+    "provider-payload",
+    "codex"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vurihuang/pi-fast-mode.git"
+  },
+  "homepage": "https://github.com/vurihuang/pi-fast-mode#readme",
+  "bugs": {
+    "url": "https://github.com/vurihuang/pi-fast-mode/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "index.ts",
+    "config.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "pack:check": "npm pack --dry-run",
+    "release:check": "npm run check && npm run pack:check",
+    "prepublishOnly": "npm run release:check"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@types/node": "^24.5.2",
+    "typescript": "^5.9.2"
+  }
+}