Skip to content

fix(codex/app-server): forward workspace bootstrap into developerInstructions#77372

Merged
steipete merged 1 commit intoopenclaw:mainfrom
lonexreb:fix/77363-codex-developer-instructions-bootstrap
May 6, 2026
Merged

fix(codex/app-server): forward workspace bootstrap into developerInstructions#77372
steipete merged 1 commit intoopenclaw:mainfrom
lonexreb:fix/77363-codex-developer-instructions-bootstrap

Conversation

@lonexreb
Copy link
Copy Markdown
Contributor

@lonexreb lonexreb commented May 4, 2026 •
edited by steipete
Loading

Summary

Fixes #77363: under the native Codex app-server runtime, OpenClaw workspace bootstrap files such as SOUL.md, IDENTITY.md, USER.md, TOOLS.md, BOOTSTRAP.md, MEMORY.md, and HEARTBEAT.md were loaded, but only merged into Codex config.instructions.

Codex treats config.instructions as the system/base-instructions lane, while developerInstructions is inserted as a developer-role message. That meant persona/style bootstrap could miss the behavior-shaping lane used by app-server turns.

Fix

Build the workspace bootstrap block before finalizing developerInstructions, then join it into:

  • the baseline developerInstructions, and
  • the context-engine developerInstructions when the context engine is active.

The bootstrap is no longer duplicated into config.instructions. AGENTS.md remains excluded from the explicit bootstrap block because Codex loads it natively.

Verification

  • pnpm exec oxfmt --check --threads=1 extensions/codex/src/app-server/run-attempt.ts extensions/codex/src/app-server/run-attempt.test.ts docs/plugins/codex-harness.md CHANGELOG.md — clean.
  • pnpm test extensions/codex/src/app-server/run-attempt.test.ts extensions/codex/src/app-server/run-attempt.context-engine.test.ts — 2 files passed, 62 tests passed.
  • pnpm docs:check-mdx docs/plugins/codex-harness.md — passed.

Real behavior proof

  • Behavior or issue addressed: Codex app-server runs now receive OpenClaw workspace bootstrap persona/context in thread/start developerInstructions, instead of only in config.instructions.
  • Real environment tested: Local OpenClaw checkout on macOS, rebased onto current origin/main, using the Codex app-server harness code path with a stub app-server request collector.
  • Exact steps or command run after the patch: Ran pnpm test extensions/codex/src/app-server/run-attempt.test.ts extensions/codex/src/app-server/run-attempt.context-engine.test.ts after the fixup commit.
  • Evidence after fix: Terminal output from the OpenClaw checkout:
Test Files  2 passed (2)
     Tests  62 passed (62)
  Duration  35.60s
[test] passed 1 Vitest shard in 43.92s

The regression test writes AGENTS.md and SOUL.md, starts runCodexAppServerAttempt, captures the actual thread/start JSON-RPC payload emitted by the harness, and verifies the payload contains "Soul voice goes here." in developerInstructions while config.instructions remains unset.

  • Observed result after fix: params.developerInstructions contains the SOUL.md bootstrap and the Codex-native AGENTS.md substitution note, raw AGENTS.md content is still excluded, and params.config?.instructions is undefined for this bootstrap path.
  • What was not tested: Live external model style comparison was not run; this is a deterministic app-server wire-format fix, and the sibling ../codex source contract was checked to confirm developer_instructions is the developer-role message lane.

Closes

Fixes #77363

@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented May 4, 2026 •
edited
Loading

Codex review: needs real behavior proof before merge.

Summary
The PR moves Codex workspace bootstrap content into developerInstructions, updates regression coverage, docs, changelog, and includes a small gateway cron test cleanup.

Reproducibility: yes. source-reproducible: current main finalizes developerInstructions before loading workspace bootstrap and only merges the bootstrap into config.instructions. I did not establish a live model-turn failure path in this read-only review.

Real behavior proof
Needs real behavior proof before merge: The PR body supplies after-fix Vitest terminal output from a stub request collector, but not live Codex app-server behavior proof. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, ask a maintainer to comment @clawsweeper re-review.

Next step before merge
Needs contributor or maintainer live behavior proof and final merge gating; there is no narrow code defect here for an automated repair lane.

