@opengeni/codex 0.2.23 → 0.2.24

package/dist/meaningful-output.d.ts

@@ -0,0 +1,2 @@
+/** Conservative progress evidence; reasoning/usage/empty terminal bookkeeping is not work. */
+export declare function hasMeaningfulCodexOutput(output: unknown): boolean;

package/dist/reasoning-configuration.d.ts

@@ -0,0 +1,16 @@
+/** Durable control records; only providerData is sent by the SDK unknown-item adapter. */
+export declare const REASONING_CONFIGURATION_FIELD = "opengeniReasoningConfiguration";
+export type ConfigurationEffort = "low" | "medium" | "high" | "xhigh" | "max";
+export declare function supportsReasoningConfiguration(model: string, effort: string): effort is ConfigurationEffort;
+export type ReasoningConfiguration = {
+    version: 1;
+    baselineEffort: ConfigurationEffort;
+    effort: ConfigurationEffort;
+    turnId: string;
+};
+export declare function readReasoningConfiguration(item: Record<string, unknown>): ReasoningConfiguration | null;
+export declare function reasoningConfigurationItem(state: ReasoningConfiguration): Record<string, unknown>;
+export declare function latestReasoningConfiguration(items: readonly Record<string, unknown>[]): ReasoningConfiguration | null;
+export declare function isReasoningConfigurationUpdate(item: Record<string, unknown>): boolean;
+/** Never leak Astra controls to an incompatible model. Coalesce only adjacent controls. */
+export declare function projectReasoningConfigurations(items: Record<string, unknown>[], enabled: boolean): Record<string, unknown>[];

package/dist/request-context.d.ts

