fix(compiler): thread actor-level system_prompt into graph node metadata #7

2026-05-22T03:54:00Z

hurui200320 commented

2026-05-22 03:54:00 +00:00

Summary

compile_actor() silently dropped the actor-level system_prompt field for type: graph actors. The CompiledActor contained no trace of it, forcing host applications to keep the raw ActorConfigSchema in scope as a workaround.

This fix applies three targeted additions across two files to close both the compilation gap and the runtime context gap.

Motivation

docs/reference/actors_schema.md explicitly documents system_prompt as "Default prompt for graph-level agents" — placing it in the same semantic category as provider and model: actor-level fields that serve as fallback defaults for all AGENT nodes. The compiler already threaded provider and model via setdefault; system_prompt was simply never added to the same pattern.

A second independent gap in Node._execute_agent() meant that even after fixing the compiler, the system_prompt value would not appear in the context dict passed to agent.process_message().

Changes

`src/cleveractors/actor/compiler.py`

_map_node() gains an actor_system_prompt: str | None = None parameter.
merged_meta.setdefault("system_prompt", actor_system_prompt) is applied inside the if node.type == NodeType.AGENT: block, after the existing provider/model calls. setdefault preserves any per-node override in config.system_prompt.
Post-review fix: The key is only set when actor_system_prompt is not None, so actors without a top-level system_prompt don't carry a "system_prompt": None entry in every AGENT node's metadata.
compile_actor() passes actor_system_prompt=config.system_prompt to _map_node().

`src/cleveractors/langgraph/nodes.py`

Node._execute_agent() extracts node_system_prompt from self.config.metadata.get("system_prompt") and injects it into the context dict before state.metadata is merged. This allows host agents to read context.get("system_prompt") without a direct reference to the raw ActorConfigSchema. Per-execution state.metadata["system_prompt"] overrides still take precedence.
Post-review fix: A defensive isinstance(raw, str) guard rejects non-string values (e.g. integer, list) that could be injected via manually constructed NodeConfig.
Post-review fix: "system_prompt" is added to ignore_keys to prevent agents from mutating it in the context dict and accidentally persisting the mutation into metadata_updates.

`docs/reference/actor_compiler.md`

Node Binding table updated: AGENT row now references a detailed "AGENT node defaults" subsection describing the system_prompt threading behavior.

`features/compiler_system_prompt.feature` + `features/steps/compiler_system_prompt_steps.py`

Ten BDD scenarios covering the full behavioral surface:

Actor-level system_prompt is threaded into each AGENT node's NodeConfig.metadata.
Per-node config.system_prompt takes precedence over the actor-level default (setdefault semantics).
agent.process_message() receives system_prompt in its context dict.
state.metadata["system_prompt"] overrides the compiled default at runtime.
state.metadata["system_prompt"] = None overrides a compiled default (clearing the prompt).
Empty-string system_prompt is threaded into AGENT node metadata.
Empty-string system_prompt is passed into the runtime context dict.
Non-AGENT nodes (TOOL, CONDITIONAL, SUBGRAPH) do not receive system_prompt in compiled metadata.
Actor without system_prompt does not add the key to AGENT node metadata (post-review: was "set to None").
Absent system_prompt is excluded from the runtime context dict.

Post-review additions

Step-definition file reorganized into functional sections (compilation assertions, runtime assertions). "Each AGENT node" step definitions include a guard against zero-AGENT-node graphs.

Quality Gates

Gate	Result
`nox -s lint`	✅ pass (0 issues)
`nox -s typecheck`	✅ pass (0 errors, 0 warnings)
`nox -s unit_tests`	✅ pass (17/17 scenarios)
`nox -s coverage_report`	✅ pass (≥ 97%)
`nox -s security_scan`	✅ pass (0 findings)
`nox -s dead_code`	✅ pass
`nox -s complexity`	✅ pass (avg complexity A)

Closes #6

