@openclaw/codex 2026.5.1-beta.1

package/src/app-server/outcome-fallback-runtime-contract.test.ts

@@ -0,0 +1,352 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { SessionManager } from "@mariozechner/pi-coding-agent";
+import type { EmbeddedRunAttemptParams } from "openclaw/plugin-sdk/agent-harness";
+import { classifyEmbeddedPiRunResultForModelFallback } from "openclaw/plugin-sdk/agent-harness-runtime";
+import {
+  createContractRunResult,
+  OUTCOME_FALLBACK_RUNTIME_CONTRACT,
+} from "openclaw/plugin-sdk/agent-runtime-test-contracts";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  CodexAppServerEventProjector,
+  type CodexAppServerToolTelemetry,
+} from "./event-projector.js";
+import { createCodexTestModel } from "./test-support.js";
+
+const THREAD_ID = "thread-outcome-contract";
+const TURN_ID = "turn-outcome-contract";
+const tempDirs = new Set<string>();
+
+type ProjectorNotification = Parameters<CodexAppServerEventProjector["handleNotification"]>[0];
+type ProjectedAttemptResult = ReturnType<CodexAppServerEventProjector["buildResult"]>;
+
+async function createParams(): Promise<EmbeddedRunAttemptParams> {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-codex-outcome-contract-"));
+  tempDirs.add(tempDir);
+  const sessionFile = path.join(tempDir, "session.jsonl");
+  SessionManager.open(sessionFile);
+  return {
+    prompt: OUTCOME_FALLBACK_RUNTIME_CONTRACT.prompt,
+    sessionId: OUTCOME_FALLBACK_RUNTIME_CONTRACT.sessionId,
+    sessionKey: OUTCOME_FALLBACK_RUNTIME_CONTRACT.sessionKey,
+    sessionFile,
+    workspaceDir: tempDir,
+    runId: OUTCOME_FALLBACK_RUNTIME_CONTRACT.runId,
+    provider: "codex",
+    modelId: OUTCOME_FALLBACK_RUNTIME_CONTRACT.primaryModel,
+    model: createCodexTestModel("codex"),
+    thinkLevel: "medium",
+  } as EmbeddedRunAttemptParams;
+}
+
+async function createProjector(): Promise<CodexAppServerEventProjector> {
+  return new CodexAppServerEventProjector(await createParams(), THREAD_ID, TURN_ID);
+}
+
+function buildToolTelemetry(
+  overrides: Partial<CodexAppServerToolTelemetry> = {},
+): CodexAppServerToolTelemetry {
+  return {
+    didSendViaMessagingTool: false,
+    messagingToolSentTexts: [],
+    messagingToolSentMediaUrls: [],
+    messagingToolSentTargets: [],
+    toolMediaUrls: [],
+    toolAudioAsVoice: false,
+    ...overrides,
+  };
+}
+
+function forCurrentTurn(
+  method: ProjectorNotification["method"],
+  params: Record<string, unknown>,
+): ProjectorNotification {
+  return {
+    method,
+    params: { threadId: THREAD_ID, turnId: TURN_ID, ...params },
+  } as ProjectorNotification;
+}
+
+function classifyProjectedAttemptResult(result: ProjectedAttemptResult) {
+  const finalAssistantText = result.assistantTexts.join("\n\n").trim();
+  return classifyEmbeddedPiRunResultForModelFallback({
+    provider: "codex",
+    model: OUTCOME_FALLBACK_RUNTIME_CONTRACT.primaryModel,
+    result: createContractRunResult({
+      ...result,
+      meta: {
+        durationMs: 1,
+        aborted: result.aborted,
+        agentHarnessResultClassification: result.agentHarnessResultClassification,
+        finalAssistantRawText: finalAssistantText || undefined,
+        finalAssistantVisibleText: finalAssistantText || undefined,
+      },
+    }),
+  });
+}
+
+afterEach(async () => {
+  for (const tempDir of tempDirs) {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+  tempDirs.clear();
+});
+
+describe("Outcome/fallback runtime contract - Codex app-server adapter", () => {
+  it("preserves an empty terminal turn for OpenClaw-owned fallback classification", async () => {
+    const projector = await createProjector();
+    await projector.handleNotification(
+      forCurrentTurn("turn/completed", {
+        turn: { id: TURN_ID, status: "completed", items: [] },
+      }),
+    );
+
+    const result = projector.buildResult(buildToolTelemetry());
+
+    expect(result.assistantTexts).toEqual([]);
+    expect(result.lastAssistant).toBeUndefined();
+    expect(result.promptError).toBeNull();
+  });
+
+  it("preserves exact NO_REPLY as assistant text instead of classifying in the adapter", async () => {
+    const projector = await createProjector();
+    await projector.handleNotification(
+      forCurrentTurn("item/agentMessage/delta", {
+        itemId: "msg-1",
+        delta: "NO_REPLY",
+      }),
+    );
+    await projector.handleNotification(
+      forCurrentTurn("turn/completed", {
+        turn: {
+          id: TURN_ID,
+          status: "completed",
+          items: [{ type: "agentMessage", id: "msg-1", text: "NO_REPLY" }],
+        },
+      }),
+    );
+
+    const result = projector.buildResult(buildToolTelemetry());
+
+    expect(result.assistantTexts).toEqual(["NO_REPLY"]);
+    expect(result.lastAssistant?.content).toEqual([{ type: "text", text: "NO_REPLY" }]);
+    expect(result.promptError).toBeNull();
+  });
+
+  it("preserves reasoning-only terminal turns for OpenClaw-owned fallback classification", async () => {
+    const projector = await createProjector();
+    await projector.handleNotification(
+      forCurrentTurn("item/reasoning/textDelta", {
+        itemId: "reasoning-1",
+        delta: OUTCOME_FALLBACK_RUNTIME_CONTRACT.reasoningOnlyText,
+      }),
+    );
+    await projector.handleNotification(
+      forCurrentTurn("turn/completed", {
+        turn: {
+          id: TURN_ID,
+          status: "completed",
+          items: [{ type: "reasoning", id: "reasoning-1" }],
+        },
+      }),
+    );
+
+    const result = projector.buildResult(buildToolTelemetry());
+
+    expect(result.assistantTexts).toEqual([]);
+    expect(result.lastAssistant).toBeUndefined();
+    expect(result.promptError).toBeNull();
+    expect(result.messagesSnapshot).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          role: "assistant",
+          content: [
+            {
+              type: "text",
+              text: `Codex reasoning:\n${OUTCOME_FALLBACK_RUNTIME_CONTRACT.reasoningOnlyText}`,
+            },
+          ],
+        }),
+      ]),
+    );
+  });
+
+  it("preserves planning-only terminal turns for OpenClaw-owned fallback classification", async () => {
+    const projector = await createProjector();
+    await projector.handleNotification(
+      forCurrentTurn("item/plan/delta", {
+        itemId: "plan-1",
+        delta: OUTCOME_FALLBACK_RUNTIME_CONTRACT.planningOnlyText,
+      }),
+    );
+    await projector.handleNotification(
+      forCurrentTurn("turn/completed", {
+        turn: {
+          id: TURN_ID,
+          status: "completed",
+          items: [
+            {
+              type: "plan",
+              id: "plan-1",
+              text: OUTCOME_FALLBACK_RUNTIME_CONTRACT.planningOnlyText,
+            },
+          ],
+        },
+      }),
+    );
+
+    const result = projector.buildResult(buildToolTelemetry());
+
+    expect(result.assistantTexts).toEqual([]);
+    expect(result.lastAssistant).toBeUndefined();
+    expect(result.promptError).toBeNull();
+    expect(result.messagesSnapshot).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          role: "assistant",
+          content: [
+            {
+              type: "text",
+              text: `Codex plan:\n${OUTCOME_FALLBACK_RUNTIME_CONTRACT.planningOnlyText}`,
+            },
+          ],
+        }),
+      ]),
+    );
+  });
+
+  it("preserves tool side-effect telemetry so fallback can stay disabled", async () => {
+    const projector = await createProjector();
+
+    const result = projector.buildResult(
+      buildToolTelemetry({
+        didSendViaMessagingTool: true,
+        messagingToolSentTexts: ["sent out of band"],
+      }),
+    );
+
+    expect(result.assistantTexts).toEqual([]);
+    expect(result.didSendViaMessagingTool).toBe(true);
+    expect(result.messagingToolSentTexts).toEqual(["sent out of band"]);
+  });
+
+  it.each([
+    {
+      name: "empty",
+      classification: "empty",
+      expectedCode: "empty_result",
+      build: async () => {
+        const projector = await createProjector();
+        await projector.handleNotification(
+          forCurrentTurn("turn/completed", {
+            turn: { id: TURN_ID, status: "completed", items: [] },
+          }),
+        );
+        return projector.buildResult(buildToolTelemetry());
+      },
+    },
+    {
+      name: "reasoning-only",
+      classification: "reasoning-only",
+      expectedCode: "reasoning_only_result",
+      build: async () => {
+        const projector = await createProjector();
+        await projector.handleNotification(
+          forCurrentTurn("item/reasoning/textDelta", {
+            itemId: "reasoning-1",
+            delta: OUTCOME_FALLBACK_RUNTIME_CONTRACT.reasoningOnlyText,
+          }),
+        );
+        await projector.handleNotification(
+          forCurrentTurn("turn/completed", {
+            turn: {
+              id: TURN_ID,
+              status: "completed",
+              items: [{ type: "reasoning", id: "reasoning-1" }],
+            },
+          }),
+        );
+        return projector.buildResult(buildToolTelemetry());
+      },
+    },
+    {
+      name: "planning-only",
+      classification: "planning-only",
+      expectedCode: "planning_only_result",
+      build: async () => {
+        const projector = await createProjector();
+        await projector.handleNotification(
+          forCurrentTurn("item/plan/delta", {
+            itemId: "plan-1",
+            delta: OUTCOME_FALLBACK_RUNTIME_CONTRACT.planningOnlyText,
+          }),
+        );
+        await projector.handleNotification(
+          forCurrentTurn("turn/completed", {
+            turn: {
+              id: TURN_ID,
+              status: "completed",
+              items: [
+                {
+                  type: "plan",
+                  id: "plan-1",
+                  text: OUTCOME_FALLBACK_RUNTIME_CONTRACT.planningOnlyText,
+                },
+              ],
+            },
+          }),
+        );
+        return projector.buildResult(buildToolTelemetry());
+      },
+    },
+  ] as const)(
+    "keeps $name terminal turns fallback-ready with adapter-produced classification",
+    async ({ build, classification, expectedCode }) => {
+      const result = await build();
+
+      expect(result.agentHarnessResultClassification).toBe(classification);
+      expect(classifyProjectedAttemptResult(result)).toMatchObject({
+        reason: "format",
+        code: expectedCode,
+      });
+    },
+  );
+
+  it("keeps exact NO_REPLY classified as an intentional silent terminal reply", async () => {
+    const projector = await createProjector();
+    await projector.handleNotification(
+      forCurrentTurn("item/agentMessage/delta", {
+        itemId: "msg-1",
+        delta: "NO_REPLY",
+      }),
+    );
+    await projector.handleNotification(
+      forCurrentTurn("turn/completed", {
+        turn: {
+          id: TURN_ID,
+          status: "completed",
+          items: [{ type: "agentMessage", id: "msg-1", text: "NO_REPLY" }],
+        },
+      }),
+    );
+
+    const result = projector.buildResult(buildToolTelemetry());
+
+    expect(classifyProjectedAttemptResult(result)).toBeNull();
+  });
+
+  it("keeps tool side effects classified as non-fallback terminal outcomes", async () => {
+    const projector = await createProjector();
+    const result = projector.buildResult(
+      buildToolTelemetry({
+        didSendViaMessagingTool: true,
+        messagingToolSentTexts: ["sent out of band"],
+      }),
+    );
+
+    expect(result.agentHarnessResultClassification).toBeUndefined();
+    expect(classifyProjectedAttemptResult(result)).toBeNull();
+  });
+});

