[refactor] Centralize Agenta platform instructions - #6365
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Important Review skippedNo new commits to review since the last review. ⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Team Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository YAML (base), Organization UI (inherited) Review profile: CHILL Plan: Team Run ID: 📒 Files selected for processing (2)
Included review availability: Your plan provides up to 8 included reviews per hour; 5 remain after this review. 📝 SummarySummary by CodeRabbit
WalkthroughThe SDK now composes shared Agenta platform instructions as a scalar ChangesAgent platform instruction rollout
Estimated code review effort: 3 (Moderate) | ~25 minutes Merge Risk: 🔵 Low · up to This change centralizes platform instructions while retaining existing harness delivery and warm-session behavior. Normal requests are covered, but malformed instruction payloads may fail unexpectedly and the protocol documentation may misdirect implementers, so these bounded issues should be addressed or accepted before merge. 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
🤖 The AI agent says: Please review three decisions before implementation: (1) SDK-owned |
📘 Docs preview
This comment updates in place on every push. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Team
Run ID: 25602467-50b0-450b-8728-f413bb140202
📒 Files selected for processing (5)
docs/design/agent-platform-instructions/README.mddocs/design/agent-platform-instructions/context.mddocs/design/agent-platform-instructions/plan.mddocs/design/agent-platform-instructions/research.mddocs/design/agent-platform-instructions/status.md
Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.
| - Exposure: an opaque transport field in the exported `run_request` schema and | ||
| `/inspect`, but not an author-configurable or persisted agent field. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings
Length of output: 4924
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- plan excerpt ---'
sed -n '1,210p' docs/design/agent-platform-instructions/plan.md
printf '%s\n' '--- implementation-slice excerpt ---'
sed -n '245,285p' docs/design/agent-platform-instructions/plan.md
printf '%s\n' '--- inspect/platformInstructions references ---'
rg -n -S -C 3 '/inspect|platformInstructions|run_request|developer_instructions|AGENTS\.md' --glob '!**/node_modules/**' --glob '!**/dist/**' .Repository: Agenta-AI/agenta
Length of output: 50375
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- cited contract sections ---'
sed -n '1,95p' docs/design/agent-platform-instructions/plan.md
sed -n '160,195p' docs/design/agent-platform-instructions/plan.md
sed -n '255,280p' docs/design/agent-platform-instructions/plan.md
sed -n '315,340p' docs/design/agent-platform-instructions/plan.md
printf '%s\n' '--- current non-archive references ---'
rg -n -S -C 2 'platformInstructions|/inspect|run_request|developer_instructions' \
--glob '!**/archive/**' \
--glob '!**/node_modules/**' \
--glob '!**/dist/**' \
--glob '!docs/design/agent-platform-instructions/plan.md' \
.
printf '%s\n' '--- likely inspect/schema files ---'
git ls-files | rg -i '(^|/)(inspect|schema|schemas|dto|mapper)([^/]*\.(py|ts|tsx|js|json))?$|agent.*(schema|inspect)|workflow.*schema'Repository: Agenta-AI/agenta
Length of output: 50375
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- plan lines 1-95 ---'
nl -ba docs/design/agent-platform-instructions/plan.md | sed -n '1,95p'
printf '%s\n' '--- plan lines 160-195 ---'
nl -ba docs/design/agent-platform-instructions/plan.md | sed -n '160,195p'
printf '%s\n' '--- plan lines 255-280 ---'
nl -ba docs/design/agent-platform-instructions/plan.md | sed -n '255,280p'
printf '%s\n' '--- plan lines 315-340 ---'
nl -ba docs/design/agent-platform-instructions/plan.md | sed -n '315,340p'
printf '%s\n' '--- agent inspect implementation ---'
nl -ba services/oss/src/agent/schemas.py | sed -n '1,220p'
nl -ba services/oss/src/agent/app.py | sed -n '120,180p'
printf '%s\n' '--- focused references ---'
rg -n -S 'platformInstructions|platform_instructions|AGENT_SCHEMAS|inspect' \
services/oss/src/agent sdks/python/oss/tests/pytest/unit/agents \
services/agent 2>/dev/null || trueRepository: Agenta-AI/agenta
Length of output: 2728
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- plan lines 1-95 ---'
cat -n docs/design/agent-platform-instructions/plan.md | sed -n '1,95p'
printf '%s\n' '--- plan lines 160-195 ---'
cat -n docs/design/agent-platform-instructions/plan.md | sed -n '160,195p'
printf '%s\n' '--- plan lines 255-280 ---'
cat -n docs/design/agent-platform-instructions/plan.md | sed -n '255,280p'
printf '%s\n' '--- plan lines 315-340 ---'
cat -n docs/design/agent-platform-instructions/plan.md | sed -n '315,340p'
printf '%s\n' '--- current /inspect schema ---'
cat -n services/oss/src/agent/schemas.py | sed -n '1,130p'
printf '%s\n' '--- current route wiring ---'
cat -n services/oss/src/agent/app.py | sed -n '135,180p'Repository: Agenta-AI/agenta
Length of output: 17599
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- inspect route and response definitions ---'
rg -n -S -C 4 'def .*inspect|inspect\(|/inspect|WorkflowRevisionData|schemas.*meta|CATALOG_TYPES' \
api/oss/src services/oss/src sdks/python/oss/src \
--glob '*.py' \
--glob '!**/archive/**' \
| head -n 500
printf '%s\n' '--- run_request definitions and consumers ---'
rg -n -S -C 3 'run_request|WireRunRequest|platformInstructions|platform_instructions' \
sdks/python api/oss services/oss services/runner \
--glob '*.py' \
--glob '*.ts' \
--glob '*.tsx' \
--glob '*.json' \
--glob '!**/archive/**' \
| head -n 700
printf '%s\n' '--- agent platform conventions ---'Repository: Agenta-AI/agenta
Length of output: 50372
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/conventions /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings
Length of output: 32157
Add /inspect coverage to the compatibility slice.
The contract requires platformInstructions in /inspect, but slice 2 lists only wire contracts and goldens. The current /inspect schema has no platformInstructions. Add the /inspect DTO, mapper, and tests, or remove /inspect from the contract.
| Compute it after runtime guidance settles. Digest only normalized, harness-effective | ||
| direct instruction inputs: | ||
|
|
||
| - `platformInstructions`. | ||
| - `agentsMd`. | ||
| - Runner runtime instructions. | ||
| - `systemPrompt` and `appendSystemPrompt` for Pi-based harnesses only. | ||
| - Operator prompt-file bytes that the pinned Pi precedence test proves affect local | ||
| Pi's final prompt. | ||
|
|
||
| Continuity lookup is already scoped by harness, so do not hash the harness name again. | ||
| Normalize absent, empty, and whitespace-only values exactly as run-plan composition | ||
| does, then hash a canonical labeled JSON object with one key per effective channel. | ||
| Do not hash joined text with an ad hoc delimiter: arbitrary instruction bytes must not | ||
| make distinct channel tuples collide. Exclude ignored non-Pi prompt fields, messages, |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
Hash final effective channels, not only contributors.
instructionDigest is described as an effective digest, but the listed inputs are pre-composition contributors. A change to separators, omission rules, ordering, or harness merging can change the effective prompt while leaving every listed value unchanged. session/load can then reuse a native conversation with stale instructions.
Hash the final per-harness instruction channels, including the exact Codex developer_instructions and overlay content. Add a regression case that changes only composition semantics.
| Before freezing the daemon environment, merge SDK platform text into | ||
| `CODEX_CONFIG.developer_instructions`. Preserve unrelated configuration such as | ||
| `cli_auth_credentials_store`; never set `sandbox_mode` through this route. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🔎 Supported by static analysis
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- target excerpt ---'
sed -n '60,90p;160,190p;250,285p;315,338p' docs/design/agent-platform-instructions/plan.md
printf '%s\n' '--- related identifiers ---'
rg -n -C 3 'instructionDigest|developer_instructions|CODEX_CONFIG|Codex|/inspect|overlay|exactly[ -]once' docs/design/agent-platform-instructionsRepository: Agenta-AI/agenta
Length of output: 35898
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings
Length of output: 4924
🏁 Script executed:
#!/bin/bash
set -e
printf '%s\n' '--- plan contract context ---'
sed -n '1,60p;120,145p;193,240p' docs/design/agent-platform-instructions/plan.md
printf '%s\n' '--- repository-wide Codex configuration references ---'
rg -n -C 2 'CODEX_CONFIG|developer_instructions|instructionDigest|instruction_digest' .Repository: Agenta-AI/agenta
Length of output: 50374
Define Codex instruction merge semantics. If CODEX_CONFIG.developer_instructions already has a value, specify the merge order and exactly-once rule. Replacement can discard operator instructions. Include the effective merged value in instructionDigest so native continuity cannot reuse a session with different instructions. Add these cases to the pinned Codex spike.
| After Daytona mount outcomes are known, render runner runtime guidance in the existing | ||
| fenced `AGENTS.md` overlay. Keep that overlay reproducible so API strip-on-persist | ||
| remains safe. Do not duplicate the SDK base in the file. | ||
|
|
||
| The first implementation spike must prove, with pinned packages: | ||
|
|
||
| 1. `developer_instructions` reaches a new Codex thread. | ||
| 2. Author `AGENTS.md` remains independently loaded. | ||
| 3. `session/load` is attempted only for a matching effective `instructionDigest`. | ||
| 4. A changed digest creates a new native thread with the new developer instructions. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🔎 Supported by static analysis
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- plan.md relevant sections ---'
sed -n '1,210p' docs/design/agent-platform-instructions/plan.md
printf '%s\n' '--- plan.md implementation and acceptance sections ---'
sed -n '250,345p' docs/design/agent-platform-instructions/plan.md
printf '%s\n' '--- candidate Codex and AGENTS-related files ---'
fd -i -t f 'codex|agent|instruction|session|inspect' . | head -200
printf '%s\n' '--- references to overlay, AGENTS.md, and session reload ---'
rg -n -i 'AGENTS\.md|overlay|session/load|developer_instructions|strip-on-persist|Codex' --glob '!docs/design/agent-platform-instructions/plan.md' . | head -300Repository: Agenta-AI/agenta
Length of output: 50374
🤖 get_repo_knowledge executed:
get_repo_knowledge Agenta-AI/agenta /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/conventions /tmp/coderabbit-repo-knowledge/agenta-ai-agenta-4b53879a/learnings
Length of output: 30582
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- plan.md continuation ---'
sed -n '205,345p' docs/design/agent-platform-instructions/plan.md
printf '%s\n' '--- Codex overlay/config implementations ---'
rg -n -C 5 'developer_instructions|CODEX_CONFIG|fenced|strip.*persist|strip.*AGENTS|AGENTS\.md|session/load' \
services/runner/src services/runner/tests docs/design/codex-harness docs/blog/entries/codex-harness.mdx \
--glob '!**/dist/**' --glob '!**/node_modules/**' | head -500
printf '%s\n' '--- relevant runner test files ---'
fd -t f . services/runner/tests | rg -i 'codex|workspace|instruction|session|continuity|inspect|prompt'Repository: Agenta-AI/agenta
Length of output: 50374
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- overlay symbol bindings ---'
rg -n 'appendPlatformGuidance|instructionsFileFor|harnessFiles|developer_instructions|CODEX_CONFIG' \
services/runner/src services/runner/tests --glob '!**/dist/**' --glob '!**/node_modules/**'
printf '%s\n' '--- matching test files ---'
rg -l -i 'appendPlatformGuidance|developer_instructions|CODEX_CONFIG|AGENTS\.md|session/load|strip.*persist' \
services/runner/tests --glob '*.ts' --glob '*.tsx' | sort
printf '%s\n' '--- workspace manager ---'
sed -n '1,260p' services/runner/src/environment/workspace-manager.ts
printf '%s\n' '--- environment overlay call sites ---'
rg -n -C 12 'appendPlatformGuidance|harnessFiles|instructionsFile' services/runner/src/environment services/runner/src/engines/sandbox_agentRepository: Agenta-AI/agenta
Length of output: 50372
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- overlay implementation and unit tests ---'
sed -n '90,180p' services/runner/src/engines/sandbox_agent/system-prompt-appendix.ts
sed -n '130,215p' services/runner/tests/unit/system-prompt-appendix.test.ts
printf '%s\n' '--- environment acquisition around Codex overlay ---'
sed -n '790,845p' services/runner/src/engines/sandbox_agent/environment.ts
printf '%s\n' '--- Codex/workspace tests around instruction delivery ---'
sed -n '1,180p' services/runner/tests/unit/platform-guidance.test.ts
sed -n '840,930p' services/runner/tests/unit/sandbox-agent-orchestration.test.ts
printf '%s\n' '--- continuity test coverage ---'
rg -n -C 6 'load|create|digest|repeated|resume|continu' services/runner/tests/unit/continuation.test.ts services/runner/tests/unit/session-continuity.test.tsRepository: Agenta-AI/agenta
Length of output: 31333
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- existing strip-on-persist references ---'
rg -n -C 8 'strip_platform_guidance|platform guidance|platform-guidance|AGENTS\.md.*strip|strip.*AGENTS' \
api services sdks --glob '*.py' --glob '*.ts' --glob '*.tsx' --glob '*.md' \
--glob '!**/dist/**' --glob '!**/node_modules/**' | head -300
printf '%s\n' '--- orchestration tests containing overlay assertions ---'
rg -n -C 20 'renders the platform guidance|writes the guidance|appendPlatformGuidance|AGENTS\.md|session/load|loadedFromContinuity' \
services/runner/tests/unit/sandbox-agent-orchestration.test.ts \
services/runner/tests/unit/system-prompt-appendix.test.ts \
services/runner/tests/unit/session-continuity.test.ts
printf '%s\n' '--- plan acceptance tail ---'
sed -n '335,390p' docs/design/agent-platform-instructions/plan.mdRepository: Agenta-AI/agenta
Length of output: 50372
Add a pinned Codex lifecycle test for exactly-once overlay delivery.
appendPlatformGuidance can add a second fenced block when AGENTS.md is delivered twice. Test a new thread, matching session/load, and strip-on-persist. Assert that one overlay remains and persistence returns only the author text.
60d527f to
d491a08
Compare
mmabrouk
changed the title
|
🤖 The AI agent says: Updated the design to the approved smaller scope and rebased its docs onto the current release/v0.114.4, which already contains the gateway-guidance separation. The plan is now 81 lines rather than 358. It adds one SDK prompt module and a scalar transport field, keeps current delivery and warm-session behavior, and removes the digest/database/restart/native-channel project. The previous digest and Codex developer-merge review concerns no longer apply because those mechanisms are out of scope. Implementation and focused QA are underway with separate SDK and runner implementers. |
There was a problem hiding this comment.
Actionable comments posted: 3
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Team
Run ID: b6914eac-f822-4415-bb76-14627f9cc9e2
📒 Files selected for processing (5)
docs/design/agent-platform-instructions/README.mddocs/design/agent-platform-instructions/context.mddocs/design/agent-platform-instructions/plan.mddocs/design/agent-platform-instructions/research.mddocs/design/agent-platform-instructions/status.md
🚧 Files skipped from review as they are similar to previous changes (3)
- docs/design/agent-platform-instructions/README.md
- docs/design/agent-platform-instructions/status.md
- docs/design/agent-platform-instructions/context.md
Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.
|
🤖 The AI agent says: Implementation is pushed. The SDK now has one platform instruction module and emits a scalar field; the runner uses its existing delivery and warm-session behavior. Two independent reviewers found no blocking issues. Local runner tests/type checks, SDK agent tests, formatting, and docs build passed; live QA and CI are in progress. The earlier review concerns about instruction digests, Codex developer merging, and a redesigned overlay do not apply to this reduced implementation because those mechanisms were removed from scope. @coderabbitai review |
|
🤖 The AI agent says: The cleanup is implemented and independently reviewed. Production code is 53 lines smaller. Local runner tests/typecheck, SDK agent tests, formatting, docs build, and locked CI SDK/API/services/runner unit/integration/acceptance checks passed. Live Pi QA also passed fresh instructions, unchanged continuation, an author edit, and a fresh control; logs confirmed warm reuse. Claude/Codex/gateway live QA remains unverified because available test credentials were rejected and automatic approval review blocked copying provider keys into the test vault without explicit permission. No provider keys were copied. Temporary QA containers were removed and workflows archived. The final docs record the results and clarify the existing delivery order requested in review. |
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/design/agent-workflows/documentation/protocol.md (1)
103-103: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winUpdate the
/runprotocol reference toservices/runner/src/protocol.ts. The currentservices/agent/src/protocol.tspath does not exist. This sends developers to a nonexistent file when they follow the living protocol documentation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Team
Run ID: 68e6c740-e08c-4bd8-b39c-010e944cb87a
📒 Files selected for processing (21)
docs/design/agent-platform-instructions/status.mddocs/design/agent-workflows/documentation/protocol.mdsdks/python/agenta/sdk/agents/adapters/agenta_builtins.pysdks/python/agenta/sdk/agents/adapters/harnesses.pysdks/python/agenta/sdk/agents/dtos.pysdks/python/agenta/sdk/agents/platform/gateway.pysdks/python/agenta/sdk/agents/platform_instructions.pysdks/python/agenta/sdk/agents/utils/wire.pysdks/python/agenta/sdk/agents/wire_models.pysdks/python/oss/tests/pytest/unit/agents/golden/run_request.gateway_connection.jsonsdks/python/oss/tests/pytest/unit/agents/platform/test_gateway_connection_resolve.pysdks/python/oss/tests/pytest/unit/agents/test_harness_adapters.pysdks/python/oss/tests/pytest/unit/agents/test_wire_contract.pyservices/runner/src/engines/sandbox_agent/run-plan.tsservices/runner/src/engines/sandbox_agent/session-identity.tsservices/runner/src/lifecycle/desired-state.tsservices/runner/src/protocol.tsservices/runner/tests/unit/lifecycle-desired-state.test.tsservices/runner/tests/unit/sandbox-agent-run-plan.test.tsservices/runner/tests/unit/session-pool.test.tsservices/runner/tests/unit/wire-contract.test.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/design/agent-platform-instructions/status.md
Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.
| request.platformInstructions !== undefined | ||
| ? request.platformInstructions.trim() || undefined | ||
| : request.gatewayGuidance?.text?.trim() || undefined; |
There was a problem hiding this comment.
🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
Validate platformInstructions before calling trim().
An authorized /run request can contain platformInstructions: null because JSON parsing only casts the value to AgentRunRequest. buildRunPlan then evaluates null !== undefined and calls null.trim(), which throws before it returns BuildRunPlanResult. Return a plan error for non-string values before trimming.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| request.platformInstructions !== undefined | |
| ? request.platformInstructions.trim() || undefined | |
| : request.gatewayGuidance?.text?.trim() || undefined; | |
| if ( | |
| request.platformInstructions !== undefined && | |
| typeof request.platformInstructions !== "string" | |
| ) { | |
| return { ok: false, error: "platformInstructions must be a string" }; | |
| } | |
| const platformInstructions = | |
| request.platformInstructions !== undefined | |
| ? request.platformInstructions.trim() || undefined | |
| : request.gatewayGuidance?.text?.trim() || undefined; |
Railway Preview Environment
|
|
🧠 Learnings used
|
1 participant
Context
Agenta's SDK kept gateway guidance separate from author instructions, but its prompt text lived beside bundled skills and each adapter carried a delivery-choice wrapper. The SDK now gives every supported agent a short shared Agenta base from one module.
Changes
platform_instructions.pycomposes the base and existing gateway guidance. The SDK sends oneplatformInstructionsstring instead of{text, carrier}. The runner chooses its existing Pi append-system or Claude/Codex instruction-file path. Author instruction fields remain unchanged on the wire.This removes the SDK carrier helper and wrapper types. Generated guidance keeps the existing warm-session behavior. No instruction digests, database migrations, restart rules, Pi patches, or Codex developer-instruction changes.
Deploy the runner before the SDK. The runner accepts the old
gatewayGuidanceinput during rollout and prefers the new field when both appear.Tests
ecb28ea14b. Format/lint, Helm, security, and documentation checks also passed. The two web image builds remain in progress.How to review
Start with
platform_instructions.py, then the SDK adapters/wire model, then the small runner change inrun-plan.ts. The design docs describe the reduced scope and rollout order.