## Summary `compile_actor()` silently dropped the actor-level `system_prompt` field for `type: graph` actors. The `CompiledActor` contained no trace of it, forcing host applications to keep the raw `ActorConfigSchema` in scope as a workaround. This fix applies three targeted additions across two files to close both the compilation gap and the runtime context gap. ## Motivation `docs/reference/actors_schema.md` explicitly documents `system_prompt` as _"Default prompt for graph-level agents"_ — placing it in the same semantic category as `provider` and `model`: actor-level fields that serve as fallback defaults for all AGENT nodes. The compiler already threaded `provider` and `model` via `setdefault`; `system_prompt` was simply never added to the same pattern. A second independent gap in `Node._execute_agent()` meant that even after fixing the compiler, the `system_prompt` value would not appear in the context dict passed to `agent.process_message()`. ## Changes ### `src/cleveractors/actor/compiler.py` - `_map_node()` gains an `actor_system_prompt: str | None = None` parameter. - `merged_meta.setdefault("system_prompt", actor_system_prompt)` is applied inside the `if node.type == NodeType.AGENT:` block, after the existing `provider`/`model` calls. `setdefault` preserves any per-node override in `config.system_prompt`. - **Post-review fix:** The key is only set when `actor_system_prompt is not None`, so actors without a top-level `system_prompt` don't carry a `"system_prompt": None` entry in every AGENT node's metadata. - `compile_actor()` passes `actor_system_prompt=config.system_prompt` to `_map_node()`. ### `src/cleveractors/langgraph/nodes.py` - `Node._execute_agent()` extracts `node_system_prompt` from `self.config.metadata.get("system_prompt")` and injects it into the context dict **before** `state.metadata` is merged. This allows host agents to read `context.get("system_prompt")` without a direct reference to the raw `ActorConfigSchema`. Per-execution `state.metadata["system_prompt"]` overrides still take precedence. - **Post-review fix:** A defensive `isinstance(raw, str)` guard rejects non-string values (e.g. integer, list) that could be injected via manually constructed `NodeConfig`. - **Post-review fix:** `"system_prompt"` is added to `ignore_keys` to prevent agents from mutating it in the context dict and accidentally persisting the mutation into `metadata_updates`. ### `docs/reference/actor_compiler.md` - Node Binding table updated: `AGENT` row now references a detailed "AGENT node defaults" subsection describing the `system_prompt` threading behavior. ### `features/compiler_system_prompt.feature` + `features/steps/compiler_system_prompt_steps.py` Ten BDD scenarios covering the full behavioral surface: 1. Actor-level `system_prompt` is threaded into each AGENT node's `NodeConfig.metadata`. 2. Per-node `config.system_prompt` takes precedence over the actor-level default (setdefault semantics). 3. `agent.process_message()` receives `system_prompt` in its context dict. 4. `state.metadata["system_prompt"]` overrides the compiled default at runtime. 5. `state.metadata["system_prompt"] = None` overrides a compiled default (clearing the prompt). 6. Empty-string `system_prompt` is threaded into AGENT node metadata. 7. Empty-string `system_prompt` is passed into the runtime context dict. 8. Non-AGENT nodes (TOOL, CONDITIONAL, SUBGRAPH) do **not** receive `system_prompt` in compiled metadata. 9. Actor without `system_prompt` does **not** add the key to AGENT node metadata (post-review: was "set to None"). 10. Absent `system_prompt` is excluded from the runtime context dict. ### Post-review additions Step-definition file reorganized into functional sections (compilation assertions, runtime assertions). "Each AGENT node" step definitions include a guard against zero-AGENT-node graphs. ## Quality Gates | Gate | Result | |------|--------| | `nox -s lint` | ✅ pass (0 issues) | | `nox -s typecheck` | ✅ pass (0 errors, 0 warnings) | | `nox -s unit_tests` | ✅ pass (17/17 scenarios) | | `nox -s coverage_report` | ✅ pass (≥ 97%) | | `nox -s security_scan` | ✅ pass (0 findings) | | `nox -s dead_code` | ✅ pass | | `nox -s complexity` | ✅ pass (avg complexity A) | Closes #6

hurui200320 added the

Type

Bug

label 2026-05-22 03:54:07 +00:00

hurui200320 added a new dependency 2026-05-22 03:56:22 +00:00

#6 compile_actor() drops graph-level system_prompt — not threaded into CompiledActor

hurui200320 force-pushed fix/compiler-thread-system-prompt from f4155e489d to a18e8c5931

2026-05-22 03:57:32 +00:00

Compare

hurui200320 force-pushed fix/compiler-thread-system-prompt from a18e8c5931 to bc01753113

2026-05-22 04:30:06 +00:00

Compare

hurui200320 force-pushed fix/compiler-thread-system-prompt from bc01753113 to 5aeadcc0aa

2026-05-22 05:18:18 +00:00

Compare

hurui200320 force-pushed fix/compiler-thread-system-prompt from 5aeadcc0aa to 61c8a6f48f

2026-05-22 05:22:23 +00:00

Compare

hurui200320 force-pushed fix/compiler-thread-system-prompt from 61c8a6f48f to dd6c20df5d

2026-05-22 06:05:27 +00:00

Compare

hurui200320 commented

2026-05-22 07:00:12 +00:00

Self-QA Review — Approved ✅

Ran 2 review/fix cycles. The PR is ready to merge.

Cycle 1 — Request Changes (0C / 3M / 5m / 2n)

All issues were addressed in the same cycle:

#	Severity	Issue	Fix
M1	Major	No test for empty-string `system_prompt` (compiler + runtime)	2 new BDD scenarios added
M2	Major	No test for `state.metadata = {"system_prompt": None}` runtime override	1 new BDD scenario added
M3	Major	CONDITIONAL and SUBGRAPH types untested (only TOOL was covered)	Mixed-graph scenario extended
m1	Minor	`setdefault(None)` unconditionally polluted AGENT node metadata shape	Guarded with `if actor_system_prompt is not None:`
m2	Minor	`metadata.get()` returned `Any`; no runtime type guard	Replaced with `isinstance(node_system_prompt, str)`
m3	Minor	`system_prompt` absent from `ignore_keys` — agent mutations leaked to state	Added `"system_prompt"` to `ignore_keys`
m4	Minor	`# Then steps for new scenarios` was a drafting artifact	Reorganized into functional sections
m5	Minor	"each AGENT node" loops tautologically passed on empty graphs	`agent_nodes_found > 0` guard added
n1	Nit	AGENT doc table row was too dense	De-densified + new subsection added

