refactor(agent-registry): use semantic agent identifiers

[seonghobae]

Current exact-head security integration (2026-09-30)

This section supersedes the older exact-identity and queued-state notes below.

• Exact published head: c5b6c926bc2937a87aa12e24e8178705ca66cc89 (tree ae855b5364a3d784f324401e579de0dd1d1fb8f2).
• Ordinary two-parent integration preserves this PR's agent-registry delta (71ea032006665ebb63f0b5616b764e63d63a897f) and carries canonical security owner naruon#1828@e725203385a6381040b22231281fc63d9ed09f62; no force-push or rebase was used.
• Exact rerun Security Scan 33841625646, job 109906894968, proved the predecessor head's Trivy failure: ten PyJWT 2.13.0 findings, three AnyIO findings, two oauthlib findings, two Next.js findings, and one Sharp finding. fix(security): repair shared dependency scan failures #1828 advances the shared manifests/locks to PyJWT 2.14.0, AnyIO 4.15.1, oauthlib 4.0.0, Next.js 16.3.6, and Sharp 0.35.4, plus the Starlette/HTTPX2 warning-clean boundary and disjoint lock-ownership contract.
• Combined-tree verification: backend 1,816 passed, 33 skipped under warnings-as-errors with inherited proxy variables removed; frontend 437 passed; focused registry/dependency contracts 14 passed; Ruff, installed-package compatibility, ESLint, TypeScript, and the production build passed. A first backend run exposed the execution sandbox's injected SOCKS proxy without optional socksio; the exact failing test passed when only those external proxy variables were removed. No source or gate was changed for that environment condition.
• The PR remains Draft. New exact-head hosted checks, a non-skipped authoritative dependency review, and qualifying independent current-head review are still required; queued/skipped/pending results are not passing.

Owner and reuse boundary

ContextualWisdomLab/naruon owns the workspace agent registry consumed by task-to-agent resolution and Noema integration. Canonical organization-owned vocabulary is semantic: agent_name, agent_framework, agent_entrypoint, agent_description, agent_capabilities, agent_enabled, and raw_entry. Historical generic names remain only at bounded compatibility surfaces.

TDD / current repair lineage

• Initial RED 53c6f80db9b185e3038ac8302ba4d3be9d31d36c required the semantic registry vocabulary.
• Review-driven REDs subsequently covered legacy raw-key reads, mutable raw metadata persistence, real-dict behavior, retained-reference coherence, direct semantic/legacy synchronization, legacy keyword construction, and dataclasses.asdict() traversal.
• Production repair c65c3c2db6398ce771e52c2e464f95c3f0961c00 keeps RegisteredAgent a frozen dataclass with semantic dataclass fields, supplies a bounded custom constructor accepting historical name/framework/entrypoint/description/capabilities/enabled/raw keywords, fails closed when legacy and semantic forms disagree, and keeps _legacy_raw_dict outside dataclass field traversal while preserving the retained synchronized dictionary pair.
• Current test-quality repair 71ea032006665ebb63f0b5616b764e63d63a897f removes mutation side effects from assertion expressions, separates setdefault/pop/popitem operations from assertions, and normalizes services.agent_registry imports to one style. Production semantics are unchanged.
• Existing registry loading continues to use semantic construction. No database schema, provider credential, network authority, writeback behavior, or task mapping changes.

Compatibility boundary

Historical JSON keys are accepted on ingress and canonicalized into semantic raw_entry. Historical Python scalar properties and the real mutable raw dictionary remain available as compatibility adapters. raw and raw_entry remain shallow synchronized mappings; frozen typed fields retain load-time values. The constructor accepts either vocabulary but rejects contradictory dual specification.

The pickle note is informational rather than an established product defect: repository search found no RegisteredAgent pickle/persistence consumer contract, so this PR does not invent an unsupported persisted-object format. A future real persisted-object consumer requires an explicit compatibility contract and RED regression before source changes.

DDD / documentation

docs/doctoring/agent-registry-semantic-identifiers.md records the Workspace Agent Registry bounded context, RegisteredAgent aggregate, anti-corruption boundary, stable-reference compatibility invariant, and APA 7 traceability.

Exact identity

• protected base: develop@042b0c70531b229af3acbd0421a2f23098d848b3
• branch: fix/agent-registry-semantic-identifiers
• exact current head: 71ea032006665ebb63f0b5616b764e63d63a897f
• lifecycle: Draft / mechanically mergeable at the latest fresh refetch; mechanical mergeability is not merge authorization.

