@99percentpeople/pi-codex-api 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pi Extensions
+
+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,207 @@
+# @99percentpeople/pi-codex-api
+
+Expose first-party Codex subscription APIs as native Pi tools and commands.
+The extension reuses Pi's existing `openai-codex` OAuth login and does not need
+an OpenAI API key, MCP server, or separate search provider.
+
+## Requirements
+
+- Pi authenticated with `/login` for the `openai-codex` provider
+- An active `openai-codex` model, or **Other providers** enabled in `/99settings`
+- A ChatGPT workspace and plan entitled to the requested Codex feature
+
+The extension still loads when Codex has not been configured. It does not
+prompt or attempt an OAuth request during installation. A tool call instead
+shows an actionable error directing you to `/login`; an expired login is
+reported the same way after Pi's refresh attempt fails.
+
+API-key authentication is intentionally rejected because these tools target the
+ChatGPT subscription backend rather than metered Platform API usage.
+
+## Install
+
+```bash
+pi install npm:@99percentpeople/pi-codex-api
+```
+
+During development:
+
+```bash
+pi install ./extensions/codex-api
+```
+
+## Tools
+
+### `codex_image`
+
+Generates or edits images through the Codex subscription image API using
+`gpt-image-2`.
+
+```text
+codex_image prompt="A quiet neon-lit ramen shop at night"
+```
+
+For edits, provide up to five image paths inside the current workspace:
+
+```text
+codex_image \
+  prompt="Change only the sky to a warm sunset" \
+  referenced_image_paths=["assets/photo.png"] \
+  output_path="assets/photo-sunset.png"
+```
+
+If an edit target was attached or generated in the conversation and has no
+usable local path, the model can instead include the smallest necessary window
+of one to five recent conversation images with `num_last_images_to_include`.
+The two reference mechanisms are mutually exclusive.
+
+The model may request a validated GPT Image 2 `WIDTHxHEIGHT` size when exact
+dimensions are part of the task. It normally omits `quality`, inheriting the
+user's **Image quality** preference, and only overrides it when the user
+explicitly requests a draft or a quality level.
+
+New images default to `output/codex-images/<tool-call-id>.png`. Reference and
+output paths must stay inside the current workspace, and existing files are
+never overwritten. The PNG is both saved locally and returned as image
+content so Codex can inspect or revise it in later turns. If a network request
+fails before an HTTP response, the error identifies the endpoint path and any
+safe transport code (for example `ECONNRESET`). The extension itself never
+retries image generation automatically, because the server may have accepted
+the first request; decide whether to retry after reviewing the error.
+
+### `codex_search`
+
+Uses the first-party Codex standalone search API. Supported command families:
+
+- web and image queries;
+- open, click, and find operations using returned reference IDs;
+- PDF page screenshots;
+- finance, weather, sports, and time lookups.
+
+Search mode is configurable as Cached, Indexed, or Live. External content is
+untrusted and should never be treated as instructions.
+
+## Parameter ownership
+
+The extension follows the current official Codex split between task intent,
+user policy, and internal protocol fields:
+
+| Owner | Search | Image |
+| --- | --- | --- |
+| AI per call | queries, recency, task-specific domains, navigation/lookup commands, response length | prompt, local or recent-conversation references, task-specific size, explicit quality override, destination path |
+| User in `/99settings` | Cached/Indexed/Live mode and search context size | default image quality |
+| Extension/backend | session/model routing, caller policy and token ceiling | fixed `gpt-image-2`, automatic background, one PNG result, reference and dimension validation |
+
+Model selection, batch count, output format, input fidelity, masks, moderation,
+and transparent background are intentionally not advertised as AI arguments on
+this subscription path. In particular, GPT Image 2 does not support native
+transparent-background output; requesting transparency through an unsupported
+field would be misleading.
+
+## Bundled skill
+
+The package also ships the Agent Skills-standard **`gpt-image-prompts`** skill
+under `skills/`. Pi discovers it with the package and can load it on demand to
+write or refine production-ready GPT Image 2 prompts for new images,
+reference-guided work, and precise edits. Invoke it explicitly with:
+
+```text
+/skill:gpt-image-prompts
+```
+
+The skill contains visual prompt-writing guidance only. It does not select or
+document tools, construct API requests, manage credentials, or prescribe file
+and execution workflows.
+
+## Tool display
+
+Web and image queries render normalized source cards instead of the backend's
+raw citation dump. The collapsed view shows three title/domain/snippet cards;
+Pi's configured tool-output expansion shortcut (`Ctrl+O` by default) expands
+every source with its full URL. Internal reference markers,
+word-limit metadata, and separators are hidden. Open/click/find/PDF operations
+use a cleaned document view, while weather, finance, sports, and time lookups
+use a compact data view. This changes only the TUI display copy: the model
+still receives the complete original search output.
+
+Search and image parameters stream into the call row while the model constructs
+them; input parameters are never repeated in the result area. Both tools also
+stream real execution stages into the active result row while they run
+(authentication, request, reference loading, generation, and saving as
+applicable). Successful `codex_search` and `codex_image` calls also request a
+rate-limited background usage refresh. The Codex search and image endpoints
+return one final response, so result bodies appear atomically rather than as
+fabricated content chunks.
+
+## Commands
+
+```text
+/codex-usage
+```
+
+Fast mode is controlled only through **Codex API → Fast mode** in
+`/99settings`. It sends `service_tier: "priority"` on Codex Responses requests
+and can reduce latency while consuming included limits faster. The extension fetches
+subscription usage directly from Codex's official ChatGPT WHAM endpoint when a
+session starts or a Codex model is selected; `/codex-usage` forces a fresh
+read, so no model request is required first. Automatic post-response refreshes
+are limited to once per minute.
+
+Pi does not currently publish an OAuth-account-change event or expose its
+credential store to extensions. As a temporary compatibility layer, this
+extension watches Pi's agent-directory `auth.json`. A short debounce reloads
+the public model registry and compares the resolved Codex Account ID. After
+`/login` replaces the account, the old snapshot is removed, the status changes
+to `Codex syncing…`, and a forced account-scoped refresh starts. `/logout`
+clears the status. In-flight requests are revision-guarded, so an old account
+cannot overwrite the newly active account. The watcher is closed on session
+teardown and never accesses Pi's private authentication runtime.
+
+`/codex-usage` groups every metered limit under a simple `Codex usage` heading.
+Each server-provided window (for example 5h, daily, or weekly) uses a fixed
+20-cell bar whose filled portion represents remaining capacity, followed only
+by `% left` and its reset time. Additional credit availability stays under the
+same limit group. Inactive zero-value placeholder windows are hidden. Response
+headers remain supported as a fallback.
+
+## Settings
+
+Use the shared menu:
+
+```text
+/99settings
+```
+
+The **Codex API** section controls:
+
+- **Other providers** — off by default. When enabled, a non-Codex model may
+  call `codex_image` and `codex_search`; the extension resolves only the
+  separately logged-in `openai-codex` OAuth account. It never sends the active
+  model provider's credentials to ChatGPT.
+- **Fast mode** — enables or disables the priority service tier;
+- Cached, Indexed, or Live search;
+- search context size;
+- default GPT Image 2 quality (`Auto`, `Low`, `Medium`, or `High`);
+- subscription usage status visibility.
+
+Configuration is stored under the `codex-api` namespace in:
+
+```text
+~/.pi/agent/99extensions.json
+```
+
+## Authentication and privacy
+
+The extension asks Pi's model registry for a refreshed OAuth token at tool-call
+time. It sends the same bearer token and `ChatGPT-Account-ID` used by Pi's
+`openai-codex` adapter. With **Other providers** enabled, it resolves that
+Codex model specifically rather than using the active model's credentials.
+Tokens are never copied into extension settings or tool results. The extracted
+ChatGPT account ID is used only as an in-memory Usage-state key and is never
+persisted or displayed. The watcher reacts only to the `auth.json` filename;
+credential parsing and resolution remain inside Pi's public model registry.
+
+Image prompts, reference images, search commands, and search context are sent
+to OpenAI's Codex backend and are subject to the active ChatGPT workspace's
+policies. Feature availability and request formats may change as Codex rolls
+out backend updates.

