@benvargas/pi-openai-verbosity 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Vargas
+
+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,162 @@
+# @benvargas/pi-openai-verbosity
+
+Per-model text verbosity overrides for pi's `openai-codex` provider.
+
+## Why This Exists
+
+This extension was originally created because pi sent OpenAI Codex provider requests with the default Responses
+API text verbosity, which made some models, especially `gpt-5.5`, noticeably more verbose than the Codex CLI.
+The goal was to align `openai-codex/gpt-5.5` with Codex CLI behavior by setting:
+
+```json
+{
+  "text": {
+    "verbosity": "low"
+  }
+}
+```
+
+pi has since shipped an upstream fix: OpenAI Codex Responses requests now default to `low` verbosity when no
+explicit verbosity is provided.
+
+That upstream change addresses the original `gpt-5.5` issue, but it also means pi now defaults every
+`openai-codex` model to `low`. That may not be ideal for all model slugs. For example, you may prefer `low` on
+`gpt-5.5`, but `medium` on an older or different model such as `gpt-5.3-codex`.
+
+This extension now provides the missing user-facing control: per-slug verbosity settings for pi's
+`openai-codex` provider.
+
+Requires pi `0.57.0` or newer.
+
+## What It Does
+
+The extension uses pi's `before_provider_request` hook to rewrite outgoing provider payloads for configured
+`openai-codex/<model>` keys.
+
+For matching models, it sets:
+
+```json
+{
+  "text": {
+    "verbosity": "low | medium | high"
+  }
+}
+```
+
+Non-matching models are left unchanged.
+
+## Install
+
+```bash
+pi install npm:@benvargas/pi-openai-verbosity
+```
+
+Or try without installing:
+
+```bash
+pi -e npm:@benvargas/pi-openai-verbosity
+```
+
+## Usage
+
+Run pi with the extension enabled:
+
+```bash
+pi -e npm:@benvargas/pi-openai-verbosity --model openai-codex/gpt-5.5
+```
+
+Use `/openai-verbosity status` inside pi to report the configured rewrite for the current model. The command also
+reloads the config file.
+
+## Config
+
+Config files follow pi's project-over-global pattern:
+
+- Project: `<repo>/.pi/extensions/pi-openai-verbosity.json`
+- Global: `~/.pi/agent/extensions/pi-openai-verbosity.json`
+
+If neither exists, the extension writes a default global config on first run.
+
+Example config:
+
+```json
+{
+  "models": {
+    "openai-codex/gpt-5.5": "low",
+    "openai-codex/gpt-5.4": "low",
+    "openai-codex/gpt-5.3-codex": "medium",
+    "openai-codex/gpt-5.3-codex-spark": "medium",
+    "openai-codex/gpt-5.2": "medium"
+  }
+}
+```
+
+Settings:
+
+- `models`: object mapping `openai-codex/<model-id>` strings to `low`, `medium`, or `high`.
+
+Project config overrides global config per model key. Any model not listed is left unchanged, which means pi's
+native default behavior applies.
+
+## Default Config
+
+By default, the extension preserves the original workaround behavior and sets known supported OpenAI Codex models
+to `low`:
+
+```json
+{
+  "models": {
+    "openai-codex/gpt-5.4": "low",
+    "openai-codex/gpt-5.5": "low",
+    "openai-codex/gpt-5.4-mini": "low",
+    "openai-codex/gpt-5.3-codex": "low",
+    "openai-codex/gpt-5.3-codex-spark": "low",
+    "openai-codex/gpt-5.2": "low",
+    "openai-codex/codex-auto-review": "low"
+  }
+}
+```
+
+You can change any value to `medium` or `high` to override pi's native low-verbosity default for that model.
+
+## Debugging
+
+Pi does not currently expose a simple CLI flag to print the final provider request body. To verify this extension is
+matching and rewriting a request, set `PI_OPENAI_VERBOSITY_DEBUG_LOG` to a JSONL file path.
+
+| Variable | Description |
+|---|---|
+| `PI_OPENAI_VERBOSITY_DEBUG_LOG` | Set to a file path to enable debug logging. Matching requests write `"before"` and `"after"` JSON entries with the full provider payload. Non-matching requests write one `"skipped"` entry. |
+
+```bash
+PI_OPENAI_VERBOSITY_DEBUG_LOG=/tmp/pi-openai-verbosity.jsonl \
+  pi -e npm:@benvargas/pi-openai-verbosity \
+  --model openai-codex/gpt-5.3-codex \
+  -p "Reply in one short sentence."
+```
+
+Then inspect the last entries:
+
+```bash
+tail -n 5 /tmp/pi-openai-verbosity.jsonl | jq .
+```
+
+These entries include prompts, messages, tools, and the rest of the provider payload, so keep the file local and
+delete it when you are done debugging.
+
+## Notes
+
+- This extension only changes outgoing provider request payloads.
+- Existing `text` fields are preserved, and only `text.verbosity` is replaced.
+- Only the `openai-codex` provider is supported.
+- This extension is most useful if you want different verbosity settings for different OpenAI Codex model slugs.
+
+## Uninstall
+
+```bash
+pi remove npm:@benvargas/pi-openai-verbosity
+```
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,323 @@
+/**
+ * OpenAI verbosity for pi.
+ *
+ * Sets OpenAI Responses `text.verbosity` for configured models via the
+ * `before_provider_request` hook. Config precedence is project
+ * `.pi/extensions/pi-openai-verbosity.json` over global
+ * `~/.pi/agent/extensions/pi-openai-verbosity.json`.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+const VERBOSITY_COMMAND = "openai-verbosity";
+const VERBOSITY_CONFIG_BASENAME = "pi-openai-verbosity.json";
+const VERBOSITY_COMMAND_ARGS = ["status"] as const;
+const DEBUG_LOG_ENV = "PI_OPENAI_VERBOSITY_DEBUG_LOG";
+const SUPPORTED_PROVIDERS = ["openai-codex"] as const;
+const DEFAULT_MODEL_VERBOSITY = {
+	"openai-codex/gpt-5.4": "low",
+	"openai-codex/gpt-5.5": "low",
+	"openai-codex/gpt-5.4-mini": "low",
+	"openai-codex/gpt-5.3-codex": "low",
+	"openai-codex/gpt-5.3-codex-spark": "low",
+	"openai-codex/gpt-5.2": "low",
+	"openai-codex/codex-auto-review": "low",
+} as const;
+
+type TextVerbosity = "low" | "medium" | "high";
+
+interface VerbosityConfigFile {
+	models?: Record<string, TextVerbosity>;
+}
+
+interface ResolvedVerbosityConfig {
+	configPath: string;
+	models: Record<string, TextVerbosity>;
+}
+
+type VerbosityPayload = {
+	text?: unknown;
+	[key: string]: unknown;
+};
+
+const DEFAULT_CONFIG_FILE: VerbosityConfigFile = {
+	models: { ...DEFAULT_MODEL_VERBOSITY },
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isTextVerbosity(value: unknown): value is TextVerbosity {
+	return value === "low" || value === "medium" || value === "high";
+}
+
+function normalizeModelKey(value: string): string | undefined {
+	const trimmed = value.trim();
+	if (!trimmed) {
+		return undefined;
+	}
+	const slashIndex = trimmed.indexOf("/");
+	if (slashIndex <= 0 || slashIndex >= trimmed.length - 1) {
+		return undefined;
+	}
+	const provider = trimmed.slice(0, slashIndex).trim();
+	const id = trimmed.slice(slashIndex + 1).trim();
+	if (!provider || !id) {
+		return undefined;
+	}
+	if (!SUPPORTED_PROVIDERS.includes(provider as (typeof SUPPORTED_PROVIDERS)[number])) {
+		return undefined;
+	}
+	return `${provider}/${id}`;
+}
+
+function normalizeModelVerbosityMap(value: unknown): Record<string, TextVerbosity> | undefined {
+	if (value === undefined) {
+		return undefined;
+	}
+	if (!isRecord(value)) {
+		return undefined;
+	}
+
+	const normalized: Record<string, TextVerbosity> = {};
+	for (const [rawKey, rawVerbosity] of Object.entries(value)) {
+		const key = normalizeModelKey(rawKey);
+		if (!key || !isTextVerbosity(rawVerbosity)) {
+			continue;
+		}
+		normalized[key] = rawVerbosity;
+	}
+	return normalized;
+}
+
+function getConfigCwd(ctx: ExtensionContext): string {
+	return ctx.cwd || process.cwd();
+}
+
+function getConfigPaths(
+	cwd: string,
+	homeDir: string = homedir(),
+): {
+	projectConfigPath: string;
+	globalConfigPath: string;
+} {
+	return {
+		projectConfigPath: join(cwd, ".pi", "extensions", VERBOSITY_CONFIG_BASENAME),
+		globalConfigPath: join(homeDir, ".pi", "agent", "extensions", VERBOSITY_CONFIG_BASENAME),
+	};
+}
+
+function readConfigFile(filePath: string): VerbosityConfigFile | null {
+	if (!existsSync(filePath)) {
+		return null;
+	}
+	try {
+		const raw = readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw) as unknown;
+		if (!isRecord(parsed)) {
+			return {};
+		}
+		const models = normalizeModelVerbosityMap(parsed.models);
+		return models === undefined ? {} : { models };
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn(`[pi-openai-verbosity] Failed to read ${filePath}: ${message}`);
+		return null;
+	}
+}
+
+function writeConfigFile(filePath: string, config: VerbosityConfigFile): void {
+	try {
+		mkdirSync(dirname(filePath), { recursive: true });
+		writeFileSync(filePath, `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn(`[pi-openai-verbosity] Failed to write ${filePath}: ${message}`);
+	}
+}
+
+function ensureDefaultConfigFile(projectConfigPath: string, globalConfigPath: string): void {
+	if (existsSync(projectConfigPath) || existsSync(globalConfigPath)) {
+		return;
+	}
+	writeConfigFile(globalConfigPath, DEFAULT_CONFIG_FILE);
+}
+
+function resolveVerbosityConfig(cwd: string, homeDir: string = homedir()): ResolvedVerbosityConfig {
+	const { projectConfigPath, globalConfigPath } = getConfigPaths(cwd, homeDir);
+	ensureDefaultConfigFile(projectConfigPath, globalConfigPath);
+
+	const globalConfig = readConfigFile(globalConfigPath) ?? {};
+	const projectConfig = readConfigFile(projectConfigPath) ?? {};
+	const selectedConfigPath = existsSync(projectConfigPath) ? projectConfigPath : globalConfigPath;
+
+	return {
+		configPath: selectedConfigPath,
+		models: {
+			...DEFAULT_MODEL_VERBOSITY,
+			...(globalConfig.models ?? {}),
+			...(projectConfig.models ?? {}),
+		},
+	};
+}
+
+function getCurrentModelKey(model: ExtensionContext["model"]): string | undefined {
+	if (!model) {
+		return undefined;
+	}
+	return `${model.provider}/${model.id}`;
+}
+
+function getVerbosityForModel(
+	model: ExtensionContext["model"],
+	models: Record<string, TextVerbosity>,
+): TextVerbosity | undefined {
+	const modelKey = getCurrentModelKey(model);
+	return modelKey ? models[modelKey] : undefined;
+}
+
+function describeConfiguredModels(models: Record<string, TextVerbosity>): string {
+	const entries = Object.entries(models);
+	if (entries.length === 0) {
+		return "none configured";
+	}
+	return entries.map(([model, verbosity]) => `${model}=${verbosity}`).join(", ");
+}
+
+function describeCurrentState(ctx: ExtensionContext, config: ResolvedVerbosityConfig): string {
+	const model = getCurrentModelKey(ctx.model) ?? "none";
+	const verbosity = getVerbosityForModel(ctx.model, config.models);
+	if (verbosity) {
+		return `OpenAI verbosity sets text.verbosity=${verbosity} for ${model}.`;
+	}
+	return `OpenAI verbosity has no setting configured for ${model}. Configured models: ${describeConfiguredModels(
+		config.models,
+	)}.`;
+}
+
+function applyTextVerbosity(payload: unknown, verbosity: TextVerbosity): unknown {
+	if (!isRecord(payload)) {
+		return payload;
+	}
+
+	const nextPayload: VerbosityPayload = { ...payload };
+	const text = isRecord(nextPayload.text) ? { ...nextPayload.text } : {};
+	text.verbosity = verbosity;
+	nextPayload.text = text;
+	return nextPayload;
+}
+
+function getPayloadTextVerbosity(payload: unknown): unknown {
+	if (!isRecord(payload) || !isRecord(payload.text)) {
+		return undefined;
+	}
+	return payload.text.verbosity;
+}
+
+function writeDebugLog(
+	entry: Record<string, unknown>,
+	debugLogPath: string | undefined = process.env[DEBUG_LOG_ENV],
+): void {
+	if (!debugLogPath) {
+		return;
+	}
+	try {
+		mkdirSync(dirname(debugLogPath), { recursive: true });
+		appendFileSync(debugLogPath, `${JSON.stringify({ timestamp: new Date().toISOString(), ...entry })}\n`, "utf-8");
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn(`[pi-openai-verbosity] Failed to write debug log ${debugLogPath}: ${message}`);
+	}
+}
+
+export default function piOpenAIVerbosity(pi: ExtensionAPI): void {
+	let cachedConfig: ResolvedVerbosityConfig | undefined;
+
+	function refreshConfig(ctx: ExtensionContext): ResolvedVerbosityConfig {
+		cachedConfig = resolveVerbosityConfig(getConfigCwd(ctx));
+		return cachedConfig;
+	}
+
+	function getConfig(ctx: ExtensionContext): ResolvedVerbosityConfig {
+		return cachedConfig ?? refreshConfig(ctx);
+	}
+
+	pi.registerCommand(VERBOSITY_COMMAND, {
+		description: "Report configured GPT text verbosity rewrites",
+		getArgumentCompletions: (prefix) => {
+			const items = VERBOSITY_COMMAND_ARGS.filter((value) => value.startsWith(prefix)).map((value) => ({
+				value,
+				label: value,
+			}));
+			return items.length > 0 ? items : null;
+		},
+		handler: async (args, ctx) => {
+			const command = args.trim().toLowerCase();
+			if (command.length > 0 && command !== "status") {
+				ctx.ui.notify("Usage: /openai-verbosity [status]", "error");
+				return;
+			}
+			ctx.ui.notify(describeCurrentState(ctx, refreshConfig(ctx)), "info");
+		},
+	});
+
+	pi.on("before_provider_request", (event, ctx) => {
+		const model = getCurrentModelKey(ctx.model) ?? null;
+		const beforeTextVerbosity = getPayloadTextVerbosity(event.payload);
+		const verbosity = getVerbosityForModel(ctx.model, getConfig(ctx).models);
+		if (!verbosity) {
+			writeDebugLog({
+				stage: "skipped",
+				model,
+				matched: false,
+				beforeTextVerbosity: beforeTextVerbosity ?? null,
+				payload: event.payload,
+			});
+			return;
+		}
+		writeDebugLog({
+			stage: "before",
+			model,
+			matched: true,
+			configuredVerbosity: verbosity,
+			beforeTextVerbosity: beforeTextVerbosity ?? null,
+			payload: event.payload,
+		});
+		const nextPayload = applyTextVerbosity(event.payload, verbosity);
+		writeDebugLog({
+			stage: "after",
+			model,
+			matched: true,
+			configuredVerbosity: verbosity,
+			beforeTextVerbosity: beforeTextVerbosity ?? null,
+			afterTextVerbosity: getPayloadTextVerbosity(nextPayload) ?? null,
+			payload: nextPayload,
+		});
+		return nextPayload;
+	});
+}
+
+export const _test = {
+	VERBOSITY_COMMAND,
+	VERBOSITY_CONFIG_BASENAME,
+	VERBOSITY_COMMAND_ARGS,
+	SUPPORTED_PROVIDERS,
+	DEFAULT_MODEL_VERBOSITY,
+	DEFAULT_CONFIG_FILE,
+	isTextVerbosity,
+	normalizeModelKey,
+	normalizeModelVerbosityMap,
+	getConfigPaths,
+	readConfigFile,
+	resolveVerbosityConfig,
+	getCurrentModelKey,
+	getVerbosityForModel,
+	describeConfiguredModels,
+	describeCurrentState,
+	applyTextVerbosity,
+	getPayloadTextVerbosity,
+	writeDebugLog,
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@benvargas/pi-openai-verbosity",
+  "version": "1.0.0",
+  "description": "Per-model OpenAI Codex text verbosity overrides for pi",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "openai",
+    "codex",
+    "openai-codex",
+    "gpt-5.5",
+    "gpt-5.3-codex",
+    "verbosity",
+    "text-verbosity",
+    "per-model"
+  ],
+  "type": "module",
+  "files": [
+    "extensions/",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": ">=0.57.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ben-vargas/pi-packages.git",
+    "directory": "packages/pi-openai-verbosity"
+  },
+  "author": "Ben Vargas",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ben-vargas/pi-packages/issues"
+  },
+  "homepage": "https://github.com/ben-vargas/pi-packages/tree/main/packages/pi-openai-verbosity#readme"
+}