pi-daybreak-param 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MercuriusDream
+
+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,77 @@
+# pi-daybreak-param
+
+Persistent `/daybreak` configuration and explicit `access_programs.cyber` request selection for Pi's **new OpenAI → Sign in with ChatGPT** integration. Tested against Pi **0.99.1**.
+
+**Experimental for ChatGPT direct-token authentication:** OpenAI documents the public Responses endpoint and the Daybreak request field separately, but does not explicitly confirm Daybreak support/entitlement for Sign in with ChatGPT direct-token grants. This extension sends the field; it does not grant access or prove that the server applied it. See [research](docs/research.md).
+
+## Try it
+
+```sh
+pi -e ./src/index.ts --daybreak-cyber daybreak_blue
+```
+
+Install from GitHub:
+
+```sh
+pi install git:github.com/MercuriusDream/pi-daybreak-param
+```
+
+Once published to npm:
+
+```sh
+pi install npm:pi-daybreak-param
+```
+
+For local development: `pi install /absolute/path/to/pi-daybreak-param`. Reload an active Pi session with `/reload` after installation.
+
+Use your existing **OpenAI / Sign in with ChatGPT** login. Authentication and token refresh remain Pi's responsibility. The wrapper also applies to API-key authentication on the same OpenAI provider. It does not modify the legacy `openai-codex` provider.
+
+### Commands
+
+```text
+/daybreak                 Open the configuration picker
+/daybreak status          Show requested selection or configuration error
+/daybreak daybreak_blue    Explicitly request Blue
+/daybreak daybreak_red     Explicitly request Red
+/daybreak standard        Explicit opt-out: request standard safeguards
+/daybreak default         Remove this extension's override (inherit existing/server behavior)
+```
+
+`standard` and `default` are **not the same**. Inheriting defaults may still enable Daybreak for an eligible account, and does not remove a field configured elsewhere. Use `standard` for explicit opt-out. The model must support the chosen program; errors are not retried with another tier or model.
+
+Menu and command selections are saved atomically to `~/.pi/agent/daybreak.json` (or the directory specified by `PI_CODING_AGENT_DIR`). They apply immediately and survive reloads/new sessions. The CLI flag is a startup override and is not saved; at the next session start it takes precedence over the saved choice. A command changes the current choice and saves it, but does not modify the CLI flag.
+
+An absent config intentionally means inherit/default. A malformed or unreadable config is an error that blocks OpenAI requests—even with a valid CLI flag. Correct it explicitly using `/daybreak <selection>` or repair the file. Other providers are outside the wrapper's scope.
+
+## Why `/daybreak`, not `/settings`?
+
+Pi 0.99.1's built-in `/settings` has hardcoded rows and callbacks, with no supported extension setting registration API. `/daybreak` therefore provides its own supported selection dialog and persistent configuration, without monkey-patching Pi or replacing the built-in settings screen.
+
+## Errors, not silent fallback
+
+The extension uses a thin provider-stream wrapper rather than the extension payload event: Pi catches payload-event handler exceptions and continues, which cannot enforce fail-closed validation.
+
+- Invalid CLI selection blocks OpenAI calls and becomes a provider error, including in non-UI modes. Correct it explicitly via `/daybreak` or restart with a valid flag.
+- Invalid command input is an error, leaving the prior selection unchanged.
+- Invalid/unreadable stored configuration blocks requests. Save failures also block requests rather than silently continuing with stale settings.
+- With an explicit selection, malformed payloads/access-program objects, mismatched request model IDs, and noncanonical endpoints fail **before HTTP**.
+- API permission, unsupported-program, and model-compatibility errors are preserved. No downgrade, field omission retry, or alternate-model retry is added.
+- The status displays **requested, not verified** access. No credential or payload logging.
+
+The provider registration preserves built-in models/authentication and delegates to Pi's own OpenAI Responses implementation, including tools, cancellation, streaming, usage, and instrumentation. It uses the actual request model, not the selected-model approximation from `before_provider_request`.
+
+## Tests
+
+```sh
+bun test
+```
+
+Optional offline wire tests against an installed Pi AI distribution:
+
+```sh
+PI_AI_TEST_DIST=/path/to/@earendil-works/pi-ai/dist \
+PI_CODING_AGENT_TEST_DIST=/path/to/@earendil-works/pi-coding-agent/dist \
+bun test
+```
+
+All wire-test HTTP is intercepted with a dummy token. Tests cover serialization and denied requests with no downgrade, plus validation failures that make **zero HTTP calls**. The optional provider-composition test also verifies that Pi's real composer retains the built-in OpenAI models, API-key authentication, and ChatGPT subscription authentication. Tests do not test real account approval or live Daybreak behavior.

