feat(agents): add versioned soul prompts across AI and built-in runtimes - #598
Sertaç Özercan (sozercan) wants to merge 18 commits into
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5ddf63d8fe
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Two critical and one moderate unresolved findings must be addressed before approval.
Get a fresh assessment by requesting another Copilot review.
Review tier: Lite (auto)
Findings: 2
Note
Copilot is running an experiment and ran this review at Lite.
Open (2)
What changed in this PR
Adds versioned Agent.spec.soul persona context for AI Tasks and built-in ACP runtimes, including pinned sources, native runtime delivery, session protection, tooling, UI, manifests, tests, and documentation.
Changes:
- Supports inline or SHA-256-pinned ConfigMap soul sources.
- Projects composed personas through supported runtime mechanisms.
- Adds persistence, revision binding, management tools, UI, CRDs, and documentation.
Outstanding findings include two critical issues and one moderate schema issue requiring changes.
| File | Reviewed changes |
|---|---|
workers/acp/supervisor/soul_projection_test.go |
Tests runtime soul projection. |
workers/acp/supervisor/server.go |
Creates protected instruction files. |
workers/acp/supervisor/prompt_handlers.go |
Restores instruction protections before resume. |
workers/acp/supervisor/opencode_env_test.go |
Tests OpenCode environment projection. |
workers/acp/supervisor/env.go |
Adds runtime projections; Critical (3 votes): Copilot’s --no-custom-instructions disables the projected soul. |
workers/acp/supervisor/env_test.go |
Tests runtime environment behavior. |
workers/acp/supervisor/config.go |
Defines projection configuration. |
website/sidebars.js |
Adds soul documentation navigation. |
website/docs/reference/configuration.md |
Documents soul configuration. |
website/docs/reference/api-reference.md |
Documents soul management arguments. |
website/docs/concepts/soul.md |
Documents soul semantics and lifecycle. |
website/docs/concepts/agent-runtimes.md |
Documents runtime persona delivery. |
ui/src/schemas/agent.ts |
Adds UI soul validation. |
ui/src/schemas/agent.test.ts |
Tests UI soul validation. |
ui/src/components/agents/agent-detail.tsx |
Displays soul configuration. |
ui/src/components/agents/agent-create-form.tsx |
Adds soul creation controls. |
ui/src/components/agents/agent-create-form.test.tsx |
Tests soul creation controls. |
manifest_staging/charts/orka/crds/task-customresourcedefinition.yaml |
Updates staged Task CRD. |
manifest_staging/charts/orka/crds/agent-customresourcedefinition.yaml |
Updates staged Agent CRD. |
internal/tools/update_agent.go |
Supports soul updates. |
internal/tools/update_agent_test.go |
Tests agent updates. |
internal/tools/soul.go |
Adds soul tooling schema; Moderate (1 vote): oneOf accepts inline and ConfigMap sources without a digest. |
internal/tools/soul_update_test.go |
Tests soul updates. |
internal/tools/create_agent.go |
Supports soul creation. |
internal/tools/create_agent_test.go |
Tests agent creation. |
internal/tools/chat_create_agent.go |
Adds soul support to chat creation. |
internal/tools/chat_create_agent_test.go |
Tests chat agent creation. |
internal/store/store.go |
Integrates soul persistence with storage. |
internal/store/sqlite/session_store.go |
Stores session data with soul handling. |
internal/store/sqlite/session_soul.go |
Persists soul session identity. |
internal/store/sqlite/session_soul_test.go |
Tests soul retention. |
internal/store/sqlite/gateway_store.go |
Stores gateway soul anchors. |
internal/store/sqlite/gateway_session_cleanup.go |
Cleans up gateway session anchors. |
internal/store/soul_types.go |
Defines soul session contracts. |
internal/store/kube/session_control.go |
Integrates soul session control. |
internal/gateway/service.go |
Handles gateway soul metadata. |
internal/controller/task_controller.go |
Integrates souls into task execution. |
internal/controller/session_manager.go |
Manages soul session metadata. |
internal/controller/opencode_runtime_validation.go |
Validates OpenCode soul runtime behavior. |
internal/controller/job_builder.go |
Delivers literal-safe AI prompts. |
internal/controller/ai_soul.go |
Pins AI task soul identity. |
internal/controller/ai_soul_test.go |
Tests AI soul binding. |
internal/controller/agent_controller.go |
Validates soul configuration during reconciliation. |
internal/controller/agent_controller_unit_test.go |
Tests agent reconciliation. |
internal/controller/acp_soul_session_test.go |
Tests ACP soul sessions. |
internal/controller/acp_dispatcher.go |
Integrates soul-aware ACP dispatch. |
internal/controller/acp_dispatcher_session.go |
Handles ACP session soul state. |
internal/controller/acp_agent_configuration.go |
Composes role and soul prompts; Critical (1 vote): session lineage omits the frozen Agent or composed-prompt revision. |
internal/controller/acp_agent_configuration_test.go |
Tests ACP agent configuration. |
internal/api/anthropic_tool_loop.go |
Integrates soul context with the tool loop. |
internal/api/anthropic_tool_loop_test.go |
Tests tool-loop soul behavior. |
internal/agentcontext/soul.go |
Resolves, validates, composes, and digests souls. |
internal/agentcontext/soul_test.go |
Tests soul resolution and validation. |
internal/admission/execution_mode.go |
Applies execution-mode soul restrictions. |
internal/admission/execution_mode_test.go |
Tests execution-mode restrictions. |
internal/acp/instruction_projection.go |
Protects native instruction files. |
internal/acp/instruction_projection_linux_test.go |
Tests Linux file protection. |
config/crd/bases/core.orka.ai_tasks.yaml |
Updates the Task CRD schema. |
config/crd/bases/core.orka.ai_agents.yaml |
Updates the Agent CRD schema. |
api/v1alpha1/zz_generated.deepcopy.go |
Updates generated deepcopy support. |
api/v1alpha1/task_types.go |
Adds task soul binding fields. |
api/v1alpha1/agent_types.go |
Adds Agent soul configuration types. |
Files not reviewed (1)
- api/v1alpha1/zz_generated.deepcopy.go: Generated file
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Copilot’s projected instructions remain disabled by --no-custom-instructions, so the feature is not delivered as intended.
Review tier: Lite (auto)
Findings: None
Note
Copilot is running an experiment and ran this review at Lite.
Resolved since last review (2)
Files not reviewed (1)
- api/v1alpha1/zz_generated.deepcopy.go: Generated file
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c29d1147f4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Three unresolved moderate findings must be addressed before approval.
Review tier: Lite (auto)
Findings: None
Note
Copilot is running an experiment and ran this review at Lite.
Files not reviewed (1)
- api/v1alpha1/zz_generated.deepcopy.go: Generated file
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a78bc88fa9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Four moderate findings remain unresolved in runtime validation, CRD source exclusivity, harness-v1 handling, and Copilot instruction delivery.
Review tier: Lite (auto)
Findings: None
Note
Copilot is running an experiment and ran this review at Lite.
Files not reviewed (1)
- api/v1alpha1/zz_generated.deepcopy.go: Generated file
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1495c0b05a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Four moderate findings remain unresolved and require fixes before approval.
Review tier: Lite (auto)
Findings: None
Note
Copilot is running an experiment and ran this review at Lite.
Files not reviewed (1)
- api/v1alpha1/zz_generated.deepcopy.go: Generated file
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
|
Live kind validation is complete for the scoped soul feature, including the cleanup regression fixed in 4cebf2e.
Limits: native AI needed that temporary direct-Provider ingress exception. One Claude acknowledgment omitted the style marker; later continuation/workspace/restart checks included it. Claude workspace reading needed a bounded 12-request retry with an explicit filename after exhausting the initial eight-request budget. Persona is guidance, not behavioral enforcement. No GitHub publication/PR reconciliation or external-workspace-provider live test was performed. The final fix passed full Go tests, full-PR lint, the Gateway subagent review, and integrated P0–P2 autoreview. No credentials or raw transcripts are included in this report. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4cebf2ec79
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
Omitted-contract v2 validation still fails in three paths, and Copilot disables the projected instruction file.
Review effort: Lite (auto)
Findings: None
Note
Copilot is running an experiment and ran this review at Lite.
Files not reviewed (1)
- api/v1alpha1/zz_generated.deepcopy.go: Generated file
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fee8def62b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 201e3b20a2
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".
Signed-off-by: Sertac Ozercan <sozercan@gmail.com>
SOUL follow-up validation — September 17, 2026Final candidate: The follow-up fixes cover positive native boot-retirement evidence, fenced abandoned-validation cleanup, SOUL/task-output precedence, strict verification of Kubernetes-reordered preparation JSON, effective built-in contract resolution before SOUL validation, and Copilot inline import-marker validation in the create UI. Qualified results, not an all-green live release gate:
Execution attribution: formats/Pod loss used Local verification: UI lint and 1,133 tests / 126 files passed with bounded concurrency; the first unconstrained run had one unchanged monitor-test timeout, which passed in focused/full reruns without changing timeouts. Latest Go suite passed controller tests and 90 package result lines but unqualified host Cleanup: test PRs 38–43 closed without merging, seven existing owned branches deleted (two Copilot planned refs were already absent), and test-repo main remains CI is still running; this comment does not certify merge-readiness. Detailed redacted local evidence is consolidated in |
There was a problem hiding this comment.
Copilot review overview
🔵 Needs a closer look
A critical RuntimePool deletion-recovery issue remains unresolved, and the cross-cutting lifecycle changes require final human review.
Review effort: Lite (auto)
Findings: 1
Note
Copilot is running an experiment and ran this review at Lite.
Open (1)
Files not reviewed (1)
- api/v1alpha1/zz_generated.deepcopy.go: Generated file
Summary
Add OpenClaw-inspired, versioned persona context through
Agent.spec.soulfor nativetype: aiTasks and every built-in harness-v2 runtime: Codex, Claude, Copilot, and OpenCode.website/docs/concepts/soul.md.Semantics and compatibility
This deliberately adapts the SOUL.md concept to Orka's control-plane model; it does not discover repository
SOUL.mdfiles or introduce an automatic self-editing loop. Persona text is not a permissions or human-approval enforcement boundary.Soul configuration is supported for AI workers and built-in harness v2, not external
runtimeRefprofiles. Copilot conservatively rejects@in composed instructions to prevent unpinned native file imports.Review follow-ups
Reject unsupported soul updates before persistence using shared controller/tool runtime validation.
Reconcile Agent readiness when referenced soul ConfigMaps change, appear, disappear, or are recreated.
Reject introducing the first soul after an AI Task has started, including stale-read retry paths.
Expose role instructions for all built-in runtime forms while keeping external runtimeRef profiles authoritative.
Verified and documented the pinned Copilot ACP delivery and existing transitive ACP lineage hashing; no speculative transport or lineage changes were made.
Validate both creation paths after installation-mode defaulting and enforce schema-level source exclusivity.
Validate composed Copilot instructions at readiness, including role ConfigMap dependency changes.
Retry operational AI preparation failures without consuming attempts, including interrupted/ambiguously acknowledged binding writes.
Pin ordinary soul-enabled Session revision metadata transactionally under the exact Task lock before Job creation, keeping identity durable through empty turns and later transcript failures without a new schema/store.
Validate default role/composed instructions using the actual AI, ACP, and native transport limits, including role-only Copilot and ConfigMap readiness recovery.
Pin explicit no-soul identity before ordinary AI Session execution, including empty/non-appended turns, using the existing hidden anchor and lock fences.
State UTF-8 byte limits accurately in tool schemas and test multibyte boundaries without reducing valid ASCII capacity.
Preserve immutable AI soul bindings during deletion-generation changes so authorized finalizer cleanup can complete; distinguish attested unbound Gateway startup errors from intentional no-soul history.
Verification
make manifests generateandmake lint-fix: passed; zero lint issues. Full PR lint also passed with CI's exact--new-from-rev=1528232cd0dd6261ad2d6917e3ae83184ea3276fscope.Full
make test: 87 packages passed, using a private Node executable-path mount and test-only Git configuration isolation for this workstation.UI lint passed;
bun run test --maxWorkers=2: 126 files / 1,131 tests passed.Independent architecture and adversarial subagent reviews: no outstanding actionable findings.
Automated feature and integrated follow-up reviews: scoped-clean at P0–P2. Native Copilot/OpenCode instruction-delivery review evidence was also checked.
CI follow-up: the stale OpenCode system-prompt rejection expectation was corrected and independently reviewed. The full live static-mode CRD validation passed on CI's pinned Kubernetes 1.33.7 image in a worktree-scoped kindctl cluster, which was then deleted.
Scoped live kind/Vekil validation passed for native AI and all four built-in harness-v2 runtimes, including Session continuity across controller restart, pinned workspace reads, guardrails, cancellation, pool replacement, and normal cleanup after the admission fix. See the validation comment for setup details and limits; GitHub publication/PR reconciliation and external workspace-provider E2E were not run.