package/client.ts

@@ -0,0 +1,237 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api";
+const CODEX_AUTH_CLAIM = "https://api.openai.com/auth";
+
+export type CodexFetch = typeof fetch;
+
+export interface CodexApiClientOptions {
+  accessToken: string;
+  accountId: string;
+  modelId?: string;
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  fetch?: CodexFetch;
+}
+
+export class CodexApiError extends Error {
+  readonly status: number;
+  readonly body: unknown;
+
+  constructor(status: number, message: string, body?: unknown) {
+    super(message);
+    this.name = "CodexApiError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+function headerValue(headers: Record<string, string> | undefined, name: string): string | undefined {
+  const normalized = name.toLowerCase();
+  return Object.entries(headers ?? {}).find(([key]) => key.toLowerCase() === normalized)?.[1];
+}
+
+export function extractCodexAccountId(accessToken: string): string {
+  try {
+    const parts = accessToken.split(".");
+    if (parts.length !== 3) throw new Error("not a JWT");
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8")) as {
+      [CODEX_AUTH_CLAIM]?: { chatgpt_account_id?: unknown };
+    };
+    const accountId = payload[CODEX_AUTH_CLAIM]?.chatgpt_account_id;
+    if (typeof accountId !== "string" || accountId.length === 0) throw new Error("missing claim");
+    return accountId;
+  } catch {
+    throw new Error("Failed to extract ChatGPT account ID from Codex OAuth token");
+  }
+}
+
+export function resolveCodexApiRoot(baseUrl = DEFAULT_CODEX_BASE_URL): string {
+  const normalized = baseUrl.trim().replace(/\/+$/, "");
+  if (normalized.endsWith("/codex/responses")) return normalized.slice(0, -"/responses".length);
+  if (normalized.endsWith("/codex")) return normalized;
+  return `${normalized}/codex`;
+}
+
+function errorMessage(status: number, statusText: string, body: unknown): string {
+  if (body && typeof body === "object") {
+    const error = (body as { error?: unknown }).error;
+    if (typeof error === "string" && error.trim()) return error;
+    if (error && typeof error === "object") {
+      const message = (error as { message?: unknown }).message;
+      if (typeof message === "string" && message.trim()) return message;
+    }
+    const message = (body as { message?: unknown }).message;
+    if (typeof message === "string" && message.trim()) return message;
+  }
+  if (typeof body === "string" && body.trim()) return body.trim();
+  return `Codex API request failed with HTTP ${status}${statusText ? ` ${statusText}` : ""}`;
+}
+
+async function responseBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function transportErrorCode(error: unknown): string | undefined {
+  const values = [
+    error,
+    error && typeof error === "object" ? (error as { cause?: unknown }).cause : undefined,
+  ];
+  for (const value of values) {
+    if (!value || typeof value !== "object") continue;
+    const code = (value as { code?: unknown }).code;
+    if (typeof code === "string" && /^[A-Z0-9_-]+$/.test(code)) return code;
+  }
+  return undefined;
+}
+
+function transportError(method: string, endpoint: string, error: unknown): CodexApiError {
+  const path = new URL(endpoint).pathname;
+  const code = transportErrorCode(error);
+  return new CodexApiError(
+    0,
+    `Codex network request failed before a response: ${method} ${path}${code ? ` (${code})` : ""}. `
+      + "No HTTP status was received, so a generation may or may not have reached ChatGPT. "
+      + "Automatic retry was not attempted.",
+  );
+}
+
+export class CodexApiClient {
+  readonly rootUrl: string;
+  readonly modelId?: string;
+  /** ChatGPT account identity used only for in-memory account-scoped state. */
+  readonly accountId: string;
+  private readonly accessToken: string;
+  private readonly headers: Record<string, string>;
+  private readonly fetchImpl: CodexFetch;
+
+  constructor(options: CodexApiClientOptions) {
+    this.rootUrl = resolveCodexApiRoot(options.baseUrl);
+    this.modelId = options.modelId;
+    this.accessToken = options.accessToken;
+    this.accountId = options.accountId;
+    this.headers = options.headers ?? {};
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  private endpoint(path: string): string {
+    const root = new URL(`${this.rootUrl}/`);
+    const endpoint = new URL(path.replace(/^\/+/, ""), root);
+    if (endpoint.protocol !== "https:" || endpoint.hostname !== "chatgpt.com" || endpoint.origin !== root.origin) {
+      throw new Error(`Refusing to send Codex OAuth credentials to non-ChatGPT endpoint: ${endpoint.origin}`);
+    }
+    return endpoint.toString();
+  }
+
+  private async request<T>(
+    method: "GET" | "POST",
+    path: string,
+    body: unknown,
+    signal?: AbortSignal,
+  ): Promise<T> {
+    const headers = new Headers(this.headers);
+    headers.set("authorization", `Bearer ${this.accessToken}`);
+    headers.set("chatgpt-account-id", this.accountId);
+    headers.set("originator", "pi");
+    headers.set("accept", "application/json");
+    if (body !== undefined) headers.set("content-type", "application/json");
+
+    const endpoint = this.endpoint(path);
+    let response: Response;
+    try {
+      response = await this.fetchImpl(endpoint, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal,
+      });
+    } catch (error) {
+      throw transportError(method, endpoint, error);
+    }
+    const parsed = await responseBody(response);
+    if (!response.ok) {
+      throw new CodexApiError(
+        response.status,
+        errorMessage(response.status, response.statusText, parsed),
+        parsed,
+      );
+    }
+    return parsed as T;
+  }
+
+  async get<T>(path: string, signal?: AbortSignal): Promise<T> {
+    return this.request<T>("GET", path, undefined, signal);
+  }
+
+  async post<T>(path: string, body: unknown, signal?: AbortSignal): Promise<T> {
+    return this.request<T>("POST", path, body, signal);
+  }
+}
+
+export interface CodexApiClientContextOptions {
+  /** Allow a non-Codex active model to use separately stored Codex OAuth. */
+  allowOtherProviders?: boolean;
+}
+
+function codexOAuthUnavailable(message?: string): Error {
+  return new Error(
+    `Codex subscription OAuth is unavailable${message ? `: ${message}` : ""}. `
+      + "Run /login and sign in to openai-codex, then retry.",
+  );
+}
+
+function resolveCodexAuthModel(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  allowOtherProviders: boolean,
+) {
+  if (ctx.model?.provider === "openai-codex") return ctx.model;
+  if (!allowOtherProviders) {
+    throw new Error(
+      "Codex API tools require an active openai-codex model. "
+        + "Enable Other providers in /99settings to use them from another model.",
+    );
+  }
+  const model = ctx.modelRegistry.getAll().find((candidate) =>
+    candidate.provider === "openai-codex" && ctx.modelRegistry.isUsingOAuth(candidate)
+  );
+  if (!model) throw codexOAuthUnavailable();
+  return model;
+}
+
+export async function createCodexApiClient(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  optionsOrFetch: CodexApiClientContextOptions | CodexFetch = {},
+  fetchImpl?: CodexFetch,
+): Promise<CodexApiClient> {
+  // Keep the former (ctx, fetch) call shape usable for extension consumers.
+  const options = typeof optionsOrFetch === "function" ? {} : optionsOrFetch;
+  const effectiveFetch = typeof optionsOrFetch === "function" ? optionsOrFetch : fetchImpl;
+  const model = resolveCodexAuthModel(ctx, options.allowOtherProviders === true);
+  if (!ctx.modelRegistry.isUsingOAuth(model)) {
+    throw codexOAuthUnavailable("API-key authentication is not supported");
+  }
+  const resolved = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!resolved.ok) throw codexOAuthUnavailable(resolved.error);
+  if (!resolved.apiKey) throw codexOAuthUnavailable();
+  const accountId = headerValue(resolved.headers, "chatgpt-account-id")
+    ?? extractCodexAccountId(resolved.apiKey);
+  const baseUrl = model.baseUrl ?? DEFAULT_CODEX_BASE_URL;
+  const endpoint = new URL(resolveCodexApiRoot(baseUrl));
+  if (endpoint.protocol !== "https:" || endpoint.hostname !== "chatgpt.com") {
+    throw new Error(`Refusing to send Codex OAuth credentials to non-ChatGPT endpoint: ${endpoint.origin}`);
+  }
+  return new CodexApiClient({
+    accessToken: resolved.apiKey,
+    accountId,
+    modelId: model.id,
+    baseUrl,
+    headers: resolved.headers,
+    fetch: effectiveFetch,
+  });
+}

