@gakr-gakr/codex 0.1.0

package/src/app-server/rate-limit-cache.ts

@@ -0,0 +1,48 @@
+import type { JsonValue } from "./protocol.js";
+
+const DEFAULT_CODEX_RATE_LIMIT_CACHE_MAX_AGE_MS = 10 * 60_000;
+const CODEX_RATE_LIMIT_CACHE_STATE = Symbol.for("autobot.codexRateLimitCacheState");
+
+type CodexRateLimitCacheState = {
+  value?: JsonValue;
+  updatedAtMs?: number;
+};
+
+function getCodexRateLimitCacheState(): CodexRateLimitCacheState {
+  const globalState = globalThis as typeof globalThis & {
+    [CODEX_RATE_LIMIT_CACHE_STATE]?: CodexRateLimitCacheState;
+  };
+  globalState[CODEX_RATE_LIMIT_CACHE_STATE] ??= {};
+  return globalState[CODEX_RATE_LIMIT_CACHE_STATE];
+}
+
+export function rememberCodexRateLimits(value: JsonValue | undefined, nowMs = Date.now()): void {
+  if (value === undefined) {
+    return;
+  }
+  const state = getCodexRateLimitCacheState();
+  state.value = value;
+  state.updatedAtMs = nowMs;
+}
+
+export function readRecentCodexRateLimits(options?: {
+  nowMs?: number;
+  maxAgeMs?: number;
+}): JsonValue | undefined {
+  const state = getCodexRateLimitCacheState();
+  if (state.value === undefined || state.updatedAtMs === undefined) {
+    return undefined;
+  }
+  const nowMs = options?.nowMs ?? Date.now();
+  const maxAgeMs = options?.maxAgeMs ?? DEFAULT_CODEX_RATE_LIMIT_CACHE_MAX_AGE_MS;
+  if (maxAgeMs >= 0 && nowMs - state.updatedAtMs > maxAgeMs) {
+    return undefined;
+  }
+  return state.value;
+}
+
+export function resetCodexRateLimitCacheForTests(): void {
+  const state = getCodexRateLimitCacheState();
+  state.value = undefined;
+  state.updatedAtMs = undefined;
+}

package/src/app-server/rate-limits.ts

