Implementation Plan: Hierarchical & Versioned Agent Namespace

 

Objective: Transition the platform from a flat agent namespace (agent_name) to a structured, hierarchical, and versioned namespace (/kind/type/name/version) to enhance organization, stability, and scalability.

Guiding Principle: All changes should support and enforce the rules of Semantic Versioning, where the "public contract" is defined by an agent's inputs and outputs.

---

Phase 1: Data Structure & Configuration Management (

This is the foundation. The way data is stored must change first.

1. New Agent Naming Convention:

   • Decision: Do we store agents in a nested dictionary (config['agents']['kind']['type']['name']['version']) or keep a flat structure where the key is the full path string (config['agents']['/kind/type/name/version'])?

   • Recommendation: Use a flat structure with the full path string as the key. This is far simpler to implement and query, avoids deep recursion, and makes agent names easily searchable.

     • Example Key: "core/protocol/http/v1.0.0"

2.  Class Modifications:

   • : This function becomes deprecated. Renaming is now handled by the "Smart Save" logic which creates new versions.

   • : No change in signature, but its internal use will now handle full path names.

   • New Helper Functions:

     • parse_name(full_name): A utility that takes a full name string and returns a dictionary: {kind, type, name, version}. This will be used everywhere.

     • get_versions_of_agent(base_name): Takes /kind/type/name and returns a sorted list of all available version strings for that agent.

     • get_latest_version(base_name): Returns the full name of the agent with the highest semantic version.

     • get_contract(full_name): A helper that returns an agent's public contract ({inputs: [...], outputs: [...]}) for easy comparison.

3. Migration Script (One-Time Operation):

   • Create a standalone Python script migrate_config.py.

   • This script will read an old config.json with a flat namespace.

   • It will iterate through each agent and prompt the user to assign a new /kind/type/name. All existing agents will be assigned v1.0.0 by default.

   • It will write a new config_v2.json file with the new hierarchical keys. This ensures a clean break and preserves the old config as a backup.

---

Phase 2: IDE Modifications (

This phase is about reflecting the new structure in the user interface.

1. Agent List Panel:

   • Data Fetching: Instead of just getting a list of names, it will now fetch all names, parse them, and group them.

   • UI Change: The CTkScrollableFrame will be replaced with a ttk.Treeview widget, which is designed for hierarchical data.

     • Top-level nodes will be kind.

     • Second-level nodes will be type.

     • Third-level nodes will be name.

     • Leaf nodes will be the individual versions.

   • This provides a much better discovery and organization experience for the user.

   • The search/filter functionality will need to be updated to search this tree structure.

2. "Smart Save" Button Logic:

   • Implement the full "Smart Save" workflow as designed previously.

   • On Click:

     1. Get the current agent's full name (e.g., /core/http/v1.2.3).

     2. Use config_manager.get_contract() to fetch the old contract.

     3. Get the new contract from the editor form.

     4. Compare contracts.

     5. If contracts differ (Breaking Change):

        • Calculate the next MAJOR version (e.g., v2.0.0).

        • Create a new agent entry in the config with the new name.

        • Inform the user: "Contract changed. Saved as new MAJOR version v2.0.0."

     6. If contracts are the same (Non-Breaking Change):

        • Calculate the next MINOR version (e.g., v1.3.0).

        • Create a new agent entry with the new name.

        • Inform the user: "Saved as new MINOR version v1.3.0."

   • After saving, refresh the agent list tree view.

3. Workflow Editor & Step Management:

   • When an agent is dragged into the "Steps" tab, the IDE should prompt the user which version they want to use, defaulting to the latest.

   • The step definition in config.json will now store the full, versioned name of the agent (e.g., "agent": "core/protocol/http/v1.0.0"). This "pins" the dependency.

   • New Feature: Add a right-click context menu item on a step: "Check for Updates." This would use config_manager.get_versions_of_agent() to see if newer, non-breaking versions are available and offer a one-click upgrade.

4. "Promote to Workflow" Modal:

   • The dialog will now need fields for the user to enter the kind, type, and name. The version will be automatically set to v1.0.0.

---

Phase 3: Core Engine & Execution (

The core engine needs minimal but critical changes to understand the new naming scheme.

1.  Function:

   • No change to core logic. This is the beauty of the design. The function simply receives an agent_name string from the step definition. It doesn't care what the string contains. It will use this full name (e.g., "core/protocol/http/v1.0.0") as the key to look up the agent definition in config['agents'] and the function in globals().

   • The function name to be compiled/cached by exec_proc_agent should be made unique to avoid collisions. A good convention would be to sanitize the full path into a valid Python function name (e.g., core_protocol_http_v1_0_0).

2. CLI Interface (

   • The command-line invocation will now take the full, versioned agent name as an argument.

   • Example: ./dynamic_workflows_agents.py /core/protocol/http/v1.2.3 --url "..."

   • The help text (when run with no arguments) should be updated to list agents in a more organized, hierarchical way.

---

Phase 4: Testing & Auxiliary Services (

1. :

   • The runner will now iterate through all versions of all agents that have a run_config block.

   • The HTML report should be updated to display the results in the same hierarchical tree structure as the IDE. This provides a clear view of which versions of which agents are passing or failing.

   • This makes the test runner even more powerful, as it can now act as a regression test suite, ensuring that new versions of an agent don't break their own established tests.

---

Rollout Plan & Timeline (Assumes 1 Developer + AI Assistant)

• Week 1: Foundation & Migration.

  • Focus entirely on Phase 1.

  • Update ConfigManager.

  • Write and test the migrate_config.py script.

  • By the end of the week, you should have a valid config_v2.json file.

• Week 2: The "Smart Save" & IDE Core.

  • Implement the ttk.Treeview for the agent list.

  • Implement the "Smart Save" logic. This is the most complex part of the UI change.

  • Ensure creating, saving, and displaying hierarchical agents works flawlessly.

• Week 3: Workflow Integration & Polish.

  • Update the "Steps" tab to handle versioned names.

  • Implement the "Check for Updates" feature.

  • Update the main CLI block and the test_runner.py service.

• Week 4: Testing & Bug Fixes.

  • Thorough end-to-end testing of all features.

  • Fix any UI glitches or logical errors.

  • Prepare for "release."

This plan provides a structured path to implementing a major architectural upgrade, ensuring that each component of your ecosystem is brought into alignment with the new, more robust, and scalable vision.