package/config.ts

@@ -0,0 +1,79 @@
+import {
+  getSharedSettingsPath,
+  readSettingsNamespace,
+  writeSettingsNamespace,
+} from "@99percentpeople/pi-shared-settings";
+
+export type CodexSearchMode = "cached" | "indexed" | "live";
+export type CodexSearchContextSize = "low" | "medium" | "high";
+export type CodexImageQuality = "auto" | "low" | "medium" | "high";
+
+export interface CodexApiConfig {
+  fastMode: boolean;
+  allowOtherProviders: boolean;
+  searchMode: CodexSearchMode;
+  searchContextSize: CodexSearchContextSize;
+  imageQuality: CodexImageQuality;
+  usageStatus: boolean;
+}
+
+export const CODEX_API_SETTINGS_NAMESPACE = "codex-api";
+
+export const DEFAULT_CODEX_API_CONFIG: CodexApiConfig = {
+  fastMode: false,
+  allowOtherProviders: false,
+  searchMode: "cached",
+  searchContextSize: "medium",
+  imageQuality: "auto",
+  usageStatus: true,
+};
+
+function oneOf<T extends string>(value: unknown, values: readonly T[], fallback: T): T {
+  return typeof value === "string" && values.includes(value as T) ? value as T : fallback;
+}
+
+export function normalizeCodexApiConfig(value: unknown): CodexApiConfig {
+  if (!value || typeof value !== "object") return { ...DEFAULT_CODEX_API_CONFIG };
+  const input = value as Record<string, unknown>;
+  return {
+    fastMode: typeof input.fastMode === "boolean"
+      ? input.fastMode
+      : DEFAULT_CODEX_API_CONFIG.fastMode,
+    allowOtherProviders: typeof input.allowOtherProviders === "boolean"
+      ? input.allowOtherProviders
+      : DEFAULT_CODEX_API_CONFIG.allowOtherProviders,
+    searchMode: oneOf(
+      input.searchMode,
+      ["cached", "indexed", "live"],
+      DEFAULT_CODEX_API_CONFIG.searchMode,
+    ),
+    searchContextSize: oneOf(
+      input.searchContextSize,
+      ["low", "medium", "high"],
+      DEFAULT_CODEX_API_CONFIG.searchContextSize,
+    ),
+    imageQuality: oneOf(
+      input.imageQuality,
+      ["auto", "low", "medium", "high"],
+      DEFAULT_CODEX_API_CONFIG.imageQuality,
+    ),
+    usageStatus: typeof input.usageStatus === "boolean"
+      ? input.usageStatus
+      : DEFAULT_CODEX_API_CONFIG.usageStatus,
+  };
+}
+
+export function getCodexApiConfigPath(): string {
+  return getSharedSettingsPath();
+}
+
+export function loadCodexApiConfig(path = getCodexApiConfigPath()): CodexApiConfig {
+  return readSettingsNamespace(CODEX_API_SETTINGS_NAMESPACE, normalizeCodexApiConfig, path);
+}
+
+export function saveCodexApiConfig(
+  config: CodexApiConfig,
+  path = getCodexApiConfigPath(),
+): void {
+  writeSettingsNamespace(CODEX_API_SETTINGS_NAMESPACE, normalizeCodexApiConfig(config), path);
+}