@@ -0,0 +1,583 @@
+import { isJsonObject, type JsonObject, type JsonValue } from "./protocol.js";
+
+const CODEX_LIMIT_ID = "codex";
+const LIMIT_WINDOW_KEYS = ["primary", "secondary"] as const;
+const ONE_SECOND_MS = 1000;
+const ONE_MINUTE_MS = 60_000;
+const ONE_HOUR_MS = 60 * ONE_MINUTE_MS;
+const ONE_DAY_MS = 24 * ONE_HOUR_MS;
+
+type LimitWindowKey = (typeof LIMIT_WINDOW_KEYS)[number];
+
+type RateLimitReset = {
+  resetsAtMs: number;
+  usedPercent?: number;
+  windowDurationMins?: number;
+};
+
+type RateLimitWindowEntry = {
+  key: LimitWindowKey;
+  window: RateLimitReset;
+};
+
+export type CodexAccountUsageSummary = {
+  usageLine?: string;
+  blocked: boolean;
+  blockedUntilMs?: number;
+  blockedUntilText?: string;
+  blockedResetRelative?: string;
+  blockingPeriod?: string;
+  blockingReason?: string;
+};
+
+export function formatCodexUsageLimitErrorMessage(params: {
+  message?: string | null;
+  codexErrorInfo?: JsonValue | null;
+  rateLimits?: JsonValue;
+  nowMs?: number;
+}): string | undefined {
+  const message = normalizeText(params.message);
+  if (!isCodexUsageLimitError(params.codexErrorInfo, message)) {
+    return undefined;
+  }
+  const nowMs = params.nowMs ?? Date.now();
+  const nextReset = selectNextRateLimitReset(params.rateLimits, nowMs);
+  const parts = ["You've reached your Codex subscription usage limit."];
+  if (nextReset) {
+    parts.push(`Next reset ${formatResetTime(nextReset.resetsAtMs, nowMs)}.`);
+  } else {
+    const codexRetryHint = extractCodexRetryHint(message);
+    if (codexRetryHint) {
+      parts.push(`Codex says to try again ${codexRetryHint}.`);
+    } else {
+      parts.push("Codex did not return a reset time for this limit.");
+    }
+  }
+  parts.push("Run /codex account for current usage details.");
+  return parts.join(" ");
+}
+
+export function shouldRefreshCodexRateLimitsForUsageLimitMessage(
+  message: string | null | undefined,
+): boolean {
+  const text = normalizeText(message);
+  return Boolean(
+    text?.includes("You've reached your Codex subscription usage limit.") &&
+    !text.includes("Next reset "),
+  );
+}
+
+export function summarizeCodexRateLimits(
+  value: JsonValue | undefined,
+  nowMs = Date.now(),
+): string | undefined {
+  const snapshots = collectCodexRateLimitSnapshots(value).filter(snapshotHasDisplayableData);
+  if (snapshots.length === 0) {
+    return undefined;
+  }
+  const summaries = snapshots
+    .slice(0, 4)
+    .map((snapshot) => summarizeRateLimitSnapshot(snapshot, nowMs))
+    .filter((summary): summary is string => summary !== undefined);
+  return summaries.length > 0 ? summaries.join("; ") : undefined;
+}
+
+export function hasCodexRateLimitSnapshots(value: JsonValue | undefined): boolean {
+  return collectCodexRateLimitSnapshots(value).length > 0;
+}
+
+export function summarizeCodexAccountRateLimits(
+  value: JsonValue | undefined,
+  nowMs = Date.now(),
+): string[] | undefined {
+  const summary = summarizeCodexAccountUsage(value, nowMs);
+  if (!summary) {
+    return undefined;
+  }
+  if (!summary.blocked) {
+    return ["Codex is available."];
+  }
+  return [
+    summary.blockedUntilText
+      ? `Codex is paused until ${summary.blockedUntilText}.`
+      : "Codex is paused by a usage limit.",
+    summary.blockingReason
+      ? `Your ${summary.blockingReason}.`
+      : "Your Codex usage limit is reached.",
+  ];
+}
+
+export function resolveCodexUsageLimitResetAtMs(
+  value: JsonValue | undefined,
+  nowMs = Date.now(),
+): number | undefined {
+  return selectBlockingRateLimitReset(value, nowMs)?.resetsAtMs;
+}
+
+export function summarizeCodexAccountUsage(
+  value: JsonValue | undefined,
+  nowMs = Date.now(),
+): CodexAccountUsageSummary | undefined {
+  const snapshots = collectCodexRateLimitSnapshots(value).filter(snapshotHasDisplayableData);
+  if (snapshots.length === 0) {
+    return undefined;
+  }
+  const usageSnapshot = snapshots.find(isCodexLimitSnapshot) ?? snapshots[0];
+  const blockedSnapshots = snapshots.filter(snapshotHasLimitBlock);
+  const blockingSnapshot =
+    blockedSnapshots.find(isCodexLimitSnapshot) ?? blockedSnapshots[0] ?? undefined;
+  const blockingReset = blockingSnapshot
+    ? selectSnapshotBlockingReset(blockingSnapshot, nowMs)
+    : undefined;
+  const blockingPeriod = formatBlockingLimitPeriod(blockingReset?.windowDurationMins);
+  const blockedUntilText = blockingReset
+    ? formatAccountResetTime(blockingReset.resetsAtMs, nowMs)
+    : undefined;
+  const blockedResetRelative = blockingReset
+    ? `in ${formatRelativeDuration(blockingReset.resetsAtMs - nowMs)}`
+    : undefined;
+  const blockingReason = blockingPeriod
+    ? `${blockingPeriod} Codex usage limit is reached`
+    : blockingSnapshot
+      ? "Codex usage limit is reached"
+      : undefined;
+  return {
+    usageLine: formatUsageLine(usageSnapshot),
+    blocked: Boolean(blockingSnapshot),
+    ...(blockingReset ? { blockedUntilMs: blockingReset.resetsAtMs } : {}),
+    ...(blockedUntilText ? { blockedUntilText } : {}),
+    ...(blockedResetRelative ? { blockedResetRelative } : {}),
+    ...(blockingPeriod ? { blockingPeriod } : {}),
+    ...(blockingReason ? { blockingReason } : {}),
+  };
+}
+
+function isCodexUsageLimitError(
+  codexErrorInfo: JsonValue | null | undefined,
+  message: string | undefined,
+): boolean {
+  if (codexErrorInfo === "usageLimitExceeded") {
+    return true;
+  }
+  if (typeof codexErrorInfo === "string") {
+    const normalized = codexErrorInfo.replace(/[_\s-]/gu, "").toLowerCase();
+    if (normalized === "usagelimitexceeded") {
+      return true;
+    }
+  }
+  return Boolean(message?.toLowerCase().includes("usage limit"));
+}
+
+function selectNextRateLimitReset(
+  value: JsonValue | undefined,
+  nowMs: number,
+): RateLimitReset | undefined {
+  const windows = collectCodexRateLimitSnapshots(value).flatMap((snapshot) =>
+    LIMIT_WINDOW_KEYS.flatMap((key) => readRateLimitWindow(snapshot, key) ?? []),
+  );
+  const futureWindows = windows.filter((window) => window.resetsAtMs > nowMs);
+  if (futureWindows.length === 0) {
+    return undefined;
+  }
+  const exhaustedWindows = futureWindows.filter(
+    (window) => window.usedPercent !== undefined && window.usedPercent >= 100,
+  );
+  const candidates = exhaustedWindows.length > 0 ? exhaustedWindows : futureWindows;
+  return candidates.toSorted((left, right) => left.resetsAtMs - right.resetsAtMs)[0];
+}
+
+function selectBlockingRateLimitReset(
+  value: JsonValue | undefined,
+  nowMs: number,
+): RateLimitReset | undefined {
+  const snapshots = collectCodexRateLimitSnapshots(value);
+  const blockedSnapshots = snapshots.filter(snapshotHasLimitBlock);
+  const blockingSnapshot =
+    blockedSnapshots.find(isCodexLimitSnapshot) ?? blockedSnapshots[0] ?? undefined;
+  return blockingSnapshot ? selectSnapshotBlockingReset(blockingSnapshot, nowMs) : undefined;
+}
+
+function summarizeRateLimitSnapshot(snapshot: JsonObject, nowMs: number): string | undefined {
+  const label = formatLimitLabel(snapshot);
+  const windows = LIMIT_WINDOW_KEYS.flatMap((key) => {
+    const window = readRateLimitWindow(snapshot, key);
+    return window ? [formatRateLimitWindow(key, window, nowMs)] : [];
+  });
+  const reachedType =
+    readString(snapshot, "rateLimitReachedType") ?? readString(snapshot, "rate_limit_reached_type");
+  const suffix = reachedType ? ` (${formatReachedType(reachedType)})` : "";
+  if (windows.length > 0) {
+    return `${label}: ${windows.join(" · ")}${suffix}`;
+  }
+  if (reachedType) {
+    return `${label}: ${formatReachedType(reachedType)}`;
+  }
+  return undefined;
+}
+
+function collectCodexRateLimitSnapshots(value: JsonValue | undefined): JsonObject[] {
+  const snapshots: JsonObject[] = [];
+  const seen = new Set<string>();
+  collectRateLimitSnapshots(value, snapshots, seen);
+  return snapshots;
+}
+
+function collectRateLimitSnapshots(
+  value: JsonValue | undefined,
+  snapshots: JsonObject[],
+  seen: Set<string>,
+): void {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      collectRateLimitSnapshots(entry, snapshots, seen);
+    }
+    return;
+  }
+  if (!isJsonObject(value)) {
+    return;
+  }
+  if (isRateLimitSnapshot(value)) {
+    addRateLimitSnapshot(value, snapshots, seen);
+    return;
+  }
+  const byLimitId = value.rateLimitsByLimitId;
+  if (isJsonObject(byLimitId)) {
+    for (const key of sortedRateLimitKeys(Object.keys(byLimitId))) {
+      collectRateLimitSnapshots(byLimitId[key], snapshots, seen);
+    }
+  }
+  const snakeByLimitId = value.rate_limits_by_limit_id;
+  if (isJsonObject(snakeByLimitId)) {
+    for (const key of sortedRateLimitKeys(Object.keys(snakeByLimitId))) {
+      collectRateLimitSnapshots(snakeByLimitId[key], snapshots, seen);
+    }
+  }
+  collectRateLimitSnapshots(value.rateLimits, snapshots, seen);
+  collectRateLimitSnapshots(value.rate_limits, snapshots, seen);
+  collectRateLimitSnapshots(value.data, snapshots, seen);
+  collectRateLimitSnapshots(value.items, snapshots, seen);
+}
+
+function sortedRateLimitKeys(keys: string[]): string[] {
+  return keys.toSorted((left, right) => {
+    if (left === CODEX_LIMIT_ID) {
+      return -1;
+    }
+    if (right === CODEX_LIMIT_ID) {
+      return 1;
+    }
+    return left.localeCompare(right);
+  });
+}
+
+function addRateLimitSnapshot(
+  snapshot: JsonObject,
+  snapshots: JsonObject[],
+  seen: Set<string>,
+): void {
+  const signature = [
+    readNullableString(snapshot, "limitId") ?? readNullableString(snapshot, "limit_id") ?? "",
+    readNullableString(snapshot, "limitName") ?? readNullableString(snapshot, "limit_name") ?? "",
+    formatWindowSignature(snapshot.primary),
+    formatWindowSignature(snapshot.secondary),
+  ].join("|");
+  if (seen.has(signature)) {
+    return;
+  }
+  seen.add(signature);
+  snapshots.push(snapshot);
+}
+
+function isRateLimitSnapshot(value: JsonObject): boolean {
+  return (
+    isJsonObject(value.primary) ||
+    isJsonObject(value.secondary) ||
+    value.rateLimitReachedType !== undefined ||
+    value.rate_limit_reached_type !== undefined ||
+    value.limitId !== undefined ||
+    value.limit_id !== undefined ||
+    value.limitName !== undefined ||
+    value.limit_name !== undefined
+  );
+}
+
+function readRateLimitWindow(
+  snapshot: JsonObject,
+  key: LimitWindowKey,
+): RateLimitReset | undefined {
+  const window = snapshot[key];
+  if (!isJsonObject(window)) {
+    return undefined;
+  }
+  const resetsAt = readNumber(window, "resetsAt") ?? readNumber(window, "resets_at");
+  return {
+    ...(typeof resetsAt === "number" && Number.isFinite(resetsAt) && resetsAt > 0
+      ? { resetsAtMs: resetsAt * 1000 }
+      : { resetsAtMs: 0 }),
+    ...readOptionalNumberField(window, "usedPercent", "used_percent"),
+    ...readOptionalNumberField(
+      window,
+      "windowDurationMins",
+      "window_duration_mins",
+      "windowMinutes",
+      "window_minutes",
+    ),
+  };
+}
+
+function snapshotHasDisplayableData(snapshot: JsonObject): boolean {
+  if (
+    readString(snapshot, "rateLimitReachedType") ??
+    readString(snapshot, "rate_limit_reached_type")
+  ) {
+    return true;
+  }
+  return readWindowEntries(snapshot).some(
+    (entry) => entry.window.usedPercent !== undefined || entry.window.resetsAtMs > 0,
+  );
+}
+
+function readOptionalNumberField(
+  record: JsonObject,
+  ...keys: string[]
+): { usedPercent?: number; windowDurationMins?: number } {
+  const value = keys.map((key) => readNumber(record, key)).find((entry) => entry !== undefined);
+  if (value === undefined) {
+    return {};
+  }
+  return keys.some((key) => key.toLowerCase().includes("window"))
+    ? { windowDurationMins: value }
+    : { usedPercent: value };
+}
+
+function formatRateLimitWindow(key: LimitWindowKey, window: RateLimitReset, nowMs: number): string {
+  return `${key} ${formatRateLimitWindowDetails(window, nowMs)}`;
+}
+
+function formatRateLimitWindowDetails(window: RateLimitReset, nowMs: number): string {
+  const remainingPercent =
+    window.usedPercent === undefined
+      ? "usage unknown"
+      : `${Math.max(0, 100 - Math.round(window.usedPercent))}% left`;
+  const reset =
+    window.resetsAtMs > nowMs ? ` ⏱${formatResetDuration(window.resetsAtMs, nowMs)}` : "";
+  return `${remainingPercent}${reset}`;
+}
+
+function formatLimitLabel(snapshot: JsonObject): string {
+  const label =
+    readNullableString(snapshot, "limitName") ??
+    readNullableString(snapshot, "limit_name") ??
+    readNullableString(snapshot, "limitId") ??
+    readNullableString(snapshot, "limit_id");
+  if (!label || label === CODEX_LIMIT_ID) {
+    return "Codex";
+  }
+  return label.replace(/[_-]+/gu, " ").replace(/\s+/gu, " ").trim();
+}
+
+function formatReachedType(value: string): string {
+  return value.replace(/[_-]+/gu, " ").replace(/\s+/gu, " ").trim();
+}
+
+function formatResetTime(resetsAtMs: number, nowMs: number): string {
+  return `in ${formatRelativeDuration(resetsAtMs - nowMs)}, ${formatCalendarResetTime(
+    resetsAtMs,
+    nowMs,
+  )}`;
+}
+
+function formatAccountResetTime(resetsAtMs: number, nowMs: number): string {
+  return `${formatCalendarResetTime(resetsAtMs, nowMs)} (in ${formatRelativeDuration(
+    resetsAtMs - nowMs,
+  )})`;
+}
+
+function snapshotHasLimitBlock(snapshot: JsonObject): boolean {
+  return Boolean(
+    readString(snapshot, "rateLimitReachedType") ??
+    readString(snapshot, "rate_limit_reached_type") ??
+    readWindowEntries(snapshot).some(
+      (entry) => entry.window.usedPercent !== undefined && entry.window.usedPercent >= 100,
+    ),
+  );
+}
+
+function isCodexLimitSnapshot(snapshot: JsonObject): boolean {
+  const id = readNullableString(snapshot, "limitId") ?? readNullableString(snapshot, "limit_id");
+  return !id || id === CODEX_LIMIT_ID;
+}
+
+function selectSnapshotBlockingReset(
+  snapshot: JsonObject,
+  nowMs: number,
+): RateLimitReset | undefined {
+  const futureWindows = readWindowEntries(snapshot)
+    .map((entry) => entry.window)
+    .filter((window) => window.resetsAtMs > nowMs);
+  const exhaustedWindows = futureWindows.filter(
+    (window) => window.usedPercent !== undefined && window.usedPercent >= 100,
+  );
+  const candidates = exhaustedWindows.length > 0 ? exhaustedWindows : futureWindows;
+  const resetSort =
+    exhaustedWindows.length > 0
+      ? (left: RateLimitReset, right: RateLimitReset) => right.resetsAtMs - left.resetsAtMs
+      : (left: RateLimitReset, right: RateLimitReset) => left.resetsAtMs - right.resetsAtMs;
+  return candidates.toSorted(resetSort)[0];
+}
+
+function readWindowEntries(snapshot: JsonObject): RateLimitWindowEntry[] {
+  return LIMIT_WINDOW_KEYS.flatMap((key) => {
+    const window = readRateLimitWindow(snapshot, key);
+    return window ? [{ key, window }] : [];
+  });
+}
+
+function formatBlockingLimitPeriod(minutes: number | undefined): string | undefined {
+  if (minutes === 7 * 24 * 60) {
+    return "weekly";
+  }
+  if (minutes === 24 * 60) {
+    return "daily";
+  }
+  if (minutes !== undefined && minutes > 0 && minutes < 24 * 60) {
+    return "short-term";
+  }
+  return undefined;
+}
+
+function formatUsageLine(snapshot: JsonObject): string | undefined {
+  const windows = readWindowEntries(snapshot)
+    .filter((entry) => entry.window.usedPercent !== undefined)
+    .toSorted(
+      (left, right) =>
+        (right.window.windowDurationMins ?? 0) - (left.window.windowDurationMins ?? 0),
+    )
+    .map((entry) => {
+      const label = formatUsageWindowLabel(entry.window.windowDurationMins);
+      return `${label} ${Math.round(entry.window.usedPercent ?? 0)}%`;
+    });
+  return windows.length > 0 ? windows.join(" \u00b7 ") : undefined;
+}
+
+function formatUsageWindowLabel(minutes: number | undefined): string {
+  if (minutes === 7 * 24 * 60) {
+    return "weekly";
+  }
+  if (minutes === 24 * 60) {
+    return "daily";
+  }
+  if (minutes !== undefined && minutes > 0 && minutes < 24 * 60) {
+    return "short-term";
+  }
+  if (minutes !== undefined && minutes > 0 && minutes % (24 * 60) === 0) {
+    const days = minutes / (24 * 60);
+    return `${days}-day`;
+  }
+  if (minutes !== undefined && minutes > 0 && minutes % 60 === 0) {
+    const hours = minutes / 60;
+    return `${hours}-hour`;
+  }
+  return "usage";
+}
+
+function formatCalendarResetTime(resetsAtMs: number, nowMs: number): string {
+  const resetDate = new Date(resetsAtMs);
+  const resetParts = new Intl.DateTimeFormat("en-US", {
+    month: "short",
+    day: "numeric",
+    ...(resetDate.getFullYear() === new Date(nowMs).getFullYear() ? {} : { year: "numeric" }),
+    hour: "numeric",
+    minute: "2-digit",
+    timeZoneName: "short",
+  }).formatToParts(resetDate);
+  const part = (type: Intl.DateTimeFormatPartTypes): string | undefined =>
+    resetParts.find((entry) => entry.type === type)?.value;
+  const dateParts = [part("month"), part("day"), part("year")].filter(Boolean);
+  const day =
+    dateParts.length > 1 ? `${dateParts[0]} ${dateParts.slice(1).join(", ")}` : dateParts[0];
+  const time = [part("hour"), part("minute")].filter(Boolean).join(":");
+  const dayPeriod = part("dayPeriod");
+  const timeZone = part("timeZoneName");
+  return [day, "at", [time, dayPeriod, timeZone].filter(Boolean).join(" ")]
+    .filter(Boolean)
+    .join(" ");
+}
+
+function formatRelativeDuration(durationMs: number): string {
+  const safeMs = Math.max(1_000, durationMs);
+  if (safeMs < ONE_MINUTE_MS) {
+    return `${Math.ceil(safeMs / 1000)} seconds`;
+  }
+  if (safeMs < ONE_HOUR_MS) {
+    const minutes = Math.ceil(safeMs / ONE_MINUTE_MS);
+    return `${minutes} ${minutes === 1 ? "minute" : "minutes"}`;
+  }
+  if (safeMs < ONE_DAY_MS) {
+    const hours = Math.ceil(safeMs / ONE_HOUR_MS);
+    return `${hours} ${hours === 1 ? "hour" : "hours"}`;
+  }
+  const days = Math.ceil(safeMs / ONE_DAY_MS);
+  return `${days} ${days === 1 ? "day" : "days"}`;
+}
+
+function formatResetDuration(resetsAtMs: number, nowMs: number): string {
+  const durationMs =
+    Math.round(Math.max(ONE_SECOND_MS, resetsAtMs - nowMs) / ONE_SECOND_MS) * ONE_SECOND_MS;
+  const days = Math.floor(durationMs / ONE_DAY_MS);
+  const hours = Math.floor((durationMs % ONE_DAY_MS) / ONE_HOUR_MS);
+  const minutes = Math.floor((durationMs % ONE_HOUR_MS) / ONE_MINUTE_MS);
+  const seconds = Math.floor((durationMs % ONE_MINUTE_MS) / ONE_SECOND_MS);
+  if (days > 0) {
+    return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+  }
+  if (hours > 0) {
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+  if (minutes > 0) {
+    return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
+  }
+  return `${seconds}s`;
+}
+
+function formatWindowSignature(value: JsonValue | undefined): string {
+  if (!isJsonObject(value)) {
+    return "";
+  }
+  return `${readNumber(value, "usedPercent") ?? readNumber(value, "used_percent") ?? ""}:${
+    readNumber(value, "resetsAt") ?? readNumber(value, "resets_at") ?? ""
+  }`;
+}
+
+function extractCodexRetryHint(message: string | undefined): string | undefined {
+  if (!message) {
+    return undefined;
+  }
+  const tryAgainAt = /\btry again\s+(at\s+[^.!?\n]+)(?:[.!?]|$)/iu.exec(message);
+  if (tryAgainAt?.[1]) {
+    return tryAgainAt[1].trim();
+  }
+  const tryAgainRelative = /\btry again\s+((?:tomorrow|in\s+[^.!?\n]+)[^.!?\n]*)(?:[.!?]|$)/iu.exec(
+    message,
+  );
+  return tryAgainRelative?.[1]?.trim();
+}
+
+function readString(record: JsonObject, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readNullableString(record: JsonObject, key: string): string | undefined {
+  return readString(record, key) ?? undefined;
+}
+
+function readNumber(record: JsonObject, key: string): number | undefined {
+  const value = record[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function normalizeText(value: string | null | undefined): string | undefined {
+  const text = value?.trim();
+  return text ? text : undefined;
+}

package/src/app-server/request.ts

@@ -0,0 +1,73 @@
+import type { resolveCodexAppServerAuthProfileIdForAgent } from "./auth-bridge.js";
+import type { CodexAppServerStartOptions } from "./config.js";
+import type {
+  CodexAppServerRequestMethod,
+  CodexAppServerRequestParams,
+  CodexAppServerRequestResult,
+  JsonValue,
+} from "./protocol.js";
+import {
+  createIsolatedCodexAppServerClient,
+  getSharedCodexAppServerClient,
+} from "./shared-client.js";
+import { withTimeout } from "./timeout.js";
+
+export async function requestCodexAppServerJson<M extends CodexAppServerRequestMethod>(params: {
+  method: M;
+  requestParams: CodexAppServerRequestParams<M>;
+  timeoutMs?: number;
+  startOptions?: CodexAppServerStartOptions;
+  authProfileId?: string | null;
+  agentDir?: string;
+  config?: Parameters<typeof resolveCodexAppServerAuthProfileIdForAgent>[0]["config"];
+  isolated?: boolean;
+}): Promise<CodexAppServerRequestResult<M>>;
+export async function requestCodexAppServerJson<T = JsonValue | undefined>(params: {
+  method: string;
+  requestParams?: unknown;
+  timeoutMs?: number;
+  startOptions?: CodexAppServerStartOptions;
+  authProfileId?: string | null;
+  agentDir?: string;
+  config?: Parameters<typeof resolveCodexAppServerAuthProfileIdForAgent>[0]["config"];
+  isolated?: boolean;
+}): Promise<T>;
+export async function requestCodexAppServerJson<T = JsonValue | undefined>(params: {
+  method: string;
+  requestParams?: unknown;
+  timeoutMs?: number;
+  startOptions?: CodexAppServerStartOptions;
+  authProfileId?: string | null;
+  agentDir?: string;
+  config?: Parameters<typeof resolveCodexAppServerAuthProfileIdForAgent>[0]["config"];
+  isolated?: boolean;
+}): Promise<T> {
+  const timeoutMs = params.timeoutMs ?? 60_000;
+  return await withTimeout(
+    (async () => {
+      const client = await (
+        params.isolated ? createIsolatedCodexAppServerClient : getSharedCodexAppServerClient
+      )({
+        startOptions: params.startOptions,
+        timeoutMs,
+        authProfileId: params.authProfileId,
+        agentDir: params.agentDir,
+        config: params.config,
+      });
+      try {
+        return await client.request<T>(params.method, params.requestParams, { timeoutMs });
+      } finally {
+        if (params.isolated) {
+          // Wait for the child to actually exit (with a SIGKILL fallback) so
+          // the parent process doesn't hang on an orphaned codex app-server.
+          // The stdio bin shim does not always propagate stdin EOF to the
+          // underlying codex binary, so the unref'd close() path can leave
+          // the child running and keep the parent's event loop alive.
+          await client.closeAndWait({ exitTimeoutMs: 2_000, forceKillDelayMs: 250 });
+        }
+      }
+    })(),
+    timeoutMs,
+    `codex app-server ${params.method} timed out`,
+  );
+}