package/src/app-server/plugin-approval-roundtrip.ts

@@ -0,0 +1,122 @@
+import {
+  callGatewayTool,
+  type EmbeddedRunAttemptParams,
+} from "openclaw/plugin-sdk/agent-harness-runtime";
+
+const DEFAULT_CODEX_APPROVAL_TIMEOUT_MS = 120_000;
+const MAX_PLUGIN_APPROVAL_TITLE_LENGTH = 80;
+const MAX_PLUGIN_APPROVAL_DESCRIPTION_LENGTH = 256;
+
+type ExecApprovalDecision = "allow-once" | "allow-always" | "deny";
+
+export type AppServerApprovalOutcome =
+  | "approved-once"
+  | "approved-session"
+  | "denied"
+  | "unavailable"
+  | "cancelled";
+
+type ApprovalRequestResult = {
+  id?: string;
+  decision?: ExecApprovalDecision | null;
+};
+
+type ApprovalWaitResult = {
+  id?: string;
+  decision?: ExecApprovalDecision | null;
+};
+
+export async function requestPluginApproval(params: {
+  paramsForRun: EmbeddedRunAttemptParams;
+  title: string;
+  description: string;
+  severity: "info" | "warning";
+  toolName: string;
+  toolCallId?: string;
+}): Promise<ApprovalRequestResult | undefined> {
+  const timeoutMs = DEFAULT_CODEX_APPROVAL_TIMEOUT_MS;
+  return callGatewayTool(
+    "plugin.approval.request",
+    { timeoutMs: timeoutMs + 10_000 },
+    {
+      pluginId: "openclaw-codex-app-server",
+      title: truncateForGateway(params.title, MAX_PLUGIN_APPROVAL_TITLE_LENGTH),
+      description: truncateForGateway(params.description, MAX_PLUGIN_APPROVAL_DESCRIPTION_LENGTH),
+      severity: params.severity,
+      toolName: params.toolName,
+      toolCallId: params.toolCallId,
+      agentId: params.paramsForRun.agentId,
+      sessionKey: params.paramsForRun.sessionKey,
+      turnSourceChannel: params.paramsForRun.messageChannel ?? params.paramsForRun.messageProvider,
+      turnSourceTo: params.paramsForRun.currentChannelId,
+      turnSourceAccountId: params.paramsForRun.agentAccountId,
+      turnSourceThreadId: params.paramsForRun.currentThreadTs,
+      timeoutMs,
+      twoPhase: true,
+    },
+    { expectFinal: false },
+  ) as Promise<ApprovalRequestResult | undefined>;
+}
+
+export function approvalRequestExplicitlyUnavailable(result: unknown): boolean {
+  if (result === null || result === undefined || typeof result !== "object") {
+    return false;
+  }
+  let descriptor: PropertyDescriptor | undefined;
+  try {
+    descriptor = Object.getOwnPropertyDescriptor(result, "decision");
+  } catch {
+    return false;
+  }
+  return descriptor !== undefined && "value" in descriptor && descriptor.value === null;
+}
+
+export async function waitForPluginApprovalDecision(params: {
+  approvalId: string;
+  signal?: AbortSignal;
+}): Promise<ExecApprovalDecision | null | undefined> {
+  const timeoutMs = DEFAULT_CODEX_APPROVAL_TIMEOUT_MS;
+  const waitPromise: Promise<ApprovalWaitResult | undefined> = callGatewayTool(
+    "plugin.approval.waitDecision",
+    { timeoutMs: timeoutMs + 10_000 },
+    { id: params.approvalId },
+  );
+  if (!params.signal) {
+    return (await waitPromise)?.decision;
+  }
+  let onAbort: (() => void) | undefined;
+  const abortPromise = new Promise<never>((_, reject) => {
+    if (params.signal!.aborted) {
+      reject(params.signal!.reason);
+      return;
+    }
+    onAbort = () => reject(params.signal!.reason);
+    params.signal!.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    return (await Promise.race([waitPromise, abortPromise]))?.decision;
+  } finally {
+    if (onAbort) {
+      params.signal.removeEventListener("abort", onAbort);
+    }
+  }
+}
+
+export function mapExecDecisionToOutcome(
+  decision: ExecApprovalDecision | null | undefined,
+): AppServerApprovalOutcome {
+  if (decision === "allow-once") {
+    return "approved-once";
+  }
+  if (decision === "allow-always") {
+    return "approved-session";
+  }
+  if (decision === null || decision === undefined) {
+    return "unavailable";
+  }
+  return "denied";
+}
+
+function truncateForGateway(value: string, maxLength: number): string {
+  return value.length <= maxLength ? value : `${value.slice(0, Math.max(0, maxLength - 3))}...`;
+}

package/src/app-server/protocol-generated/json/DynamicToolCallParams.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "properties": {
+    "arguments": true,
+    "callId": {
+      "type": "string"
+    },
+    "namespace": {
+      "type": ["string", "null"]
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "tool": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    }
+  },
+  "required": ["arguments", "callId", "threadId", "tool", "turnId"],
+  "title": "DynamicToolCallParams",
+  "type": "object"
+}