package/docs/research.md

@@ -0,0 +1,54 @@
+# Research and integration notes
+
+## Pi version inspected
+
+Installed `@earendil-works/pi-coding-agent` **0.99.1**, including the installed JavaScript, declarations, and bundled source-map TypeScript. This is a version-specific source review, not a claim about an uninspected upstream revision.
+
+Relevant paths under Pi's `packages/` source layout:
+
+- `ai/src/providers/openai.ts`: the new `openai` provider offers API-key auth and **Sign in with ChatGPT**, using the public Responses API.
+- `ai/src/auth/oauth/openai-chatgpt.ts`: dynamic public OAuth client, `resource=https://api.openai.com/v1`, scope `chatgpt.tokens.use.direct`. Its `toAuth` returns the access token to the existing API implementation. The extension does not change this flow.
+- `ai/src/providers/openai-codex.ts`: a separate, explicitly legacy provider using `https://chatgpt.com/backend-api` and `openai-codex-responses`. Not the target of this extension.
+- `ai/src/api/openai-responses.ts`: `buildParams` has no named `access_programs` field, but merges generic `samplingParams` last. `stream` invokes `options.onPayload` before calling `client.responses.create`. Its ChatGPT-specific field omissions do not strip an extension-added `access_programs` value.
+- `coding-agent/src/core/sdk.ts`: the payload callback dispatches extension `before_provider_request` handlers.
+- `coding-agent/src/core/extensions/runner.ts`: each handler receives the prior handler's payload; a non-undefined return replaces the whole payload. Handler exceptions are reported, not an effective way to block the request.
+- `coding-agent/src/core/extensions/types.ts`: payload event contains only `payload`, not request model/auth metadata. The context exposes the selected model, which is not necessarily the routed physical request model.
+- `coding-agent/examples/extensions/provider-payload.ts`: reference for returning the replacement payload directly.
+
+There is **no explicit built-in Daybreak switch or `access_programs.cyber` option** in the inspected Pi request implementation. However, generic `samplingParams` can already carry the field. Therefore an extension is a convenient command/flag interface, not the only way to serialize the parameter.
+
+## OpenAI documentation
+
+- [Responses API Daybreak guide](https://developers.openai.com/api/docs/guides/daybreak): `access_programs.cyber` accepts `standard`, `daybreak_blue`, `daybreak_red`; optional omission lets the server choose its defaults. The parameter selects approved access, it does not grant approval. Model compatibility matters. `null` is not a request value.
+- [Daybreak overview](https://help.openai.com/en/articles/20001258-openai-daybreak-trusted-access-for-cyber-overview) and [migration guide](https://help.openai.com/en/articles/20001532-openai-daybreak-migration-org-consolidation-guide): official Codex signed in with ChatGPT has a Daybreak toggle in its Advanced model picker, with account/workspace eligibility controls. This does not document the legacy backend wire protocol or prove third-party direct-token entitlement.
+
+The new Pi sign-in flow reaches the documented public endpoint, so the extension can serialize the documented field. **Whether the SIWC route accepts/honors that field, and whether a particular direct ChatGPT OAuth grant is entitled to Daybreak, are not established by source inspection or offline tests.** The API-key/project examples in the guide should not be presented as proof of subscription-token approval. No real credentials were read and no authenticated requests were made during development.
+
+Research used indexed official-page text; direct fetch of the Daybreak guide failed through the available fetch service. Treat rollout and entitlement details as something to confirm with OpenAI for your account.
+
+## Extension contracts and boundaries
+
+Uses `pi.on`, `registerFlag`, `registerCommand`, `ctx.ui.setStatus`, and a thin `registerProvider("openai", { api, streamSimple })` wrapper around Pi's own OpenAI Responses implementation. The initially considered payload-event approach was removed because its swallowed exceptions cannot satisfy the user's fail-closed requirement.
+
+- `coding-agent/src/core/provider-composer.ts` confirms that a stream-only legacy registration preserves the existing models and composes both built-in authentication methods when neither models nor auth overrides are supplied.
+- The wrapper composes the existing `onPayload` callback, then validates/transforms the body using the **actual request model**. Callback errors propagate through the OpenAI implementation into a terminal provider error before HTTP.
+- Loading the factory only registers capabilities; no background resources, timers, credential access, or startup I/O.
+- Explicit `default` is no override; `standard` is explicit opt-out. Explicit selection preserves other top-level request fields and other access-program keys.
+- Invalid CLI configuration is retained as an error state that blocks OpenAI calls; it is not converted into default behavior. Invalid commands throw. Invalid payloads/endpoint/model identity throw when applying an explicit selection.
+- Selection changes wait for idle. Menu/command selections persist atomically in the agent directory's `daybreak.json`. Each `session_start` validates that file, then selects the CLI override or saved value. Invalid reads/writes block OpenAI requests; only a genuinely absent config has the intentional initial inherit state.
+- UI status is guarded by `ctx.hasUI`. CLI flag works in print/JSON/RPC modes; no custom terminal UI is needed.
+- Scope: requests through the `openai` provider and `openai-responses` API. An explicit program requires the canonical `https://api.openai.com/v1` endpoint and matching payload model ID. Both auth methods are preserved. Other providers, including legacy Codex, are outside this registration.
+- Existing payload handlers run before this final transformation. `default` does not remove values configured in `samplingParams` or added elsewhere. Another provider replacement can conflict with this registration.
+- No automatic retries with another program/model, permission-error masking, approval claims, or removal of safeguards.
+
+### SIWC-specific documentation
+
+[Models and inference](https://developers.openai.com/siwc/token-sharing-open-source/models-and-inference) documents direct OAuth-token use at `api.openai.com/v1/responses` and instructs callers not to use the ChatGPT backend endpoints. [Token reference](https://developers.openai.com/siwc/token-sharing-open-source/token-reference) documents the audience and direct-token scope. [Preview limitations](https://developers.openai.com/siwc/token-sharing-open-source/preview-limitations) does not list `access_programs` among unsupported fields, but that omission is **not an explicit support guarantee**. Daybreak approval on another product surface is not documented as transferring to SIWC.
+
+### Built-in settings limitation
+
+A dedicated source review confirmed no supported extension API/event to append settings rows in Pi 0.99.1. `interactive-mode.ts` intercepts `/settings`, constructs the selector with explicit built-in configuration/callbacks, and `components/settings-selector.ts` builds hardcoded items and dispatches a hardcoded switch. Extension context settings are not a mutation/registration interface. The user subsequently chose `/daybreak` instead of a core change. The extension now provides a supported `/daybreak` selection dialog with persistent configuration; it does not claim native `/settings` integration or monkey-patch internals.
+
+## Verification
+
+Unit tests cover values, explicit default behavior, immutable merging, malformed-body errors, endpoint/model-identity errors, CLI initialization, command errors/changes/reset, and non-UI startup. Optional installed-Pi integration tests use a dummy token and intercepted HTTP to check that the real OpenAI client serializes the added field, preserves a 403 denial without retrying, and makes zero HTTP calls for invalid configuration or payload. This verifies transport, **not server entitlement**.

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "pi-daybreak-param",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "Persistent /daybreak access-program selection for Pi's OpenAI and Sign in with ChatGPT requests",
+  "license": "MIT",
+  "author": "MercuriusDream",
+  "repository": { "type": "git", "url": "git+https://github.com/MercuriusDream/pi-daybreak-param.git" },
+  "homepage": "https://github.com/MercuriusDream/pi-daybreak-param#readme",
+  "bugs": { "url": "https://github.com/MercuriusDream/pi-daybreak-param/issues" },
+  "files": ["src/", "docs/", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "keywords": ["pi-package"],
+  "pi": { "extensions": ["./src/index.ts"] },
+  "peerDependencies": { "@earendil-works/pi-coding-agent": "*", "@earendil-works/pi-ai": "*" },
+  "scripts": { "test": "bun test" }
+}

package/src/config.ts

@@ -0,0 +1,52 @@
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import { parseMode, type CyberMode } from "./payload.ts";
+
+export interface ModeStore {
+	read(): CyberMode;
+	write(mode: CyberMode): void;
+}
+
+export function fileModeStore(path: string): ModeStore {
+	return {
+		read() {
+			let text: string;
+			try {
+				text = readFileSync(path, "utf8");
+			} catch (error) {
+				// An absent configuration is an intentional initial state, not error recovery.
+				if ((error as NodeJS.ErrnoException).code === "ENOENT") return "default";
+				throw error;
+			}
+			const value: unknown = JSON.parse(text);
+			if (typeof value !== "object" || value === null || Array.isArray(value)) {
+				throw new Error(`Invalid Daybreak configuration at ${path}: expected an object.`);
+			}
+			const config = value as Record<string, unknown>;
+			const mode = parseMode(config.cyber);
+			if (config.version !== 1 || !mode) {
+				throw new Error(`Invalid Daybreak configuration at ${path}: expected version 1 and a valid cyber selection.`);
+			}
+			return mode;
+		},
+		write(mode) {
+			if (!parseMode(mode)) throw new Error("Invalid Daybreak selection; configuration was not saved.");
+			mkdirSync(dirname(path), { recursive: true });
+			const temp = `${path}.${randomUUID()}.tmp`;
+			try {
+				writeFileSync(temp, `${JSON.stringify({ version: 1, cyber: mode }, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+				renameSync(temp, path);
+			} catch (error) {
+				try {
+					unlinkSync(temp);
+				} catch (cleanupError) {
+					if ((cleanupError as NodeJS.ErrnoException).code !== "ENOENT") {
+						throw new AggregateError([error, cleanupError], "Failed to save Daybreak configuration and clean up temporary file.");
+					}
+				}
+				throw error;
+			}
+		},
+	};
+}

package/src/controller.ts

@@ -0,0 +1,104 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { Api, SimpleStreamOptions, StreamFunction } from "@earendil-works/pi-ai";
+import { isDirectOpenAI, MODES, parseMode, selectCyberProgram, type CyberMode } from "./payload.ts";
+import type { ModeStore } from "./config.ts";
+
+const LABELS: Record<CyberMode, string> = {
+	standard: "Standard — explicit Daybreak opt-out",
+	daybreak_blue: "Daybreak Blue — requires approved access",
+	daybreak_red: "Daybreak Red — requires approved access",
+	default: "Inherit — no override (not an opt-out)",
+};
+
+export function registerDaybreak(pi: ExtensionAPI, streamOpenAI: StreamFunction<Api, SimpleStreamOptions>, store: ModeStore) {
+	pi.registerFlag("daybreak-cyber", {
+		type: "string",
+		description: `OpenAI access_programs.cyber request selection: ${MODES.join(", ")}. Requires approved access.`,
+	});
+
+	let mode: CyberMode = "default";
+	let configError: Error | undefined = new Error("Daybreak configuration has not been initialized. OpenAI request blocked.");
+	const refreshStatus = (ctx: ExtensionContext) => {
+		if (ctx.hasUI) {
+			ctx.ui.setStatus("daybreak-param", configError ? "Cyber config: ERROR" :
+				mode !== "default" && isDirectOpenAI(ctx.model) ? `Cyber request: ${mode} (not verified)` : undefined);
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		const flag = pi.getFlag("daybreak-cyber");
+		try {
+			// Always validate stored configuration: a flag must not hide a broken config file.
+			const saved = store.read();
+			if (flag === undefined) {
+				mode = saved;
+			} else {
+				const parsed = parseMode(flag);
+				if (!parsed) throw new Error(`Invalid --daybreak-cyber value: ${String(flag)}. Expected ${MODES.join(", ")}.`);
+				mode = parsed;
+			}
+			configError = undefined;
+		} catch (error) {
+			configError = new Error(`Daybreak configuration error: ${error instanceof Error ? error.message : String(error)} OpenAI requests are blocked until corrected.`);
+			if (ctx.hasUI) ctx.ui.notify(configError.message, "error");
+		}
+		refreshStatus(ctx);
+	});
+	pi.on("model_select", (_event, ctx) => refreshStatus(ctx));
+
+	pi.registerCommand("daybreak", {
+		description: `Configure persistent cyber selection, or /daybreak status: ${MODES.join(" | ")}`,
+		handler: async (args, ctx) => {
+			let value = args.trim();
+			if (value === "status") {
+				ctx.ui.notify(configError?.message ?? `Cyber request selection: ${mode}. This is not confirmation of Daybreak access.`, configError ? "error" : "info");
+				return;
+			}
+			await ctx.waitForIdle();
+			if (!value) {
+				if (!ctx.hasUI) throw new Error("Use /daybreak <selection> or --daybreak-cyber in non-UI mode.");
+				const selected = await ctx.ui.select(`Cyber request selection: ${configError ? "CONFIG ERROR" : mode} (access not verified)`, Object.values(LABELS));
+				if (selected === undefined) return; // Explicit user cancellation changes nothing.
+				const entry = Object.entries(LABELS).find(([, label]) => label === selected);
+				if (!entry) throw new Error("Invalid Daybreak menu selection.");
+				value = entry[0];
+			}
+			const next = parseMode(value);
+			if (!next) throw new Error(`Usage: /daybreak ${MODES.join(" | ")}. Invalid selection: ${value}`);
+			try {
+				store.write(next);
+			} catch (error) {
+				configError = new Error(`Failed to save Daybreak configuration: ${error instanceof Error ? error.message : String(error)} OpenAI requests are blocked until corrected.`);
+				refreshStatus(ctx);
+				throw configError;
+			}
+			mode = next;
+			configError = undefined;
+			refreshStatus(ctx);
+			ctx.ui.notify(next === "default"
+				? "Saved: inherit. Extension override disabled; existing payload and server defaults are unchanged."
+				: `Saved: request ${next} on OpenAI Responses calls. OpenAI still checks model compatibility and your approved access.`, "info");
+		},
+	});
+
+	// Preserve built-in models and BOTH authentication methods. Only delegate streaming.
+	// Unlike extension event handlers, exceptions in this onPayload callback terminate
+	// the provider stream before client.responses.create sends the HTTP request.
+	pi.registerProvider("openai", {
+		api: "openai-responses",
+		streamSimple(model, context, options) {
+			const requestMode = mode;
+			const requestError = configError;
+			return streamOpenAI(model, context, {
+				...options,
+				onPayload: async (payload, requestModel) => {
+					if (requestError) throw requestError;
+					const prior = await options?.onPayload?.(payload, requestModel);
+					const current = prior === undefined ? payload : prior;
+					const replacement = selectCyberProgram(current, requestModel, requestMode);
+					return replacement === undefined ? current : replacement;
+				},
+			});
+		},
+	});
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+import { join } from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { openAIResponsesApi } from "@earendil-works/pi-ai/compat";
+import { registerDaybreak } from "./controller.ts";
+import { fileModeStore } from "./config.ts";
+
+export default function daybreak(pi: ExtensionAPI) {
+	registerDaybreak(pi, openAIResponsesApi().streamSimple, fileModeStore(join(getAgentDir(), "daybreak.json")));
+}

package/src/payload.ts

@@ -0,0 +1,47 @@
+export const MODES = ["default", "standard", "daybreak_blue", "daybreak_red"] as const;
+export type CyberMode = (typeof MODES)[number];
+
+export function parseMode(value: unknown): CyberMode | undefined {
+	return typeof value === "string" && MODES.includes(value as CyberMode)
+		? (value as CyberMode)
+		: undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export interface RequestModel {
+	provider: string;
+	api: string;
+	id: string;
+	baseUrl: string;
+}
+
+export function isDirectOpenAI(model: RequestModel | undefined): boolean {
+	// Match Pi's own SIWC detection exactly. Similar-looking URLs (including a
+	// trailing slash, query, fragment, or userinfo) do not use the same code path.
+	return model?.provider === "openai" && model.api === "openai-responses"
+		&& model.baseUrl === "https://api.openai.com/v1";
+}
+
+/** Return the replacement body itself, not { payload: ... }. Never mutate other handlers' objects. */
+export function selectCyberProgram(
+	payload: unknown,
+	model: RequestModel | undefined,
+	mode: CyberMode,
+): Record<string, unknown> | undefined {
+	// Default is a no-op, preserving Pi/server defaults and other extensions' choices.
+	if (mode === "default") return undefined;
+	if (!isDirectOpenAI(model)) throw new Error("Daybreak selection requires the direct OpenAI Responses endpoint.");
+	if (!isRecord(payload)) throw new Error("OpenAI request payload must be an object.");
+	if (payload.model !== model!.id) throw new Error("OpenAI request model does not match the selected request model.");
+	// Invalid values are errors, not a reason to silently send an unmodified request.
+	if (payload.access_programs !== undefined && !isRecord(payload.access_programs)) {
+		throw new Error("access_programs must be an object (not null).");
+	}
+	return {
+		...payload,
+		access_programs: { ...(payload.access_programs as Record<string, unknown> | undefined), cyber: mode },
+	};
+}