The PR was returned from Ready to Draft on 2026-09-04 after a fresh exact-head sweep found live non-passing governance evidence and unresolved current-head review findings. This is a lifecycle repair, not a source rollback.

Current-head review state

The three GitHub Code Quality source findings on predecessor head c65c3c2... were repaired by direct child 71ea032..., replied to with exact-head evidence, and resolved. The source delta is bounded to backend/tests/test_agent_registry.py: predecessor→current is one commit, one file, +17/-14.

One Devin analysis thread remains open intentionally: its review environment lacked pytest, so hosted verification must prove the focused compatibility suite on the new exact head before that analysis is closed.

Noema's APPROVED review was submitted for predecessor head c65c3c2db6398ce771e52c2e464f95c3f0961c00. Because the test repair advanced the head, that approval is now predecessor evidence and is not transferred to 71ea032006665ebb63f0b5616b764e63d63a897f.

Current-head verification state

Fresh repository-owned workflow runs were created for exact head 71ea032006665ebb63f0b5616b764e63d63a897f. At the latest refetch, Application CI, Security Scan, Dependency Review, SAST Semgrep, Bandit Security Scan, and Build and Publish Docker Images are all queued. No predecessor GREEN is promoted to this head.

Protected develop remains 042b0c70531b229af3acbd0421a2f23098d848b3 and currently requires, among other contexts, backend (Python 3.14), frontend, security, CodeQL analyses, required-workflow-bootstrap, scorecard, osv-scan, trivy-fs, strix, coverage-source-tree, coverage-evidence, image validations, opencode-review, and authoritative dependency review.

On predecessor head c65c3c2..., the latest Strix and OpenCode review checks were cancelled. Those results neither prove a Naruon source defect nor authorize a bypass; the new exact head requires fresh central owner verdicts.

Merge boundary

Queued, in-progress, cancelled, neutral, absent, stale, predecessor, model-only, status-only and author-only evidence is non-passing. Merge only if the unchanged then-current exact head satisfies every live required repository/organization check, all valid findings/threads are resolved, and any qualifying independent non-author approval required by live governance is current after the latest push. No force-push, destructive rebase, self-approval, bypass, gate weakening, or predecessor evidence transfer.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 1111f7b8-2073-4556-bd99-ae7389b192ca

📥 Commits

Reviewing files that changed from the base of the PR and between 042b0c7 and 4df9db7.

📒 Files selected for processing (4)

• backend/services/agent_registry.py
• backend/tests/test_agent_registry.py
• docs/doctoring/agent-registry-semantic-identifiers.md
• registered_agents.json

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The agent registry now uses agent_* fields and raw_entry as its canonical contract. It accepts legacy catalog keys, preserves legacy Python properties and raw mappings, updates task resolution, and adds focused tests and documentation.

Changes

Agent Registry Semantic Identifier Migration

Layer / File(s)	Summary
Canonical registry contract backend/services/agent_registry.py, registered_agents.json	RegisteredAgent now stores semantic fields. Registry helpers translate between semantic and legacy keys. The catalog uses semantic keys.
Loading and task resolution backend/services/agent_registry.py	Agent loading accepts semantic-first entries with legacy fallbacks and stores canonical raw_entry data. Task resolution checks agent_enabled.
Compatibility validation and documentation backend/tests/test_agent_registry.py, docs/doctoring/agent-registry-semantic-identifiers.md	Tests cover semantic fields, legacy properties, and raw mappings. Documentation records the identifier contract and compatibility boundary.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to 4df9d

This PR renames agent registry fields while preserving historical JSON and Python access patterns through compatibility adapters, without changing task mapping or execution authority. No actionable merge-blocking risk remains after normal checks and review.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: refactoring the agent registry to use semantic agent identifiers.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/agent-registry-semantic-identifiers

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[devin-ai-integration]

Devin Review found 4 new potential issues.

[devin-ai-integration]

🔍 Focused verification remains unavailable

The required registry test suite could not run because pytest is absent. Exact-head CI must verify the expanded compatibility surface.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[github-actions]

PR governance metadata gate is not ready for c65c3c2db6398ce771e52c2e464f95c3f0961c00:

• 4 unresolved current review thread(s) remain.
• Required check strix is CANCELLED on the current head.
• Current-head CodeRabbit review comment has blocking warning/failure evidence on c65c3c2.

[seonghobae]

Exact-head RCA update for c65c3c2db6398ce771e52c2e464f95c3f0961c00:

• Required Noema Review run 33540025141, job 99963686917 is a real current-head terminal failure.
• Checkout/trusted-source resolution, repository-scoped cwl-noema-review token minting, live-head validation, target visibility lookup, and contextual-orchestrator sidecar provisioning all succeeded.
• The sidecar explicitly routed through orchestrator/free; its gateway preflight reached a usable free pool. Provider-route timeouts/404s and a Bytez discovery warning were tolerated by the pool and were not the terminal cause.
• The model phase failed closed with Noema approve cannot contain a confirmed adversarial probe. Central scripts/ci/noema_review_gate.py intentionally rejects an approve decision whenever adversarial_validation contains a confirmed probe. The unpublished contradictory envelope therefore cannot be treated as approval, and the underlying probe cannot be presumed cleared merely because publication failed.
• Classification: model-output/control-contract inconsistency handled by the central fail-closed gate, not established Naruon product/test, checkout, permission, or routing failure. No source/gate change is justified from this evidence.
• I re-ran only the failed exact-head Noema job without changing the branch. Successor job 100143353861 is currently queued and is non-passing until terminal. If it produces REQUEST_CHANGES, the finding must be investigated as substantive; if it fails again, the new exact envelope/diagnostic should be used for central-owner RCA rather than weakening the validator.

No predecessor evidence is transferred, and no queued/cancelled/skipped state is being counted as success.

[seonghobae]

@cwl-noema-review review

Re-review the unchanged exact head c65c3c2db6398ce771e52c2e464f95c3f0961c00 against the current protected develop base. Use the existing central review path and ContextualWisdomLab/contextual-orchestrator orchestrator/free pool. The predecessor required-workflow run was created at 2026-09-01T17:49:27Z and therefore used central .github@4ae90e18b03a3a455e13e501628010cabc5c37a8, before merged .github#1617 added typed/bounded malformed-verdict repair. Produce fresh exact-head evidence under the current central source; do not transfer the predecessor failure/review, change the branch, merge, self-approve, weaken a gate, or treat non-terminal evidence as passing.

[cwl-noema-review]

Noema LLM review

The refactor successfully transitions the agent registry to semantic identifiers while maintaining a robust, bidirectional compatibility layer for legacy consumers. The implementation of _SemanticRawDict and _LegacyRawDict ensures that mutations to either the semantic raw_entry or the legacy raw property are synchronized, preserving reference identity and JSON serializability. All previously identified regressions (constructor compatibility, dataclass serialization, and mutation synchronization) have been addressed and verified by the expanded test suite in backend/tests/test_agent_registry.py.

Reviewed changed lines

• backend/services/agent_registry.py:141 (RIGHT): Correctly implements the write-through synchronization from legacy keys to semantic keys in the authoritative raw_entry.
• backend/services/agent_registry.py:273 (RIGHT): The custom init correctly reconciles legacy and semantic constructor arguments, preventing TypeErrors for legacy callers.
• backend/services/agent_registry.py:411 (RIGHT): The property 'raw' returns the retained _legacy_raw_dict, ensuring reference identity across multiple accesses.

Adversarial validation

• backend/tests/test_agent_registry.py:245 (RIGHT) falsified: Mutating a retained reference to agent.raw will be observed by a second reference to the same agent's raw property. — test_retained_raw_references_share_one_coherent_dictionary verifies 'first_raw is second_raw' and that mutations are shared.
• backend/tests/test_agent_registry.py:318 (RIGHT) falsified: Calling dataclasses.asdict() on RegisteredAgent will crash due to the _LegacyRawDict constructor expecting a _SemanticRawDict. — test_registered_agent_asdict_exposes_only_semantic_dataclass_state verifies that asdict succeeds and excludes internal synchronization state.
• Residual risk: Low. The only remaining fragility is pickle support, which is explicitly declared as unsupported and not used in the codebase.

Findings

• No blocking findings.

• Result: APPROVE
• Head SHA: c65c3c2db6398ce771e52c2e464f95c3f0961c00
• Reviewer credential: noema-review-github-app-refresh
• Actor: cwl-noema-review[bot]