package/src/app-server/protocol-generated/json/v2/ErrorNotification.json

@@ -0,0 +1,162 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "CodexErrorInfo": {
+      "description": "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
+      "oneOf": [
+        {
+          "enum": [
+            "contextWindowExceeded",
+            "usageLimitExceeded",
+            "serverOverloaded",
+            "cyberPolicy",
+            "internalServerError",
+            "unauthorized",
+            "badRequest",
+            "threadRollbackFailed",
+            "sandboxError",
+            "other"
+          ],
+          "type": "string"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "httpConnectionFailed": {
+              "properties": {
+                "httpStatusCode": {
+                  "format": "uint16",
+                  "minimum": 0.0,
+                  "type": ["integer", "null"]
+                }
+              },
+              "type": "object"
+            }
+          },
+          "required": ["httpConnectionFailed"],
+          "title": "HttpConnectionFailedCodexErrorInfo",
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Failed to connect to the response SSE stream.",
+          "properties": {
+            "responseStreamConnectionFailed": {
+              "properties": {
+                "httpStatusCode": {
+                  "format": "uint16",
+                  "minimum": 0.0,
+                  "type": ["integer", "null"]
+                }
+              },
+              "type": "object"
+            }
+          },
+          "required": ["responseStreamConnectionFailed"],
+          "title": "ResponseStreamConnectionFailedCodexErrorInfo",
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "The response SSE stream disconnected in the middle of a turn before completion.",
+          "properties": {
+            "responseStreamDisconnected": {
+              "properties": {
+                "httpStatusCode": {
+                  "format": "uint16",
+                  "minimum": 0.0,
+                  "type": ["integer", "null"]
+                }
+              },
+              "type": "object"
+            }
+          },
+          "required": ["responseStreamDisconnected"],
+          "title": "ResponseStreamDisconnectedCodexErrorInfo",
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Reached the retry limit for responses.",
+          "properties": {
+            "responseTooManyFailedAttempts": {
+              "properties": {
+                "httpStatusCode": {
+                  "format": "uint16",
+                  "minimum": 0.0,
+                  "type": ["integer", "null"]
+                }
+              },
+              "type": "object"
+            }
+          },
+          "required": ["responseTooManyFailedAttempts"],
+          "title": "ResponseTooManyFailedAttemptsCodexErrorInfo",
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "description": "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
+          "properties": {
+            "activeTurnNotSteerable": {
+              "properties": {
+                "turnKind": {
+                  "$ref": "#/definitions/NonSteerableTurnKind"
+                }
+              },
+              "required": ["turnKind"],
+              "type": "object"
+            }
+          },
+          "required": ["activeTurnNotSteerable"],
+          "title": "ActiveTurnNotSteerableCodexErrorInfo",
+          "type": "object"
+        }
+      ]
+    },
+    "NonSteerableTurnKind": {
+      "enum": ["review", "compact"],
+      "type": "string"
+    },
+    "TurnError": {
+      "properties": {
+        "additionalDetails": {
+          "default": null,
+          "type": ["string", "null"]
+        },
+        "codexErrorInfo": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/CodexErrorInfo"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "message": {
+          "type": "string"
+        }
+      },
+      "required": ["message"],
+      "type": "object"
+    }
+  },
+  "properties": {
+    "error": {
+      "$ref": "#/definitions/TurnError"
+    },
+    "threadId": {
+      "type": "string"
+    },
+    "turnId": {
+      "type": "string"
+    },
+    "willRetry": {
+      "type": "boolean"
+    }
+  },
+  "required": ["error", "threadId", "turnId", "willRetry"],
+  "title": "ErrorNotification",
+  "type": "object"
+}