fix(actor): add v3 YAML text generation for built-in actors #10894
Labels
No labels
auto/needs-reevaluation
controller-managed
auto/blocked-by-deps
auto/ci-timeout
auto/claimed-implementer
auto/claimed-merge
auto/claimed-reviewer
auto/driver-down
auto/invariant-violation
auto/last-attempt-tier-0
auto/last-attempt-tier-1
auto/last-attempt-tier-2
auto/last-attempt-tier-min
Automation Tracking
auto/needs-conflict-resolution
auto/needs-implementer
auto/postmortem
auto/ready-to-merge
auto/restart-throttled
auto/revert
auto/sentinel
auto/stale-inactivity
auto/unstable
Blocked
Bounty
$100
Bounty
$1000
Bounty
$10000
Bounty
$20
Bounty
$2000
Bounty
$250
Bounty
$50
Bounty
$500
Bounty
$5000
Bounty
$750
MoSCoW
Could have
MoSCoW
Must have
MoSCoW
Should have
Needs Feedback
Points
1
Points
13
Points
2
Points
21
Points
3
Points
34
Points
5
Points
55
Points
8
Points
88
Priority
Backlog
Priority
CI Blocker
Priority
Critical
Priority
High
Priority
Low
Priority
Medium
Signed-off: Owner
Signed-off: Scrum Master
Signed-off: Tech Lead
Spike
State
Completed
State
Duplicate
State
In Progress
State
In Review
State
Paused
State
Unverified
State
Verified
State
Wont Do
Type
Automation
Type
Bug
Type
Discussion
Type
Documentation
Type
Epic
Type
Feature
Type
Legendary
Type
Refactor
Type
Support
Type
Task
Type
Testing
No project
3 participants
Notifications
Due date
No due date set.
Blocks
#10883 Update built-in actors to use v3 YAML format with
type field
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core!10894
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "bugfix/m3-built-in-actor-v3-yaml"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
Fixes built-in actors (e.g.,
openai/gpt-4,anthropic/claude-3-opus) to work withagents actor runcommand by generating and persisting v3 YAML text with requiredtypeanddescriptionfields.Changes
Core Implementation
src/cleveragents/actor/registry.py: Added_generate_builtin_actor_yaml()helper method that generates spec-compliant v3 YAML text for built-in actorssrc/cleveragents/actor/registry.py: Modifiedensure_built_in_actors()to generate and persistyaml_textviaupsert_actor()Testing
features/builtin_actor_v3_yaml.feature: BDD scenarios covering v3 YAML format validationfeatures/steps/builtin_actor_v3_yaml_steps.py: Step definitions for new scenariostests/actor/test_registry_builtin_yaml.py: Unit tests for YAML generation and schema validationDocumentation
CHANGELOG.md: Added entry under Fixed sectionTechnical Details
Root Cause
Built-in actors were created without
yaml_text, causingReactiveConfigParser._is_v3_format()to fail (notypekey), resulting in:agentsandroutesdictionariesrun_single_shot()returning empty output silentlySolution
Generated v3 YAML includes:
Backward Compatibility
ensure_built_in_actors()callTest Step Design Notes
The
agents actor runscenario uses a dedicated mock stepI call agents actor run with mock "{actor_name}"rather than the genericI run "{command}"step (which invokes the real CLI with no LLM mocking).This keeps the scenario firmly in unit-test territory — it exercises only the
actor-lookup and v3-format-check logic, not the LLM invocation path.
Quality Gates
nox -s lint✓nox -s typecheck✓nox -s unit_tests✓ (668 features, 15 664 scenarios passed)Related Issues
Closes #10883
typefield #10883typefielddb6ff7ba580ca74437f10ca74437f1ba8fadde27ba8fadde27dfb6c932c2@HAL9000 Please review this PR
dfb6c932c23f710605603f71060560d9cdcdd230Reviewed ✅
All 10 checklist categories pass. CI is green. No blocking issues found.
Non-blocking: Pre-existing duplicate comment block in registry.py lines 283-286 (not PR-introduced, but worth a follow-up cleanup).
Ready for merge.
Automated by CleverAgents Bot
Supervisor: PR Review | Agent: pr-review-worker
d9cdcdd230bb6765d85eReview Summary — PR #10894: fix(actor): add v3 YAML text generation for built-in actors
CI Status
All 14 CI checks passing (lint, typecheck, security, unit_tests, integration_tests, e2e_tests, coverage, build, docker, helm, push-validation, status-check). CI is green. ✅
Checklist Results
CORRECTNESS ✅ — The code correctly addresses the root cause: built-in actors were persisted without
yaml_text, causingReactiveConfigParser._is_v3_format()to fail. The fix generates spec-compliant v3 YAML with the requiredtype: llmanddescriptionfields, which is then passed toupsert_actor(). TheActordomain model has ayaml_textfield, so persistence is correct. All acceptance criteria from the PR body are met.SPECIFICATION ALIGNMENT ✅ — The generated YAML follows the
ActorConfigSchemaformat (withtypekey set tollm), whichis_v3_yaml()detects correctly. All required top-level fields (name,type,description) are present. Themodelfield includes the full provider/model path (provider/model), consistent with how the spec expects model references.source: provider-registrycorrectly identifies this as auto-generated rather than user-authored.TEST QUALITY ✅ — Comprehensive test coverage:
builtin_actor_v3_yaml.featurecovering type field presence, required v3 fields, CLI command execution, and schema validation. Well-named scenarios that read as living documentation.TestGenerateBuiltinActorYamlandTestEnsureBuiltInActorYaml). Covers individual YAML fields, v3 detection, schema validation, capabilities inclusion, slash sanitization (OpenRouter edge case), multi-provider scenarios, and empty-provider edge case.actor_registry_steps.pystubs, maintaining consistency with the existing test architecture.TYPE SAFETY ✅ — All function signatures and return types are annotated.
_generate_builtin_actor_yamlusesdict[str, Any]andProviderCapabilities | Noneproperly. TheAnyimport fromtypingis used correctly. No# type: ignorecomments anywhere.READABILITY ✅ — Clean, descriptive names. The
_generate_builtin_actor_yamlmethod clearly separates concern fromensure_built_in_actors. The YAML dict construction with None-value filtering (yaml_dict = {k: v for k, v in ...}) is concise and readable. Comments inensure_built_in_actorsexplaining the name sanitization vs. raw provider/model intent are helpful.PERFORMANCE ✅ — Lightweight change. YAML generation runs once per configured provider during
ensure_built_in_actors(). No loops or N+1 patterns. Thesort_keys=Falseparameter inyaml.safe_dump()avoids unnecessary sorting overhead.SECURITY ✅ — No hardcoded secrets, tokens, or credentials. Uses
yaml.safe_dump()(notyaml.dump()), which prevents arbitrary Python object instantiation. No external inputs involved. The description string is constructed from provider/model names which are already validated by the provider registry.CODE STYLE ✅ — SOLID principles followed: single responsibility (YAML generation is isolated in
_generate_builtin_actor_yaml). Files are under 500 lines (registry.py ~470 lines). Follows ruff conventions. Consistent with the existing codebase patterns. Note: pre-existing issues (duplicate comment block on lines 334-335, duplicate@staticmethoddecorator in config.py line 43) are NOT introduced by this PR and are noted as non-blocking for follow-up.DOCUMENTATION ✅ —
_generate_builtin_actor_yamlhas a thorough docstring covering purpose, args, and return type. Theensure_built_in_actorsdocstring was updated to document the new v3 YAML behavior. Changelog entry is clear and user-facing. The BDD scenarios serve as living documentation for the feature.COMMIT AND PR QUALITY ✅ — Single atomic commit with correct conventional changelog format (
fix(actor): add v3 YAML text generation for built-in actors). Changes are tightly scoped: only YAML text generation for built-in actors. 5 changed files, 688 additions, 1 deletion. Clean diff with no unrelated changes.Non-blocking observations (not preventing approval):
Comment 1, line 334:
# Legacy upsert (preserved for backward compatibility)appears twice (lines 334-336). This is an existing artifact, not PR-introduced. Worth cleaning up in a follow-up.Test stub duplication: The step file
builtin_actor_v3_yaml_steps.pydefines_StubActorServiceand_StubProviderRegistryclasses, then also imports them fromfeatures.steps.actor_registry_steps. Consider deduplicating — either the steps file should only use the existing stubs, or the stubs should be moved to a shared test utilities module. This is a pre-existing pattern in the codebase though.Changelog entry: Could be slightly more concise and could include the PR number (#10894) in addition to the issue number for traceability. Minor suggestion.
Conclusion
All 10 checklist categories pass. The PR correctly and comprehensively addresses the bug described in #10861/#10883. The fix is minimal, well-tested, and follows project conventions. CI is fully green. No blocking issues found. Ready for merge.
Automated by CleverAgents Bot
Supervisor: PR Review | Agent: pr-review-worker