After fixes: 17/17 scenarios, all 7 quality gates ✅

Cycle 2 — Approve (0C / 0M / 3m / 3n)

No further fixes applied. Remaining items are non-blocking:

#	Severity	Issue
m1	Minor	No test for non-string non-None `system_prompt` in node metadata
m2	Minor	No explicit test that `ignore_keys` exclusion works
m3	Minor	No scenario for actor-None + per-node `system_prompt` override combination
n1	Nit	Commit message body references stale scenario counts and guard semantics
n2	Nit	`_CapturingAgent` uses shallow `dict()` copy instead of `deepcopy`
n3	Nit	Gherkin step pattern fragile for quoted `"None"` edge case

These can be addressed in a follow-up ticket if desired.

Quality Gates (final)

Gate	Status
`nox -s lint`	✅ Pass
`nox -s typecheck`	✅ Pass (0 errors)
`nox -s unit_tests`	✅ Pass (17/17)
`nox -s coverage_report`	✅ Pass (≥ 97%)
`nox -s security_scan`	✅ Pass (0 findings)
`nox -s dead_code`	✅ Pass
`nox -s complexity`	✅ Pass (avg A)

## Self-QA Review — Approved ✅ Ran 2 review/fix cycles. The PR is ready to merge. ### Cycle 1 — Request Changes (0C / 3M / 5m / 2n) All issues were addressed in the same cycle: | # | Severity | Issue | Fix | |---|----------|-------|-----| | M1 | Major | No test for empty-string `system_prompt` (compiler + runtime) | 2 new BDD scenarios added | | M2 | Major | No test for `state.metadata = {"system_prompt": None}` runtime override | 1 new BDD scenario added | | M3 | Major | CONDITIONAL and SUBGRAPH types untested (only TOOL was covered) | Mixed-graph scenario extended | | m1 | Minor | `setdefault(None)` unconditionally polluted AGENT node metadata shape | Guarded with `if actor_system_prompt is not None:` | | m2 | Minor | `metadata.get()` returned `Any`; no runtime type guard | Replaced with `isinstance(node_system_prompt, str)` | | m3 | Minor | `system_prompt` absent from `ignore_keys` — agent mutations leaked to state | Added `"system_prompt"` to `ignore_keys` | | m4 | Minor | `# Then steps for new scenarios` was a drafting artifact | Reorganized into functional sections | | m5 | Minor | "each AGENT node" loops tautologically passed on empty graphs | `agent_nodes_found > 0` guard added | | n1 | Nit | AGENT doc table row was too dense | De-densified + new subsection added | After fixes: **17/17 scenarios**, all 7 quality gates ✅ ### Cycle 2 — Approve (0C / 0M / 3m / 3n) No further fixes applied. Remaining items are non-blocking: | # | Severity | Issue | |---|----------|-------| | m1 | Minor | No test for non-string non-None `system_prompt` in node metadata | | m2 | Minor | No explicit test that `ignore_keys` exclusion works | | m3 | Minor | No scenario for actor-None + per-node `system_prompt` override combination | | n1 | Nit | Commit message body references stale scenario counts and guard semantics | | n2 | Nit | `_CapturingAgent` uses shallow `dict()` copy instead of `deepcopy` | | n3 | Nit | Gherkin step pattern fragile for quoted `"None"` edge case | These can be addressed in a follow-up ticket if desired. ### Quality Gates (final) | Gate | Status | |------|--------| | `nox -s lint` | ✅ Pass | | `nox -s typecheck` | ✅ Pass (0 errors) | | `nox -s unit_tests` | ✅ Pass (17/17) | | `nox -s coverage_report` | ✅ Pass (≥ 97%) | | `nox -s security_scan` | ✅ Pass (0 findings) | | `nox -s dead_code` | ✅ Pass | | `nox -s complexity` | ✅ Pass (avg A) |

hurui200320 merged commit dd6c20df5d into master

2026-05-22 07:08:20 +00:00

hurui200320 deleted branch fix/compiler-thread-system-prompt

2026-05-22 07:08:20 +00:00

CoreRasurae referenced this pull request

2026-06-08 23:13:51 +00:00

feat(registry): extend TemplateType and integrate PackageReference into template system #35

CoreRasurae referenced this pull request

2026-06-09 10:36:52 +00:00

feat(registry): extend TemplateType and integrate PackageReference into template system #35

CoreRasurae referenced this pull request

2026-06-09 20:19:55 +00:00