Skip to content

codex: support native app-server background spawns for Codex harness agents#74768

Closed
91wan wants to merge 2 commits intoopenclaw:mainfrom
91wan:codex/native-app-server-background-spawn
Closed

codex: support native app-server background spawns for Codex harness agents#74768
91wan wants to merge 2 commits intoopenclaw:mainfrom
91wan:codex/native-app-server-background-spawn

Conversation

@91wan
Copy link
Copy Markdown
Contributor

@91wan 91wan commented Apr 30, 2026

Why

Codex app-server is the native Codex integration path; ACP/acpx remains the generic harness backend.

What

  • Allows the existing legacy embeddedHarness: { runtime: "codex", fallback: "none" } config shape to participate in agent runtime policy resolution when agentRuntime is not present.
  • Keeps sessions_spawn({ agentId: "codex", task: "..." }) on the normal OpenClaw child-session path, while the child agent can select the existing native Codex app-server harness through runtime policy.
  • Starts the required Codex owner plugin when legacy embeddedHarness forces the Codex runtime.
  • Preserves explicit agentRuntime precedence and only uses legacy embeddedHarness to fill missing runtime/fallback policy fields.

What not

  • Does not replace ACP/acpx.
  • Does not change default agent routing.
  • Does not touch Computer Use install behavior.
  • Does not use WebSocket.
  • Does not make Codex app-server a global default.

Tests

  • pnpm exec oxfmt --check --threads=1 src/agents/agent-runtime-policy.ts src/agents/harness/selection.test.ts src/plugins/channel-plugin-ids.test.ts src/agents/tools/sessions-spawn-tool.test.ts - PASS.
  • pnpm test src/agents/harness/selection.test.ts src/plugins/channel-plugin-ids.test.ts src/agents/tools/sessions-spawn-tool.test.ts -- --reporter=verbose - PASS, 2 Vitest shards, 50 agent tests and 68 plugin tests.
  • pnpm test extensions/codex/src/app-server/run-attempt.test.ts src/agents/acp-spawn.test.ts src/agents/openclaw-tools.subagents.sessions-spawn.lifecycle.test.ts -- --reporter=verbose - PASS, 2 Vitest shards, 63 agent tests and 39 extension tests.
  • git diff --check - PASS.
  • CI=true OPENCLAW_LOCAL_CHECK=0 pnpm check:changed - PASS.

Note: broad changed-gate proof ran locally because the blacksmith Testbox CLI was unavailable in this checkout.

@openclaw-barnacle openclaw-barnacle Bot added agents Agent runtime and tooling size: S labels Apr 30, 2026
@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented Apr 30, 2026 •
edited
Loading

Codex review: needs maintainer review before merge.

Summary
The branch makes legacy embeddedHarness runtime/fallback fields feed the shared agentRuntime policy resolver, adds harness/startup/sessions_spawn tests, and records the Codex compatibility fix in CHANGELOG.md.

Reproducibility: yes. Current main has a source-level reproduction: a config with only embeddedHarness: { runtime: "codex", fallback: "none" } is schema-valid and doctor-migratable, but resolveAgentRuntimePolicy returns undefined and shared harness/startup paths depend on that resolver.

Next step before merge
No repair lane is needed; the remaining action is normal maintainer review, current CI/mergeability confirmation, and any rebase needed against current main.

Security
Cleared: The diff is limited to runtime-policy TypeScript, focused tests, and changelog text, with no concrete security or supply-chain regression found.

Review details

Best possible solution:

Land the resolver-level compatibility after ordinary review and CI, preserving explicit agentRuntime precedence while letting legacy configs continue to select enabled owner plugins through manifest activation.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main has a source-level reproduction: a config with only embeddedHarness: { runtime: "codex", fallback: "none" } is schema-valid and doctor-migratable, but resolveAgentRuntimePolicy returns undefined and shared harness/startup paths depend on that resolver.

Is this the best way to solve the issue?

Yes. The resolver-level fill-missing merge is the narrowest maintainable fix because it mirrors the existing doctor migration and avoids scattering Codex-specific compatibility logic across harness selection, startup planning, and runtime metadata call sites.