@@ -48,6 +48,8 @@ export type CodexModelRequestEvent = {
     providerRequestId?: string;
     status?: number;
     willRetry?: boolean;
+    /** Only true for a successful response with substantive assistant/tool output. */
+    meaningfulOutput?: boolean;
 };
 export type CodexRequestOpaqueArtifacts = {
     requestId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/codex",
-  "version": "0.2.23",
+  "version": "0.2.24",
   "description": "ChatGPT/Codex subscription auth + transport: device-code login, token refresh, and the Responses-backend fetch. Pure HTTP + transforms; no database dependency.",
   "license": "Apache-2.0",
   "repository": {

package/src/fetch.ts

@@ -11,6 +11,7 @@
 // Stream parsing is delegated to the SDK (SSE passthrough; spec §0(d)).
 
 import { randomUUID } from "node:crypto";
+import { hasMeaningfulCodexOutput } from "./meaningful-output";
 import { CODEX_ORIGINATOR } from "./constants";
 import { normalizeCodexRequestBody } from "./normalize";
 import { opaqueProviderArtifactFingerprints } from "./opaque-artifact";
@@ -95,6 +96,9 @@ export type CodexEncryptedArtifactRejection = {
   kind: "encrypted_content_rejected";
 };
 
+/** Exact Codex `error.code` for an opaque artifact the backend can no longer use. */
+export const CODEX_ENCRYPTED_CONTENT_REJECTION_CODE = "invalid_encrypted_content";
+
 /**
  * Classify only the provider's definitive request rejection for an opaque
  * reasoning artifact that it can no longer decrypt/parse. A Codex transport
@@ -113,6 +117,14 @@ export function classifyCodexEncryptedArtifactRejection(
         ? (value.error as Record<string, unknown>)
         : null;
     const status = Number(value.status ?? body?.status);
+    // The exact provider error code names this family without a message
+    // match: production compaction requests have been rejected with it while
+    // the human-readable text varied. It is never a generic 400.
+    const exactCode =
+      typeof body?.code === "string" ? body.code : typeof value.code === "string" ? value.code : "";
+    if (status === 400 && exactCode === CODEX_ENCRYPTED_CONTENT_REJECTION_CODE) {
+      return { status: 400, kind: "encrypted_content_rejected" };
+    }
     const message = [
       typeof value.message === "string" ? value.message : "",
       typeof body?.message === "string" ? body.message : "",
@@ -221,8 +233,7 @@ type RequestTerminalOutcome = "completed" | "failed" | "timed_out";
 
 type SemanticTerminalState = {
   phase: "completed" | "failed" | null;
-  /** Non-streaming callers must parse the complete SSE body before settling. */
-  deferTransportTerminal: boolean;
+  meaningfulOutput?: boolean;
 };
 
 type CodexSseEvent = {
@@ -312,6 +323,13 @@ function markSemanticTerminal(state: SemanticTerminalState, phase: "completed" |
   }
 }
 
+/** EOF and post-terminal cleanup must preserve the same recovery evidence. */
+function semanticCompletionEvidence(state: SemanticTerminalState | undefined): {
+  meaningfulOutput?: boolean;
+} {
+  return state?.phase === "completed" ? { meaningfulOutput: state.meaningfulOutput === true } : {};
+}
+
 function terminalOutcomeForPhase(
   phase: CodexModelRequestEvent["phase"],
 ): RequestTerminalOutcome | null {
@@ -426,6 +444,7 @@ async function observedResponse(
     if (semanticTerminal) markSemanticTerminal(semanticTerminal, "failed");
     await emitRequestEvent(audit, {
       phase: semanticTerminal?.phase ?? (res.ok ? "completed" : "failed"),
+      ...semanticCompletionEvidence(semanticTerminal),
       responseObserved: true,
       status: res.status,
       ...(requestId ? { providerRequestId: requestId } : {}),
@@ -459,6 +478,7 @@ async function observedResponse(
         void reader.cancel(error).catch(() => undefined);
         void emitRequestEvent(audit, {
           phase,
+          ...semanticCompletionEvidence(semanticTerminal),
           responseObserved: true,
           ...(phase === "timed_out" ? { timeoutClass: klass } : {}),
           status: res.status,
@@ -486,6 +506,7 @@ async function observedResponse(
         void reader.cancel(reason).catch(() => undefined);
         void emitRequestEvent(audit, {
           phase: semanticTerminal?.phase ?? "failed",
+          ...semanticCompletionEvidence(semanticTerminal),
           responseObserved: true,
           status: res.status,
           ...(requestId ? { providerRequestId: requestId } : {}),
@@ -512,14 +533,12 @@ async function observedResponse(
         if (chunk.done) {
           terminal = true;
           clearTimers();
-          if (semanticTerminal && semanticTerminal.phase === null) {
-            if (!semanticTerminal.deferTransportTerminal) {
-              markSemanticTerminal(semanticTerminal, "failed");
-            }
-          }
-          if (!semanticTerminal?.deferTransportTerminal || semanticTerminal.phase !== null) {
+          // The SSE parser owns EOF classification: it may still have a final
+          // terminal block buffered without a blank separator.
+          if (!semanticTerminal || semanticTerminal.phase !== null) {
             await emitRequestEvent(audit, {
               phase: semanticTerminal?.phase ?? (res.ok ? "completed" : "failed"),
+              ...semanticCompletionEvidence(semanticTerminal),
               responseObserved: true,
               status: res.status,
               ...(requestId ? { providerRequestId: requestId } : {}),
@@ -555,6 +574,7 @@ async function observedResponse(
         }
         await emitRequestEvent(audit, {
           phase: semanticPhase ?? "failed",
+          ...semanticCompletionEvidence(semanticTerminal),
           responseObserved: true,
           status: res.status,
           ...(requestId ? { providerRequestId: requestId } : {}),
@@ -575,6 +595,7 @@ async function observedResponse(
         }
         await emitRequestEvent(audit, {
           phase: semanticTerminal?.phase ?? "failed",
+          ...semanticCompletionEvidence(semanticTerminal),
           responseObserved: true,
           status: res.status,
           ...(requestId ? { providerRequestId: requestId } : {}),
@@ -749,7 +770,6 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
       });
       const semanticTerminal: SemanticTerminalState = {
         phase: null,
-        deferTransportTerminal: !callerWantsStream,
       };
       try {
         await ctx.beforeProviderDispatch?.();
@@ -835,9 +855,23 @@ export function codexSubscriptionFetch(base: FetchLike = globalThis.fetch): Fetc
         return buffered;
       }
       if (callerWantsStream) {
-        res = validateCodexStream(res, (phase) => {
-          markSemanticTerminal(semanticTerminal, phase);
-        });
+        res = validateCodexStream(
+          res,
+          (phase, meaningfulOutput) => {
+            markSemanticTerminal(semanticTerminal, phase);
+            semanticTerminal.meaningfulOutput = meaningfulOutput === true;
+          },
+          async () => {
+            const upstreamRequestId = providerRequestId(res.headers);
+            await emitRequestEvent(audit, {
+              phase: semanticTerminal.phase ?? "failed",
+              ...semanticCompletionEvidence(semanticTerminal),
+              responseObserved: true,
+              status: res.status,
+              ...(upstreamRequestId ? { providerRequestId: upstreamRequestId } : {}),
+            });
+          },
+        );
       } else {
         res = await sseToJsonResponse(res, audit, semanticTerminal);
       }
@@ -1081,6 +1115,7 @@ async function sseToJsonResponse(
   markSemanticTerminal(semanticTerminal, "completed");
   await emitRequestEvent(audit, {
     phase: "completed",
+    meaningfulOutput: hasMeaningfulCodexOutput(final?.output),
     responseObserved: true,
     status: res.status,
     ...(upstreamRequestId ? { providerRequestId: upstreamRequestId } : {}),
@@ -1362,7 +1397,8 @@ function codexSseFailureError(
  */
 function validateCodexStream(
   res: Response,
-  onSemanticTerminal?: (phase: "completed" | "failed") => void,
+  onSemanticTerminal?: (phase: "completed" | "failed", meaningfulOutput?: boolean) => void,
+  onParsedEof?: () => Promise<void>,
 ): Response {
   if (!res.body) {
     onSemanticTerminal?.("failed");
@@ -1389,6 +1425,12 @@ function validateCodexStream(
   const encoder = new TextEncoder();
   let buffer = "";
   let successfulTerminalSeen = false;
+  let meaningfulOutput = false;
+  const observeOutput = (output: unknown) => {
+    meaningfulOutput ||= hasMeaningfulCodexOutput(output);
+  };
+  const observeTerminal = (phase: "completed" | "failed") =>
+    onSemanticTerminal?.(phase, phase === "completed" && meaningfulOutput);
   const emitCompleteBlocks = (
     controller: TransformStreamDefaultController<Uint8Array>,
     final: boolean,
@@ -1398,7 +1440,7 @@ function validateCodexStream(
       const block = buffer.slice(0, boundary.start);
       const separator = buffer.slice(boundary.start, boundary.end);
       buffer = buffer.slice(boundary.end);
-      successfulTerminalSeen ||= inspectCodexSseBlock(block, res, onSemanticTerminal);
+      successfulTerminalSeen ||= inspectCodexSseBlock(block, res, observeTerminal, observeOutput);
       controller.enqueue(encoder.encode(`${block}${separator}`));
       boundary = findSseBlockBoundary(buffer, final);
     }
@@ -1408,21 +1450,34 @@ function validateCodexStream(
       buffer += decoder.decode(chunk, { stream: true });
       emitCompleteBlocks(controller, false);
     },
-    flush(controller) {
-      buffer += decoder.decode();
-      emitCompleteBlocks(controller, true);
-      if (buffer.length > 0) {
-        successfulTerminalSeen ||= inspectCodexSseBlock(buffer, res, onSemanticTerminal);
-        controller.enqueue(encoder.encode(buffer));
-        buffer = "";
-      }
-      if (!successfulTerminalSeen) {
-        throw codexSseFailureError(
-          res,
-          null,
-          "invalid_sse_terminal",
-          "The Codex response stream ended without a terminal response",
-        );
+    async flush(controller) {
+      try {
+        buffer += decoder.decode();
+        emitCompleteBlocks(controller, true);
+        if (buffer.length > 0) {
+          successfulTerminalSeen ||= inspectCodexSseBlock(
+            buffer,
+            res,
+            observeTerminal,
+            observeOutput,
+          );
+          controller.enqueue(encoder.encode(buffer));
+          buffer = "";
+        }
+        if (!successfulTerminalSeen) {
+          observeTerminal("failed");
+          throw codexSseFailureError(
+            res,
+            null,
+            "invalid_sse_terminal",
+            "The Codex response stream ended without a terminal response",
+          );
+        }
+      } finally {
+        // Raw transport EOF can precede parsing a final block without a blank
+        // separator. Settle only after that parse; the audit fence deduplicates
+        // an earlier terminal already observed from a complete block.
+        await onParsedEof?.();
       }
     },
   });
@@ -1475,14 +1530,15 @@ const CODEX_TERMINAL_TYPE_HINTS = [
 ] as const;
 
 /**
- * Parse only blocks that can be terminal. Ordinary deltas and output items pass
- * without object allocation; failed/error/incomplete terminals throw before the
+ * Parse terminal blocks and completed output items (retaining only a progress
+ * boolean). Ordinary deltas pass without object allocation; failure terminals throw before the
  * model can mistake them for an ordinary response_done event.
  */
 function inspectCodexSseBlock(
   block: string,
   source: Response,
   onSemanticTerminal?: (phase: "completed" | "failed") => void,
+  onOutput?: (output: unknown) => void,
 ): boolean {
   const lines = block.split(/\r\n|\r|\n/);
   const dataStr = lines
@@ -1492,7 +1548,10 @@ function inspectCodexSseBlock(
   if (!dataStr || dataStr === "[DONE]") {
     return false;
   }
-  if (!CODEX_TERMINAL_TYPE_HINTS.some((terminalType) => dataStr.includes(terminalType))) {
+  if (
+    !dataStr.includes('"response.output_item.done"') &&
+    !CODEX_TERMINAL_TYPE_HINTS.some((terminalType) => dataStr.includes(terminalType))
+  ) {
     return false;
   }
   let ev: CodexSseEvent;
@@ -1502,6 +1561,7 @@ function inspectCodexSseBlock(
     return false;
   }
   const terminal = classifyCodexSseTerminal(ev);
+  if (ev.type === "response.output_item.done") onOutput?.([ev.item]);
   if (terminal?.phase === "failed") {
     onSemanticTerminal?.("failed");
     throw codexSseFailureError(
@@ -1517,6 +1577,7 @@ function inspectCodexSseBlock(
     );
   }
   if (terminal?.phase === "completed") {
+    onOutput?.(ev.response?.output);
     onSemanticTerminal?.("completed");
     return true;
   }

package/src/index.ts

@@ -15,3 +15,4 @@ export * from "./opaque-artifact";
 export * from "./images";
 export * from "./realtime";
 export * from "./realtime-v3";
+export * from "./reasoning-configuration";

package/src/meaningful-output.ts

@@ -0,0 +1,36 @@
+/** Conservative progress evidence; reasoning/usage/empty terminal bookkeeping is not work. */
+export function hasMeaningfulCodexOutput(output: unknown): boolean {
+  if (!Array.isArray(output)) return false;
+  return output.some((value) => {
+    if (!value || typeof value !== "object") return false;
+    const item = value as Record<string, unknown>;
+    if (item.status !== undefined && item.status !== "completed") return false;
+    if (item.type === "message" && item.role === "assistant" && Array.isArray(item.content)) {
+      return item.content.some((part: unknown) => {
+        if (!part || typeof part !== "object") return false;
+        const content = part as Record<string, unknown>;
+        return (
+          content.type === "output_text" &&
+          typeof content.text === "string" &&
+          content.text.trim().length > 0
+        );
+      });
+    }
+    if (item.type === "function_call" || item.type === "custom_tool_call") {
+      const payload = item.type === "function_call" ? item.arguments : item.input;
+      return (
+        typeof item.name === "string" &&
+        item.name.trim().length > 0 &&
+        typeof item.call_id === "string" &&
+        item.call_id.length > 0 &&
+        typeof payload === "string" &&
+        payload.trim().length > 0
+      );
+    }
+    return (
+      item.type === "image_generation_call" &&
+      typeof item.result === "string" &&
+      item.result.length > 0
+    );
+  });
+}

package/src/reasoning-configuration.ts

@@ -0,0 +1,85 @@
+/** Durable control records; only providerData is sent by the SDK unknown-item adapter. */
+export const REASONING_CONFIGURATION_FIELD = "opengeniReasoningConfiguration";
+export type ConfigurationEffort = "low" | "medium" | "high" | "xhigh" | "max";
+const efforts = new Set<string>(["low", "medium", "high", "xhigh", "max"]);
+export function supportsReasoningConfiguration(
+  model: string,
+  effort: string,
+): effort is ConfigurationEffort {
+  return model === "gpt-6-astra" && efforts.has(effort);
+}
+export type ReasoningConfiguration = {
+  version: 1;
+  baselineEffort: ConfigurationEffort;
+  effort: ConfigurationEffort;
+  turnId: string;
+};
+export function readReasoningConfiguration(
+  item: Record<string, unknown>,
+): ReasoningConfiguration | null {
+  const state = item[REASONING_CONFIGURATION_FIELD] as ReasoningConfiguration | undefined;
+  if (
+    !state ||
+    state.version !== 1 ||
+    !efforts.has(state.baselineEffort) ||
+    !efforts.has(state.effort) ||
+    typeof state.turnId !== "string"
+  )
+    return null;
+  const data = item.providerData as Record<string, unknown> | undefined;
+  if (
+    item.type !== "unknown" ||
+    data?.type !== "configuration_update" ||
+    (data.reasoning as { effort?: unknown })?.effort !== state.effort
+  )
+    return null;
+  return state;
+}
+export function reasoningConfigurationItem(state: ReasoningConfiguration): Record<string, unknown> {
+  return {
+    type: "unknown",
+    providerData: { type: "configuration_update", reasoning: { effort: state.effort } },
+    [REASONING_CONFIGURATION_FIELD]: state,
+  };
+}
+export function latestReasoningConfiguration(
+  items: readonly Record<string, unknown>[],
+): ReasoningConfiguration | null {
+  for (let i = items.length - 1; i >= 0; i--) {
+    const state = readReasoningConfiguration(items[i]!);
+    if (state) return state;
+  }
+  return null;
+}
+export function isReasoningConfigurationUpdate(item: Record<string, unknown>): boolean {
+  return (
+    item.type === "configuration_update" ||
+    (item.type === "unknown" &&
+      (item.providerData as { type?: unknown } | undefined)?.type === "configuration_update")
+  );
+}
+/** Never leak Astra controls to an incompatible model. Coalesce only adjacent controls. */
+export function projectReasoningConfigurations(
+  items: Record<string, unknown>[],
+  enabled: boolean,
+): Record<string, unknown>[] {
+  const projected: Record<string, unknown>[] = [];
+  for (const item of items) {
+    if (!isReasoningConfigurationUpdate(item)) {
+      projected.push(item);
+      continue;
+    }
+    if (!enabled) continue;
+    if (projected.length && isReasoningConfigurationUpdate(projected[projected.length - 1]!))
+      projected.pop();
+    projected.push(
+      item.type === "unknown"
+        ? { type: "unknown", providerData: item.providerData }
+        : {
+            type: "unknown",
+            providerData: { type: "configuration_update", reasoning: item.reasoning },
+          },
+    );
+  }
+  return projected;
+}

package/src/request-context.ts

@@ -60,6 +60,8 @@ export type CodexModelRequestEvent = {
   providerRequestId?: string;
   status?: number;
   willRetry?: boolean;
+  /** Only true for a successful response with substantive assistant/tool output. */
+  meaningfulOutput?: boolean;
 };
 
 export type CodexRequestOpaqueArtifacts = {