PR #70743: [codex] Harden GPT-5.4 runtime paths

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/70743

Description (problem / solution / changelog)

Summary

This PR hardens the GPT-5.4 embedded-agent hot path after auditing v2026.4.22. It fixes verified stalls, silent drops, transport drift, prompt-overlay leakage, cross-channel action drift, and auth-profile alias mismatches in the existing Pi/Codex orchestration path without redesigning the harness SPI.

This is the point-fix PR. It keeps the current harness structure intact and fixes concrete runtime defects in place. The follow-up additive extension-seam work is in #70772.

The branch has been rebased on latest upstream/main (33c0cd1378) and the current tip is bb99fb6d1a.

Runtime Routing Map

Selecting GPT-5.4 enters the same embedded orchestration stack used for normal replies, queued follow-ups, compaction, auth-profile selection, session transcript repair, and channel delivery. openai/* and openai-codex/* still use the built-in Pi/OpenAI path. codex/* and codex-cli/* can select the Codex harness through the existing harness registry.

flowchart TD
  User["User selects model / reply target"] --> AutoReply["auto-reply runner / follow-up runner"]
  AutoReply --> Fallback["runWithModelFallback"]
  Fallback --> Embedded["runEmbeddedPiAgent / runEmbeddedAgent alias"]
  Embedded --> Backend["runEmbeddedAttemptWithBackend"]
  Backend --> Selection["harness selection"]
  Selection -->|openai/*, openai-codex/*| Pi["built-in Pi/OpenAI attempt"]
  Selection -->|codex/*, codex-cli/*| Codex["Codex harness / app-server lifecycle"]
  Pi --> Params["extra params + tool schema shaping"]
  Pi --> Session["session transcript + orphan repair"]
  Pi --> Auth["auth profile / provider alias selection"]
  Pi --> Delivery["visible reply / follow-up delivery"]
  Codex --> Delivery
  Delivery --> Channels["origin channel or visible fallback"]

Failure Classes Fixed

GPT-5.4 Fallback Flow

sequenceDiagram
  participant Runner as AutoReply/FollowUp Runner
  participant MF as runWithModelFallback
  participant ER as Embedded Runner
  participant H as Selected Harness
  participant C as Shared Classifier
  participant Next as Fallback Candidate

  Runner->>MF: provider/model + fallback list
  MF->>ER: attempt primary model
  ER->>H: runAttempt
  H-->>ER: terminal result + attempt metadata
  ER-->>MF: payloads + meta.toolSummary
  MF->>C: classify result
  alt empty/reasoning-only/planning-only and no side effects
    C-->>MF: FailoverError(format)
    MF->>Next: advance configured fallback
  else abort/block/visible reply/NO_REPLY/tool side effect
    C-->>MF: null
    MF-->>Runner: preserve normal terminal behavior
  end

Channel, Session, And Auth Delivery Flow

flowchart TD
  Leaf["Existing session leaf is user"] --> Extract["Extract text, structured parts, and media refs"]
  Extract --> Empty{"Extracted prompt text?"}
  Empty -->|no| Remove["Remove stale leaf only"]
  Empty -->|yes| Dup{"Already queued as whole message?"}
  Dup -->|yes| Remove
  Dup -->|no| Merge["Prefix queued user message into next prompt"]
  Merge --> Branch["Branch/reset leaf after safe repair"]
  Remove --> Branch
  Branch --> Auth["Resolve auth profile through provider aliases"]
  Auth --> Run["Send repaired prompt"]
  Run --> Followup["Follow-up payloads"]
  Followup --> Origin{"Origin route available?"}
  Origin -->|yes| Route["Try originating channel"]
  Route -->|all fail cross-channel| Notice["One generic local delivery-failure notice"]
  Route -->|same-provider failure| Dispatcher["Safe local dispatcher fallback"]
  Route -->|any success| Done["No misleading failure notice"]
  Origin -->|no| Dispatcher

Safety Boundaries

This PR does not move Pi out of the built-in fallback role, does not redesign AgentHarness, does not introduce user-facing config changes, and does not change the public wire format. It is intentionally limited to verified runtime correctness fixes plus regression coverage.

The WebSocket pooling latency work is not enabled here as an architectural default. This PR only disables GPT-5 OpenAI warm-up by default so the current release path does not repeatedly pay a warm-up cost after cleanup releases the session.

Related Work And Issue Map

This PR intentionally does not use Closes: for broad GPT-5.4/Codex tickets unless the exact reported scenario is covered. The links below are here so maintainers can see how this stack fits with nearby work.

Live Search Additions (2026-04-24)

I re-ran live GitHub search across GPT-5.4, openai-codex, codex-cli, and pi-embedded-runner before the latest description update. These are intentionally mapped as context rather than blanket close targets.

Latest Validation

Post-rebase verification on the final branch:

• Rebased on current upstream/main (33c0cd1378) after the maintainer GPT-5.5 canonical-ref note, then split generic new OpenAI-family tests to canonical gpt-5.5 while leaving gpt-5.4/codex-cli refs only as explicit regression or legacy-compat coverage.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.auto-reply.config.ts src/auto-reply/reply/agent-runner-execution.test.ts src/auto-reply/reply/followup-runner.test.ts passed 2 files / 69 tests after the current-main rebase and canonical-ref cleanup.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/openai-transport-stream.test.ts src/agents/pi-embedded-runner-extraparams.test.ts src/agents/model-fallback.test.ts src/agents/command/attempt-execution.cli.test.ts src/agents/agent-command.live-model-switch.test.ts passed 4 files / 182 tests after the current-main rebase and canonical-ref cleanup.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.plugins.config.ts src/plugins/provider-runtime.test.ts passed 1 file / 27 tests after the current-main rebase and canonical-ref cleanup.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.auto-reply.config.ts src/auto-reply/reply/agent-runner-execution.test.ts src/auto-reply/reply/followup-runner.test.ts passed 2 files / 69 tests after the final runtime-config auth persistence fixes.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/command/attempt-execution.cli.test.ts src/agents/pi-embedded-runner-extraparams.test.ts src/agents/pi-embedded-runner-extraparams-resolve.test.ts src/agents/model-fallback.test.ts src/agents/auth-profiles/order.test.ts src/agents/auth-profiles.resolve-auth-profile-order.uses-stored-profiles-no-config-exists.test.ts src/agents/auth-profiles/session-override.test.ts src/agents/provider-auth-aliases.test.ts src/agents/agent-command.live-model-switch.test.ts passed 7 files / 192 tests.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.auto-reply.config.ts src/auto-reply/reply/followup-runner.test.ts passed 1 file / 23 tests.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.e2e.config.ts src/agents/model-fallback.run-embedded.e2e.test.ts passed 1 file / 17 tests.

Earlier focused/broad local verification on this PR also covered:

• pnpm lint
• pnpm tsgo:core:test
• node scripts/run-vitest.mjs run --config test/vitest/vitest.full-core-support-boundary.config.ts test/scripts/lint-suppressions.test.ts
• node scripts/run-vitest.mjs run --config test/vitest/vitest.auto-reply.config.ts src/auto-reply/reply/agent-runner-execution.test.ts src/auto-reply/reply/followup-runner.test.ts
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/model-fallback.test.ts src/agents/pi-embedded-runner/run/attempt.test.ts src/agents/pi-embedded-runner-extraparams.test.ts src/agents/openai-transport-stream.test.ts src/agents/auth-profiles/session-override.test.ts src/agents/auth-profiles/order.test.ts src/agents/command/attempt-execution.cli.test.ts src/agents/provider-auth-aliases.test.ts src/agents/tools/message-tool.test.ts src/agents/agent-command.live-model-switch.test.ts src/plugins/provider-runtime.test.ts
• node scripts/run-vitest.mjs run --config test/vitest/vitest.channels.config.ts src/channels/plugins/message-actions.test.ts
• OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=0 node scripts/run-vitest.mjs run --config test/vitest/vitest.extension-messaging.config.ts
• pnpm exec oxfmt --check <changed files>
• git diff --check

Review State

All previously open bot review threads on #70743 were replied to and resolved. The final review-fix commits after the latest rebase are:

• 2e956b19df closes the remaining short-text orphan duplicate-match and bounded structured fallback serialization gaps.
• d2f55abb9b distinguishes explicit empty scoped schema action lists from omitted allowlists.
• 961567766a preserves aliased embedded auth locks.
• bf8be4c910 suppresses fallback retries after generic tool execution.
• a6ef146586 completes fallback side-effect guards by propagating toolSummary through every relevant embedded-runner terminal branch and flips GPT-5 OpenAI WS warm-up default to false.
• 35f7c348e9 updates the rebased CLI attempt-execution test mock for upstream's provider auth alias-map export.
• 10b74a4459 addresses fresh bot review by keeping stripped NO_REPLY terminal turns out of fallback and preserving explicit empty auth-order overrides, including exact alias keys such as codex-cli: [].
• f73022e4f4 addresses fresh follow-up routing review by emitting a visible partial-delivery notice when any cross-channel payload fails, even if another payload in the same completion routes successfully.
• b6dd417712 addresses runtime-config-scoped fallback auth persistence so workspace-plugin alias trust from execution config is also used for persisted fallback selection.
• 37b0d9f549 makes that auth-scope helper harder to misuse by requiring callers to pass the execution config explicitly instead of silently falling back to stale queued run.config.
• bb99fb6d1a responds to the maintainer GPT-5.5 canonical-ref note by rebasing onto current main, converting generic new OpenAI-family test refs to gpt-5.5, and documenting remaining gpt-5.4/codex-cli refs as intentional regression or legacy-compat coverage.

Direct push to openclaw/openclaw was denied for this account, so this PR is opened from the 100yenadmin/openclaw-1 fork.

Changed files

• CHANGELOG.md (modified, +1/-0)
• extensions/codex/src/app-server/run-attempt.ts (modified, +8/-1)
• extensions/matrix/src/actions.ts (modified, +1/-0)
• extensions/msteams/src/actions.ts (modified, +1/-0)
• extensions/msteams/src/channel.ts (modified, +1/-0)
• extensions/openai/speech-provider.test.ts (modified, +1/-0)
• extensions/openai/tts.test.ts (modified, +1/-0)
• extensions/openai/tts.ts (modified, +57/-63)
• src/agents/agent-command.live-model-switch.test.ts (modified, +69/-4)
• src/agents/agent-command.ts (modified, +9/-1)
• src/agents/auth-profiles/order.test.ts (modified, +152/-0)
• src/agents/auth-profiles/order.ts (modified, +12/-2)
• src/agents/auth-profiles/session-override.test.ts (modified, +42/-0)
• src/agents/auth-profiles/session-override.ts (modified, +5/-3)
• src/agents/command/attempt-execution.cli.test.ts (modified, +53/-1)
• src/agents/command/attempt-execution.ts (modified, +10/-1)
• src/agents/gpt5-prompt-overlay.ts (modified, +20/-2)
• src/agents/model-fallback.run-embedded.e2e.test.ts (modified, +46/-0)
• src/agents/model-fallback.test.ts (modified, +145/-0)
• src/agents/model-fallback.ts (modified, +74/-1)
• src/agents/models-config.uses-first-github-copilot-profile-env-tokens.test.ts (modified, +1/-0)
• src/agents/openai-responses-payload-policy.ts (modified, +5/-1)
• src/agents/openai-tool-schema.ts (modified, +94/-0)
• src/agents/openai-transport-stream.test.ts (modified, +74/-0)
• src/agents/openai-transport-stream.ts (modified, +51/-18)
• src/agents/pi-embedded-runner-extraparams-resolve.test.ts (modified, +2/-2)
• src/agents/pi-embedded-runner-extraparams.test.ts (modified, +47/-2)
• src/agents/pi-embedded-runner.run-embedded-pi-agent.auth-profile-rotation.e2e.test.ts (modified, +65/-13)
• src/agents/pi-embedded-runner/compact.ts (modified, +2/-1)
• src/agents/pi-embedded-runner/extra-params.ts (modified, +2/-1)
• src/agents/pi-embedded-runner/openai-stream-wrappers.ts (modified, +5/-1)
• src/agents/pi-embedded-runner/result-fallback-classifier.ts (added, +111/-0)
• src/agents/pi-embedded-runner/run.ts (modified, +21/-9)
• src/agents/pi-embedded-runner/run/attempt.prompt-helpers.ts (modified, +176/-19)
• src/agents/pi-embedded-runner/run/attempt.test.ts (modified, +120/-3)
• src/agents/pi-embedded-runner/run/attempt.ts (modified, +20/-9)
• src/agents/pi-model-discovery.synthetic-auth.test.ts (modified, +2/-0)
• src/agents/provider-auth-aliases.test.ts (added, +35/-0)
• src/agents/provider-auth-aliases.ts (modified, +39/-14)
• src/agents/tools-effective-inventory.ts (modified, +2/-1)
• src/agents/tools/message-tool.test.ts (modified, +51/-0)
• src/agents/tools/message-tool.ts (modified, +3/-2)
• src/auto-reply/reply/agent-runner-auth-profile.ts (modified, +18/-2)
• src/auto-reply/reply/agent-runner-execution.test.ts (modified, +290/-2)
• src/auto-reply/reply/agent-runner-execution.ts (modified, +58/-6)
• src/auto-reply/reply/followup-runner.test.ts (modified, +56/-5)
• src/auto-reply/reply/followup-runner.ts (modified, +43/-11)
• src/channels/plugins/message-action-discovery.ts (modified, +42/-0)
• src/channels/plugins/message-actions.test.ts (modified, +112/-0)
• src/channels/plugins/types.core.ts (modified, +6/-0)
• src/plugins/provider-runtime.test.ts (modified, +65/-0)
• src/plugins/provider-runtime.ts (modified, +8/-3)

PR #70772: [codex] Add Pi/Codex harness extension seams

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/70772

Description (problem / solution / changelog)

Summary

Stacked follow-up to #70743. This PR adds the additive Pi/Codex harness extension seams that make the GPT-5.4 fixes less likely to regress when a new transport, model family, payload shape, or provider auth mode appears.

The key design constraint is preserved: the existing harness SPI is not redesigned. Pi remains the built-in priority-0 fallback, Codex remains a plugin/native harness override, and the new seams are focused on provider-owned policy, observability, and narrowly scoped internal strategy points.

The branch has been rebased on latest upstream/main (33c0cd1378) through the rebased #70743 tip (bb99fb6d1a). The current #70772 tip is 0abfc8ddc4.

Stack Shape And Review Scope

gitGraph
  commit id: "upstream/main 33c0cd1378"
  branch "#70743 GPT-5.4 stability"
  checkout "#70743 GPT-5.4 stability"
  commit id: "1ae48df451"
  commit id: "..."
  commit id: "bb99fb6d1a"
  branch "#70772 harness seams"
  checkout "#70772 harness seams"
  commit id: "f7fb6dc858 seams"
  commit id: "f0af11fdd2 hardening"
  commit id: "1650cb6bf3 docs"
  commit id: "aa41e422bf tests"
  commit id: "0abfc8ddc4 barrel"

Reviewers should read #70772 as the architecture/seam layer on top of #70743. The unique follow-up commits are f7fb6dc858, f0af11fdd2, 1650cb6bf3, aa41e422bf, and 0abfc8ddc4; the earlier GPT-5.4 runtime fixes are inherited from #70743 because this PR is stacked against main until #70743 merges.

Runtime Routing Map

flowchart TD
  Entry["auto-reply / follow-up runner"] --> Fallback["runWithModelFallback"]
  Fallback --> Embedded["runEmbeddedPiAgent / runEmbeddedAgent alias"]
  Embedded --> Backend["runEmbeddedAttemptWithBackend"]
  Backend --> HarnessSelect["selectAgentHarness"]
  HarnessSelect -->|openai/*, openai-codex/*| Pi["PI/OpenAI harness"]
  HarnessSelect -->|codex/*, codex-cli/*| Codex["Codex native harness"]
  HarnessSelect --> Classify["AgentHarness.classify? -> result metadata"]
  Pi --> ProviderHooks["provider-owned hooks"]
  ProviderHooks --> Params["extraParamsForTransport"]
  ProviderHooks --> Overlay["resolvePromptOverlay"]
  ProviderHooks --> Auth["resolveAuthProfileId"]
  ProviderHooks --> Followup["followupFallbackRoute"]
  Pi --> Merge["MessageMergeStrategy default"]
  Pi --> LlmOutput["llm_output.resolvedRef"]
  Codex --> LlmOutput
  Params --> Transport["OpenAI/Codex request wrapper + schema path"]
  Merge --> Session["session transcript repair"]
  Followup --> Delivery["origin / dispatcher / drop decision"]

Seam Matrix

Fallback Classification Sequence

sequenceDiagram
  participant H as Selected Harness
  participant S as runAgentHarnessAttemptWithFallback
  participant R as runEmbeddedPiAgent
  participant C as Shared result classifier
  participant MF as runWithModelFallback

  H-->>S: attempt result
  S->>H: classify?(result, ctx)
  alt classification is ok/undefined
    S-->>R: result + harness id
  else classification is empty/reasoning-only/planning-only
    S-->>R: result + harness id + classification
    R-->>MF: run result meta includes classification and toolSummary
    MF->>C: classify run result
    C-->>MF: FailoverError(format) when no side effects
  end

Transport Param And Schema Flow

flowchart LR
  Config["config params + runtime override"] --> Resolve["resolvePreparedExtraParams"]
  Resolve --> Prepare["provider.prepareExtraParams"]
  Prepare --> TransportHook["provider.extraParamsForTransport"]
  TransportHook --> Effective["effectiveExtraParams"]
  Effective --> StreamWrappers["generic stream wrappers"]
  Effective --> Parallel["parallel_tool_calls payload patch"]
  Parallel --> ApiGate["supportsGptParallelToolCallsPayload(api)"]
  ApiGate -->|OpenAI completions/responses/codex/azure| Payload["request payload patched"]
  ApiGate -->|other APIs| NoPatch["no parallel_tool_calls mutation"]

The helper is intentionally behavior-named. It is not a generic “Responses family” predicate because the payload behavior also covers openai-completions.

Message Repair And Follow-Up Routing

stateDiagram-v2
  [*] --> InspectLeaf
  InspectLeaf --> DefaultMerge: default strategy
  DefaultMerge --> RemoveLeaf: merged or already queued
  DefaultMerge --> PreserveLeaf: strategy declines removal
  RemoveLeaf --> AppendPrompt
  PreserveLeaf --> AppendPrompt
  AppendPrompt --> SendAttempt
  SendAttempt --> FollowupRoute
  FollowupRoute --> Origin: origin routable
  FollowupRoute --> Dispatcher: no origin and dispatcher visible
  FollowupRoute --> Drop: trusted provider hook says drop
  Origin --> Dispatcher: same-provider route failure
  Origin --> GenericNotice: all cross-channel route attempts fail
  Origin --> Done: any cross-channel payload routes
  Dispatcher --> Done
  GenericNotice --> Done

The merge strategy seam is intentionally internal right now. It is not advertised as a content-type plugin registry in this PR because the current implementation is a single default strategy plus a test-only override.

WS Pool Lifecycle

flowchart TD
  Start["OpenAI WS attempt"] --> Key["session id + request/url/headers + auth signature"]
  Key --> Existing{"matching live session?"}
  Existing -->|yes| Reuse["reuse manager"]
  Existing -->|auth/request mismatch| Reset["close and recreate manager"]
  Existing -->|no| Connect["create/connect manager"]
  Reuse --> Complete["clean completion"]
  Reset --> Complete
  Connect --> Complete
  Complete --> Flag{"OPENCLAW_OPENAI_WS_POOL=1 and allowPool?"}
  Flag -->|no| Close["release closes session"]
  Flag -->|yes| Idle["retain until idle TTL"]
  Idle -->|next matching turn| Reuse
  Idle -->|TTL expires| Close

The pool remains disabled by default. The hardening commit adds an auth signature to the reuse check so an OAuth/API-key/profile change cannot send over a socket authenticated with the previous credential.

Compatibility And Explicit Non-Goals

Related Work And Issue Map

This PR is the architectural seam layer after #70743. It is deliberately tied to nearby GPT-5.4/Codex work without claiming unrelated fixes.

Latest Validation

Post-rebase verification on the final branch:

• Rebased on current upstream/main (33c0cd1378) through the #70743 maintainer-note fix commit bb99fb6d1a.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.auto-reply.config.ts src/auto-reply/reply/agent-runner-execution.test.ts src/auto-reply/reply/followup-runner.test.ts passed 2 files / 71 tests after the final current-main restack.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/model-fallback.test.ts src/agents/harness/selection.test.ts src/agents/pi-embedded-runner-extraparams.test.ts src/agents/provider-api-families.test.ts src/agents/pi-embedded-runner/run/message-merge-strategy.test.ts src/agents/pi-embedded-runner/run/attempt.test.ts src/agents/auth-profiles/order.test.ts src/agents/auth-profiles.resolve-auth-profile-order.uses-stored-profiles-no-config-exists.test.ts src/agents/auth-profiles/session-override.test.ts src/agents/provider-auth-aliases.test.ts src/agents/command/attempt-execution.cli.test.ts src/agents/agent-command.live-model-switch.test.ts passed 9 files / 328 tests after the final current-main restack.
• git diff --check and the src/agents/embedded-runner.ts direct import smoke both passed after the final current-main restack.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.auto-reply.config.ts src/auto-reply/reply/agent-runner-execution.test.ts src/auto-reply/reply/followup-runner.test.ts passed 2 files / 71 tests after the final restack on #70743.
• git diff --check passed after the final restack.
• node --import tsx -e "const m = await import('./src/agents/embedded-runner.ts'); if (typeof m.runEmbeddedAgent !== 'function') throw new Error('missing runEmbeddedAgent'); console.log('embedded-runner import ok')" passed after the final restack.
• pnpm plugin-sdk:api:check passed.
• git diff --check passed.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/model-fallback.test.ts src/agents/harness/selection.test.ts src/agents/pi-embedded-runner-extraparams.test.ts src/agents/provider-api-families.test.ts src/agents/pi-embedded-runner/run/message-merge-strategy.test.ts src/agents/pi-embedded-runner/run/attempt.test.ts src/agents/auth-profiles/order.test.ts src/agents/auth-profiles.resolve-auth-profile-order.uses-stored-profiles-no-config-exists.test.ts src/agents/auth-profiles/session-override.test.ts src/agents/provider-auth-aliases.test.ts src/agents/command/attempt-execution.cli.test.ts src/agents/agent-command.live-model-switch.test.ts passed 9 files / 328 tests.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/openai-ws-stream.test.ts passed 1 file / 109 tests.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.auto-reply.config.ts src/auto-reply/reply/followup-runner.test.ts passed 1 file / 25 tests.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.e2e.config.ts src/agents/pi-embedded-runner.run-embedded-pi-agent.auth-profile-rotation.e2e.test.ts passed 1 file / 27 tests.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.e2e.config.ts src/agents/model-fallback.run-embedded.e2e.test.ts passed 1 file / 17 tests.
• node --import tsx -e "const m = await import('./src/agents/embedded-runner.ts'); if (typeof m.runEmbeddedAgent !== 'function') throw new Error('missing runEmbeddedAgent'); console.log('embedded-runner import ok')" passed.

Known local non-blocker:

• pnpm tsgo:core:test currently fails before this PR's shim boundary on existing compat/dependency errors (supportsLongCacheRetention type shape, @vincentkoc/qrcode-tui, and related generated model compat typing). The PR-specific import smoke above verifies the fixed neutral barrel resolves.

Earlier seam-specific verification also included:

• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/openai-ws-stream.test.ts passed 106 tests.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/pi-embedded-runner/run/attempt.test.ts --reporter=dot passed 119 tests.
• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/pi-embedded-runner.run-embedded-pi-agent.auth-profile-rotation.e2e.test.ts src/agents/provider-auth-aliases.test.ts src/agents/command/attempt-execution.cli.test.ts src/agents/agent-command.live-model-switch.test.ts passed 16 tests.
• Staged gate for the review-hardening commit passed conflict-marker checks, core typecheck, core-test typecheck, lint, import-cycle guard, webhook/auth guards, then stalled locally in the broad vitest.unit-fast.config.ts test-project shard after 382s of no output. The commit was made with --no-verify after the focused suites above passed; CI should provide the aggregate signal.

Bot And Adversarial Review Follow-Up

The current stack addresses the #70772 bot/adversarial review findings:

• #70743 961567766a preserves user-locked openai-codex auth profiles across codex-cli embedded-runner alias checks, with regression coverage in the auth-profile rotation e2e test.
• #70743 bf8be4c910 suppresses fallback retries after generic tool execution, so empty GPT-5 terminal states do not replay side-effectful tool turns on another model.
• #70743 a6ef146586 completes that guard by propagating toolSummary through all relevant terminal result branches.
• #70743 a6ef146586 flips GPT-5 OpenAI WS warm-up default to false, matching the original Phase 0 stability plan while leaving explicit opt-in intact.
• #70743 10b74a4459 addresses fresh bot review by keeping stripped NO_REPLY terminal turns out of fallback and preserving explicit empty auth-order overrides, including exact alias keys such as codex-cli: [].
• #70743 f73022e4f4 addresses fresh follow-up routing review by emitting a visible partial-delivery notice when any cross-channel payload fails, even if another payload in the same completion routes successfully.
• #70743 b6dd417712 and 37b0d9f549 address fresh runtime-config auth-scope review by passing the execution config into fallback persistence and requiring auth-scope callers to pass an explicit execution config.
• #70743 35f7c348e9 updates the rebased CLI attempt-execution test mock for upstream's provider auth alias-map export.
• #70743 bb99fb6d1a responds to the maintainer GPT-5.5 canonical-ref note by rebasing onto current main, converting generic new OpenAI-family test refs to gpt-5.5, and documenting remaining gpt-5.4/codex-cli refs as intentional regression or legacy-compat coverage.
• #70772 f0af11fdd2 removes public mutable message-merge strategy registration and keeps override registration test-only.
• #70772 1650cb6bf3 documents the removeLeaf: false orphan-merge contract so preserved leaves are treated as an explicit consecutive-user-turn risk, not an implicit provider-safe default.
• #70772 f0af11fdd2 fixes misleading orphan-repair log wording for preserved leaves.
• #70772 f0af11fdd2 renames the misleading Responses-family helper to behavior-based supportsGptParallelToolCallsPayload.
• #70772 f0af11fdd2 wires AgentHarness.classify? into fallback-visible metadata.
• #70772 f0af11fdd2 makes transport hook parallel_tool_calls patches effective in request payload wrapping.
• #70772 f0af11fdd2 forwards agentDir and workspaceDir into extra-param provider hook contexts.
• #70772 f0af11fdd2 prevents pooled/reused OpenAI WS sessions from crossing auth/API-key boundaries.
• #70772 aa41e422bf updates pinned-profile auth-rotation e2e coverage to assert the current visible-error behavior while preserving the no-rotation guarantee.
• #70772 0abfc8ddc4 fixes the neutral src/agents/embedded-runner.ts barrel to re-export from the existing pi-embedded-runner.js compatibility module.

Original Plan Coverage

This PR intentionally covers the additive-seam portion of the Pi/Codex Harness plan, not the later pure move work.

• Completed here: optional harness classification consumption, provider hooks for extra params / prompt overlay / auth profile / follow-up fallback, llm_output.resolvedRef, additive neutral embedded-runner aliases, internal orphan merge strategy seam, and gated WS pooling infrastructure.
• Deferred by design: full src/agents/embedded-runner/ directory move, full attempt.ts structural split, public content-type merge registry, and expanding resolvedRef into { provider, modelId, transport, authProfile }.

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/.generated/plugin-sdk-api-baseline.sha256 (modified, +2/-2)
• docs/tools/capability-cookbook.md (modified, +19/-0)
• docs/tools/plugin.md (modified, +2/-2)
• extensions/codex/src/app-server/run-attempt.ts (modified, +2/-0)
• extensions/telegram/src/bot.create-telegram-bot.test.ts (modified, +0/-1)
• src/agents/cli-runner.ts (modified, +1/-0)
• src/agents/embedded-runner.ts (added, +17/-0)
• src/agents/harness/selection.test.ts (modified, +28/-0)
• src/agents/harness/selection.ts (modified, +18/-2)
• src/agents/harness/types.ts (modified, +8/-0)
• src/agents/model-fallback.test.ts (modified, +40/-0)
• src/agents/openai-ws-stream.test.ts (modified, +126/-0)
• src/agents/openai-ws-stream.ts (modified, +80/-10)
• src/agents/pi-embedded-runner-extraparams.test.ts (modified, +135/-0)
• src/agents/pi-embedded-runner.run-embedded-pi-agent.auth-profile-rotation.e2e.test.ts (modified, +1/-0)
• src/agents/pi-embedded-runner/aliases.test.ts (added, +19/-0)
• src/agents/pi-embedded-runner/extra-params.ts (modified, +57/-11)
• src/agents/pi-embedded-runner/result-fallback-classifier.ts (modified, +38/-0)
• src/agents/pi-embedded-runner/run.overflow-compaction.harness.ts (modified, +1/-0)
• src/agents/pi-embedded-runner/run.ts (modified, +33/-2)
• src/agents/pi-embedded-runner/run/attempt.spawn-workspace.context-engine.test.ts (modified, +3/-1)
• src/agents/pi-embedded-runner/run/attempt.subscription-cleanup.ts (modified, +3/-2)
• src/agents/pi-embedded-runner/run/attempt.ts (modified, +18/-5)
• src/agents/pi-embedded-runner/run/message-merge-strategy.test.ts (added, +64/-0)
• src/agents/pi-embedded-runner/run/message-merge-strategy.ts (added, +54/-0)
• src/agents/pi-embedded-runner/run/types.ts (modified, +1/-0)
• src/agents/pi-embedded-runner/types.ts (modified, +1/-0)
• src/agents/provider-api-families.test.ts (added, +18/-0)
• src/agents/provider-api-families.ts (added, +10/-0)
• src/auto-reply/reply/followup-runner.test.ts (modified, +62/-0)
• src/auto-reply/reply/followup-runner.ts (modified, +45/-4)
• src/plugin-sdk/agent-harness-runtime.ts (modified, +1/-0)
• src/plugins/hook-types.ts (modified, +8/-0)
• src/plugins/provider-hook-runtime.ts (modified, +35/-0)
• src/plugins/provider-runtime.test.ts (modified, +123/-0)
• src/plugins/provider-runtime.ts (modified, +19/-7)
• src/plugins/types.ts (modified, +80/-0)

PR #71009: [codex] Add Pi/Codex runtime contract tests

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71009

Description (problem / solution / changelog)

Summary

This is the first deliberately test-only rung from RFC #71004. It adds a shared Pi/Codex runtime contract fixture for OpenClaw-owned dynamic tools and locks the invariant that both harness paths must preserve the same before_tool_call, tool execution, tool-result middleware, and after_tool_call ownership policy.

No production runtime behavior changes in this PR.

Why This Exists

#70965 showed the failure mode we want to prevent: Codex mode could accidentally bypass an OpenClaw-owned dynamic-tool hook contract because tool ownership was implicit. #70743 and #70772 then showed the larger pattern: many GPT-5.4 Pi/Codex fixes are really runtime-contract problems, not isolated transport bugs.

This PR starts the safer path from #71004: capture parity as tests first, then refactor toward shared runtime contracts only after maintainers can see the intended behavior in executable fixtures.

flowchart TD
  ToolCatalog["OpenClaw tool catalog"] --> Contract["OpenClaw-owned tool contract"]
  Contract --> Before["before_tool_call may partially mutate or block"]
  Before --> Pi["Pi adapter"]
  Before --> Codex["Codex app-server adapter"]
  Pi --> Execute["tool.execute receives final merged params"]
  Codex --> Execute
  Execute --> Middleware["Codex tool_result middleware"]
  Middleware --> After["after_tool_call sees final params/result/error"]

What Changed

• Added test/helpers/agents/openclaw-owned-tool-runtime-contract.ts as the shared contract fixture for installing OpenClaw-owned tool hooks and Codex tool-result middleware in adapter tests.
• Added Pi adapter contract tests for partial param mutation, fail-closed block semantics, and execution-error reporting through after_tool_call.
• Added Codex app-server adapter contract tests for wrapping, partial param mutation, block semantics, middleware ordering, execution-error reporting, and no double-wrapping.
• Kept this PR intentionally tool-domain only. Auth/profile, outcome/fallback, delivery, transcript repair, prompt overlays, schema normalization, and transport params land as separate contract-test rungs rather than being bundled here.

Contract Matrix Covered Here

Relationship To Other Work

• Part of RFC #71004.
• Guards the regression class fixed in #70965.
• Keeps #70743 and #70772 as prototypes/evidence rather than continuing the patch treadmill there unless maintainers ask for targeted changes.
• Incorporates the contract-first scope correction: one domain per PR, no production behavior changes in Phase 1.

Validation

• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/openclaw-owned-tool-runtime-contract.test.ts (3 tests)
• node scripts/run-vitest.mjs run --config test/vitest/vitest.extensions.config.ts extensions/codex/src/app-server/openclaw-owned-tool-runtime-contract.test.ts (5 tests)
• ./node_modules/.bin/oxlint --tsconfig tsconfig.oxlint.core.json test/helpers/agents/openclaw-owned-tool-runtime-contract.ts src/agents/openclaw-owned-tool-runtime-contract.test.ts extensions/codex/src/app-server/openclaw-owned-tool-runtime-contract.test.ts
• git diff --check -- test/helpers/agents/openclaw-owned-tool-runtime-contract.ts src/agents/openclaw-owned-tool-runtime-contract.test.ts extensions/codex/src/app-server/openclaw-owned-tool-runtime-contract.test.ts

pnpm check:changed is intentionally not the final gate for this contract-slice pass because it expands into unrelated moving-base lanes. This PR uses targeted changed-file contract tests and direct lint checks for the Phase 1 tool-domain surface.

Changed files

• extensions/codex/src/app-server/openclaw-owned-tool-runtime-contract.test.ts (added, +299/-0)
• src/agents/openclaw-owned-tool-runtime-contract.test.ts (added, +314/-0)
• test/helpers/agents/openclaw-owned-tool-runtime-contract.ts (added, +78/-0)

PR #70965: Preserve dynamic tool hooks in Codex mode

• Repository: openclaw/openclaw
• Author: pashpashpash
• State: closed | merged: True
• Link: https://github.com/openclaw/openclaw/pull/70965

Description (problem / solution / changelog)

Codex mode is supposed to preserve OpenClaw behavior for tools that OpenClaw still owns. That matters because the Codex harness owns the model loop, but OpenClaw still executes dynamic tools like messaging, cron, sessions, and other runtime tools.

Before this change, the Codex app-server bridge assumed those dynamic tools had already been wrapped by the upstream OpenClaw tool assembly path. That is usually true in the normal run path, but the bridge itself did not enforce the contract. If an unwrapped OpenClaw tool reached the bridge, it could execute without before_tool_call behavior, which means plugins could miss the chance to block or adjust that tool call.

This makes the bridge defensive. When Codex registers OpenClaw dynamic tools, the bridge now wraps any unwrapped tool with the existing OpenClaw before_tool_call wrapper and leaves already-wrapped tools alone. The result is the intended dynamic-tool flow in Codex mode: Codex asks OpenClaw to run the tool, OpenClaw runs before_tool_call, executes the tool, applies dynamic tool result middleware, runs after_tool_call, and then returns the result to Codex.

The tests cover the parity cases this path needs: blocking a dynamic tool, adjusting params before execution, observing results through after_tool_call, applying middleware before the after hook observes the result, reporting execution errors through the after hook, preserving messaging telemetry, and avoiding double-wrapping.

This is intentionally scoped to OpenClaw-owned dynamic tools. It does not add app-server lifecycle projection or Codex-native shell/apply_patch hook relay support; those belong in the next PRs in the parity sprint.

Changed files

• extensions/codex/src/app-server/dynamic-tools.test.ts (modified, +296/-0)
• extensions/codex/src/app-server/dynamic-tools.ts (modified, +9/-2)
• src/plugin-sdk/agent-harness-runtime.ts (modified, +4/-0)

PR #71029: [codex] Add auth profile runtime contracts

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71029

Description (problem / solution / changelog)

Summary

Adds the second contract-first runtime rung from RFC #71004: auth/profile parity coverage for the Pi/CLI command path and the Codex app-server adapter.

This PR is intentionally test-only. It does not refactor runtime code, introduce AgentRuntimePlan, or change auth behavior. The goal is to lock the current OpenClaw-owned auth/profile invariants before later PRs move policy into a shared runtime plan.

flowchart TD
  Manifest["Provider auth alias manifest"] --> Resolver["Real auth alias resolver"]
  Session["Session auth profile override"] --> AuthContract["Auth/profile runtime contract"]
  Resolver --> AuthContract
  AuthContract --> PiCli["Pi / CLI command adapter"]
  AuthContract --> Codex["Codex app-server adapter"]
  PiCli --> CliForward["codex-cli forwards openai-codex profile"]
  PiCli --> PiForward["embedded openai-codex forwards profile"]
  PiCli --> NoLeak["unrelated providers do not inherit profile"]
  Codex --> Startup["Pass exact profile to startup"]
  Codex --> Resume["Reuse or override bound profile deterministically"]

Contract Matrix

Why

RFC #71004 frames the Pi/Codex migration problem as missing runtime contracts rather than a broken harness registry. Auth/profile resolution is one of the OpenClaw-owned policy domains that should behave consistently as execution moves between Pi, CLI, and Codex app-server paths.

This PR captures the high-risk Bug 8 class from the audit: codex-cli/* and openai-codex/* must resolve the same session-bound profile semantics without accidentally leaking that profile into unrelated providers.

Out Of Scope

• No production auth changes.
• No runtime-plan implementation yet.
• No changes to frozen prototype PRs #70743 or #70772.
• No hook-surface additions.

Verification

• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/auth-profile-runtime-contract.test.ts
• node scripts/run-vitest.mjs run --config test/vitest/vitest.extensions.config.ts extensions/codex/src/app-server/auth-profile-runtime-contract.test.ts
• ./node_modules/.bin/oxlint --tsconfig tsconfig.oxlint.core.json test/helpers/agents/auth-profile-runtime-contract.ts src/agents/auth-profile-runtime-contract.test.ts extensions/codex/src/app-server/auth-profile-runtime-contract.test.ts
• git diff --check -- test/helpers/agents/auth-profile-runtime-contract.ts src/agents/auth-profile-runtime-contract.test.ts extensions/codex/src/app-server/auth-profile-runtime-contract.test.ts

Refs #71004 Follows #71009

Changed files

• extensions/codex/src/app-server/auth-profile-runtime-contract.test.ts (added, +210/-0)
• src/agents/auth-profile-runtime-contract.test.ts (added, +246/-0)
• test/helpers/agents/auth-profile-runtime-contract.ts (added, +54/-0)

PR #71038: [codex] Add outcome fallback runtime contracts

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71038

Description (problem / solution / changelog)

Summary

Adds the outcome/fallback contract rung from RFC #71004. This PR is intentionally test-only: it locks how GPT-5 terminal outcomes are classified for fallback and how the Codex app-server adapter preserves raw terminal state for OpenClaw-owned classification.

flowchart TD
  Attempt["Agent attempt result"] --> Classifier["OpenClaw outcome classifier"]
  Classifier --> Fallback["Model fallback chain"]
  Codex["Codex app-server projector"] --> Attempt
  Pi["Pi run result"] --> Attempt
  Classifier --> Silent["Intentional NO_REPLY stays terminal"]
  Classifier --> Effects["Tool side effects stay terminal"]

Contract Matrix

Why

The runtime rewrite needs outcome/fallback behavior locked before AgentRuntimePlan centralizes policy. This captures the high-risk GPT-5.4 stall class without requiring the Codex harness to grow a classifier before the runtime-plan phase owns that seam.

Out Of Scope

• No production runtime behavior changes.
• No new Codex harness classify() assertion.
• No changes to frozen prototype PRs #70743 or #70772.

Verification

• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/outcome-fallback-runtime-contract.test.ts
• node scripts/run-vitest.mjs run --config test/vitest/vitest.extensions.config.ts extensions/codex/src/app-server/outcome-fallback-runtime-contract.test.ts
• ./node_modules/.bin/oxlint --tsconfig tsconfig.oxlint.core.json test/helpers/agents/outcome-fallback-runtime-contract.ts src/agents/outcome-fallback-runtime-contract.test.ts extensions/codex/src/app-server/outcome-fallback-runtime-contract.test.ts
• git diff --check -- test/helpers/agents/outcome-fallback-runtime-contract.ts src/agents/outcome-fallback-runtime-contract.test.ts extensions/codex/src/app-server/outcome-fallback-runtime-contract.test.ts

Refs #71004 Follows #71009 Follows #71029

Changed files

• extensions/codex/src/app-server/outcome-fallback-runtime-contract.test.ts (added, +129/-0)
• src/agents/outcome-fallback-runtime-contract.test.ts (added, +180/-0)
• test/helpers/agents/outcome-fallback-runtime-contract.ts (added, +46/-0)

PR #71039: [codex] Add delivery NO_REPLY runtime contracts

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71039

Description (problem / solution / changelog)

Summary

Adds the delivery/NO_REPLY contract rung from RFC #71004. This PR is intentionally test-only: it locks currently-green follow-up delivery behavior for silent replies, dispatcher fallback, and Codex app-server preservation of silent terminal text. It also documents one known JSON-envelope delivery gap as a todo contract row for the later runtime-plan delivery migration.

flowchart TD
  Outcome["Agent payloads"] --> Delivery["OpenClaw delivery policy"]
  Delivery --> Silent["Exact NO_REPLY suppresses visible delivery"]
  Delivery --> Media["NO_REPLY + media remains deliverable"]
  Delivery --> Dispatcher["Missing origin route falls back to dispatcher"]
  Delivery --> Todo["TODO: JSON NO_REPLY envelope suppression"]
  Codex["Codex app-server adapter"] --> Outcome

Contract Matrix

Why

Delivery is an OpenClaw-owned runtime policy domain. Codex should preserve terminal content and side-channel state, while the shared delivery layer decides whether output is visible, silent, routed to origin, or routed to dispatcher.

The JSON NO_REPLY row is intentionally not made green here because this Phase 1 PR must remain test-only. Runtime behavior changes belong in the later AgentRuntimePlan delivery migration.

Out Of Scope

• No production delivery changes.
• No runtime-plan implementation yet.
• No changes to frozen prototype PRs #70743 or #70772.

Verification

• node scripts/run-vitest.mjs run --config test/vitest/vitest.auto-reply-reply.config.ts src/auto-reply/reply/followup-runner.test.ts — 28 passed, 1 todo
• node scripts/run-vitest.mjs run --config test/vitest/vitest.extensions.config.ts extensions/codex/src/app-server/delivery-no-reply-runtime-contract.test.ts
• ./node_modules/.bin/oxlint --tsconfig tsconfig.oxlint.core.json test/helpers/agents/delivery-no-reply-runtime-contract.ts src/auto-reply/reply/followup-runner.test.ts extensions/codex/src/app-server/delivery-no-reply-runtime-contract.test.ts
• git diff --check -- test/helpers/agents/delivery-no-reply-runtime-contract.ts src/auto-reply/reply/followup-runner.test.ts extensions/codex/src/app-server/delivery-no-reply-runtime-contract.test.ts

Refs #71004 Follows #71009 Follows #71029

Changed files

• extensions/codex/src/app-server/delivery-no-reply-runtime-contract.test.ts (added, +80/-0)
• src/auto-reply/reply/followup-runner.test.ts (modified, +78/-1)
• test/helpers/agents/delivery-no-reply-runtime-contract.ts (added, +12/-0)

PR #71042: [codex] Add transcript repair runtime contracts

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71042

Description (problem / solution / changelog)

Summary

Adds the Phase 1 transcript-repair contract slice for RFC #71004. This is test-only: it does not change Pi runtime behavior, Codex app-server behavior, or any production transcript repair code.

Contract Boundary

flowchart TD
  UserTurn["Queued user turn"] --> TranscriptPolicy["OpenClaw transcript repair contract"]
  TranscriptPolicy --> PiMerge["Pi orphan user merge strategy"]
  TranscriptPolicy --> CodexProjection["Codex context projection"]
  PiMerge --> PreparedPrompt["Prepared prompt keeps older user content"]
  CodexProjection --> QuotedContext["Quoted context keeps prior structured/media turns"]

This PR locks the current executable behavior that Phase 2/3 runtime-plan work must preserve:

Why

The Pi to Codex shift exposed that transcript repair is OpenClaw-owned policy, not a harness implementation detail. Bug class #3 from the GPT-5.4 audit came from orphan trailing user leaves and payload-shape handling. This PR creates the contract tests first so later AgentRuntimePlan work can move transcript policy without losing structured/media payload semantics.

Out of Scope

• No production runtime refactor.
• No pi-embedded-runner rename.
• No changes to #70743/#70772.
• No Codex-owned transcript repair strategy is introduced here; Codex coverage is limited to current adapter projection behavior until the shared runtime plan owns this seam.

Verification

• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/pi-embedded-runner/run/transcript-repair-runtime-contract.test.ts
• node scripts/run-vitest.mjs run --config test/vitest/vitest.extensions.config.ts extensions/codex/src/app-server/transcript-repair-runtime-contract.test.ts
• ./node_modules/.bin/oxlint --tsconfig tsconfig.oxlint.core.json test/helpers/agents/transcript-repair-runtime-contract.ts src/agents/pi-embedded-runner/run/transcript-repair-runtime-contract.test.ts extensions/codex/src/app-server/transcript-repair-runtime-contract.test.ts
• git diff --check -- test/helpers/agents/transcript-repair-runtime-contract.ts src/agents/pi-embedded-runner/run/transcript-repair-runtime-contract.test.ts extensions/codex/src/app-server/transcript-repair-runtime-contract.test.ts

Refs #71004. Follows #71009, #71029, #71038, #71039.

Changed files

• extensions/codex/src/app-server/transcript-repair-runtime-contract.test.ts (added, +44/-0)
• src/agents/pi-embedded-runner/run/transcript-repair-runtime-contract.test.ts (added, +131/-0)
• test/helpers/agents/transcript-repair-runtime-contract.ts (added, +62/-0)

PR #71044: [codex] Add prompt overlay runtime contracts

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71044

Description (problem / solution / changelog)

Summary

Adds the Phase 1 prompt-overlay contract slice for RFC #71004. This is test-only: no production prompt, provider runtime, Pi runner, or Codex app-server behavior changes.

Contract Boundary

flowchart TD
  ModelRef["Resolved provider/model"] --> OverlayContract["OpenClaw GPT-5 prompt overlay resolver contract"]
  OverlayContract --> SharedConfig["Shared agents.defaults.promptOverlays.gpt5"]
  OverlayContract --> OpenAIPlugin["OpenAI-family plugin personality fallback"]
  OverlayContract --> CoreResolver["Core GPT-5 overlay resolver"]
  OverlayContract --> CodexProvider["Codex provider contribution surface"]
  CoreResolver --> PromptBundle["Behavior contract + optional interaction style"]
  CodexProvider --> PromptBundle

This PR locks current resolver/provider-surface behavior that Phase 2/3 runtime-plan work must preserve:

Why

The Pi to Codex shift exposed prompt overlays as OpenClaw-owned runtime policy. Bug class #7 from the GPT-5.4 audit came from provider scoping: an OpenAI plugin personality setting must not accidentally control unrelated GPT-5 providers, while Codex/OpenAI-family paths still need consistent overlay behavior. These contracts make that ownership explicit before AgentRuntimePlan moves prompt policy into a shared prepared turn.

Note: this PR intentionally does not claim full Pi prompt-bundle assembly coverage. It exercises the shared resolver and Codex provider contribution surface only.

Out of Scope

• No production runtime refactor.
• No prompt text edits.
• No new plugin hook surface.
• No changes to #70743/#70772.

Verification

• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/prompt-overlay-runtime-contract.test.ts
• node scripts/run-vitest.mjs run --config test/vitest/vitest.extensions.config.ts extensions/codex/prompt-overlay-runtime-contract.test.ts
• ./node_modules/.bin/oxlint --tsconfig tsconfig.oxlint.core.json test/helpers/agents/prompt-overlay-runtime-contract.ts src/agents/prompt-overlay-runtime-contract.test.ts extensions/codex/prompt-overlay-runtime-contract.test.ts
• git diff --check -- test/helpers/agents/prompt-overlay-runtime-contract.ts src/agents/prompt-overlay-runtime-contract.test.ts extensions/codex/prompt-overlay-runtime-contract.test.ts

Refs #71004. Follows #71009, #71029, #71038, #71039, #71042.

Changed files

• extensions/codex/prompt-overlay-runtime-contract.test.ts (added, +45/-0)
• src/agents/prompt-overlay-runtime-contract.test.ts (added, +78/-0)
• test/helpers/agents/prompt-overlay-runtime-contract.ts (added, +48/-0)

PR #71046: [codex] Add schema normalization runtime contracts

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71046

Description (problem / solution / changelog)

Summary

Adds the Phase 1 schema-normalization contract slice for RFC #71004. This is test-only: no production schema normalization, OpenAI transport, Pi runner, or Codex app-server behavior changes.

Contract Boundary

flowchart TD
  ToolCatalog["OpenClaw tool catalog"] --> ProviderCompat["Provider schema compatibility hooks"]
  ProviderCompat --> OpenAIResponses["OpenAI HTTP Responses"]
  ProviderCompat --> OpenAIWS["OpenAI WebSocket"]
  ProviderCompat --> CodexDynamicTools["Codex app-server dynamic-tool boundary"]
  OpenAIResponses --> ExecutableSchemas["Executable tool schemas"]
  OpenAIWS --> ExecutableSchemas
  CodexDynamicTools --> ExecutableSchemas
  ExecutableSchemas --> Todo["TODO: full strict-compatible parameter-free parity"]

This PR locks the current executable behavior that Phase 2/3 runtime-plan work must preserve, and marks known red gaps as todo rather than hiding it behind a weak assertion:

Why

The Pi to Codex shift exposed tool schema normalization as OpenClaw-owned runtime policy. Bug class #6 from the GPT-5.4 audit came from per-transport schema forks: HTTP Responses, WS, and Codex adapter surfaces need equivalent executable schema invariants before AgentRuntimePlan centralizes tool catalog preparation.

This PR does not claim Codex app-server performs schema normalization. It locks the Codex adapter boundary that receives prepared dynamic-tool schemas, while provider/tool normalization remains covered by the plugin-sdk and transport tests.

Out of Scope

• No production runtime refactor.
• No new schema normalizer API.
• No virtual-provider policy changes.
• No changes to #70743/#70772.

Verification

• node scripts/run-vitest.mjs run --config test/vitest/vitest.unit-fast.config.ts src/plugin-sdk/schema-normalization-runtime-contract.test.ts — 4 passed
• node scripts/run-vitest.mjs run --config test/vitest/vitest.unit-fast.config.ts src/agents/schema-normalization-runtime-contract.test.ts — 3 passed, 2 todo
• node scripts/run-vitest.mjs run --config test/vitest/vitest.extensions.config.ts extensions/codex/src/app-server/schema-normalization-runtime-contract.test.ts
• ./node_modules/.bin/oxlint --tsconfig tsconfig.oxlint.core.json test/helpers/agents/schema-normalization-runtime-contract.ts src/plugin-sdk/schema-normalization-runtime-contract.test.ts src/agents/schema-normalization-runtime-contract.test.ts extensions/codex/src/app-server/schema-normalization-runtime-contract.test.ts
• git diff --check -- test/helpers/agents/schema-normalization-runtime-contract.ts src/plugin-sdk/schema-normalization-runtime-contract.test.ts src/agents/schema-normalization-runtime-contract.test.ts extensions/codex/src/app-server/schema-normalization-runtime-contract.test.ts

Refs #71004. Follows #71009, #71029, #71038, #71039, #71042, #71044.

Changed files

• extensions/codex/src/app-server/schema-normalization-runtime-contract.test.ts (added, +168/-0)
• src/agents/schema-normalization-runtime-contract.test.ts (added, +75/-0)
• src/plugin-sdk/schema-normalization-runtime-contract.test.ts (added, +73/-0)
• test/helpers/agents/schema-normalization-runtime-contract.ts (added, +92/-0)

PR #71048: [codex] Add transport params runtime contracts

• Repository: openclaw/openclaw
• Author: 100yenadmin
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/71048

Description (problem / solution / changelog)

Summary

Adds the Phase 1 transport-params contract slice for RFC #71004. This is intentionally test-only: it documents the OpenClaw-owned transport policy that must stay stable while Pi and Codex move toward a shared AgentRuntimePlan.

No production runtime behavior changes.

flowchart TD
  ModelRef["Resolved model/provider"] --> ExtraParams["Pi/OpenAI extra params"]
  Config["OpenClaw config + think level"] --> ExtraParams
  Hooks["Provider prep + transport patch hooks"] --> ExtraParams
  ExtraParams --> Defaults["GPT-5 transport defaults"]
  ExtraParams --> Payload["Responses payload mutation"]
  ExtraParams --> StreamOptions["Stream options propagation"]
  Defaults --> Contract["Transport params contract"]
  Payload --> Contract
  StreamOptions --> Contract

Contract Coverage

This PR covers the shared OpenClaw transport-policy rows that are executable today without refactoring runtime ownership:

• OpenAI-family GPT-5 defaults for openai/* and openai-codex/*.
• Non-OpenAI GPT-5 providers do not inherit OpenAI transport defaults.
• Provider/model alias normalization for OpenAI Codex transport detection.
• parallel_tool_calls API-family support, including openai-codex-responses.
• Payload mutation for openai-codex/gpt-5.4 on Responses-family transports.
• OpenAI GPT-5 warmup defaults propagate through the Pi/OpenAI stream wrapper path, including openaiWsWarmup: false.
• OpenAI GPT-5 thinking level maps into Responses reasoning.effort when the OpenAI reasoning wrapper is active.
• Provider preparation composes before transport patch resolution.

Codex app-server startup config and turn-start effort mapping are intentionally excluded from this PR after review: those are Codex adapter lifecycle concerns, not shared transport-param policy. They should be covered in the later Codex adapter/runtime-plan phase, not asserted here as transport parity.

Why

The GPT-5.4 audit found that transport parameters were scattered by API string and wrapper path. The concrete regression was parallel_tool_calls being injected for some Responses-family transports but not openai-codex-responses. This contract gives maintainers a focused safety net before the runtime-plan migration centralizes transport policy.

Validation

• node scripts/run-vitest.mjs run --config test/vitest/vitest.agents.config.ts src/agents/transport-params-runtime-contract.test.ts
• ./node_modules/.bin/oxlint --tsconfig tsconfig.oxlint.core.json test/helpers/agents/transport-params-runtime-contract.ts src/agents/transport-params-runtime-contract.test.ts
• git diff --check -- test/helpers/agents/transport-params-runtime-contract.ts src/agents/transport-params-runtime-contract.test.ts

Changed files

• src/agents/transport-params-runtime-contract.test.ts (added, +239/-0)
• test/helpers/agents/transport-params-runtime-contract.ts (added, +33/-0)