@monotykamary/pi-better-openai 0.1.23 → 0.1.25

package/README.md

@@ -85,7 +85,7 @@ Example config:
   },
   "image": {
     "enabled": true,
-    "defaultModel": "gpt-5.5",
+    "defaultModel": "gpt-image-2",
     "defaultSave": "project",
     "outputFormat": "png",
     "timeoutMs": 180000
@@ -135,10 +135,10 @@ Use the command for quick generation:
 Agents can call the `openai_image` tool directly. Supported parameters:
 
 - `prompt` (required): pass the user's image wording verbatim.
-- `action`: `auto`, `generate`, or `edit`.
+- `action`: `auto`, `generate`, or `edit`. `auto` uses the edit endpoint when `images` are supplied; explicit `edit` requires images, while explicit `generate` does not accept them.
 - `images`: up to five distinct project-local reference/edit image paths. Paths must stay inside the current workspace and point to readable PNG, JPEG, WebP, or GIF files; each file is limited to 20 MB and the combined input to 50 MB.
-- `model`: Codex image model override, for example `openai-codex/gpt-5.5`.
-- `outputFormat`: `png`, `jpeg`, or `webp`.
+- `model`: GPT Image model override for the standalone Codex Images API, for example `gpt-image-2`.
+- `outputFormat`: `png`, `jpeg`, or `webp`. Codex returns PNG and the extension converts other formats locally.
 - `save`: `project`, `global`, `custom`, or `none`.
 - `saveDir`: required for `save: "custom"` unless `PI_IMAGE_SAVE_DIR` is set.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-better-openai",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "Improve OpenAI in pi with fast mode, usage stats, realtime voice, image generation, and footer polish.",
   "keywords": [
     "fast",
@@ -71,9 +71,6 @@
     "@oh-my-pi/pi-natives-linux-x64": "17.2.9",
     "@oh-my-pi/pi-natives-win32-x64": "17.2.9"
   },
-  "overrides": {
-    "postcss": "8.5.25"
-  },
   "engines": {
     "node": ">=22.19.0"
   },
@@ -83,7 +80,7 @@
     ]
   },
   "scripts": {
-    "check": "npm run typecheck && npm run lint && npm run format:check && npm test",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm test",
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "lint": "oxlint --deny-warnings index.ts src/*.ts src/*/*.ts tests/*.ts",

package/src/config.ts

@@ -130,9 +130,11 @@ export const DEFAULT_FOOTER_CONFIG: Required<FooterConfig> = {
   mode: "replace",
 };
 
+export const DEFAULT_IMAGE_MODEL = "gpt-image-2";
+
 export const DEFAULT_IMAGE_CONFIG: Required<ImageConfig> = {
   enabled: true,
-  defaultModel: "gpt-5.5",
+  defaultModel: DEFAULT_IMAGE_MODEL,
   defaultSave: "project",
   outputFormat: "png",
   timeoutMs: 180_000,
@@ -276,8 +278,8 @@ export const IMAGE_SETTING_DESCRIPTORS: readonly SettingsOptionDescriptor[] = [
     key: "defaultModel",
     label: "Image model",
     currentValue: (cfg) => cfg.image.defaultModel,
-    values: ["gpt-5.5", "gpt-5.4", "gpt-5.2", "gpt-5"],
-    description: "Mainline model used for image generation when current model is not openai-codex.",
+    values: ["gpt-image-2"],
+    description: "GPT Image model used by the standalone Codex Images API.",
     parse: stringSetting,
   },
   {
@@ -297,7 +299,7 @@ export const IMAGE_SETTING_DESCRIPTORS: readonly SettingsOptionDescriptor[] = [
     label: "Image format",
     currentValue: (cfg) => cfg.image.outputFormat,
     values: IMAGE_OUTPUT_FORMATS,
-    description: "Generated image file format.",
+    description: "Returned image format (converted locally from the Codex PNG response).",
     parse: stringSetting,
   },
   {
@@ -502,6 +504,12 @@ export function readRawConfig(path: string): Record<string, unknown> {
   }
 }
 
+export function normalizeImageModel(value: string): string {
+  const trimmed = value.trim();
+  const model = trimmed.includes("/") ? trimmed.split("/").pop() || trimmed : trimmed;
+  return model.startsWith("gpt-5") ? DEFAULT_IMAGE_MODEL : model;
+}
+
 export function readConfig(path: string): ConfigFile | undefined {
   if (!existsSync(path)) return undefined;
   const parsed = readRawConfig(path);
@@ -532,7 +540,7 @@ export function readConfig(path: string): ConfigFile | undefined {
     config.image = {};
     if (typeof parsed.image.enabled === "boolean") config.image.enabled = parsed.image.enabled;
     if (typeof parsed.image.defaultModel === "string" && parsed.image.defaultModel.trim())
-      config.image.defaultModel = parsed.image.defaultModel.trim();
+      config.image.defaultModel = normalizeImageModel(parsed.image.defaultModel);
     if (
       typeof parsed.image.defaultSave === "string" &&
       (IMAGE_SAVE_MODES as readonly string[]).includes(parsed.image.defaultSave)

package/src/image.ts

@@ -5,8 +5,7 @@ import { extname, isAbsolute, join, resolve, sep } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Box, Container, Image, Text } from "@earendil-works/pi-tui";
 import sharp from "sharp";
-import type { ResolvedConfig } from "./config.ts";
-import { isRecord } from "./config.ts";
+import { isRecord, normalizeImageModel, type ResolvedConfig } from "./config.ts";
 import {
   extractAccountIdFromJwt,
   getCodexCredentials,
@@ -17,13 +16,14 @@ import { piAgentDir, resolveUserPath } from "./paths.ts";
 
 const OPENAI_IMAGE_TOOL = "openai_image";
 const OPENAI_IMAGE_COMMAND = "openai-image";
-const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
+const CODEX_IMAGES_BASE_URL = "https://chatgpt.com/backend-api/codex/images";
+const CODEX_IMAGE_GENERATIONS_URL = `${CODEX_IMAGES_BASE_URL}/generations`;
+const CODEX_IMAGE_EDITS_URL = `${CODEX_IMAGES_BASE_URL}/edits`;
 const DEFAULT_TIMEOUT_MS = 180_000;
 const MAX_IMAGE_INPUT_BYTES = 20 * 1024 * 1024;
 const MAX_IMAGE_INPUTS = 5;
 const MAX_TOTAL_IMAGE_INPUT_BYTES = 50 * 1024 * 1024;
 const SUPPORTED_INPUT_IMAGE_FORMATS = new Set(["png", "jpeg", "jpg", "webp", "gif"]);
-const SSE_EVENT_BOUNDARY = /\r?\n\r?\n/;
 
 export const IMAGE_SAVE_MODES = ["none", "project", "global", "custom"] as const;
 export const IMAGE_ACTIONS = ["auto", "generate", "edit"] as const;
@@ -56,12 +56,12 @@ const TOOL_PARAMS = {
     model: {
       type: "string",
       description:
-        "OpenAI Codex model to drive the hosted image_generation tool. Defaults to current openai-codex model or config default.",
+        "GPT Image model for the standalone Codex Images API. Defaults to the configured image model.",
     },
     outputFormat: {
       type: "string",
       enum: IMAGE_OUTPUT_FORMATS,
-      description: "Generated image format.",
+      description: "Returned image format; JPEG and WebP are converted locally from Codex PNG.",
     },
     save: {
       type: "string",
@@ -131,15 +131,9 @@ async function getCredentials(
   throw new Error("Missing openai-codex OAuth credentials. Run /login openai-codex.");
 }
 
-function resolveModel(
-  params: Pick<ToolParams, "model">,
-  ctx: ExtensionContext,
-  cfg: ResolvedConfig,
-): string {
+function resolveModel(params: Pick<ToolParams, "model">, cfg: ResolvedConfig): string {
   const model = params.model?.trim();
-  if (model) return model.includes("/") ? model.split("/").pop() || model : model;
-  if (ctx.model?.provider === "openai-codex") return ctx.model.id;
-  return cfg.image.defaultModel;
+  return normalizeImageModel(model || cfg.image.defaultModel);
 }
 
 function resolveImageConfig(cfg: ResolvedConfig, params: ToolParams) {
@@ -263,35 +257,48 @@ async function saveImage(
   return path;
 }
 
+type ConcreteImageAction = Exclude<ImageAction, "auto">;
+
+type StandaloneImageRequest = {
+  action: ConcreteImageAction;
+  endpoint: string;
+  body: Record<string, unknown>;
+};
+
 function buildRequest(
   params: ToolParams,
   model: string,
   cfg: ResolvedConfig,
   images: ImageInput[],
-) {
-  const { action, outputFormat } = resolveImageConfig(cfg, params);
-  const content: Array<Record<string, unknown>> = [{ type: "input_text", text: params.prompt }];
-  for (const image of images) {
-    content.push({
-      type: "input_image",
-      detail: "auto",
-      image_url: `data:${image.mimeType};base64,${image.data}`,
-    });
-  }
-  const tool: Record<string, unknown> = { type: "image_generation", output_format: outputFormat };
-  if (action !== "auto") tool.action = action;
-  return {
+): StandaloneImageRequest {
+  const { action: requestedAction } = resolveImageConfig(cfg, params);
+  const action: ConcreteImageAction =
+    requestedAction === "auto" ? (images.length > 0 ? "edit" : "generate") : requestedAction;
+  if (action === "edit" && images.length === 0)
+    throw new Error("action=edit requires at least one image.");
+  if (action === "generate" && images.length > 0)
+    throw new Error("action=generate does not accept images; use action=auto or action=edit.");
+
+  const common = {
+    prompt: params.prompt,
+    background: "auto",
     model,
-    instructions: "",
-    input: [{ role: "user", content }],
-    tools: [tool],
-    tool_choice: { type: "image_generation" },
-    parallel_tool_calls: false,
-    store: false,
-    stream: true,
-    include: [],
-    client_metadata: { "x-codex-installation-id": "pi-better-openai" },
+    quality: "auto",
+    size: "auto",
   };
+  if (action === "edit") {
+    return {
+      action,
+      endpoint: CODEX_IMAGE_EDITS_URL,
+      body: {
+        images: images.map((image) => ({
+          image_url: `data:${image.mimeType};base64,${image.data}`,
+        })),
+        ...common,
+      },
+    };
+  }
+  return { action, endpoint: CODEX_IMAGE_GENERATIONS_URL, body: common };
 }
 
 function dataUrlParts(value: string, fallbackMimeType: string): { data: string; mimeType: string } {
@@ -304,21 +311,72 @@ function dataUrlParts(value: string, fallbackMimeType: string): { data: string;
   return { data: value.trim(), mimeType: fallbackMimeType };
 }
 
-function asImageResultItem(
-  value: unknown,
-):
-  | { id?: string; status?: string; revised_prompt?: string; result?: string; b64_json?: string }
-  | undefined {
-  if (!isRecord(value) || value.type !== "image_generation_call") return undefined;
-  return value as {
-    id?: string;
-    status?: string;
-    revised_prompt?: string;
-    result?: string;
-    b64_json?: string;
+function parseImageResponsePayload(payload: unknown, requestId: string): ExtractedImageResult {
+  if (!isRecord(payload) || !Array.isArray(payload.data))
+    throw new Error("Invalid response from Codex Images API.");
+
+  let image: Record<string, unknown> | undefined;
+  for (const item of payload.data) {
+    if (isRecord(item) && typeof item.b64_json === "string" && item.b64_json.trim()) {
+      image = item;
+      break;
+    }
+  }
+  if (!image) throw new Error("No image data returned by Codex Images API.");
+
+  const responseFormat =
+    typeof payload.output_format === "string" &&
+    (IMAGE_OUTPUT_FORMATS as readonly string[]).includes(payload.output_format)
+      ? (payload.output_format as ImageOutputFormat)
+      : "png";
+  const { data, mimeType } = dataUrlParts(
+    image.b64_json as string,
+    imageMimeType(`image.${responseFormat}`, responseFormat),
+  );
+  const safeRequestId = requestId.replace(/[^a-zA-Z0-9_-]/g, "_") || randomUUID().slice(0, 8);
+  return {
+    id: typeof image.id === "string" ? image.id : `ig_${safeRequestId}`,
+    status: "completed",
+    revisedPrompt: typeof image.revised_prompt === "string" ? image.revised_prompt : undefined,
+    data,
+    mimeType,
   };
 }
 
+async function parseImageResponse(
+  response: Response,
+  requestId: string,
+): Promise<ExtractedImageResult> {
+  let payload: unknown;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error("Invalid response from Codex Images API.");
+  }
+  return parseImageResponsePayload(payload, requestId);
+}
+
+async function convertImageOutput(
+  image: ExtractedImageResult,
+  outputFormat: ImageOutputFormat,
+): Promise<ExtractedImageResult> {
+  const targetMimeType = imageMimeType(`image.${outputFormat}`, outputFormat);
+  if (image.mimeType === targetMimeType) return image;
+
+  try {
+    const input = sharp(Buffer.from(image.data, "base64"), { animated: false });
+    const output =
+      outputFormat === "jpeg"
+        ? await input.jpeg().toBuffer()
+        : outputFormat === "webp"
+          ? await input.webp().toBuffer()
+          : await input.png().toBuffer();
+    return { ...image, data: output.toString("base64"), mimeType: targetMimeType };
+  } catch {
+    throw new Error(`Failed to convert Codex image output to ${outputFormat}.`);
+  }
+}
+
 function isImageContent(
   value: unknown,
 ): value is { type: "image"; data: string; mimeType: string } {
@@ -330,106 +388,6 @@ function isImageContent(
   );
 }
 
-function extractImageFromEvent(
-  event: unknown,
-  fallbackMimeType: string,
-): ExtractedImageResult | undefined {
-  if (!isRecord(event)) return undefined;
-  const item = asImageResultItem(event.item) ?? asImageResultItem(event);
-  if (item) {
-    const raw =
-      typeof item.result === "string" && item.result.trim()
-        ? item.result
-        : typeof item.b64_json === "string"
-          ? item.b64_json
-          : undefined;
-    if (!raw) return undefined;
-    const { data, mimeType } = dataUrlParts(raw, fallbackMimeType);
-    return {
-      id: typeof item.id === "string" ? item.id : `ig_${randomUUID().slice(0, 8)}`,
-      status: typeof item.status === "string" ? item.status : "completed",
-      revisedPrompt: typeof item.revised_prompt === "string" ? item.revised_prompt : undefined,
-      data,
-      mimeType,
-    };
-  }
-  const partial =
-    typeof event.partial_image_b64 === "string"
-      ? event.partial_image_b64
-      : typeof event.b64_json === "string"
-        ? event.b64_json
-        : undefined;
-  if (typeof partial === "string" && partial.trim()) {
-    const { data, mimeType } = dataUrlParts(partial, fallbackMimeType);
-    return { id: `ig_${randomUUID().slice(0, 8)}`, status: "partial", data, mimeType };
-  }
-  return undefined;
-}
-
-async function parseSseForImage(
-  response: Response,
-  fallbackMimeType: string,
-  signal?: AbortSignal,
-): Promise<ExtractedImageResult> {
-  if (!response.body) throw new Error("No response body from Codex image request.");
-  const reader = response.body.getReader();
-  const decoder = new TextDecoder();
-  let buffer = "";
-  try {
-    while (true) {
-      if (signal?.aborted) throw new Error("Image request was aborted.");
-      const { done, value } = await reader.read();
-      if (done) break;
-      buffer += decoder.decode(value, { stream: true });
-      let boundary = SSE_EVENT_BOUNDARY.exec(buffer);
-      while (boundary) {
-        const idx = boundary.index;
-        const chunk = buffer.slice(0, idx);
-        buffer = buffer.slice(idx + boundary[0].length);
-        const data = chunk
-          .split(/\r?\n/)
-          .filter((line) => line.startsWith("data:"))
-          .map((line) => line.slice(5).trim())
-          .join("\n")
-          .trim();
-        if (data && data !== "[DONE]") {
-          let event: unknown;
-          try {
-            event = JSON.parse(data);
-          } catch {
-            event = undefined;
-          }
-          const image = extractImageFromEvent(event, fallbackMimeType);
-          if (image?.data && image.status === "completed") {
-            await reader.cancel().catch(() => undefined);
-            return image;
-          }
-          if (isRecord(event) && event.type === "response.failed") {
-            const error =
-              isRecord(event.response) && isRecord(event.response.error)
-                ? event.response.error
-                : undefined;
-            const message = sanitizeDiagnosticError(
-              typeof error?.message === "string" ? error.message : "Codex image request failed.",
-            );
-            throw new Error(message);
-          }
-          if (isRecord(event) && event.type === "error") {
-            const message = sanitizeDiagnosticError(
-              typeof event.message === "string" ? event.message : JSON.stringify(event),
-            );
-            throw new Error(`Codex image error: ${message}`);
-          }
-        }
-        boundary = SSE_EVENT_BOUNDARY.exec(buffer);
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-  throw new Error("No completed image_generation_call result returned by Codex.");
-}
-
 async function requestCodexImage(
   params: ToolParams,
   ctx: ExtensionContext,
@@ -437,9 +395,10 @@ async function requestCodexImage(
   requestSignal?: AbortSignal,
 ): Promise<CodexImageResult> {
   if (!cfg.image.enabled) throw new Error("OpenAI image generation is disabled in config.");
+  if (!params.prompt.trim()) throw new Error("Image prompt must not be empty.");
   const cwd = ctx.cwd || process.cwd();
-  const model = resolveModel(params, ctx, cfg);
-  const { action, outputFormat, save } = resolveImageConfig(cfg, params);
+  const model = resolveModel(params, cfg);
+  const { outputFormat, save } = resolveImageConfig(cfg, params);
   const saveDir = resolveSaveDir(save, params, cwd);
   const timeoutSignal = AbortSignal.timeout(cfg.image.timeoutMs);
   const baseSignal = requestSignal ?? ctx.signal;
@@ -447,18 +406,19 @@ async function requestCodexImage(
   const credentials = await getCredentials(ctx, signal);
   const images = await readImageInputs(params.images, cwd);
   const request = buildRequest(params, model, cfg, images);
-  const response = await fetch(CODEX_RESPONSES_URL, {
+  const requestId = randomUUID();
+  const response = await fetch(request.endpoint, {
     method: "POST",
     headers: {
       authorization: `Bearer ${credentials.accessToken}`,
       "chatgpt-account-id": credentials.accountId,
-      "OpenAI-Beta": "responses=experimental",
-      accept: "text/event-stream",
+      accept: "application/json",
       "content-type": "application/json",
       originator: "codex_cli_rs",
       "User-Agent": "codex_cli_rs/0.0.0 (pi-better-openai)",
+      "x-codex-image-turn-id": requestId,
     },
-    body: JSON.stringify(request),
+    body: JSON.stringify(request.body),
     signal,
   });
   if (!response.ok) {
@@ -467,15 +427,19 @@ async function requestCodexImage(
       : "";
     throw new Error(`Codex image request failed (${response.status}${statusText}).`);
   }
-  const parsed = await parseSseForImage(
-    response,
-    imageMimeType(`image.${outputFormat}`, outputFormat),
-    signal,
-  );
+  const parsed = await parseImageResponse(response, requestId);
+  const converted = await convertImageOutput(parsed, outputFormat);
   const savedPath = saveDir
-    ? await saveImage(parsed.data, outputFormat, saveDir, parsed.id)
+    ? await saveImage(converted.data, outputFormat, saveDir, converted.id)
     : undefined;
-  return { ...parsed, prompt: params.prompt, savedPath, model, action, outputFormat };
+  return {
+    ...converted,
+    prompt: params.prompt,
+    savedPath,
+    model,
+    action: request.action,
+    outputFormat,
+  };
 }
 
 function displayPath(path: string): string {
@@ -488,7 +452,7 @@ function displayPath(path: string): string {
 
 function resultText(result: CodexImageResult): string {
   const parts = [
-    `Generated image using OpenAI image_generation tool via openai-codex/${result.model}.`,
+    `Generated image using the OpenAI Codex Images API with ${result.model}.`,
     `Action: ${result.action}.`,
     `Prompt: ${result.prompt}`,
   ];
@@ -534,8 +498,8 @@ export function registerOpenAIImage(
       authFound: credentials !== undefined,
       authSource: credentials?.source,
       accountId: maskIdentifier(credentials?.accountId),
-      endpoint: CODEX_RESPONSES_URL,
-      defaultModel: ctx.model?.provider === "openai-codex" ? ctx.model.id : cfg.image.defaultModel,
+      endpoint: CODEX_IMAGES_BASE_URL,
+      defaultModel: cfg.image.defaultModel,
       defaultSave: cfg.image.defaultSave,
       enabled: cfg.image.enabled,
       lastStatus,
@@ -596,7 +560,7 @@ export function registerOpenAIImage(
   });
 
   pi.registerCommand(OPENAI_IMAGE_COMMAND, {
-    description: "Generate an image with OpenAI Codex image generation",
+    description: "Generate an image with the standalone OpenAI Codex Images API",
     handler: async (args, ctx) => {
       const prompt = args.trim();
       if (!prompt) {
@@ -621,7 +585,7 @@ export function registerOpenAIImage(
     name: OPENAI_IMAGE_TOOL,
     label: "OpenAI image",
     description:
-      "Generate or edit images through OpenAI Codex subscription auth using the hosted image_generation tool. Supports local reference/edit images and saves to the project by default.",
+      "Generate or edit images through the standalone Codex Images API using OpenAI subscription auth. Supports local reference/edit images and saves to the project by default.",
     promptSnippet: "Generate or edit raster images via OpenAI Codex subscription auth.",
     promptGuidelines: [
       "Use openai_image when the user asks to generate or edit a raster image, photo, illustration, mockup, texture, sprite, or bitmap asset.",
@@ -631,12 +595,12 @@ export function registerOpenAIImage(
     parameters: TOOL_PARAMS,
     async execute(_toolCallId, params: ToolParams, signal, onUpdate, ctx) {
       const cfg = getConfig(ctx);
-      const model = resolveModel(params, ctx, cfg);
+      const model = resolveModel(params, cfg);
       onUpdate?.({
         content: [
           {
             type: "text",
-            text: `Requesting OpenAI image_generation via openai-codex/${model}...`,
+            text: `Requesting OpenAI Codex image via ${model}...`,
           },
         ],
         details: undefined,
@@ -656,7 +620,9 @@ export function registerOpenAIImage(
 }
 
 export const _imageTest = {
-  CODEX_RESPONSES_URL,
+  CODEX_IMAGES_BASE_URL,
+  CODEX_IMAGE_GENERATIONS_URL,
+  CODEX_IMAGE_EDITS_URL,
   DEFAULT_TIMEOUT_MS,
   OPENAI_IMAGE_TOOL,
   OPENAI_IMAGE_COMMAND,
@@ -666,7 +632,7 @@ export const _imageTest = {
   extractAccountIdFromJwt,
   imageMimeType,
   dataUrlParts,
-  extractImageFromEvent,
+  parseImageResponsePayload,
   displayPath,
   buildRequest,
 };

package/src/live/controller.ts

@@ -25,7 +25,14 @@ Treat delegation context as your own internal progress and result. Never mention
 
 For greetings, clarification, or ordinary conversation that needs no tools, answer directly without delegating. Preserve one-assistant continuity: converse here, delegate execution, then communicate the returned result as your own.`;
 
-export type LivePhase = "connecting" | "listening" | "working" | "speaking" | "muted" | "error";
+export type LivePhase =
+  | "standby"
+  | "connecting"
+  | "listening"
+  | "working"
+  | "speaking"
+  | "muted"
+  | "error";
 
 export interface LiveTranscript {
   role: "user" | "assistant";

package/src/live/focus.ts

@@ -0,0 +1,92 @@
+// Terminal focus tracking via private mode 1004 (xterm focus-event reporting).
+// Enabling `CSI ? 1004 h` makes the terminal emit `CSI I` on focus-in and
+// `CSI O` on focus-out as input sequences; pi-tui's stdin buffer frames them
+// as generic CSI and forwards them to input listeners unmodified, so an
+// extension can observe them without any upstream keymap changes. Support is
+// detected with a DECRQM probe (`CSI ? 1004 $ p` -> `CSI ? 1004 ; 1 $ y` set /
+// `; 2 $ y` reset); terminals that ignore both sequences simply fall back to
+// the FIFO floor policy. Supported by iTerm2, kitty, WezTerm, Alacritty, foot,
+// Windows Terminal, xterm.js, and modern tmux.
+
+export const FOCUS_REPORTING_ENABLE = "\x1b[?1004h";
+export const FOCUS_REPORTING_DISABLE = "\x1b[?1004l";
+export const FOCUS_IN_SEQUENCE = "\x1b[I";
+export const FOCUS_OUT_SEQUENCE = "\x1b[O";
+export const DECRQM_FOCUS_QUERY = "\x1b[?1004$p";
+
+export type FocusInputListener = (data: string) => { consume?: boolean; data?: string } | undefined;
+
+export interface FocusTerminalHandle {
+  write(data: string): void;
+  addInputListener(listener: FocusInputListener): () => void;
+}
+
+export function parseFocusSequence(data: string): boolean | undefined {
+  if (data === FOCUS_IN_SEQUENCE) return true;
+  if (data === FOCUS_OUT_SEQUENCE) return false;
+  return undefined;
+}
+
+export function parseDecrqmFocusResponse(data: string): boolean | undefined {
+  if (data === "\x1b[?1004;1$y" || data === "\x1b[?1004;3$y") return true;
+  if (data === "\x1b[?1004;2$y" || data === "\x1b[?1004;4$y") return false;
+  return undefined;
+}
+
+export function probeFocusReporting(
+  handle: FocusTerminalHandle,
+  timeoutMs = 400,
+): Promise<boolean> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let removeListener: (() => void) | undefined;
+    const done = (supported: boolean) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      removeListener?.();
+      resolve(supported);
+    };
+    const timer = setTimeout(() => done(false), timeoutMs);
+    timer.unref?.();
+    try {
+      removeListener = handle.addInputListener((data) => {
+        const state = parseDecrqmFocusResponse(data);
+        if (state === undefined) return undefined;
+        done(true);
+        return { consume: true };
+      });
+      handle.write(DECRQM_FOCUS_QUERY);
+    } catch {
+      done(false);
+    }
+  });
+}
+
+export function attachFocusReporting(
+  handle: FocusTerminalHandle,
+  onFocus: (focused: boolean) => void,
+): () => void {
+  const removeListener = handle.addInputListener((data) => {
+    const focused = parseFocusSequence(data);
+    if (focused === undefined) return undefined;
+    onFocus(focused);
+    return { consume: true };
+  });
+  try {
+    handle.write(FOCUS_REPORTING_ENABLE);
+  } catch {
+    // The terminal write path is best-effort; focus events simply never arrive.
+  }
+  let disposed = false;
+  return () => {
+    if (disposed) return;
+    disposed = true;
+    removeListener();
+    try {
+      handle.write(FOCUS_REPORTING_DISABLE);
+    } catch {
+      // Nothing to undo on a torn-down tty.
+    }
+  };
+}