Security
Cleared: The diff touches prompt construction, docs/changelog, tests, and a test helper; I found no concrete dependency, workflow, secret, permission, or artifact-execution concern.

Review details

Best possible solution:

Land this PR or an equivalent narrow patch after live app-server proof confirms workspace persona files reach an actual Codex thread start/resume path and final checks are green.

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

Yes, source-reproducible: current main finalizes developerInstructions before loading workspace bootstrap and only merges the bootstrap into config.instructions. I did not establish a live model-turn failure path in this read-only review.

Is this the best way to solve the issue?

Yes for the code direction: the Codex protocol has an explicit developerInstructions field and the patch moves the existing bootstrap block into that path without adding a new API. Merge should still wait for real behavior proof and completed checks.

Acceptance criteria:

  • pnpm test extensions/codex/src/app-server/run-attempt.test.ts extensions/codex/src/app-server/run-attempt.context-engine.test.ts
  • pnpm docs:check-mdx docs/plugins/codex-harness.md
  • pnpm exec oxfmt --check --threads=1 extensions/codex/src/app-server/run-attempt.ts extensions/codex/src/app-server/run-attempt.test.ts docs/plugins/codex-harness.md CHANGELOG.md

What I checked:

  • Current main misses developerInstructions bootstrap: Current main initializes developerInstructions from baseDeveloperInstructions, runs the prompt-build hook with that value, and only later builds workspaceBootstrapInstructions for the config.instructions path. (extensions/codex/src/app-server/run-attempt.ts:486, 5969ac8ccf8b)
  • Current regression test covers only config.instructions: The existing bootstrap test writes AGENTS.md and SOUL.md, then asserts SOUL.md appears in config.instructions; it does not prove the app-server developerInstructions payload contains the bootstrap. (extensions/codex/src/app-server/run-attempt.test.ts:955, 5969ac8ccf8b)
  • Protocol supports explicit developerInstructions: Generated thread start/resume types expose developerInstructions, and OpenClaw forwards that field separately from the generic config object. (extensions/codex/src/app-server/thread-lifecycle.ts:195, 5969ac8ccf8b)
  • PR patch targets the implicated path: The PR builds workspaceBootstrapInstructions before finalizing developerInstructions, joins it into the baseline and context-engine paths, and updates the focused test to assert config.instructions is unset for this bootstrap path. (extensions/codex/src/app-server/run-attempt.ts:484, 5f0771539db4)
  • Docs support workspace bootstrap as session context: Workspace docs describe SOUL.md and related files as loaded every session, and the Codex harness docs currently describe forwarding those files through Codex config instructions. Public docs: docs/concepts/agent-workspace.md. (docs/concepts/agent-workspace.md:60, 5969ac8ccf8b)
  • Proof remains harness-only: The PR body's real-behavior section reports Vitest output from a stub app-server request collector; it does not include a live Codex app-server session/resume transcript, terminal run, or redacted runtime log showing persona behavior changed. (5f0771539db4)

Likely related people:

  • steipete: Recent path history shows repeated Codex app-server, test, and gateway cron maintenance, and Peter also committed the current PR's gateway test cleanup. (role: recent maintainer and adjacent owner; confidence: high; commits: 538605ff44d2, e428a2dfe2a3, e37607349bb7; files: extensions/codex/src/app-server/run-attempt.ts, extensions/codex/src/app-server/run-attempt.test.ts, extensions/codex/src/app-server/thread-lifecycle.ts)
  • keshavbotagent: Recent merged work touched Codex app-server run-attempt/test behavior around dynamic/native tool progress on the same central harness path. (role: recent adjacent maintainer; confidence: medium; commits: 3f210b10ce3a; files: extensions/codex/src/app-server/run-attempt.ts, extensions/codex/src/app-server/run-attempt.test.ts)
  • VACInc: Recent Codex thread-continuity work touched the thread lifecycle surface that forwards developer instructions into thread start/resume. (role: adjacent thread-lifecycle contributor; confidence: medium; commits: 8cf1800ee961; files: extensions/codex/src/app-server/thread-lifecycle.ts, extensions/codex/src/app-server/run-attempt.test.ts)