What I checked:

  • Current resolver ignores legacy policy: On current main, resolveAgentRuntimePolicy only reads agentRuntime and returns undefined when that object has no runtime policy, so embeddedHarness cannot affect shared runtime resolution. (src/agents/agent-runtime-policy.ts:7, 8283c5d6cc3f)
  • Legacy config shape remains accepted: The config schema still exposes AgentEmbeddedHarnessSchema on agent entries next to AgentRuntimePolicySchema, so this is still a valid legacy input shape rather than invalid config. (src/config/zod-schema.agent-runtime.ts:813, 8283c5d6cc3f)
  • Doctor migration defines fill-missing behavior: The legacy migration copies embeddedHarness.runtime into missing agentRuntime.id and embeddedHarness.fallback into missing agentRuntime.fallback, preserving explicit new fields. (src/commands/doctor/shared/legacy-config-migrations.runtime.agents.ts:179, 8283c5d6cc3f)
  • Harness selection uses the shared resolver: Harness selection resolves per-agent and default runtime policy through resolveAgentRuntimePolicy, so resolver compatibility reaches the actual embedded harness selection path. (src/agents/harness/selection.ts:315, 8283c5d6cc3f)
  • Startup activation uses configured harness runtimes: Startup plugin planning collects configured harness runtimes through collectConfiguredAgentHarnessRuntimes, which currently reads only the shared runtime resolver before matching plugin startup.agentHarnesses. (src/agents/harness-runtimes.ts:22, 8283c5d6cc3f)
  • Codex ownership is manifest-backed: The Codex plugin manifest declares activation.onAgentHarnesses: ["codex"], so collecting a configured codex runtime is the generic startup mechanism for the native Codex owner plugin. (extensions/codex/openclaw.plugin.json:21, 8283c5d6cc3f)

Likely related people:

  • steipete: Current-main blame for the resolver, harness selection, startup runtime collection, Codex manifest metadata, and legacy doctor migration points to Peter Steinberger, and local history shows the original harness registry, app-server, PI fallback, and shared runtime activation work in this area. (role: introduced behavior and recent maintainer; confidence: high; commits: ad264a9f5a2d, 2d80bbc43de0, 31a0b7bd42a5; files: src/agents/agent-runtime-policy.ts, src/agents/harness/selection.ts, src/agents/harness-runtimes.ts)
  • duqaXxX: Local history shows a directly related forced-runtime activation fix for Codex harness startup, adjacent to this PR's legacy-runtime startup activation path. (role: adjacent activation contributor; confidence: medium; commits: 69ba924b530e; files: src/plugins/gateway-startup-plugin-ids.ts, src/plugins/channel-plugin-ids.test.ts, extensions/codex/openclaw.plugin.json)
  • vincentkoc: Recent local history shows Codex app-server startup/auth and shared harness test work by Vincent Koc, which is adjacent to the native app-server behavior this PR keeps selectable. (role: adjacent Codex app-server maintainer; confidence: medium; commits: f1cc8f0cfc7c, b5dfeaab4ce3, c902d20eb7ed; files: extensions/codex/src/app-server/run-attempt.ts, extensions/codex/src/app-server/shared-client.ts, extensions/codex/provider.ts)

Remaining risk / open question:

  • The PR head is based on an older main SHA, so maintainers should confirm current mergeability and CI before landing.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 8283c5d6cc3f.

@91wan 91wan force-pushed the codex/native-app-server-background-spawn branch 23 times, most recently from 7c83e36 to d162898 Compare May 1, 2026 00:45
@91wan 91wan force-pushed the codex/native-app-server-background-spawn branch from 7e5000e to 1876af7 Compare May 1, 2026 01:21
@vincentkoc vincentkoc mentioned this pull request May 3, 2026
Merged
25 tasks
@91wan
Copy link
Copy Markdown
Contributor Author

91wan commented May 5, 2026

Closing as superseded by current upstream. Latest main/release already includes Codex app-server/harness runtime support, and this branch now only preserves a legacy embeddedHarness compatibility slice while conflicting with current main. I am retiring it to reduce stale PR noise.

@91wan 91wan closed this May 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

agents Agent runtime and tooling size: S

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@91wan