Remaining risk / open question:

  • The proof in the PR body is still a stubbed JSON-RPC harness run, not live Codex app-server behavior.
  • One GitHub check run was still in progress for head 5f0771539db40baca3772b48bcb18accad543a75 at inspection.
  • The patch intentionally stops sending this bootstrap through config.instructions; I did not find a concrete breakage, but it changes the older documented lane.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 5969ac8ccf8b.

@lonexreb lonexreb force-pushed the fix/77363-codex-developer-instructions-bootstrap branch from 72511bf to fbd3446 Compare May 4, 2026 17:56
@lonexreb
Copy link
Copy Markdown
Contributor Author

lonexreb commented May 4, 2026

Addressed [P3] from clawsweeper review. Rebased onto current origin/main and added Thanks @lonexreb to the changelog entry. Diff is unchanged otherwise; targeted tests still green (51 in run-attempt.test.ts, 5 in run-attempt.context-engine.test.ts).

@clawsweeper clawsweeper Bot mentioned this pull request May 5, 2026
Open
@lonexreb lonexreb force-pushed the fix/77363-codex-developer-instructions-bootstrap branch 2 times, most recently from 1060519 to 99c68ba Compare May 5, 2026 05:35
@openclaw-barnacle openclaw-barnacle Bot added the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label May 5, 2026
@lonexreb lonexreb force-pushed the fix/77363-codex-developer-instructions-bootstrap branch from 99c68ba to ecb9e0b Compare May 5, 2026 18:12
@steipete steipete force-pushed the fix/77363-codex-developer-instructions-bootstrap branch from ecb9e0b to af3ab09 Compare May 6, 2026 07:33
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: S proof: supplied External PR includes structured after-fix real behavior proof. and removed size: XS triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 6, 2026
@steipete steipete force-pushed the fix/77363-codex-developer-instructions-bootstrap branch from af3ab09 to 6a7ddf1 Compare May 6, 2026 07:36
@openclaw-barnacle openclaw-barnacle Bot added the gateway Gateway runtime label May 6, 2026
@steipete steipete force-pushed the fix/77363-codex-developer-instructions-bootstrap branch 2 times, most recently from 2620592 to ffdcb2d Compare May 6, 2026 07:57
@openclaw-barnacle openclaw-barnacle Bot removed the gateway Gateway runtime label May 6, 2026
@lonexreb @steipete
fix(codex/app-server): forward bootstrap into developerInstructions
49b4b3a 
The OpenClaw workspace bootstrap block (SOUL.md, IDENTITY.md, USER.md,
TOOLS.md, BOOTSTRAP.md, MEMORY.md, HEARTBEAT.md) was only being merged into
Codex's config.instructions. The Codex app-server runtime overlay
consistently applies the explicit developerInstructions field, so persona
and style guidance present in the workspace was failing to shape Codex
behavior on session resume.

Build the workspace bootstrap block before finalizing developerInstructions
and join it into both:

- the baseline developerInstructions (initial assignment), and
- the context-engine developerInstructions (when context engine is active),
  preserving the existing config-engine projection addition.

The existing config.instructions merge stays intact, so the bootstrap now
reaches Codex through both paths and downstream hooks
(resolveAgentHarnessBeforePromptBuildResult) see what Codex will actually
receive. AGENTS.md remains excluded because Codex loads it natively.

Update the existing 'passes OpenClaw bootstrap files through ...' test to
also assert the developerInstructions field carries SOUL.md and the Codex
AGENTS.md substitution note while still excluding the native AGENTS.md
content.

Fixes openclaw#77363.
@steipete steipete force-pushed the fix/77363-codex-developer-instructions-bootstrap branch from ffdcb2d to 49b4b3a Compare May 6, 2026 08:04
@steipete steipete merged commit 9edeffc into openclaw:main May 6, 2026
87 checks passed
@steipete steipete mentioned this pull request May 6, 2026
Closed
@github-actions github-actions Bot mentioned this pull request May 6, 2026
Open
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

docs Improvements or additions to documentation extensions: codex proof: supplied External PR includes structured after-fix real behavior proof. size: S

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

fix (codex harness): Codex app-server: forward OpenClaw persona bootstrap into developer instructions

2 participants

@lonexreb @steipete