Merge remote-tracking branch 'origin' into feature/integration-extended

Expand integration tool coverage across 40 vendors

.claude/settings.local.json.example

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git status:*)",
+      "Bash(gh run view:*)",
+      "Bash(uv run:*)",
+      "Bash(env:*)",
+      "Bash(python -m py_compile:*)",
+      "Bash(python -m pytest:*)",
+      "Bash(source:*)",
+      "Bash(find:*)",
+      "Bash(PYTHONPATH=core:exports:tools/src uv run pytest:*)"
+    ]
+  },
+  "enabledMcpjsonServers": ["tools"]
+}

.claude/skills/agent-workflow/SKILL.md

@@ -1,463 +0,0 @@
----
-name: agent-workflow
-description: Complete workflow for building, implementing, and testing goal-driven agents. Orchestrates building-agents-* and testing-agent skills. Use when starting a new agent project, unsure which skill to use, or need end-to-end guidance.
-license: Apache-2.0
-metadata:
-  author: hive
-  version: "2.0"
-  type: workflow-orchestrator
-  orchestrates:
-    - building-agents-core
-    - building-agents-construction
-    - building-agents-patterns
-    - testing-agent
-    - setup-credentials
----
-
-# Agent Development Workflow
-
-Complete Standard Operating Procedure (SOP) for building production-ready goal-driven agents.
-
-## Overview
-
-This workflow orchestrates specialized skills to take you from initial concept to production-ready agent:
-
-1. **Understand Concepts** → `/building-agents-core` (optional)
-2. **Build Structure** → `/building-agents-construction`
-3. **Optimize Design** → `/building-agents-patterns` (optional)
-4. **Setup Credentials** → `/setup-credentials` (if agent uses tools requiring API keys)
-5. **Test & Validate** → `/testing-agent`
-
-## When to Use This Workflow
-
-Use this meta-skill when:
-- Starting a new agent from scratch
-- Unclear which skill to use first
-- Need end-to-end guidance for agent development
-- Want consistent, repeatable agent builds
-
-**Skip this workflow** if:
-- You only need to test an existing agent → use `/testing-agent` directly
-- You know exactly which phase you're in → use specific skill directly
-
-## Quick Decision Tree
-
-```
-"Need to understand agent concepts" → building-agents-core
-"Build a new agent" → building-agents-construction
-"Optimize my agent design" → building-agents-patterns
-"Set up API keys for my agent" → setup-credentials
-"Test my agent" → testing-agent
-"Not sure what I need" → Read phases below, then decide
-"Agent has structure but needs implementation" → See agent directory STATUS.md
-```
-
-## Phase 0: Understand Concepts (Optional)
-
-**Duration**: 5-10 minutes
-**Skill**: `/building-agents-core`
-**Input**: Questions about agent architecture
-
-### When to Use
-
-- First time building an agent
-- Need to understand node types, edges, goals
-- Want to validate tool availability
-- Learning about pause/resume architecture
-
-### What This Phase Provides
-
-- Architecture overview (Python packages, not JSON)
-- Core concepts (Goal, Node, Edge, Pause/Resume)
-- Tool discovery and validation procedures
-- Workflow overview
-
-**Skip this phase** if you already understand agent fundamentals.
-
-## Phase 1: Build Agent Structure
-
-**Duration**: 15-30 minutes
-**Skill**: `/building-agents-construction`
-**Input**: User requirements ("Build an agent that...")
-
-### What This Phase Does
-
-Creates the complete agent architecture:
-- Package structure (`exports/agent_name/`)
-- Goal with success criteria and constraints
-- Workflow graph (nodes and edges)
-- Node specifications
-- CLI interface
-- Documentation
-
-### Process
-
-1. **Create package** - Directory structure with skeleton files
-2. **Define goal** - Success criteria and constraints written to agent.py
-3. **Design nodes** - Each node approved and written incrementally
-4. **Connect edges** - Workflow graph with conditional routing
-5. **Finalize** - Agent class, exports, and documentation
-
-### Outputs
-
-- ✅ `exports/agent_name/` package created
-- ✅ Goal defined in agent.py
-- ✅ 3-5 success criteria defined
-- ✅ 1-5 constraints defined
-- ✅ 5-10 nodes specified in nodes/__init__.py
-- ✅ 8-15 edges connecting workflow
-- ✅ Validated structure (passes `python -m agent_name validate`)
-- ✅ README.md with usage instructions
-- ✅ CLI commands (info, validate, run, shell)
-
-### Success Criteria
-
-You're ready for Phase 2 when:
-- Agent structure validates without errors
-- All nodes and edges are defined
-- CLI commands work (info, validate)
-- You see: "Agent complete: exports/agent_name/"
-
-### Common Outputs
-
-The building-agents-construction skill produces:
-```
-exports/agent_name/
-├── __init__.py          (package exports)
-├── __main__.py          (CLI interface)
-├── agent.py             (goal, graph, agent class)
-├── nodes/__init__.py    (node specifications)
-├── config.py            (configuration)
-├── implementations.py   (may be created for Python functions)
-└── README.md            (documentation)
-```
-
-### Next Steps
-
-**If structure complete and validated:**
-→ Check `exports/agent_name/STATUS.md` or `IMPLEMENTATION_GUIDE.md`
-→ These files explain implementation options
-→ You may need to add Python functions or MCP tools (not covered by current skills)
-
-**If want to optimize design:**
-→ Proceed to Phase 1.5 (building-agents-patterns)
-
-**If ready to test:**
-→ Proceed to Phase 2
-
-## Phase 1.5: Optimize Design (Optional)
-
-**Duration**: 10-15 minutes
-**Skill**: `/building-agents-patterns`
-**Input**: Completed agent structure
-
-### When to Use
-
-- Want to add pause/resume functionality
-- Need error handling patterns
-- Want to optimize performance
-- Need examples of complex routing
-- Want best practices guidance
-
-### What This Phase Provides
-
-- Practical examples and patterns
-- Pause/resume architecture
-- Error handling strategies
-- Anti-patterns to avoid
-- Performance optimization techniques
-
-**Skip this phase** if your agent design is straightforward.
-
-## Phase 2: Test & Validate
-
-**Duration**: 20-40 minutes
-**Skill**: `/testing-agent`
-**Input**: Working agent from Phase 1
-
-### What This Phase Does
-
-Creates comprehensive test suite:
-- Constraint tests (verify hard requirements)
-- Success criteria tests (measure goal achievement)
-- Edge case tests (handle failures gracefully)
-- Integration tests (end-to-end workflows)
-
-### Process
-
-1. **Analyze agent** - Read goal, constraints, success criteria
-2. **Generate tests** - Create pytest files in `exports/agent_name/tests/`
-3. **User approval** - Review and approve each test
-4. **Run evaluation** - Execute tests and collect results
-5. **Debug failures** - Identify and fix issues
-6. **Iterate** - Repeat until all tests pass
-
-### Outputs
-
-- ✅ Test files in `exports/agent_name/tests/`
-- ✅ Test report with pass/fail metrics
-- ✅ Coverage of all success criteria
-- ✅ Coverage of all constraints
-- ✅ Edge case handling verified
-
-### Success Criteria
-
-You're done when:
-- All tests pass
-- All success criteria validated
-- All constraints verified
-- Agent handles edge cases
-- Test coverage is comprehensive
-
-### Next Steps
-
-**Agent ready for:**
-- Production deployment
-- Integration into larger systems
-- Documentation and handoff
-- Continuous monitoring
-
-## Phase Transitions
-
-### From Phase 1 to Phase 2
-
-**Trigger signals:**
-- "Agent complete: exports/..."
-- Structure validation passes
-- README indicates implementation complete
-
-**Before proceeding:**
-- Verify agent can be imported: `from exports.agent_name import default_agent`
-- Check if implementation is needed (see STATUS.md or IMPLEMENTATION_GUIDE.md)
-- Confirm agent executes without import errors
-
-### Skipping Phases
-
-**When to skip Phase 1:**
-- Agent structure already exists
-- Only need to add tests
-- Modifying existing agent
-
-**When to skip Phase 2:**
-- Prototyping or exploring
-- Agent not production-bound
-- Manual testing sufficient
-
-## Common Patterns
-
-### Pattern 1: Complete New Build (Simple)
-
-```
-User: "Build an agent that monitors files"
-→ Use /building-agents-construction
-→ Agent structure created
-→ Use /testing-agent
-→ Tests created and passing
-→ Done: Production-ready agent
-```
-
-### Pattern 1b: Complete New Build (With Learning)
-
-```
-User: "Build an agent (first time)"
-→ Use /building-agents-core (understand concepts)
-→ Use /building-agents-construction (build structure)
-→ Use /building-agents-patterns (optimize design)
-→ Use /testing-agent (validate)
-→ Done: Production-ready agent
-```
-
-### Pattern 2: Test Existing Agent
-
-```
-User: "Test my agent at exports/my_agent"
-→ Skip Phase 1
-→ Use /testing-agent directly
-→ Tests created
-→ Done: Validated agent
-```
-
-### Pattern 3: Iterative Development
-
-```
-User: "Build an agent"
-→ Use /building-agents-construction (Phase 1)
-→ Implementation needed (see STATUS.md)
-→ [User implements functions]
-→ Use /testing-agent (Phase 2)
-→ Tests reveal bugs
-→ [Fix bugs manually]
-→ Re-run tests
-→ Done: Working agent
-```
-
-### Pattern 4: Complex Agent with Patterns
-
-```
-User: "Build an agent with multi-turn conversations"
-→ Use /building-agents-core (learn pause/resume)
-→ Use /building-agents-construction (build structure)
-→ Use /building-agents-patterns (implement pause/resume pattern)
-→ Use /testing-agent (validate conversation flows)
-→ Done: Complex conversational agent
-```
-
-## Skill Dependencies
-
-```
-agent-workflow (meta-skill)
-    │
-    ├── building-agents-core (foundational)
-    │   ├── Architecture concepts
-    │   ├── Node/Edge/Goal definitions
-    │   ├── Tool discovery procedures
-    │   └── Workflow overview
-    │
-    ├── building-agents-construction (procedural)
-    │   ├── Creates package structure
-    │   ├── Defines goal
-    │   ├── Adds nodes incrementally
-    │   ├── Connects edges
-    │   ├── Finalizes agent class
-    │   └── Requires: building-agents-core
-    │
-    ├── building-agents-patterns (reference)
-    │   ├── Best practices
-    │   ├── Pause/resume patterns
-    │   ├── Error handling
-    │   ├── Anti-patterns
-    │   └── Performance optimization
-    │
-    └── testing-agent
-        ├── Reads agent goal
-        ├── Generates tests
-        ├── Runs evaluation
-        └── Reports results
-```
-
-## Troubleshooting
-
-### "Agent structure won't validate"
-
-- Check node IDs match between nodes/__init__.py and agent.py
-- Verify all edges reference valid node IDs
-- Ensure entry_node exists in nodes list
-- Run: `PYTHONPATH=core:exports python -m agent_name validate`
-
-### "Agent has structure but won't run"
-
-- Check for STATUS.md or IMPLEMENTATION_GUIDE.md in agent directory
-- Implementation may be needed (Python functions or MCP tools)
-- This is expected - building-agents-construction creates structure, not implementation
-- See implementation guide for completion options
-
-### "Tests are failing"
-
-- Review test output for specific failures
-- Check agent goal and success criteria
-- Verify constraints are met
-- Use `/testing-agent` to debug and iterate
-- Fix agent code and re-run tests
-
-### "Not sure which phase I'm in"
-
-Run these checks:
-
-```bash
-# Check if agent structure exists
-ls exports/my_agent/agent.py
-
-# Check if it validates
-PYTHONPATH=core:exports python -m my_agent validate
-
-# Check if tests exist
-ls exports/my_agent/tests/
-
-# If structure exists and validates → Phase 2 (testing)
-# If structure doesn't exist → Phase 1 (building)
-# If tests exist but failing → Debug phase
-```
-
-## Best Practices
-
-### For Phase 1 (Building)
-
-1. **Start with clear requirements** - Know what the agent should do
-2. **Define success criteria early** - Measurable goals drive design
-3. **Keep nodes focused** - One responsibility per node
-4. **Use descriptive names** - Node IDs should explain purpose
-5. **Validate incrementally** - Check structure after each major addition
-
-### For Phase 2 (Testing)
-
-1. **Test constraints first** - Hard requirements must pass
-2. **Mock external dependencies** - Use mock mode for LLMs/APIs
-3. **Cover edge cases** - Test failures, not just success paths
-4. **Iterate quickly** - Fix one test at a time
-5. **Document test patterns** - Future tests follow same structure
-
-### General Workflow
-
-1. **Use version control** - Git commit after each phase
-2. **Document decisions** - Update README with changes
-3. **Keep iterations small** - Build → Test → Fix → Repeat
-4. **Preserve working states** - Tag successful iterations
-5. **Learn from failures** - Failed tests reveal design issues
-
-## Exit Criteria
-
-You're done with the workflow when:
-
-✅ Agent structure validates
-✅ All tests pass
-✅ Success criteria met
-✅ Constraints verified
-✅ Documentation complete
-✅ Agent ready for deployment
-
-## Additional Resources
-
-- **building-agents-core**: See `.claude/skills/building-agents-core/SKILL.md`
-- **building-agents-construction**: See `.claude/skills/building-agents-construction/SKILL.md`
-- **building-agents-patterns**: See `.claude/skills/building-agents-patterns/SKILL.md`
-- **testing-agent**: See `.claude/skills/testing-agent/SKILL.md`
-- **Agent framework docs**: See `core/README.md`
-- **Example agents**: See `exports/` directory
-
-## Summary
-
-This workflow provides a proven path from concept to production-ready agent:
-
-1. **Learn** with `/building-agents-core` → Understand fundamentals (optional)
-2. **Build** with `/building-agents-construction` → Get validated structure
-3. **Optimize** with `/building-agents-patterns` → Apply best practices (optional)
-4. **Test** with `/testing-agent` → Get verified functionality
-
-The workflow is **flexible** - skip phases as needed, iterate freely, and adapt to your specific requirements. The goal is **production-ready agents** built with **consistent, repeatable processes**.
-
-## Skill Selection Guide
-
-**Choose building-agents-core when:**
-- First time building agents
-- Need to understand architecture
-- Validating tool availability
-- Learning about node types and edges
-
-**Choose building-agents-construction when:**
-- Actually building an agent
-- Have clear requirements
-- Ready to write code
-- Want step-by-step guidance
-
-**Choose building-agents-patterns when:**
-- Agent structure complete
-- Need advanced patterns
-- Implementing pause/resume
-- Optimizing performance
-- Want best practices
-
-**Choose testing-agent when:**
-- Agent structure complete
-- Ready to validate functionality
-- Need comprehensive test coverage
-- Debugging agent behavior

.claude/skills/agent-workflow/examples/file-monitor-example.md

@@ -1,199 +0,0 @@
-# Example: File Monitor Agent
-
-This example shows the complete agent-workflow in action for building a file monitoring agent.
-
-## Initial Request
-
-```
-User: "Build an agent that monitors ~/Downloads and copies new files to ~/Documents"
-```
-
-## Phase 1: Building (20 minutes)
-
-### Step 1: Create Structure
-
-Agent invokes `/building-agents` skill and:
-
-1. Creates `exports/file_monitor_agent/` package
-2. Writes skeleton files (__init__.py, __main__.py, agent.py, etc.)
-
-**Output**: Package structure visible immediately
-
-### Step 2: Define Goal
-
-```python
-goal = Goal(
-    id="file-monitor-copy",
-    name="Automated File Monitor & Copy",
-    success_criteria=[
-        # 100% detection rate
-        # 100% copy success
-        # 100% conflict resolution
-        # >99% uptime
-    ],
-    constraints=[
-        # Preserve originals
-        # Handle errors gracefully
-        # Track state
-        # Respect permissions
-    ]
-)
-```
-
-**Output**: Goal written to agent.py
-
-### Step 3: Design Nodes
-
-7 nodes approved and written incrementally:
-
-1. `initialize-state` - Set up tracking
-2. `list-downloads` - Scan directory
-3. `identify-new-files` - Find new files
-4. `check-for-new-files` - Router
-5. `copy-files` - Copy with conflict resolution
-6. `update-state` - Mark as processed
-7. `wait-interval` - Sleep between cycles
-
-**Output**: All nodes in nodes/__init__.py
-
-### Step 4: Connect Edges
-
-8 edges connecting the workflow loop:
-
-```
-initialize → list → identify → check
-                                ↓  ↓
-                              copy  wait
-                                ↓    ↑
-                              update ↓
-                                ↓    ↓
-                              wait → list (loop)
-```
-
-**Output**: Edges written to agent.py
-
-### Step 5: Finalize
-
-```bash
-$ PYTHONPATH=core:exports python -m file_monitor_agent validate
-✓ Agent is valid
-
-$ PYTHONPATH=core:exports python -m file_monitor_agent info
-Agent: File Monitor & Copy Agent
-Nodes: 7
-Edges: 8
-```
-
-**Phase 1 Complete**: Structure validated ✅
-
-### Status After Phase 1
-
-```
-exports/file_monitor_agent/
-├── __init__.py          ✅ (exports)
-├── __main__.py          ✅ (CLI)
-├── agent.py             ✅ (goal, graph, agent class)
-├── nodes/__init__.py    ✅ (7 nodes)
-├── config.py            ✅ (configuration)
-├── implementations.py   ✅ (Python functions)
-├── README.md            ✅ (documentation)
-├── IMPLEMENTATION_GUIDE.md ✅ (next steps)
-└── STATUS.md            ✅ (current state)
-```
-
-**Note**: Implementation gap exists - data flow needs connection (covered in STATUS.md)
-
-## Phase 2: Testing (25 minutes)
-
-### Step 1: Analyze Agent
-
-Agent invokes `/testing-agent` skill and:
-
-1. Reads goal from `exports/file_monitor_agent/agent.py`
-2. Identifies 4 success criteria to test
-3. Identifies 4 constraints to verify
-4. Plans test coverage
-
-### Step 2: Generate Tests
-
-Creates test files:
-
-```
-exports/file_monitor_agent/tests/
-├── conftest.py              (fixtures)
-├── test_constraints.py      (4 constraint tests)
-├── test_success_criteria.py (4 success tests)
-└── test_edge_cases.py       (error handling)
-```
-
-Tests approved incrementally by user.
-
-### Step 3: Run Tests
-
-```bash
-$ PYTHONPATH=core:exports pytest exports/file_monitor_agent/tests/
-
-test_constraints.py::test_preserves_originals     PASSED
-test_constraints.py::test_handles_errors          PASSED
-test_constraints.py::test_tracks_state            PASSED
-test_constraints.py::test_respects_permissions    PASSED
-
-test_success_criteria.py::test_detects_all_files  PASSED
-test_success_criteria.py::test_copies_all_files   PASSED
-test_success_criteria.py::test_resolves_conflicts PASSED
-test_success_criteria.py::test_continuous_run     PASSED
-
-test_edge_cases.py::test_empty_directory          PASSED
-test_edge_cases.py::test_permission_denied        PASSED
-test_edge_cases.py::test_disk_full                PASSED
-test_edge_cases.py::test_large_files              PASSED
-
-========================== 12 passed in 3.42s ==========================
-```
-
-**Phase 2 Complete**: All tests pass ✅
-
-## Final Output
-
-**Production-Ready Agent:**
-
-```bash
-# Run the agent
-./RUN_AGENT.sh
-
-# Or manually
-PYTHONPATH=core:exports:tools/src python -m file_monitor_agent run
-```
-
-**Capabilities:**
-- Monitors ~/Downloads continuously
-- Copies new files to ~/Documents
-- Resolves conflicts with timestamps
-- Handles errors gracefully
-- Tracks processed files
-- Runs as background service
-
-**Total Time**: ~45 minutes from concept to production
-
-## Key Learnings
-
-1. **Incremental building** - Files written immediately, visible throughout
-2. **Validation early** - Structure validated before moving to implementation
-3. **Test-driven** - Tests reveal real behavior
-4. **Documentation included** - README, STATUS, and guides auto-generated
-5. **Repeatable process** - Same workflow for any agent type
-
-## Variations
-
-**For simpler agents:**
-- Fewer nodes (3-5 instead of 7)
-- Simpler workflow (linear instead of looping)
-- Faster build time (10-15 minutes)
-
-**For complex agents:**
-- More nodes (10-15+)
-- Multiple subgraphs
-- Pause/resume points for human-in-the-loop
-- Longer build time (45-60 minutes)
-
-The workflow scales to your needs!

.claude/skills/building-agents-construction/SKILL.md

@@ -1,361 +0,0 @@
----
-name: building-agents-construction
-description: Step-by-step guide for building goal-driven agents. Creates package structure, defines goals, adds nodes, connects edges, and finalizes agent class. Use when actively building an agent.
-license: Apache-2.0
-metadata:
-  author: hive
-  version: "2.0"
-  type: procedural
-  part_of: building-agents
-  requires: building-agents-core
----
-
-# Agent Construction - EXECUTE THESE STEPS
-
-**THIS IS AN EXECUTABLE WORKFLOW. DO NOT DISPLAY THIS FILE. EXECUTE THE STEPS BELOW.**
-
-When this skill is loaded, IMMEDIATELY begin executing Step 1. Do not explain what you will do - just do it.
-
----
-
-## STEP 1: Initialize Build Environment
-
-**EXECUTE THESE TOOL CALLS NOW:**
-
-1. Register the hive-tools MCP server:
-
-```
-mcp__agent-builder__add_mcp_server(
-    name="hive-tools",
-    transport="stdio",
-    command="python",
-    args='["mcp_server.py", "--stdio"]',
-    cwd="tools",
-    description="Hive tools MCP server"
-)
-```
-
-2. Create a build session (replace AGENT_NAME with the user's requested agent name in snake_case):
-
-```
-mcp__agent-builder__create_session(name="AGENT_NAME")
-```
-
-3. Discover available tools:
-
-```
-mcp__agent-builder__list_mcp_tools()
-```
-
-4. Create the package directory:
-
-```
-mkdir -p exports/AGENT_NAME/nodes
-```
-
-**AFTER completing these calls**, tell the user:
-
-> ✅ Build environment initialized
->
-> - Session created
-> - Available tools: [list the tools from step 3]
->
-> Proceeding to define the agent goal...
-
-**THEN immediately proceed to STEP 2.**
-
----
-
-## STEP 2: Define and Approve Goal
-
-**PROPOSE a goal to the user.** Based on what they asked for, propose:
-
-- Goal ID (kebab-case)
-- Goal name
-- Goal description
-- 3-5 success criteria (each with: id, description, metric, target, weight)
-- 2-4 constraints (each with: id, description, constraint_type, category)
-
-**FORMAT your proposal as a clear summary, then ask for approval:**
-
-> **Proposed Goal: [Name]**
->
-> [Description]
->
-> **Success Criteria:**
->
-> 1. [criterion 1]
-> 2. [criterion 2]
->    ...
->
-> **Constraints:**
->
-> 1. [constraint 1]
-> 2. [constraint 2]
->    ...
-
-**THEN call AskUserQuestion:**
-
-```
-AskUserQuestion(questions=[{
-    "question": "Do you approve this goal definition?",
-    "header": "Goal",
-    "options": [
-        {"label": "Approve", "description": "Goal looks good, proceed"},
-        {"label": "Modify", "description": "I want to change something"}
-    ],
-    "multiSelect": false
-}])
-```
-
-**WAIT for user response.**
-
-- If **Approve**: Call `mcp__agent-builder__set_goal(...)` with the goal details, then proceed to STEP 3
-- If **Modify**: Ask what they want to change, update proposal, ask again
-
----
-
-## STEP 3: Design Node Workflow
-
-**BEFORE designing nodes**, review the available tools from Step 1. Nodes can ONLY use tools that exist.
-
-**DESIGN the workflow** as a series of nodes. For each node, determine:
-
-- node_id (kebab-case)
-- name
-- description
-- node_type: `"llm_generate"` (no tools) or `"llm_tool_use"` (uses tools)
-- input_keys (what data this node receives)
-- output_keys (what data this node produces)
-- tools (ONLY tools that exist - empty list for llm_generate)
-- system_prompt
-
-**PRESENT the workflow to the user:**
-
-> **Proposed Workflow: [N] nodes**
->
-> 1. **[node-id]** - [description]
->
->    - Type: [llm_generate/llm_tool_use]
->    - Input: [keys]
->    - Output: [keys]
->    - Tools: [tools or "none"]
->
-> 2. **[node-id]** - [description]
->    ...
->
-> **Flow:** node1 → node2 → node3 → ...
-
-**THEN call AskUserQuestion:**
-
-```
-AskUserQuestion(questions=[{
-    "question": "Do you approve this workflow design?",
-    "header": "Workflow",
-    "options": [
-        {"label": "Approve", "description": "Workflow looks good, proceed to build nodes"},
-        {"label": "Modify", "description": "I want to change the workflow"}
-    ],
-    "multiSelect": false
-}])
-```
-
-**WAIT for user response.**
-
-- If **Approve**: Proceed to STEP 4
-- If **Modify**: Ask what they want to change, update design, ask again
-
----
-
-## STEP 4: Build Nodes One by One
-
-**FOR EACH node in the approved workflow:**
-
-1. **Call** `mcp__agent-builder__add_node(...)` with the node details
-
-   - input_keys and output_keys must be JSON strings: `'["key1", "key2"]'`
-   - tools must be a JSON string: `'["tool1"]'` or `'[]'`
-
-2. **Call** `mcp__agent-builder__test_node(...)` to validate:
-
-```
-mcp__agent-builder__test_node(
-    node_id="the-node-id",
-    test_input='{"key": "test value"}',
-    mock_llm_response='{"output_key": "test output"}'
-)
-```
-
-3. **Check result:**
-
-   - If valid: Tell user "✅ Node [id] validated" and continue to next node
-   - If invalid: Show errors, fix the node, re-validate
-
-4. **Show progress** after each node:
-
-```
-mcp__agent-builder__get_session_status()
-```
-
-> ✅ Node [X] of [Y] complete: [node-id]
-
-**AFTER all nodes are added and validated**, proceed to STEP 5.
-
----
-
-## STEP 5: Connect Edges
-
-**DETERMINE the edges** based on the workflow flow. For each connection:
-
-- edge_id (kebab-case)
-- source (node that outputs)
-- target (node that receives)
-- condition: `"on_success"`, `"always"`, `"on_failure"`, or `"conditional"`
-- condition_expr (Python expression, only if conditional)
-- priority (integer, lower = higher priority)
-
-**FOR EACH edge, call:**
-
-```
-mcp__agent-builder__add_edge(
-    edge_id="source-to-target",
-    source="source-node-id",
-    target="target-node-id",
-    condition="on_success",
-    condition_expr="",
-    priority=1
-)
-```
-
-**AFTER all edges are added, validate the graph:**
-
-```
-mcp__agent-builder__validate_graph()
-```
-
-- If valid: Tell user "✅ Graph structure validated" and proceed to STEP 6
-- If invalid: Show errors, fix edges, re-validate
-
----
-
-## STEP 6: Generate Agent Package
-
-**EXPORT the graph data:**
-
-```
-mcp__agent-builder__export_graph()
-```
-
-This returns JSON with all the goal, nodes, edges, and MCP server configurations.
-
-**THEN write the Python package files** using the exported data. Create these files in `exports/AGENT_NAME/`:
-
-1. `config.py` - Runtime configuration with model settings
-2. `nodes/__init__.py` - All NodeSpec definitions
-3. `agent.py` - Goal, edges, graph config, and agent class
-4. `__init__.py` - Package exports
-5. `__main__.py` - CLI interface
-6. `mcp_servers.json` - MCP server configurations
-7. `README.md` - Usage documentation
-
-**IMPORTANT entry_points format:**
-
-- MUST be: `{"start": "first-node-id"}`
-- NOT: `{"first-node-id": ["input_keys"]}` (WRONG)
-- NOT: `{"first-node-id"}` (WRONG - this is a set)
-
-**Use the example agent** at `.claude/skills/building-agents-construction/examples/online_research_agent/` as a template for file structure and patterns.
-
-**AFTER writing all files, tell the user:**
-
-> ✅ Agent package created: `exports/AGENT_NAME/`
->
-> **Files generated:**
->
-> - `__init__.py` - Package exports
-> - `agent.py` - Goal, nodes, edges, agent class
-> - `config.py` - Runtime configuration
-> - `__main__.py` - CLI interface
-> - `nodes/__init__.py` - Node definitions
-> - `mcp_servers.json` - MCP server config
-> - `README.md` - Usage documentation
->
-> **Test your agent:**
->
-> ```bash
-> cd /home/timothy/oss/hive
-> PYTHONPATH=core:exports python -m AGENT_NAME validate
-> PYTHONPATH=core:exports python -m AGENT_NAME info
-> ```
-
----
-
-## STEP 7: Verify and Test
-
-**RUN validation:**
-
-```bash
-cd /home/timothy/oss/hive && PYTHONPATH=core:exports python -m AGENT_NAME validate
-```
-
-- If valid: Agent is complete!
-- If errors: Fix the issues and re-run
-
-**SHOW final session summary:**
-
-```
-mcp__agent-builder__get_session_status()
-```
-
-**TELL the user the agent is ready** and suggest next steps:
-
-- Run with mock mode to test without API calls
-- Use `/testing-agent` skill for comprehensive testing
-- Use `/setup-credentials` if the agent needs API keys
-
----
-
-## REFERENCE: Node Types
-
-| Type           | tools param            | Use when                                       |
-| -------------- | ---------------------- | ---------------------------------------------- |
-| `llm_generate` | `'[]'`                 | Pure reasoning, JSON output, no external calls |
-| `llm_tool_use` | `'["tool1", "tool2"]'` | Needs to call MCP tools                        |
-
----
-
-## REFERENCE: Edge Conditions
-
-| Condition     | When edge is followed                 |
-| ------------- | ------------------------------------- |
-| `on_success`  | Source node completed successfully    |
-| `on_failure`  | Source node failed                    |
-| `always`      | Always, regardless of success/failure |
-| `conditional` | When condition_expr evaluates to True |
-
----
-
-## REFERENCE: System Prompt Best Practice
-
-For nodes with JSON output, include this in the system_prompt:
-
-```
-CRITICAL: Return ONLY raw JSON. NO markdown, NO code blocks.
-Just the JSON object starting with { and ending with }.
-
-Return this exact structure:
-{
-  "key1": "...",
-  "key2": "..."
-}
-```
-
----
-
-## COMMON MISTAKES TO AVOID
-
-1. **Using tools that don't exist** - Always check `mcp__agent-builder__list_mcp_tools()` first
-2. **Wrong entry_points format** - Must be `{"start": "node-id"}`, NOT a set or list
-3. **Skipping validation** - Always validate nodes and graph before proceeding
-4. **Not waiting for approval** - Always ask user before major steps
-5. **Displaying this file** - Execute the steps, don't show documentation

.claude/skills/building-agents-construction/examples/online_research_agent/README.md

@@ -1,80 +0,0 @@
-# Online Research Agent
-
-Deep-dive research agent that searches 10+ sources and produces comprehensive narrative reports with citations.
-
-## Features
-
-- Generates multiple search queries from a topic
-- Searches and fetches 15+ web sources
-- Evaluates and ranks sources by relevance
-- Synthesizes findings into themes
-- Writes narrative report with numbered citations
-- Quality checks for uncited claims
-- Saves report to local markdown file
-
-## Usage
-
-### CLI
-
-```bash
-# Show agent info
-python -m online_research_agent info
-
-# Validate structure
-python -m online_research_agent validate
-
-# Run research on a topic
-python -m online_research_agent run --topic "impact of AI on healthcare"
-
-# Interactive shell
-python -m online_research_agent shell
-```
-
-### Python API
-
-```python
-from online_research_agent import default_agent
-
-# Simple usage
-result = await default_agent.run({"topic": "climate change solutions"})
-
-# Check output
-if result.success:
-    print(f"Report saved to: {result.output['file_path']}")
-    print(result.output['final_report'])
-```
-
-## Workflow
-
-```
-parse-query → search-sources → fetch-content → evaluate-sources
-                                                      ↓
-                                write-report ← synthesize-findings
-                                      ↓
-                               quality-check → save-report
-```
-
-## Output
-
-Reports are saved to `./research_reports/` as markdown files with:
-
-1. Executive Summary
-2. Introduction
-3. Key Findings (by theme)
-4. Analysis
-5. Conclusion
-6. References
-
-## Requirements
-
-- Python 3.11+
-- LLM provider API key (Groq, Cerebras, etc.)
-- Internet access for web search/fetch
-
-## Configuration
-
-Edit `config.py` to change:
-
-- `model`: LLM model (default: groq/moonshotai/kimi-k2-instruct-0905)
-- `temperature`: Generation temperature (default: 0.7)
-- `max_tokens`: Max tokens per response (default: 16384)

.claude/skills/building-agents-construction/examples/online_research_agent/__init__.py

@@ -1,23 +0,0 @@
-"""
-Online Research Agent - Deep-dive research with narrative reports.
-
-Research any topic by searching multiple sources, synthesizing information,
-and producing a well-structured narrative report with citations.
-"""
-
-from .agent import OnlineResearchAgent, default_agent, goal, nodes, edges
-from .config import RuntimeConfig, AgentMetadata, default_config, metadata
-
-__version__ = "1.0.0"
-
-__all__ = [
-    "OnlineResearchAgent",
-    "default_agent",
-    "goal",
-    "nodes",
-    "edges",
-    "RuntimeConfig",
-    "AgentMetadata",
-    "default_config",
-    "metadata",
-]

.claude/skills/building-agents-construction/examples/online_research_agent/agent.py

@@ -1,419 +0,0 @@
-"""Agent graph construction for Online Research Agent."""
-
-from framework.graph import EdgeSpec, EdgeCondition, Goal, SuccessCriterion, Constraint
-from framework.graph.edge import GraphSpec
-from framework.graph.executor import ExecutionResult
-from framework.runtime.agent_runtime import AgentRuntime, create_agent_runtime
-from framework.runtime.execution_stream import EntryPointSpec
-from framework.llm import LiteLLMProvider
-from framework.runner.tool_registry import ToolRegistry
-
-from .config import default_config, metadata
-from .nodes import (
-    parse_query_node,
-    search_sources_node,
-    fetch_content_node,
-    evaluate_sources_node,
-    synthesize_findings_node,
-    write_report_node,
-    quality_check_node,
-    save_report_node,
-)
-
-# Goal definition
-goal = Goal(
-    id="comprehensive-online-research",
-    name="Comprehensive Online Research",
-    description="Research any topic by searching multiple sources, synthesizing information, and producing a well-structured narrative report with citations.",
-    success_criteria=[
-        SuccessCriterion(
-            id="source-coverage",
-            description="Query 10+ diverse sources",
-            metric="source_count",
-            target=">=10",
-            weight=0.20,
-        ),
-        SuccessCriterion(
-            id="relevance",
-            description="All sources directly address the query",
-            metric="relevance_score",
-            target="90%",
-            weight=0.25,
-        ),
-        SuccessCriterion(
-            id="synthesis",
-            description="Synthesize findings into coherent narrative",
-            metric="coherence_score",
-            target="85%",
-            weight=0.25,
-        ),
-        SuccessCriterion(
-            id="citations",
-            description="Include citations for all claims",
-            metric="citation_coverage",
-            target="100%",
-            weight=0.15,
-        ),
-        SuccessCriterion(
-            id="actionable",
-            description="Report answers the user's question",
-            metric="answer_completeness",
-            target="90%",
-            weight=0.15,
-        ),
-    ],
-    constraints=[
-        Constraint(
-            id="no-hallucination",
-            description="Only include information found in sources",
-            constraint_type="quality",
-            category="accuracy",
-        ),
-        Constraint(
-            id="source-attribution",
-            description="Every factual claim must cite its source",
-            constraint_type="quality",
-            category="accuracy",
-        ),
-        Constraint(
-            id="recency-preference",
-            description="Prefer recent sources when relevant",
-            constraint_type="quality",
-            category="relevance",
-        ),
-        Constraint(
-            id="no-paywalled",
-            description="Avoid sources that require payment to access",
-            constraint_type="functional",
-            category="accessibility",
-        ),
-    ],
-)
-
-# Node list
-nodes = [
-    parse_query_node,
-    search_sources_node,
-    fetch_content_node,
-    evaluate_sources_node,
-    synthesize_findings_node,
-    write_report_node,
-    quality_check_node,
-    save_report_node,
-]
-
-# Edge definitions
-edges = [
-    EdgeSpec(
-        id="parse-to-search",
-        source="parse-query",
-        target="search-sources",
-        condition=EdgeCondition.ON_SUCCESS,
-        priority=1,
-    ),
-    EdgeSpec(
-        id="search-to-fetch",
-        source="search-sources",
-        target="fetch-content",
-        condition=EdgeCondition.ON_SUCCESS,
-        priority=1,
-    ),
-    EdgeSpec(
-        id="fetch-to-evaluate",
-        source="fetch-content",
-        target="evaluate-sources",
-        condition=EdgeCondition.ON_SUCCESS,
-        priority=1,
-    ),
-    EdgeSpec(
-        id="evaluate-to-synthesize",
-        source="evaluate-sources",
-        target="synthesize-findings",
-        condition=EdgeCondition.ON_SUCCESS,
-        priority=1,
-    ),
-    EdgeSpec(
-        id="synthesize-to-write",
-        source="synthesize-findings",
-        target="write-report",
-        condition=EdgeCondition.ON_SUCCESS,
-        priority=1,
-    ),
-    EdgeSpec(
-        id="write-to-quality",
-        source="write-report",
-        target="quality-check",
-        condition=EdgeCondition.ON_SUCCESS,
-        priority=1,
-    ),
-    EdgeSpec(
-        id="quality-to-save",
-        source="quality-check",
-        target="save-report",
-        condition=EdgeCondition.ON_SUCCESS,
-        priority=1,
-    ),
-]
-
-# Graph configuration
-entry_node = "parse-query"
-entry_points = {"start": "parse-query"}
-pause_nodes = []
-terminal_nodes = ["save-report"]
-
-
-class OnlineResearchAgent:
-    """
-    Online Research Agent - Deep-dive research with narrative reports.
-
-    Uses AgentRuntime for multi-entrypoint support with HITL pause/resume.
-    """
-
-    def __init__(self, config=None):
-        self.config = config or default_config
-        self.goal = goal
-        self.nodes = nodes
-        self.edges = edges
-        self.entry_node = entry_node
-        self.entry_points = entry_points
-        self.pause_nodes = pause_nodes
-        self.terminal_nodes = terminal_nodes
-        self._runtime: AgentRuntime | None = None
-        self._graph: GraphSpec | None = None
-
-    def _build_entry_point_specs(self) -> list[EntryPointSpec]:
-        """Convert entry_points dict to EntryPointSpec list."""
-        specs = []
-        for ep_id, node_id in self.entry_points.items():
-            if ep_id == "start":
-                trigger_type = "manual"
-                name = "Start"
-            elif "_resume" in ep_id:
-                trigger_type = "resume"
-                name = f"Resume from {ep_id.replace('_resume', '')}"
-            else:
-                trigger_type = "manual"
-                name = ep_id.replace("-", " ").title()
-
-            specs.append(
-                EntryPointSpec(
-                    id=ep_id,
-                    name=name,
-                    entry_node=node_id,
-                    trigger_type=trigger_type,
-                    isolation_level="shared",
-                )
-            )
-        return specs
-
-    def _create_runtime(self, mock_mode=False) -> AgentRuntime:
-        """Create AgentRuntime instance."""
-        import json
-        from pathlib import Path
-
-        # Persistent storage in ~/.hive for telemetry and run history
-        storage_path = Path.home() / ".hive" / "online_research_agent"
-        storage_path.mkdir(parents=True, exist_ok=True)
-
-        tool_registry = ToolRegistry()
-
-        # Load MCP servers (always load, needed for tool validation)
-        mcp_config_path = Path(__file__).parent / "mcp_servers.json"
-        if mcp_config_path.exists():
-            tool_registry.load_mcp_config(mcp_config_path)
-
-        llm = None
-        if not mock_mode:
-            # LiteLLMProvider uses environment variables for API keys
-            llm = LiteLLMProvider(
-                model=self.config.model,
-                api_key=self.config.api_key,
-                api_base=self.config.api_base,
-            )
-
-        self._graph = GraphSpec(
-            id="online-research-agent-graph",
-            goal_id=self.goal.id,
-            version="1.0.0",
-            entry_node=self.entry_node,
-            entry_points=self.entry_points,
-            terminal_nodes=self.terminal_nodes,
-            pause_nodes=self.pause_nodes,
-            nodes=self.nodes,
-            edges=self.edges,
-            default_model=self.config.model,
-            max_tokens=self.config.max_tokens,
-        )
-
-        # Create AgentRuntime with all entry points
-        self._runtime = create_agent_runtime(
-            graph=self._graph,
-            goal=self.goal,
-            storage_path=storage_path,
-            entry_points=self._build_entry_point_specs(),
-            llm=llm,
-            tools=list(tool_registry.get_tools().values()),
-            tool_executor=tool_registry.get_executor(),
-        )
-
-        return self._runtime
-
-    async def start(self, mock_mode=False) -> None:
-        """Start the agent runtime."""
-        if self._runtime is None:
-            self._create_runtime(mock_mode=mock_mode)
-        await self._runtime.start()
-
-    async def stop(self) -> None:
-        """Stop the agent runtime."""
-        if self._runtime is not None:
-            await self._runtime.stop()
-
-    async def trigger(
-        self,
-        entry_point: str,
-        input_data: dict,
-        correlation_id: str | None = None,
-        session_state: dict | None = None,
-    ) -> str:
-        """
-        Trigger execution at a specific entry point (non-blocking).
-
-        Args:
-            entry_point: Entry point ID (e.g., "start", "pause-node_resume")
-            input_data: Input data for the execution
-            correlation_id: Optional ID to correlate related executions
-            session_state: Optional session state to resume from (with paused_at, memory)
-
-        Returns:
-            Execution ID for tracking
-        """
-        if self._runtime is None or not self._runtime.is_running:
-            raise RuntimeError("Agent runtime not started. Call start() first.")
-        return await self._runtime.trigger(
-            entry_point, input_data, correlation_id, session_state=session_state
-        )
-
-    async def trigger_and_wait(
-        self,
-        entry_point: str,
-        input_data: dict,
-        timeout: float | None = None,
-        session_state: dict | None = None,
-    ) -> ExecutionResult | None:
-        """
-        Trigger execution and wait for completion.
-
-        Args:
-            entry_point: Entry point ID
-            input_data: Input data for the execution
-            timeout: Maximum time to wait (seconds)
-            session_state: Optional session state to resume from (with paused_at, memory)
-
-        Returns:
-            ExecutionResult or None if timeout
-        """
-        if self._runtime is None or not self._runtime.is_running:
-            raise RuntimeError("Agent runtime not started. Call start() first.")
-        return await self._runtime.trigger_and_wait(
-            entry_point, input_data, timeout, session_state=session_state
-        )
-
-    async def run(
-        self, context: dict, mock_mode=False, session_state=None
-    ) -> ExecutionResult:
-        """
-        Run the agent (convenience method for simple single execution).
-
-        For more control, use start() + trigger_and_wait() + stop().
-        """
-        await self.start(mock_mode=mock_mode)
-        try:
-            # Determine entry point based on session_state
-            if session_state and "paused_at" in session_state:
-                paused_node = session_state["paused_at"]
-                resume_key = f"{paused_node}_resume"
-                if resume_key in self.entry_points:
-                    entry_point = resume_key
-                else:
-                    entry_point = "start"
-            else:
-                entry_point = "start"
-
-            result = await self.trigger_and_wait(
-                entry_point, context, session_state=session_state
-            )
-            return result or ExecutionResult(success=False, error="Execution timeout")
-        finally:
-            await self.stop()
-
-    async def get_goal_progress(self) -> dict:
-        """Get goal progress across all executions."""
-        if self._runtime is None:
-            raise RuntimeError("Agent runtime not started")
-        return await self._runtime.get_goal_progress()
-
-    def get_stats(self) -> dict:
-        """Get runtime statistics."""
-        if self._runtime is None:
-            return {"running": False}
-        return self._runtime.get_stats()
-
-    def info(self):
-        """Get agent information."""
-        return {
-            "name": metadata.name,
-            "version": metadata.version,
-            "description": metadata.description,
-            "goal": {
-                "name": self.goal.name,
-                "description": self.goal.description,
-            },
-            "nodes": [n.id for n in self.nodes],
-            "edges": [e.id for e in self.edges],
-            "entry_node": self.entry_node,
-            "entry_points": self.entry_points,
-            "pause_nodes": self.pause_nodes,
-            "terminal_nodes": self.terminal_nodes,
-            "multi_entrypoint": True,
-        }
-
-    def validate(self):
-        """Validate agent structure."""
-        errors = []
-        warnings = []
-
-        node_ids = {node.id for node in self.nodes}
-        for edge in self.edges:
-            if edge.source not in node_ids:
-                errors.append(f"Edge {edge.id}: source '{edge.source}' not found")
-            if edge.target not in node_ids:
-                errors.append(f"Edge {edge.id}: target '{edge.target}' not found")
-
-        if self.entry_node not in node_ids:
-            errors.append(f"Entry node '{self.entry_node}' not found")
-
-        for terminal in self.terminal_nodes:
-            if terminal not in node_ids:
-                errors.append(f"Terminal node '{terminal}' not found")
-
-        for pause in self.pause_nodes:
-            if pause not in node_ids:
-                errors.append(f"Pause node '{pause}' not found")
-
-        # Validate entry points
-        for ep_id, node_id in self.entry_points.items():
-            if node_id not in node_ids:
-                errors.append(
-                    f"Entry point '{ep_id}' references unknown node '{node_id}'"
-                )
-
-        return {
-            "valid": len(errors) == 0,
-            "errors": errors,
-            "warnings": warnings,
-        }
-
-
-# Create default instance
-default_agent = OnlineResearchAgent()

.claude/skills/building-agents-construction/examples/online_research_agent/nodes/__init__.py

@@ -1,396 +0,0 @@
-"""Node definitions for Online Research Agent."""
-
-from framework.graph import NodeSpec
-
-# Node 1: Parse Query
-parse_query_node = NodeSpec(
-    id="parse-query",
-    name="Parse Query",
-    description="Analyze the research topic and generate 3-5 diverse search queries to cover different aspects",
-    node_type="llm_generate",
-    input_keys=["topic"],
-    output_keys=["search_queries", "research_focus", "key_aspects"],
-    output_schema={
-        "research_focus": {
-            "type": "string",
-            "required": True,
-            "description": "Brief statement of what we're researching",
-        },
-        "key_aspects": {
-            "type": "array",
-            "required": True,
-            "description": "List of 3-5 key aspects to investigate",
-        },
-        "search_queries": {
-            "type": "array",
-            "required": True,
-            "description": "List of 3-5 search queries",
-        },
-    },
-    system_prompt="""\
-You are a research query strategist. Given a research topic, analyze it and generate search queries.
-
-Your task:
-1. Understand the core research question
-2. Identify 3-5 key aspects to investigate
-3. Generate 3-5 diverse search queries that will find comprehensive information
-
-CRITICAL: Return ONLY raw JSON. NO markdown, NO code blocks.
-
-Return this JSON structure:
-{
-  "research_focus": "Brief statement of what we're researching",
-  "key_aspects": ["aspect1", "aspect2", "aspect3"],
-  "search_queries": [
-    "query 1 - broad overview",
-    "query 2 - specific angle",
-    "query 3 - recent developments",
-    "query 4 - expert opinions",
-    "query 5 - data/statistics"
-  ]
-}
-""",
-    tools=[],
-    max_retries=3,
-)
-
-# Node 2: Search Sources
-search_sources_node = NodeSpec(
-    id="search-sources",
-    name="Search Sources",
-    description="Execute web searches using the generated queries to find 15+ source URLs",
-    node_type="llm_tool_use",
-    input_keys=["search_queries", "research_focus"],
-    output_keys=["source_urls", "search_results_summary"],
-    output_schema={
-        "source_urls": {
-            "type": "array",
-            "required": True,
-            "description": "List of source URLs found",
-        },
-        "search_results_summary": {
-            "type": "string",
-            "required": True,
-            "description": "Brief summary of what was found",
-        },
-    },
-    system_prompt="""\
-You are a research assistant executing web searches. Use the web_search tool to find sources.
-
-Your task:
-1. Execute each search query using web_search tool
-2. Collect URLs from search results
-3. Aim for 15+ diverse sources
-
-After searching, return JSON with found sources:
-{
-  "source_urls": ["url1", "url2", ...],
-  "search_results_summary": "Brief summary of what was found"
-}
-""",
-    tools=["web_search"],
-    max_retries=3,
-)
-
-# Node 3: Fetch Content
-fetch_content_node = NodeSpec(
-    id="fetch-content",
-    name="Fetch Content",
-    description="Fetch and extract content from the discovered source URLs",
-    node_type="llm_tool_use",
-    input_keys=["source_urls", "research_focus"],
-    output_keys=["fetched_sources", "fetch_errors"],
-    output_schema={
-        "fetched_sources": {
-            "type": "array",
-            "required": True,
-            "description": "List of fetched source objects with url, title, content",
-        },
-        "fetch_errors": {
-            "type": "array",
-            "required": True,
-            "description": "List of URLs that failed to fetch",
-        },
-    },
-    system_prompt="""\
-You are a content fetcher. Use web_scrape tool to retrieve content from URLs.
-
-Your task:
-1. Fetch content from each source URL using web_scrape tool
-2. Extract the main content relevant to the research focus
-3. Track any URLs that failed to fetch
-
-After fetching, return JSON:
-{
-  "fetched_sources": [
-    {"url": "...", "title": "...", "content": "extracted text..."},
-    ...
-  ],
-  "fetch_errors": ["url that failed", ...]
-}
-""",
-    tools=["web_scrape"],
-    max_retries=3,
-)
-
-# Node 4: Evaluate Sources
-evaluate_sources_node = NodeSpec(
-    id="evaluate-sources",
-    name="Evaluate Sources",
-    description="Score sources for relevance and quality, filter to top 10",
-    node_type="llm_generate",
-    input_keys=["fetched_sources", "research_focus", "key_aspects"],
-    output_keys=["ranked_sources", "source_analysis"],
-    output_schema={
-        "ranked_sources": {
-            "type": "array",
-            "required": True,
-            "description": "List of ranked sources with scores",
-        },
-        "source_analysis": {
-            "type": "string",
-            "required": True,
-            "description": "Overview of source quality and coverage",
-        },
-    },
-    system_prompt="""\
-You are a source evaluator. Assess each source for quality and relevance.
-
-Scoring criteria:
-- Relevance to research focus (1-10)
-- Source credibility (1-10)
-- Information depth (1-10)
-- Recency if relevant (1-10)
-
-Your task:
-1. Score each source
-2. Rank by combined score
-3. Select top 10 sources
-4. Note what each source uniquely contributes
-
-Return JSON:
-{
-  "ranked_sources": [
-    {"url": "...", "title": "...", "content": "...", "score": 8.5, "unique_value": "..."},
-    ...
-  ],
-  "source_analysis": "Overview of source quality and coverage"
-}
-""",
-    tools=[],
-    max_retries=3,
-)
-
-# Node 5: Synthesize Findings
-synthesize_findings_node = NodeSpec(
-    id="synthesize-findings",
-    name="Synthesize Findings",
-    description="Extract key facts from sources and identify common themes",
-    node_type="llm_generate",
-    input_keys=["ranked_sources", "research_focus", "key_aspects"],
-    output_keys=["key_findings", "themes", "source_citations"],
-    output_schema={
-        "key_findings": {
-            "type": "array",
-            "required": True,
-            "description": "List of key findings with sources and confidence",
-        },
-        "themes": {
-            "type": "array",
-            "required": True,
-            "description": "List of themes with descriptions and supporting sources",
-        },
-        "source_citations": {
-            "type": "object",
-            "required": True,
-            "description": "Map of facts to supporting URLs",
-        },
-    },
-    system_prompt="""\
-You are a research synthesizer. Analyze multiple sources to extract insights.
-
-Your task:
-1. Identify key facts from each source
-2. Find common themes across sources
-3. Note contradictions or debates
-4. Build a citation map (fact -> source URL)
-
-Return JSON:
-{
-  "key_findings": [
-    {"finding": "...", "sources": ["url1", "url2"], "confidence": "high/medium/low"},
-    ...
-  ],
-  "themes": [
-    {"theme": "...", "description": "...", "supporting_sources": ["url1", ...]},
-    ...
-  ],
-  "source_citations": {
-    "fact or claim": ["supporting url1", "url2"],
-    ...
-  }
-}
-""",
-    tools=[],
-    max_retries=3,
-)
-
-# Node 6: Write Report
-write_report_node = NodeSpec(
-    id="write-report",
-    name="Write Report",
-    description="Generate a narrative report with proper citations",
-    node_type="llm_generate",
-    input_keys=[
-        "key_findings",
-        "themes",
-        "source_citations",
-        "research_focus",
-        "ranked_sources",
-    ],
-    output_keys=["report_content", "references"],
-    output_schema={
-        "report_content": {
-            "type": "string",
-            "required": True,
-            "description": "Full markdown report text with citations",
-        },
-        "references": {
-            "type": "array",
-            "required": True,
-            "description": "List of reference objects with number, url, title",
-        },
-    },
-    system_prompt="""\
-You are a research report writer. Create a well-structured narrative report.
-
-Report structure:
-1. Executive Summary (2-3 paragraphs)
-2. Introduction (context and scope)
-3. Key Findings (organized by theme)
-4. Analysis (synthesis and implications)
-5. Conclusion
-6. References (numbered list of all sources)
-
-Citation format: Use numbered citations like [1], [2] that correspond to the References section.
-
-IMPORTANT:
-- Every factual claim MUST have a citation
-- Write in clear, professional prose
-- Be objective and balanced
-- Highlight areas of consensus and debate
-
-Return JSON:
-{
-  "report_content": "Full markdown report text with citations...",
-  "references": [
-    {"number": 1, "url": "...", "title": "..."},
-    ...
-  ]
-}
-""",
-    tools=[],
-    max_retries=3,
-)
-
-# Node 7: Quality Check
-quality_check_node = NodeSpec(
-    id="quality-check",
-    name="Quality Check",
-    description="Verify all claims have citations and report is coherent",
-    node_type="llm_generate",
-    input_keys=["report_content", "references", "source_citations"],
-    output_keys=["quality_score", "issues", "final_report"],
-    output_schema={
-        "quality_score": {
-            "type": "number",
-            "required": True,
-            "description": "Quality score 0-1",
-        },
-        "issues": {
-            "type": "array",
-            "required": True,
-            "description": "List of issues found and fixed",
-        },
-        "final_report": {
-            "type": "string",
-            "required": True,
-            "description": "Corrected full report",
-        },
-    },
-    system_prompt="""\
-You are a quality assurance reviewer. Check the research report for issues.
-
-Check for:
-1. Uncited claims (factual statements without [n] citation)
-2. Broken citations (references to non-existent numbers)
-3. Coherence (logical flow between sections)
-4. Completeness (all key aspects covered)
-5. Accuracy (claims match source content)
-
-If issues found, fix them in the final report.
-
-Return JSON:
-{
-  "quality_score": 0.95,
-  "issues": [
-    {"type": "uncited_claim", "location": "paragraph 3", "fixed": true},
-    ...
-  ],
-  "final_report": "Corrected full report with all issues fixed..."
-}
-""",
-    tools=[],
-    max_retries=3,
-)
-
-# Node 8: Save Report
-save_report_node = NodeSpec(
-    id="save-report",
-    name="Save Report",
-    description="Write the final report to a local markdown file",
-    node_type="llm_tool_use",
-    input_keys=["final_report", "references", "research_focus"],
-    output_keys=["file_path", "save_status"],
-    output_schema={
-        "file_path": {
-            "type": "string",
-            "required": True,
-            "description": "Path where report was saved",
-        },
-        "save_status": {
-            "type": "string",
-            "required": True,
-            "description": "Status of save operation",
-        },
-    },
-    system_prompt="""\
-You are a file manager. Save the research report to disk.
-
-Your task:
-1. Generate a filename from the research focus (slugified, with date)
-2. Use the write_to_file tool to save the report as markdown
-3. Save to the ./research_reports/ directory
-
-Filename format: research_YYYY-MM-DD_topic-slug.md
-
-Return JSON:
-{
-  "file_path": "research_reports/research_2026-01-23_topic-name.md",
-  "save_status": "success"
-}
-""",
-    tools=["write_to_file"],
-    max_retries=3,
-)
-
-__all__ = [
-    "parse_query_node",
-    "search_sources_node",
-    "fetch_content_node",
-    "evaluate_sources_node",
-    "synthesize_findings_node",
-    "write_report_node",
-    "quality_check_node",
-    "save_report_node",
-]

.claude/skills/building-agents-core/SKILL.md

@@ -1,303 +0,0 @@
----
-name: building-agents-core
-description: Core concepts for goal-driven agents - architecture, node types, tool discovery, and workflow overview. Use when starting agent development or need to understand agent fundamentals.
-license: Apache-2.0
-metadata:
-  author: hive
-  version: "1.0"
-  type: foundational
-  part_of: building-agents
----
-
-# Building Agents - Core Concepts
-
-Foundational knowledge for building goal-driven agents as Python packages.
-
-## Architecture: Python Services (Not JSON Configs)
-
-Agents are built as Python packages:
-
-```
-exports/my_agent/
-├── __init__.py          # Package exports
-├── __main__.py          # CLI (run, info, validate, shell)
-├── agent.py             # Graph construction (goal, edges, agent class)
-├── nodes/__init__.py    # Node definitions (NodeSpec)
-├── config.py            # Runtime config
-└── README.md            # Documentation
-```
-
-**Key Principle: Agent is visible and editable during build**
-
-- ✅ Files created immediately as components are approved
-- ✅ User can watch files grow in their editor
-- ✅ No session state - just direct file writes
-- ✅ No "export" step - agent is ready when build completes
-
-## Core Concepts
-
-### Goal
-
-Success criteria and constraints (written to agent.py)
-
-```python
-goal = Goal(
-    id="research-goal",
-    name="Technical Research Agent",
-    description="Research technical topics thoroughly",
-    success_criteria=[
-        SuccessCriterion(
-            id="completeness",
-            description="Cover all aspects of topic",
-            metric="coverage_score",
-            target=">=0.9",
-            weight=0.4,
-        ),
-        # 3-5 success criteria total
-    ],
-    constraints=[
-        Constraint(
-            id="accuracy",
-            description="All information must be verified",
-            constraint_type="hard",
-            category="quality",
-        ),
-        # 1-5 constraints total
-    ],
-)
-```
-
-### Node
-
-Unit of work (written to nodes/__init__.py)
-
-**Node Types:**
-
-- `llm_generate` - Text generation, parsing
-- `llm_tool_use` - Actions requiring tools
-- `router` - Conditional branching
-- `function` - Deterministic operations
-
-```python
-search_node = NodeSpec(
-    id="search-web",
-    name="Search Web",
-    description="Search for information online",
-    node_type="llm_tool_use",
-    input_keys=["query"],
-    output_keys=["search_results"],
-    system_prompt="Search the web for: {query}",
-    tools=["web_search"],
-    max_retries=3,
-)
-```
-
-### Edge
-
-Connection between nodes (written to agent.py)
-
-**Edge Conditions:**
-
-- `on_success` - Proceed if node succeeds
-- `on_failure` - Handle errors
-- `always` - Always proceed
-- `conditional` - Based on expression
-
-```python
-EdgeSpec(
-    id="search-to-analyze",
-    source="search-web",
-    target="analyze-results",
-    condition=EdgeCondition.ON_SUCCESS,
-    priority=1,
-)
-```
-
-### Pause/Resume
-
-Multi-turn conversations
-
-- **Pause nodes** - Stop execution, wait for user input
-- **Resume entry points** - Continue from pause with user's response
-
-```python
-# Example pause/resume configuration
-pause_nodes = ["request-clarification"]
-entry_points = {
-    "start": "analyze-request",
-    "request-clarification_resume": "process-clarification"
-}
-```
-
-## Tool Discovery & Validation
-
-**CRITICAL:** Before adding a node with tools, you MUST verify the tools exist.
-
-Tools are provided by MCP servers. Never assume a tool exists - always discover dynamically.
-
-### Step 1: Register MCP Server (if not already done)
-
-```python
-mcp__agent-builder__add_mcp_server(
-    name="tools",
-    transport="stdio",
-    command="python",
-    args='["mcp_server.py", "--stdio"]',
-    cwd="../tools"
-)
-```
-
-### Step 2: Discover Available Tools
-
-```python
-# List all tools from all registered servers
-mcp__agent-builder__list_mcp_tools()
-
-# Or list tools from a specific server
-mcp__agent-builder__list_mcp_tools(server_name="tools")
-```
-
-This returns available tools with their descriptions and parameters:
-
-```json
-{
-  "success": true,
-  "tools_by_server": {
-    "tools": [
-      {
-        "name": "web_search",
-        "description": "Search the web...",
-        "parameters": ["query"]
-      },
-      {
-        "name": "web_scrape",
-        "description": "Scrape a URL...",
-        "parameters": ["url"]
-      }
-    ]
-  },
-  "total_tools": 14
-}
-```
-
-### Step 3: Validate Before Adding Nodes
-
-Before writing a node with `tools=[...]`:
-
-1. Call `list_mcp_tools()` to get available tools
-2. Check each tool in your node exists in the response
-3. If a tool doesn't exist:
-   - **DO NOT proceed** with the node
-   - Inform the user: "The tool 'X' is not available. Available tools are: ..."
-   - Ask if they want to use an alternative or proceed without the tool
-
-### Tool Validation Anti-Patterns
-
-❌ **Never assume a tool exists** - always call `list_mcp_tools()` first
-❌ **Never write a node with unverified tools** - validate before writing
-❌ **Never silently drop tools** - if a tool doesn't exist, inform the user
-❌ **Never guess tool names** - use exact names from discovery response
-
-### Example Validation Flow
-
-```python
-# 1. User requests: "Add a node that searches the web"
-# 2. Discover available tools
-tools_response = mcp__agent-builder__list_mcp_tools()
-
-# 3. Check if web_search exists
-available = [t["name"] for tools in tools_response["tools_by_server"].values() for t in tools]
-if "web_search" not in available:
-    # Inform user and ask how to proceed
-    print("❌ 'web_search' not available. Available tools:", available)
-else:
-    # Proceed with node creation
-    # ...
-```
-
-## Workflow Overview: Incremental File Construction
-
-```
-1. CREATE PACKAGE → mkdir + write skeletons
-2. DEFINE GOAL → Write to agent.py + config.py
-3. FOR EACH NODE:
-   - Propose design
-   - User approves
-   - Write to nodes/__init__.py IMMEDIATELY ← FILE WRITTEN
-   - (Optional) Validate with test_node ← MCP VALIDATION
-   - User can open file and see it
-4. CONNECT EDGES → Update agent.py ← FILE WRITTEN
-   - (Optional) Validate with validate_graph ← MCP VALIDATION
-5. FINALIZE → Write agent class to agent.py ← FILE WRITTEN
-6. DONE - Agent ready at exports/my_agent/
-```
-
-**Files written immediately. MCP tools optional for validation/testing bookkeeping.**
-
-### The Key Difference
-
-**OLD (Bad):**
-
-```
-MCP add_node → Session State → MCP add_node → Session State → ...
-                                                                ↓
-                                                     MCP export_graph
-                                                                ↓
-                                                       Files appear
-```
-
-**NEW (Good):**
-
-```
-Write node to file → (Optional: MCP test_node) → Write node to file → ...
-       ↓                                               ↓
-  File visible                                    File visible
-  immediately                                     immediately
-```
-
-**Bottom line:** Use Write/Edit for construction, MCP for validation if needed.
-
-## When to Use This Skill
-
-Use building-agents-core when:
-- Starting a new agent project and need to understand fundamentals
-- Need to understand agent architecture before building
-- Want to validate tool availability before proceeding
-- Learning about node types, edges, and graph execution
-
-**Next Steps:**
-- Ready to build? → Use `building-agents-construction` skill
-- Need patterns and examples? → Use `building-agents-patterns` skill
-
-## MCP Tools for Validation
-
-After writing files, optionally use MCP tools for validation:
-
-**test_node** - Validate node configuration with mock inputs
-```python
-mcp__agent-builder__test_node(
-    node_id="search-web",
-    test_input='{"query": "test query"}',
-    mock_llm_response='{"results": "mock output"}'
-)
-```
-
-**validate_graph** - Check graph structure
-```python
-mcp__agent-builder__validate_graph()
-# Returns: unreachable nodes, missing connections, etc.
-```
-
-**create_session** - Track session state for bookkeeping
-```python
-mcp__agent-builder__create_session(session_name="my-build")
-```
-
-**Key Point:** Files are written FIRST. MCP tools are for validation only.
-
-## Related Skills
-
-- **building-agents-construction** - Step-by-step building process
-- **building-agents-patterns** - Best practices and examples
-- **agent-workflow** - Complete workflow orchestrator
-- **testing-agent** - Test and validate completed agents

.claude/skills/building-agents-patterns/SKILL.md

@@ -1,497 +0,0 @@
----
-name: building-agents-patterns
-description: Best practices, patterns, and examples for building goal-driven agents. Includes pause/resume architecture, hybrid workflows, anti-patterns, and handoff to testing. Use when optimizing agent design.
-license: Apache-2.0
-metadata:
-  author: hive
-  version: "1.0"
-  type: reference
-  part_of: building-agents
----
-
-# Building Agents - Patterns & Best Practices
-
-Design patterns, examples, and best practices for building robust goal-driven agents.
-
-**Prerequisites:** Complete agent structure using `building-agents-construction`.
-
-## Practical Example: Hybrid Workflow
-
-How to build a node using both direct file writes and optional MCP validation:
-
-```python
-# 1. WRITE TO FILE FIRST (Primary - makes it visible)
-node_code = '''
-search_node = NodeSpec(
-    id="search-web",
-    node_type="llm_tool_use",
-    input_keys=["query"],
-    output_keys=["search_results"],
-    system_prompt="Search the web for: {query}",
-    tools=["web_search"],
-)
-'''
-
-Edit(
-    file_path="exports/research_agent/nodes/__init__.py",
-    old_string="# Nodes will be added here",
-    new_string=node_code
-)
-
-print("✅ Added search_node to nodes/__init__.py")
-print("📁 Open exports/research_agent/nodes/__init__.py to see it!")
-
-# 2. OPTIONALLY VALIDATE WITH MCP (Secondary - bookkeeping)
-validation = mcp__agent-builder__test_node(
-    node_id="search-web",
-    test_input='{"query": "python tutorials"}',
-    mock_llm_response='{"search_results": [...mock results...]}'
-)
-
-print(f"✓ Validation: {validation['success']}")
-```
-
-**User experience:**
-
-- Immediately sees node in their editor (from step 1)
-- Gets validation feedback (from step 2)
-- Can edit the file directly if needed
-
-This combines visibility (files) with validation (MCP tools).
-
-## Pause/Resume Architecture
-
-For agents needing multi-turn conversations with user interaction:
-
-### Basic Pause/Resume Flow
-
-```python
-# Define pause nodes - execution stops at these nodes
-pause_nodes = ["request-clarification", "await-approval"]
-
-# Define entry points - where to resume from each pause
-entry_points = {
-    "start": "analyze-request",  # Initial entry
-    "request-clarification_resume": "process-clarification",  # Resume from clarification
-    "await-approval_resume": "execute-action",  # Resume from approval
-}
-```
-
-### Example: Multi-Turn Research Agent
-
-```python
-# Nodes
-nodes = [
-    NodeSpec(id="analyze-request", ...),
-    NodeSpec(id="request-clarification", ...),  # PAUSE NODE
-    NodeSpec(id="process-clarification", ...),
-    NodeSpec(id="generate-results", ...),
-    NodeSpec(id="await-approval", ...),  # PAUSE NODE
-    NodeSpec(id="execute-action", ...),
-]
-
-# Edges with resume flows
-edges = [
-    EdgeSpec(
-        id="analyze-to-clarify",
-        source="analyze-request",
-        target="request-clarification",
-        condition=EdgeCondition.CONDITIONAL,
-        condition_expr="needs_clarification == true",
-    ),
-    # When resumed, goes to process-clarification
-    EdgeSpec(
-        id="clarify-to-process",
-        source="request-clarification",
-        target="process-clarification",
-        condition=EdgeCondition.ALWAYS,
-    ),
-    EdgeSpec(
-        id="results-to-approval",
-        source="generate-results",
-        target="await-approval",
-        condition=EdgeCondition.ALWAYS,
-    ),
-    # When resumed, goes to execute-action
-    EdgeSpec(
-        id="approval-to-execute",
-        source="await-approval",
-        target="execute-action",
-        condition=EdgeCondition.ALWAYS,
-    ),
-]
-
-# Configuration
-pause_nodes = ["request-clarification", "await-approval"]
-entry_points = {
-    "start": "analyze-request",
-    "request-clarification_resume": "process-clarification",
-    "await-approval_resume": "execute-action",
-}
-```
-
-### Running Pause/Resume Agents
-
-```python
-# Initial run - will pause at first pause node
-result1 = await agent.run(
-    context={"query": "research topic"},
-    session_state=None
-)
-
-# Check if paused
-if result1.paused_at:
-    print(f"Paused at: {result1.paused_at}")
-
-    # Resume with user input
-    result2 = await agent.run(
-        context={"user_response": "clarification details"},
-        session_state=result1.session_state  # Pass previous state
-    )
-```
-
-## Anti-Patterns
-
-### What NOT to Do
-
-❌ **Don't rely on `export_graph`** - Write files immediately, not at end
-```python
-# BAD: Building in session state, exporting at end
-mcp__agent-builder__add_node(...)
-mcp__agent-builder__add_node(...)
-mcp__agent-builder__export_graph()  # Files appear only now
-
-# GOOD: Writing files immediately
-Write(file_path="...", content=node_code)  # File visible now
-Write(file_path="...", content=node_code)  # File visible now
-```
-
-❌ **Don't hide code in session** - Write to files as components approved
-```python
-# BAD: Accumulating changes invisibly
-session.add_component(component1)
-session.add_component(component2)
-# User can't see anything yet
-
-# GOOD: Incremental visibility
-Edit(file_path="...", ...)  # User sees change 1
-Edit(file_path="...", ...)  # User sees change 2
-```
-
-❌ **Don't wait to write files** - Agent visible from first step
-```python
-# BAD: Building everything before writing
-design_all_nodes()
-design_all_edges()
-write_everything_at_once()
-
-# GOOD: Write as you go
-write_package_structure()  # Visible
-write_goal()  # Visible
-write_node_1()  # Visible
-write_node_2()  # Visible
-```
-
-❌ **Don't batch everything** - Write incrementally
-```python
-# BAD: Batching all nodes
-nodes = [design_node_1(), design_node_2(), ...]
-write_all_nodes(nodes)
-
-# GOOD: One at a time with user feedback
-write_node_1()  # User approves
-write_node_2()  # User approves
-write_node_3()  # User approves
-```
-
-### MCP Tools - Correct Usage
-
-**MCP tools OK for:**
-✅ `test_node` - Validate node configuration with mock inputs
-✅ `validate_graph` - Check graph structure
-✅ `create_session` - Track session state for bookkeeping
-✅ Other validation tools
-
-**Just don't:** Use MCP as the primary construction method or rely on export_graph
-
-## Best Practices
-
-### 1. Show Progress After Each Write
-
-```python
-# After writing a node
-print("✅ Added analyze_request_node to nodes/__init__.py")
-print("📊 Progress: 1/6 nodes added")
-print("📁 Open exports/my_agent/nodes/__init__.py to see it!")
-```
-
-### 2. Let User Open Files During Build
-
-```python
-# Encourage file inspection
-print("✅ Goal written to agent.py")
-print("")
-print("💡 Tip: Open exports/my_agent/agent.py in your editor to see the goal!")
-```
-
-### 3. Write Incrementally - One Component at a Time
-
-```python
-# Good flow
-write_package_structure()
-show_user("Package created")
-
-write_goal()
-show_user("Goal written")
-
-for node in nodes:
-    get_approval(node)
-    write_node(node)
-    show_user(f"Node {node.id} written")
-```
-
-### 4. Test As You Build
-
-```python
-# After adding several nodes
-print("💡 You can test current state with:")
-print("  PYTHONPATH=core:exports python -m my_agent validate")
-print("  PYTHONPATH=core:exports python -m my_agent info")
-```
-
-### 5. Keep User Informed
-
-```python
-# Clear status updates
-print("🔨 Creating package structure...")
-print("✅ Package created: exports/my_agent/")
-print("")
-print("📝 Next: Define agent goal")
-```
-
-## Continuous Monitoring Agents
-
-For agents that run continuously without terminal nodes:
-
-```python
-# No terminal nodes - loops forever
-terminal_nodes = []
-
-# Workflow loops back to start
-edges = [
-    EdgeSpec(id="monitor-to-check", source="monitor", target="check-condition"),
-    EdgeSpec(id="check-to-wait", source="check-condition", target="wait"),
-    EdgeSpec(id="wait-to-monitor", source="wait", target="monitor"),  # Loop
-]
-
-# Entry node only
-entry_node = "monitor"
-entry_points = {"start": "monitor"}
-pause_nodes = []
-```
-
-**Example: File Monitor**
-
-```python
-nodes = [
-    NodeSpec(id="list-files", ...),
-    NodeSpec(id="check-new-files", node_type="router", ...),
-    NodeSpec(id="process-files", ...),
-    NodeSpec(id="wait-interval", node_type="function", ...),
-]
-
-edges = [
-    EdgeSpec(id="list-to-check", source="list-files", target="check-new-files"),
-    EdgeSpec(
-        id="check-to-process",
-        source="check-new-files",
-        target="process-files",
-        condition=EdgeCondition.CONDITIONAL,
-        condition_expr="new_files_count > 0",
-    ),
-    EdgeSpec(
-        id="check-to-wait",
-        source="check-new-files",
-        target="wait-interval",
-        condition=EdgeCondition.CONDITIONAL,
-        condition_expr="new_files_count == 0",
-    ),
-    EdgeSpec(id="process-to-wait", source="process-files", target="wait-interval"),
-    EdgeSpec(id="wait-to-list", source="wait-interval", target="list-files"),  # Loop back
-]
-
-terminal_nodes = []  # No terminal - runs forever
-```
-
-## Complex Routing Patterns
-
-### Multi-Condition Router
-
-```python
-router_node = NodeSpec(
-    id="decision-router",
-    node_type="router",
-    input_keys=["analysis_result"],
-    output_keys=["decision"],
-    system_prompt="""
-    Based on the analysis result, decide the next action:
-    - If confidence > 0.9: route to "execute"
-    - If 0.5 <= confidence <= 0.9: route to "review"
-    - If confidence < 0.5: route to "clarify"
-
-    Return: {"decision": "execute|review|clarify"}
-    """,
-)
-
-# Edges for each route
-edges = [
-    EdgeSpec(
-        id="router-to-execute",
-        source="decision-router",
-        target="execute-action",
-        condition=EdgeCondition.CONDITIONAL,
-        condition_expr="decision == 'execute'",
-        priority=1,
-    ),
-    EdgeSpec(
-        id="router-to-review",
-        source="decision-router",
-        target="human-review",
-        condition=EdgeCondition.CONDITIONAL,
-        condition_expr="decision == 'review'",
-        priority=2,
-    ),
-    EdgeSpec(
-        id="router-to-clarify",
-        source="decision-router",
-        target="request-clarification",
-        condition=EdgeCondition.CONDITIONAL,
-        condition_expr="decision == 'clarify'",
-        priority=3,
-    ),
-]
-```
-
-## Error Handling Patterns
-
-### Graceful Failure with Fallback
-
-```python
-# Primary node with error handling
-nodes = [
-    NodeSpec(id="api-call", max_retries=3, ...),
-    NodeSpec(id="fallback-cache", ...),
-    NodeSpec(id="report-error", ...),
-]
-
-edges = [
-    # Success path
-    EdgeSpec(
-        id="api-success",
-        source="api-call",
-        target="process-results",
-        condition=EdgeCondition.ON_SUCCESS,
-    ),
-    # Fallback on failure
-    EdgeSpec(
-        id="api-to-fallback",
-        source="api-call",
-        target="fallback-cache",
-        condition=EdgeCondition.ON_FAILURE,
-        priority=1,
-    ),
-    # Report if fallback also fails
-    EdgeSpec(
-        id="fallback-to-error",
-        source="fallback-cache",
-        target="report-error",
-        condition=EdgeCondition.ON_FAILURE,
-        priority=1,
-    ),
-]
-```
-
-## Performance Optimization
-
-### Parallel Node Execution
-
-```python
-# Use multiple edges from same source for parallel execution
-edges = [
-    EdgeSpec(
-        id="start-to-search1",
-        source="start",
-        target="search-source-1",
-        condition=EdgeCondition.ALWAYS,
-    ),
-    EdgeSpec(
-        id="start-to-search2",
-        source="start",
-        target="search-source-2",
-        condition=EdgeCondition.ALWAYS,
-    ),
-    EdgeSpec(
-        id="start-to-search3",
-        source="start",
-        target="search-source-3",
-        condition=EdgeCondition.ALWAYS,
-    ),
-    # Converge results
-    EdgeSpec(
-        id="search1-to-merge",
-        source="search-source-1",
-        target="merge-results",
-    ),
-    EdgeSpec(
-        id="search2-to-merge",
-        source="search-source-2",
-        target="merge-results",
-    ),
-    EdgeSpec(
-        id="search3-to-merge",
-        source="search-source-3",
-        target="merge-results",
-    ),
-]
-```
-
-## Handoff to Testing
-
-When agent is complete, transition to testing phase:
-
-```python
-print("""
-✅ Agent complete: exports/my_agent/
-
-Next steps:
-1. Switch to testing-agent skill
-2. Generate and approve tests
-3. Run evaluation
-4. Debug any failures
-
-Command: "Test the agent at exports/my_agent/"
-""")
-```
-
-### Pre-Testing Checklist
-
-Before handing off to testing-agent:
-
-- [ ] Agent structure validates: `python -m agent_name validate`
-- [ ] All nodes defined in nodes/__init__.py
-- [ ] All edges connect valid nodes
-- [ ] Entry node specified
-- [ ] Agent can be imported: `from exports.agent_name import default_agent`
-- [ ] README.md with usage instructions
-- [ ] CLI commands work (info, validate)
-
-## Related Skills
-
-- **building-agents-core** - Fundamental concepts
-- **building-agents-construction** - Step-by-step building
-- **testing-agent** - Test and validate agents
-- **agent-workflow** - Complete workflow orchestrator
-
----
-
-**Remember: Agent is actively constructed, visible the whole time. No hidden state. No surprise exports. Just transparent, incremental file building.**

.claude/skills/setup-credentials/SKILL.md

@@ -1,649 +0,0 @@
----
-name: setup-credentials
-description: Set up and install credentials for an agent. Detects missing credentials from agent config, collects them from the user, and stores them securely in the local encrypted store at ~/.hive/credentials.
-license: Apache-2.0
-metadata:
-  author: hive
-  version: "2.2"
-  type: utility
----
-
-# Setup Credentials
-
-Interactive credential setup for agents with multiple authentication options. Detects what's missing, offers auth method choices, validates with health checks, and stores credentials securely.
-
-## When to Use
-
-- Before running or testing an agent for the first time
-- When `AgentRunner.run()` fails with "missing required credentials"
-- When a user asks to configure credentials for an agent
-- After building a new agent that uses tools requiring API keys
-
-## Workflow
-
-### Step 1: Identify the Agent
-
-Determine which agent needs credentials. The user will either:
-
-- Name the agent directly (e.g., "set up credentials for hubspot-agent")
-- Have an agent directory open (check `exports/` for agent dirs)
-- Be working on an agent in the current session
-
-Locate the agent's directory under `exports/{agent_name}/`.
-
-### Step 2: Detect Required Credentials (Bash-First)
-
-Use bash commands to determine what the agent needs and what's already configured. This avoids Python import issues and works even when `HIVE_CREDENTIAL_KEY` is not set.
-
-#### Step 2a: Read Agent Requirements
-
-Extract `required_tools` and node types from the agent config:
-
-```bash
-# Get required tools
-jq -r '.required_tools[]?' exports/{agent_name}/agent.json 2>/dev/null
-
-# Get node types from graph nodes
-jq -r '.graph.nodes[]?.node_type' exports/{agent_name}/agent.json 2>/dev/null | sort -u
-```
-
-Map the extracted tools and node types to credentials by reading the spec files directly:
-
-```bash
-# Read all credential specs — each file defines tools, node_types, env_var, and credential_id
-cat tools/src/aden_tools/credentials/llm.py tools/src/aden_tools/credentials/search.py tools/src/aden_tools/credentials/email.py tools/src/aden_tools/credentials/integrations.py
-```
-
-For each `CredentialSpec`, match its `tools` and `node_types` lists against the agent's required tools and node types. Extract the `env_var`, `credential_id`, and `credential_group` for every match. This is the list of needed credentials.
-
-#### Step 2b: Check Existing Credential Sources
-
-For each needed credential, check three sources. A credential is "found" if it exists in ANY of them:
-
-**1. Encrypted store metadata index** (unencrypted JSON — no decryption key needed):
-
-```bash
-cat ~/.hive/credentials/metadata/index.json 2>/dev/null | jq -r '.credentials | keys[]'
-```
-
-If a credential ID appears in this list, it is stored in the encrypted store.
-
-**2. Environment variables:**
-
-```bash
-# Check each needed env var, e.g.:
-printenv ANTHROPIC_API_KEY > /dev/null 2>&1 && echo "ANTHROPIC_API_KEY: set" || echo "ANTHROPIC_API_KEY: not set"
-printenv BRAVE_SEARCH_API_KEY > /dev/null 2>&1 && echo "BRAVE_SEARCH_API_KEY: set" || echo "BRAVE_SEARCH_API_KEY: not set"
-```
-
-**3. Project `.env` file:**
-
-```bash
-# Check each needed env var, e.g.:
-grep -q '^ANTHROPIC_API_KEY=' .env 2>/dev/null && echo "ANTHROPIC_API_KEY: in .env" || echo "ANTHROPIC_API_KEY: not in .env"
-grep -q '^BRAVE_SEARCH_API_KEY=' .env 2>/dev/null && echo "BRAVE_SEARCH_API_KEY: in .env" || echo "BRAVE_SEARCH_API_KEY: not in .env"
-```
-
-#### Step 2c: HIVE_CREDENTIAL_KEY Check
-
-If any credentials were found in the encrypted store metadata index, verify the encryption key is available. The key is typically persisted to shell config by a previous setup-credentials run.
-
-Check both the current session AND shell config files:
-
-```bash
-# Check 1: Current session
-printenv HIVE_CREDENTIAL_KEY > /dev/null 2>&1 && echo "session: set" || echo "session: not set"
-
-# Check 2: Shell config files (where setup-credentials persists it)
-# Note: check each file individually to avoid non-zero exit when one doesn't exist
-for f in ~/.zshrc ~/.bashrc ~/.profile; do [ -f "$f" ] && grep -q 'HIVE_CREDENTIAL_KEY' "$f" && echo "$f"; done
-```
-
-Decision logic:
-- **In current session** — no action needed, credentials in the store are usable
-- **In shell config but NOT in current session** — the key is persisted but this shell hasn't sourced it. Run `source ~/.zshrc` (or `~/.bashrc`), then re-check. Credentials in the store are usable after sourcing.
-- **Not in session AND not in shell config** — the key was never persisted. Warn the user that credentials in the store cannot be decrypted. Help fix the key situation (recover/re-persist), do NOT re-collect credential values that are already stored.
-
-#### Step 2d: Compute Missing & Group
-
-Diff the "needed" credentials against the "found" credentials to get the truly missing list.
-
-Group related credentials by their `credential_group` field from the spec files. Credentials that share the same non-empty `credential_group` value should be presented as a single setup step rather than asking for each one individually.
-
-**If nothing is missing and there's no HIVE_CREDENTIAL_KEY issue:** Report all credentials as configured and skip Steps 3-5. Example:
-
-```
-All required credentials are already configured:
-  ✓ anthropic (ANTHROPIC_API_KEY) — found in encrypted store
-  ✓ brave_search (BRAVE_SEARCH_API_KEY) — found in environment
-Your agent is ready to run!
-```
-
-**If credentials are missing:** Continue to Step 3 with only the missing ones.
-
-### Step 3: Present Auth Options for Each Missing Credential
-
-For each missing credential, check what authentication methods are available:
-
-```python
-from aden_tools.credentials import CREDENTIAL_SPECS
-
-spec = CREDENTIAL_SPECS.get("hubspot")
-if spec:
-    # Determine available auth options
-    auth_options = []
-    if spec.aden_supported:
-        auth_options.append("aden")
-    if spec.direct_api_key_supported:
-        auth_options.append("direct")
-    auth_options.append("custom")  # Always available
-
-    # Get setup info
-    setup_info = {
-        "env_var": spec.env_var,
-        "description": spec.description,
-        "help_url": spec.help_url,
-        "api_key_instructions": spec.api_key_instructions,
-    }
-```
-
-Present the available options using AskUserQuestion:
-
-```
-Choose how to configure HUBSPOT_ACCESS_TOKEN:
-
-  1) Aden Platform (OAuth) (Recommended)
-     Secure OAuth2 flow via integration.adenhq.com
-     - Quick setup with automatic token refresh
-     - No need to manage API keys manually
-
-  2) Direct API Key
-     Enter your own API key manually
-     - Requires creating a HubSpot Private App
-     - Full control over scopes and permissions
-
-  3) Local Credential Setup (Advanced)
-     Programmatic configuration for CI/CD
-     - For automated deployments
-     - Requires manual API calls
-```
-
-### Step 4: Execute Auth Flow Based on User Choice
-
-#### Option 1: Aden Platform (OAuth)
-
-This is the recommended flow for supported integrations (HubSpot, etc.).
-
-**How Aden OAuth Works:**
-
-The ADEN_API_KEY represents a user who has already completed OAuth authorization on Aden's platform. When users sign up and connect integrations on Aden, those OAuth tokens are stored server-side. Having an ADEN_API_KEY means:
-
-1. User has an Aden account
-2. User has already authorized integrations (HubSpot, etc.) via OAuth on Aden
-3. We just need to sync those credentials down to the local credential store
-
-**4.1a. Check for ADEN_API_KEY**
-
-```python
-import os
-aden_key = os.environ.get("ADEN_API_KEY")
-```
-
-If not set, guide user to get one from Aden (this is where they do OAuth):
-
-```python
-from aden_tools.credentials import open_browser, get_aden_setup_url
-
-# Open browser to Aden - user will sign up and connect integrations there
-url = get_aden_setup_url()  # https://integration.adenhq.com/setup
-success, msg = open_browser(url)
-
-print("Please sign in to Aden and connect your integrations (HubSpot, etc.).")
-print("Once done, copy your API key and return here.")
-```
-
-Ask user to provide the ADEN_API_KEY they received.
-
-**4.1b. Save ADEN_API_KEY to Shell Config**
-
-With user approval, persist ADEN_API_KEY to their shell config:
-
-```python
-from aden_tools.credentials import (
-    detect_shell,
-    add_env_var_to_shell_config,
-    get_shell_source_command,
-)
-
-shell_type = detect_shell()  # 'bash', 'zsh', or 'unknown'
-
-# Ask user for approval before modifying shell config
-# If approved:
-success, config_path = add_env_var_to_shell_config(
-    "ADEN_API_KEY",
-    user_provided_key,
-    comment="Aden Platform (OAuth) API key"
-)
-
-if success:
-    source_cmd = get_shell_source_command()
-    print(f"Saved to {config_path}")
-    print(f"Run: {source_cmd}")
-```
-
-Also save to `~/.hive/configuration.json` for the framework:
-
-```python
-import json
-from pathlib import Path
-
-config_path = Path.home() / ".hive" / "configuration.json"
-config = json.loads(config_path.read_text()) if config_path.exists() else {}
-
-config["aden"] = {
-    "api_key_configured": True,
-    "api_url": "https://api.adenhq.com"
-}
-
-config_path.parent.mkdir(parents=True, exist_ok=True)
-config_path.write_text(json.dumps(config, indent=2))
-```
-
-**4.1c. Sync Credentials from Aden Server**
-
-Since the user has already authorized integrations on Aden, use the one-liner factory method:
-
-```python
-from core.framework.credentials import CredentialStore
-
-# This single call handles everything:
-# - Creates encrypted local storage at ~/.hive/credentials
-# - Configures Aden client from ADEN_API_KEY env var
-# - Syncs all credentials from Aden server automatically
-store = CredentialStore.with_aden_sync(
-    base_url="https://api.adenhq.com",
-    auto_sync=True,  # Syncs on creation
-)
-
-# Check what was synced
-synced = store.list_credentials()
-print(f"Synced credentials: {synced}")
-
-# If the required credential wasn't synced, the user hasn't authorized it on Aden yet
-if "hubspot" not in synced:
-    print("HubSpot not found in your Aden account.")
-    print("Please visit https://integration.adenhq.com to connect HubSpot, then try again.")
-```
-
-For more control over the sync process:
-
-```python
-from core.framework.credentials import CredentialStore
-from core.framework.credentials.aden import (
-    AdenCredentialClient,
-    AdenClientConfig,
-    AdenSyncProvider,
-)
-
-# Create client (API key loaded from ADEN_API_KEY env var)
-client = AdenCredentialClient(AdenClientConfig(
-    base_url="https://api.adenhq.com",
-))
-
-# Create provider and store
-provider = AdenSyncProvider(client=client)
-store = CredentialStore.with_encrypted_storage()
-
-# Manual sync
-synced_count = provider.sync_all(store)
-print(f"Synced {synced_count} credentials from Aden")
-```
-
-**4.1d. Run Health Check**
-
-```python
-from aden_tools.credentials import check_credential_health
-
-# Get the token from the store
-cred = store.get_credential("hubspot")
-token = cred.keys["access_token"].value.get_secret_value()
-
-result = check_credential_health("hubspot", token)
-if result.valid:
-    print("HubSpot credentials validated successfully!")
-else:
-    print(f"Validation failed: {result.message}")
-    # Offer to retry the OAuth flow
-```
-
-#### Option 2: Direct API Key
-
-For users who prefer manual API key management.
-
-**4.2a. Show Setup Instructions**
-
-```python
-from aden_tools.credentials import CREDENTIAL_SPECS
-
-spec = CREDENTIAL_SPECS.get("hubspot")
-if spec and spec.api_key_instructions:
-    print(spec.api_key_instructions)
-# Output:
-# To get a HubSpot Private App token:
-# 1. Go to HubSpot Settings > Integrations > Private Apps
-# 2. Click "Create a private app"
-# 3. Name your app (e.g., "Hive Agent")
-# ...
-
-if spec and spec.help_url:
-    print(f"More info: {spec.help_url}")
-```
-
-**4.2b. Collect API Key from User**
-
-Use AskUserQuestion to securely collect the API key:
-
-```
-Please provide your HubSpot access token:
-(This will be stored securely in ~/.hive/credentials)
-```
-
-**4.2c. Run Health Check Before Storing**
-
-```python
-from aden_tools.credentials import check_credential_health
-
-result = check_credential_health("hubspot", user_provided_token)
-if not result.valid:
-    print(f"Warning: {result.message}")
-    # Ask user if they want to:
-    # 1. Try a different token
-    # 2. Continue anyway (not recommended)
-```
-
-**4.2d. Store in Local Encrypted Store**
-
-```python
-from core.framework.credentials import CredentialStore, CredentialObject, CredentialKey
-from pydantic import SecretStr
-
-store = CredentialStore.with_encrypted_storage()
-
-cred = CredentialObject(
-    id="hubspot",
-    name="HubSpot Access Token",
-    keys={
-        "access_token": CredentialKey(
-            name="access_token",
-            value=SecretStr(user_provided_token),
-        )
-    },
-)
-store.save_credential(cred)
-```
-
-**4.2e. Export to Current Session**
-
-```bash
-export HUBSPOT_ACCESS_TOKEN="the-value"
-```
-
-#### Option 3: Local Credential Setup (Advanced)
-
-For programmatic/CI/CD setups.
-
-**4.3a. Show Documentation**
-
-```
-For advanced credential management, you can use the CredentialStore API directly:
-
-  from core.framework.credentials import CredentialStore, CredentialObject, CredentialKey
-  from pydantic import SecretStr
-
-  store = CredentialStore.with_encrypted_storage()
-
-  cred = CredentialObject(
-      id="hubspot",
-      name="HubSpot Access Token",
-      keys={"access_token": CredentialKey(name="access_token", value=SecretStr("..."))}
-  )
-  store.save_credential(cred)
-
-For CI/CD environments:
-  - Set HIVE_CREDENTIAL_KEY for encryption
-  - Pre-populate ~/.hive/credentials programmatically
-  - Or use environment variables directly (HUBSPOT_ACCESS_TOKEN)
-
-Documentation: See core/framework/credentials/README.md
-```
-
-### Step 5: Record Configuration Method
-
-Track which auth method was used for each credential in `~/.hive/configuration.json`:
-
-```python
-import json
-from pathlib import Path
-from datetime import datetime
-
-config_path = Path.home() / ".hive" / "configuration.json"
-config = json.loads(config_path.read_text()) if config_path.exists() else {}
-
-if "credential_methods" not in config:
-    config["credential_methods"] = {}
-
-config["credential_methods"]["hubspot"] = {
-    "method": "aden",  # or "direct" or "custom"
-    "configured_at": datetime.now().isoformat(),
-}
-
-config_path.write_text(json.dumps(config, indent=2))
-```
-
-### Step 6: Verify All Credentials
-
-Run validation again to confirm everything is set:
-
-```python
-runner = AgentRunner.load("exports/{agent_name}")
-validation = runner.validate()
-assert not validation.missing_credentials, "Still missing credentials!"
-```
-
-Report the result to the user.
-
-## Health Check Reference
-
-Health checks validate credentials by making lightweight API calls:
-
-| Credential      | Endpoint                                | What It Checks                     |
-| --------------- | --------------------------------------- | ---------------------------------- |
-| `anthropic`     | `POST /v1/messages`                     | API key validity                   |
-| `brave_search`  | `GET /res/v1/web/search?q=test&count=1` | API key validity                   |
-| `google_search` | `GET /customsearch/v1?q=test&num=1`     | API key + CSE ID validity          |
-| `github`        | `GET /user`                             | Token validity, user identity      |
-| `hubspot`       | `GET /crm/v3/objects/contacts?limit=1`  | Bearer token validity, CRM scopes  |
-| `resend`        | `GET /domains`                          | API key validity                   |
-
-```python
-from aden_tools.credentials import check_credential_health, HealthCheckResult
-
-result: HealthCheckResult = check_credential_health("hubspot", token_value)
-# result.valid: bool
-# result.message: str
-# result.details: dict (status_code, rate_limited, etc.)
-```
-
-## Encryption Key (HIVE_CREDENTIAL_KEY)
-
-The local encrypted store requires `HIVE_CREDENTIAL_KEY` to encrypt/decrypt credentials.
-
-- If the user doesn't have one, `EncryptedFileStorage` will auto-generate one and log it
-- The user MUST persist this key (e.g., in `~/.bashrc` or a secrets manager)
-- Without this key, stored credentials cannot be decrypted
-- This is the ONLY secret that should live in `~/.bashrc` or environment config
-
-If `HIVE_CREDENTIAL_KEY` is not set:
-
-1. Let the store generate one
-2. Tell the user to save it: `export HIVE_CREDENTIAL_KEY="{generated_key}"`
-3. Recommend adding it to `~/.bashrc` or their shell profile
-
-## Security Rules
-
-- **NEVER** log, print, or echo credential values in tool output
-- **NEVER** store credentials in plaintext files, git-tracked files, or agent configs
-- **NEVER** hardcode credentials in source code
-- **ALWAYS** use `SecretStr` from Pydantic when handling credential values in Python
-- **ALWAYS** use the local encrypted store (`~/.hive/credentials`) for persistence
-- **ALWAYS** run health checks before storing credentials (when possible)
-- **ALWAYS** verify credentials were stored by re-running validation, not by reading them back
-- When modifying `~/.bashrc` or `~/.zshrc`, confirm with the user first
-
-## Credential Sources Reference
-
-All credential specs are defined in `tools/src/aden_tools/credentials/`:
-
-| File              | Category      | Credentials                                   | Aden Supported |
-| ----------------- | ------------- | --------------------------------------------- | -------------- |
-| `llm.py`          | LLM Providers | `anthropic`                                   | No             |
-| `search.py`       | Search Tools  | `brave_search`, `google_search`, `google_cse` | No             |
-| `email.py`        | Email         | `resend`                                      | No             |
-| `integrations.py` | Integrations  | `github`, `hubspot`                           | No / Yes       |
-
-**Note:** Additional LLM providers (Cerebras, Groq, OpenAI) are handled by LiteLLM via environment
-variables (`CEREBRAS_API_KEY`, `GROQ_API_KEY`, `OPENAI_API_KEY`) but are not yet in CREDENTIAL_SPECS.
-Add them to `llm.py` as needed.
-
-To check what's registered:
-
-```python
-from aden_tools.credentials import CREDENTIAL_SPECS
-for name, spec in CREDENTIAL_SPECS.items():
-    print(f"{name}: aden={spec.aden_supported}, direct={spec.direct_api_key_supported}")
-```
-
-## Migration: CredentialManager → CredentialStore
-
-**CredentialManager is deprecated.** Use CredentialStore instead.
-
-| Old (Deprecated)                          | New (Recommended)                                                    |
-| ----------------------------------------- | -------------------------------------------------------------------- |
-| `CredentialManager()`                     | `CredentialStore.with_encrypted_storage()`                           |
-| `creds.get("hubspot")`                    | `store.get("hubspot")` or `store.get_key("hubspot", "access_token")` |
-| `creds.validate_for_tools(tools)`         | Use `store.is_available(cred_id)` per credential                     |
-| `creds.get_auth_options("hubspot")`       | Check `CREDENTIAL_SPECS["hubspot"].aden_supported`                   |
-| `creds.get_setup_instructions("hubspot")` | Access `CREDENTIAL_SPECS["hubspot"]` directly                        |
-
-**Why migrate?**
-
-- **CredentialStore** supports encrypted storage, multi-key credentials, template resolution, and automatic token refresh
-- **CredentialManager** only reads from environment variables and .env files (no encryption, no refresh)
-- **CredentialStoreAdapter** exists for backward compatibility during migration
-
-```python
-# Old way (deprecated)
-from aden_tools.credentials import CredentialManager
-creds = CredentialManager()
-token = creds.get("hubspot")
-
-# New way (recommended)
-from core.framework.credentials import CredentialStore
-store = CredentialStore.with_encrypted_storage()
-token = store.get("hubspot")
-
-# With Aden sync (recommended for OAuth integrations)
-store = CredentialStore.with_aden_sync()
-token = store.get_key("hubspot", "access_token")
-```
-
-## Example Session
-
-```
-User: /setup-credentials for my research-agent
-
-Agent: Let me check what credentials your research-agent needs.
-
-[Reads agent config]
-$ jq -r '.required_tools[]?' exports/research-agent/agent.json
-web_search
-google_search
-
-$ jq -r '.graph.nodes[]?.node_type' exports/research-agent/agent.json | sort -u
-llm_tool_use
-
-[Maps tools/nodes to credentials using lookup table]
-Needed: anthropic, brave_search, google_search, google_cse
-
-[Checks encrypted store metadata index]
-$ cat ~/.hive/credentials/metadata/index.json | jq -r '.credentials | keys[]'
-anthropic
-brave_search
-
-[Checks environment variables]
-$ printenv ANTHROPIC_API_KEY > /dev/null 2>&1 && echo "set" || echo "not set"
-not set
-$ printenv BRAVE_SEARCH_API_KEY > /dev/null 2>&1 && echo "set" || echo "not set"
-not set
-$ printenv GOOGLE_API_KEY > /dev/null 2>&1 && echo "set" || echo "not set"
-not set
-$ printenv GOOGLE_CSE_ID > /dev/null 2>&1 && echo "set" || echo "not set"
-not set
-
-[Checks HIVE_CREDENTIAL_KEY since credentials found in store]
-$ printenv HIVE_CREDENTIAL_KEY > /dev/null 2>&1 && echo "session: set" || echo "session: not set"
-session: not set
-$ for f in ~/.zshrc ~/.bashrc ~/.profile; do [ -f "$f" ] && grep -q 'HIVE_CREDENTIAL_KEY' "$f" && echo "$f"; done
-/Users/user/.zshrc
-
-[Key is in shell config but not current session — sourcing it]
-$ source ~/.zshrc
-
-[Computes missing credentials]
-Found:
-  ✓ anthropic (ANTHROPIC_API_KEY) — in encrypted store
-  ✓ brave_search (BRAVE_SEARCH_API_KEY) — in encrypted store
-Missing:
-  ✗ google_search (GOOGLE_API_KEY)
-  ✗ google_cse (GOOGLE_CSE_ID)
-
-Agent: 2 of 4 required credentials are already configured. Only Google Custom
-Search needs setup (2 values as a single group).
-
---- Setting up Google Custom Search (google_search + google_cse) ---
-
-This requires two values that work together.
-
-First, the Google API Key:
-1. Go to https://console.cloud.google.com/apis/credentials
-2. Create a new project (or select an existing one)
-3. Enable the "Custom Search API" from the API Library
-4. Go to Credentials > Create Credentials > API Key
-5. Copy the generated API key
-
-[AskUserQuestion: "Please provide your Google API key:"]
-[User provides key]
-
-Now, the Custom Search Engine ID:
-1. Go to https://programmablesearchengine.google.com/controlpanel/all
-2. Click "Add" to create a new search engine
-3. Under "What to search", select "Search the entire web"
-4. Give your search engine a name
-5. Click "Create"
-6. Copy the Search Engine ID (cx value)
-
-[AskUserQuestion: "Please provide your Google CSE ID:"]
-[User provides ID]
-
-[Runs health check with both values - GET /customsearch/v1?q=test&num=1 → 200 OK]
-[Stores both in local encrypted store, exports to env]
-
-✓ Google Custom Search credentials valid
-
-All credentials are now configured:
-  ✓ anthropic (ANTHROPIC_API_KEY) — already in encrypted store
-  ✓ brave_search (BRAVE_SEARCH_API_KEY) — already in encrypted store
-  ✓ google_search (GOOGLE_API_KEY) — stored in encrypted store
-  ✓ google_cse (GOOGLE_CSE_ID) — stored in encrypted store
-  Your agent is ready to run!
-```

.claude/skills/testing-agent/examples/testing-youtube-agent.md

@@ -1,351 +0,0 @@
-# Example: Testing a YouTube Research Agent
-
-This example walks through testing a YouTube research agent that finds relevant videos based on a topic.
-
-## Prerequisites
-
-- Agent built with building-agents skill at `exports/youtube-research/`
-- Goal defined with success criteria and constraints
-
-## Step 1: Load the Goal
-
-First, load the goal that was defined during the Goal stage:
-
-```json
-{
-    "id": "youtube-research",
-    "name": "YouTube Research Agent",
-    "description": "Find relevant YouTube videos on a given topic",
-    "success_criteria": [
-        {
-            "id": "find_videos",
-            "description": "Find 3-5 relevant videos",
-            "metric": "video_count",
-            "target": "3-5",
-            "weight": 1.0
-        },
-        {
-            "id": "relevance",
-            "description": "Videos must be relevant to the topic",
-            "metric": "relevance_score",
-            "target": ">0.8",
-            "weight": 0.8
-        }
-    ],
-    "constraints": [
-        {
-            "id": "api_limits",
-            "description": "Must not exceed YouTube API rate limits",
-            "constraint_type": "hard",
-            "category": "technical"
-        },
-        {
-            "id": "content_safety",
-            "description": "Must filter out inappropriate content",
-            "constraint_type": "hard",
-            "category": "safety"
-        }
-    ]
-}
-```
-
-## Step 2: Get Constraint Test Guidelines
-
-During the Goal stage (or early Eval), get test guidelines for constraints:
-
-```python
-result = generate_constraint_tests(
-    goal_id="youtube-research",
-    goal_json='<goal JSON above>',
-    agent_path="exports/youtube-research"
-)
-```
-
-**The result contains guidelines (not generated tests):**
-- `output_file`: Where to write tests
-- `file_header`: Imports and fixtures to use
-- `test_template`: Format for test functions
-- `constraints_formatted`: The constraints to test
-- `test_guidelines`: Rules for writing tests
-
-## Step 3: Write Constraint Tests
-
-Using the guidelines, write tests directly with the Write tool:
-
-```python
-# Write constraint tests using the provided file_header and guidelines
-Write(
-    file_path="exports/youtube-research/tests/test_constraints.py",
-    content='''
-"""Constraint tests for youtube-research agent."""
-
-import os
-import pytest
-from exports.youtube_research import default_agent
-
-
-pytestmark = pytest.mark.skipif(
-    not os.environ.get("ANTHROPIC_API_KEY") and not os.environ.get("MOCK_MODE"),
-    reason="API key required for real testing."
-)
-
-
-@pytest.mark.asyncio
-async def test_constraint_api_limits_respected():
-    """Verify API rate limits are not exceeded."""
-    import time
-    mock_mode = bool(os.environ.get("MOCK_MODE"))
-
-    for i in range(10):
-        result = await default_agent.run({"topic": f"test_{i}"}, mock_mode=mock_mode)
-        time.sleep(0.1)
-
-    # Should complete without rate limit errors
-    assert "rate limit" not in str(result).lower()
-
-
-@pytest.mark.asyncio
-async def test_constraint_content_safety_filter():
-    """Verify inappropriate content is filtered."""
-    mock_mode = bool(os.environ.get("MOCK_MODE"))
-    result = await default_agent.run({"topic": "general topic"}, mock_mode=mock_mode)
-
-    for video in result.videos:
-        assert video.safe_for_work is True
-        assert video.age_restricted is False
-'''
-)
-```
-
-## Step 4: Get Success Criteria Test Guidelines
-
-After the agent is built, get success criteria test guidelines:
-
-```python
-result = generate_success_tests(
-    goal_id="youtube-research",
-    goal_json='<goal JSON>',
-    node_names="search_node,filter_node,rank_node,format_node",
-    tool_names="youtube_search,video_details,channel_info",
-    agent_path="exports/youtube-research"
-)
-```
-
-## Step 5: Write Success Criteria Tests
-
-Using the guidelines, write success criteria tests:
-
-```python
-Write(
-    file_path="exports/youtube-research/tests/test_success_criteria.py",
-    content='''
-"""Success criteria tests for youtube-research agent."""
-
-import os
-import pytest
-from exports.youtube_research import default_agent
-
-
-pytestmark = pytest.mark.skipif(
-    not os.environ.get("ANTHROPIC_API_KEY") and not os.environ.get("MOCK_MODE"),
-    reason="API key required for real testing."
-)
-
-
-@pytest.mark.asyncio
-async def test_find_videos_happy_path():
-    """Test finding videos for a common topic."""
-    mock_mode = bool(os.environ.get("MOCK_MODE"))
-    result = await default_agent.run({"topic": "machine learning"}, mock_mode=mock_mode)
-
-    assert result.success
-    assert 3 <= len(result.videos) <= 5
-    assert all(v.title for v in result.videos)
-    assert all(v.video_id for v in result.videos)
-
-
-@pytest.mark.asyncio
-async def test_find_videos_minimum_boundary():
-    """Test at minimum threshold (3 videos)."""
-    mock_mode = bool(os.environ.get("MOCK_MODE"))
-    result = await default_agent.run({"topic": "niche topic xyz"}, mock_mode=mock_mode)
-
-    assert len(result.videos) >= 3
-
-
-@pytest.mark.asyncio
-async def test_relevance_score_threshold():
-    """Test relevance scoring meets threshold."""
-    mock_mode = bool(os.environ.get("MOCK_MODE"))
-    result = await default_agent.run({"topic": "python programming"}, mock_mode=mock_mode)
-
-    for video in result.videos:
-        assert video.relevance_score > 0.8
-
-
-@pytest.mark.asyncio
-async def test_find_videos_no_results_graceful():
-    """Test graceful handling of no results."""
-    mock_mode = bool(os.environ.get("MOCK_MODE"))
-    result = await default_agent.run({"topic": "xyznonexistent123"}, mock_mode=mock_mode)
-
-    # Should not crash, return empty or message
-    assert result.videos == [] or result.message
-'''
-)
-```
-
-## Step 6: Run All Tests
-
-Execute all tests:
-
-```python
-result = run_tests(
-    goal_id="youtube-research",
-    agent_path="exports/youtube-research",
-    test_types='["all"]',
-    parallel=4
-)
-```
-
-**Results:**
-
-```json
-{
-    "goal_id": "youtube-research",
-    "overall_passed": false,
-    "summary": {
-        "total": 6,
-        "passed": 5,
-        "failed": 1,
-        "pass_rate": "83.3%"
-    },
-    "duration_ms": 4521,
-    "results": [
-        {"test_id": "test_constraint_api_001", "passed": true, "duration_ms": 1234},
-        {"test_id": "test_constraint_content_001", "passed": true, "duration_ms": 456},
-        {"test_id": "test_success_001", "passed": true, "duration_ms": 789},
-        {"test_id": "test_success_002", "passed": true, "duration_ms": 654},
-        {"test_id": "test_success_003", "passed": true, "duration_ms": 543},
-        {"test_id": "test_success_004", "passed": false, "duration_ms": 845,
-         "error_category": "IMPLEMENTATION_ERROR",
-         "error_message": "TypeError: 'NoneType' object has no attribute 'videos'"}
-    ]
-}
-```
-
-## Step 7: Debug the Failed Test
-
-```python
-result = debug_test(
-    goal_id="youtube-research",
-    test_name="test_find_videos_no_results_graceful",
-    agent_path="exports/youtube-research"
-)
-```
-
-**Debug Output:**
-
-```json
-{
-    "test_id": "test_success_004",
-    "test_name": "test_find_videos_no_results_graceful",
-    "input": {"topic": "xyznonexistent123"},
-    "expected": "Empty list or message",
-    "actual": {"error": "TypeError: 'NoneType' object has no attribute 'videos'"},
-    "passed": false,
-    "error_message": "TypeError: 'NoneType' object has no attribute 'videos'",
-    "error_category": "IMPLEMENTATION_ERROR",
-    "stack_trace": "Traceback (most recent call last):\n  File \"filter_node.py\", line 42\n    for video in result.videos:\nTypeError: 'NoneType' object has no attribute 'videos'",
-    "logs": [
-        {"timestamp": "2026-01-20T10:00:01", "node": "search_node", "level": "INFO", "msg": "Searching for: xyznonexistent123"},
-        {"timestamp": "2026-01-20T10:00:02", "node": "search_node", "level": "WARNING", "msg": "No results found"},
-        {"timestamp": "2026-01-20T10:00:02", "node": "filter_node", "level": "ERROR", "msg": "NoneType error"}
-    ],
-    "runtime_data": {
-        "execution_path": ["start", "search_node", "filter_node"],
-        "node_outputs": {
-            "search_node": null
-        }
-    },
-    "suggested_fix": "Add null check in filter_node before accessing .videos attribute",
-    "iteration_guidance": {
-        "stage": "Agent",
-        "action": "Fix the code in nodes/edges",
-        "restart_required": false,
-        "description": "The goal is correct, but filter_node doesn't handle null results from search_node."
-    }
-}
-```
-
-## Step 8: Iterate Based on Category
-
-Since this is an **IMPLEMENTATION_ERROR**, we:
-
-1. **Don't restart** the Goal → Agent → Eval flow
-2. **Fix the agent** using building-agents skill:
-   - Modify `filter_node` to handle null results
-3. **Re-run Eval** (tests only)
-
-### Fix in building-agents:
-
-```python
-# Update the filter_node to handle null
-add_node(
-    node_id="filter_node",
-    name="Filter Node",
-    description="Filter and rank videos",
-    node_type="function",
-    input_keys=["search_results"],
-    output_keys=["filtered_videos"],
-    system_prompt="""
-    Filter videos by relevance.
-    IMPORTANT: Handle case where search_results is None or empty.
-    Return empty list if no results.
-    """
-)
-```
-
-### Re-export and re-test:
-
-```python
-# Re-export the fixed agent
-export_graph(path="exports/youtube-research")
-
-# Re-run tests
-result = run_tests(
-    goal_id="youtube-research",
-    agent_path="exports/youtube-research",
-    test_types='["all"]'
-)
-```
-
-**Updated Results:**
-
-```json
-{
-    "goal_id": "youtube-research",
-    "overall_passed": true,
-    "summary": {
-        "total": 6,
-        "passed": 6,
-        "failed": 0,
-        "pass_rate": "100.0%"
-    }
-}
-```
-
-## Summary
-
-1. **Got guidelines** for constraint tests during Goal stage
-2. **Wrote** constraint tests using Write tool
-3. **Got guidelines** for success criteria tests during Eval stage
-4. **Wrote** success criteria tests using Write tool
-5. **Ran** tests in parallel
-6. **Debugged** the one failure
-7. **Categorized** as IMPLEMENTATION_ERROR
-8. **Fixed** the agent (not the goal)
-9. **Re-ran** Eval only (didn't restart full flow)
-10. **Passed** all tests
-
-The agent is now validated and ready for production use.

.cursor/mcp.json

@@ -1,20 +0,0 @@
-{
-  "mcpServers": {
-    "agent-builder": {
-      "command": "python",
-      "args": ["-m", "framework.mcp.agent_builder_server"],
-      "cwd": "core",
-      "env": {
-        "PYTHONPATH": "../tools/src"
-      }
-    },
-    "tools": {
-      "command": "python",
-      "args": ["mcp_server.py", "--stdio"],
-      "cwd": "tools",
-      "env": {
-        "PYTHONPATH": "src"
-      }
-    }
-  }
-}

.cursor/skills/agent-workflow

@@ -1 +0,0 @@
-../../.claude/skills/agent-workflow

.cursor/skills/building-agents-construction

@@ -1 +0,0 @@
-../../.claude/skills/building-agents-construction

.cursor/skills/building-agents-core

@@ -1 +0,0 @@
-../../.claude/skills/building-agents-core

.cursor/skills/building-agents-patterns

@@ -1 +0,0 @@
-../../.claude/skills/building-agents-patterns

.cursor/skills/testing-agent

@@ -1 +0,0 @@
-../../.claude/skills/testing-agent

.github/ISSUE_TEMPLATE/integration-bounty.yml

@@ -0,0 +1,89 @@
+name: Integration Bounty
+description: A bounty task for the integration contribution program
+title: "[Bounty]: "
+labels: []
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## Integration Bounty
+
+        This issue is part of the [Integration Bounty Program](../../docs/bounty-program/README.md).
+        **Claim this bounty** by commenting below — a maintainer will assign you within 24 hours.
+
+  - type: dropdown
+    id: bounty-type
+    attributes:
+      label: Bounty Type
+      options:
+        - "Test a Tool (20 pts)"
+        - "Write Docs (20 pts)"
+        - "Code Contribution (30 pts)"
+        - "New Integration (75 pts)"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: difficulty
+    attributes:
+      label: Difficulty
+      options:
+        - Easy
+        - Medium
+        - Hard
+    validations:
+      required: true
+
+  - type: input
+    id: tool-name
+    attributes:
+      label: Tool Name
+      description: The integration this bounty targets (e.g., `airtable`, `salesforce`)
+      placeholder: e.g., airtable
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What needs to be done to complete this bounty.
+      placeholder: |
+        Describe the specific task, including:
+        - What the contributor needs to do
+        - Links to relevant files in the repo
+        - Any setup requirements (API keys, accounts, etc.)
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance-criteria
+    attributes:
+      label: Acceptance Criteria
+      description: What "done" looks like. The PR or report must meet all criteria.
+      placeholder: |
+        - [ ] Criterion 1
+        - [ ] Criterion 2
+        - [ ] CI passes
+    validations:
+      required: true
+
+  - type: textarea
+    id: relevant-files
+    attributes:
+      label: Relevant Files
+      description: Links to tool directory, credential spec, health check file, etc.
+      placeholder: |
+        - Tool: `tools/src/aden_tools/tools/{tool_name}/`
+        - Credential spec: `tools/src/aden_tools/credentials/{category}.py`
+        - Health checks: `tools/src/aden_tools/credentials/health_check.py`
+
+  - type: textarea
+    id: resources
+    attributes:
+      label: Resources
+      description: Links to API docs, examples, or guides that will help the contributor.
+      placeholder: |
+        - [Building Tools Guide](../../tools/BUILDING_TOOLS.md)
+        - [Tool README Template](../../docs/bounty-program/templates/tool-readme-template.md)
+        - API docs: https://...

.github/workflows/bounty-completed.yml

@@ -0,0 +1,37 @@
+name: Bounty completed
+description: Awards points and notifies Discord when a bounty PR is merged
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  bounty-notify:
+    if: >
+      github.event.pull_request.merged == true &&
+      contains(join(github.event.pull_request.labels.*.name, ','), 'bounty:')
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Award XP and notify Discord
+        run: bun run scripts/bounty-tracker.ts notify
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_BOUNTY_WEBHOOK_URL }}
+          LURKR_API_KEY: ${{ secrets.LURKR_API_KEY }}
+          LURKR_GUILD_ID: ${{ secrets.LURKR_GUILD_ID }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}

.github/workflows/ci.yml

@@ -5,7 +5,7 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
-
+    
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
@@ -24,6 +24,8 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
 
       - name: Install dependencies
         run: uv sync --project core --group dev
@@ -54,20 +56,21 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
 
-      - name: Install dependencies
+      - name: Install dependencies and run tests
+        working-directory: core
         run: |
-          cd core
           uv sync
-
-      - name: Run tests
-        run: |
-          cd core
           uv run pytest tests/ -v
 
   test-tools:
-    name: Test Tools
-    runs-on: ubuntu-latest
+    name: Test Tools (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
     steps:
       - uses: actions/checkout@v4
 
@@ -78,10 +81,12 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
 
       - name: Install dependencies and run tests
+        working-directory: tools
         run: |
-          cd tools
           uv sync --extra dev
           uv run pytest tests/ -v
 
@@ -99,10 +104,12 @@ jobs:
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
-
+        with:
+          enable-cache: true
+            
       - name: Install dependencies
+        working-directory: core
         run: |
-          cd core
           uv sync
 
       - name: Validate exported agents
@@ -126,7 +133,7 @@ jobs:
           for agent_dir in "${agent_dirs[@]}"; do
             if [ -f "$agent_dir/agent.json" ]; then
               echo "Validating $agent_dir"
-              python -c "import json; json.load(open('$agent_dir/agent.json'))"
+              uv run python -c "import json; json.load(open('$agent_dir/agent.json'))"
               validated=$((validated + 1))
             fi
           done

.github/workflows/link-discord.yml

@@ -0,0 +1,126 @@
+name: Link Discord account
+description: Auto-creates a PR to add contributor to contributors.yml when a link-discord issue is opened
+
+on:
+  issues:
+    types: [opened]
+
+jobs:
+  link-discord:
+    if: contains(github.event.issue.labels.*.name, 'link-discord')
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Parse issue and update contributors.yml
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            const issue = context.payload.issue;
+            const githubUsername = issue.user.login;
+
+            // Parse the issue body for form fields
+            const body = issue.body || '';
+
+            // Extract Discord ID — look for the numeric value after the "Discord User ID" heading
+            const discordMatch = body.match(/### Discord User ID\s*\n\s*(\d{17,20})/);
+            if (!discordMatch) {
+              await github.rest.issues.createComment({
+                ...context.repo,
+                issue_number: issue.number,
+                body: `Could not find a valid Discord ID in the issue body. Please make sure you entered a numeric ID (17-20 digits), not a username.\n\nExample: \`123456789012345678\``
+              });
+              await github.rest.issues.update({
+                ...context.repo,
+                issue_number: issue.number,
+                state: 'closed',
+                state_reason: 'not_planned'
+              });
+              return;
+            }
+            const discordId = discordMatch[1];
+
+            // Extract display name (optional)
+            const nameMatch = body.match(/### Display Name \(optional\)\s*\n\s*(.+)/);
+            const displayName = nameMatch ? nameMatch[1].trim() : '';
+
+            // Check if user already exists
+            const yml = fs.readFileSync('contributors.yml', 'utf-8');
+            if (yml.includes(`github: ${githubUsername}`)) {
+              await github.rest.issues.createComment({
+                ...context.repo,
+                issue_number: issue.number,
+                body: `@${githubUsername} is already in \`contributors.yml\`. If you need to update your Discord ID, please edit the file directly via PR.`
+              });
+              await github.rest.issues.update({
+                ...context.repo,
+                issue_number: issue.number,
+                state: 'closed',
+                state_reason: 'completed'
+              });
+              return;
+            }
+
+            // Append entry to contributors.yml
+            let entry = `  - github: ${githubUsername}\n    discord: "${discordId}"`;
+            if (displayName && displayName !== '_No response_') {
+              entry += `\n    name: ${displayName}`;
+            }
+            entry += '\n';
+
+            const updated = yml.trimEnd() + '\n' + entry;
+            fs.writeFileSync('contributors.yml', updated);
+
+            // Set outputs for commit step
+            core.exportVariable('GITHUB_USERNAME', githubUsername);
+            core.exportVariable('DISCORD_ID', discordId);
+            core.exportVariable('ISSUE_NUMBER', issue.number.toString());
+
+      - name: Create PR
+        run: |
+          # Check if there are changes
+          if git diff --quiet contributors.yml; then
+            echo "No changes to contributors.yml"
+            exit 0
+          fi
+
+          BRANCH="docs/link-discord-${GITHUB_USERNAME}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git add contributors.yml
+          git commit -m "docs: link @${GITHUB_USERNAME} to Discord"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --title "docs: link @${GITHUB_USERNAME} to Discord" \
+            --body "Adds @${GITHUB_USERNAME} (Discord \`${DISCORD_ID}\`) to \`contributors.yml\` for bounty XP tracking.
+
+          Closes #${ISSUE_NUMBER}" \
+            --base main \
+            --head "$BRANCH" \
+            --label "link-discord"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Notify on issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const username = process.env.GITHUB_USERNAME;
+            const issueNumber = parseInt(process.env.ISSUE_NUMBER);
+
+            await github.rest.issues.createComment({
+              ...context.repo,
+              issue_number: issueNumber,
+              body: `A PR has been created to link your account. A maintainer will merge it shortly — once merged, you'll receive XP and Discord pings when your bounty PRs are merged.`
+            });

.github/workflows/pr-requirements-enforce.yml

@@ -0,0 +1,54 @@
+# Closes PRs that still have the `pr-requirements-warning` label
+# after contributors were warned in pr-requirements.yml.
+name: PR Requirements Enforcement
+on:
+  schedule:
+    - cron: "0 0 * * *"   # runs every day once at midnight 
+jobs:
+  enforce:
+    name: Close PRs still failing contribution requirements
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Close PRs still failing requirements
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { owner, repo } = context.repo;
+            const prs = await github.paginate(github.rest.pulls.list, {
+              owner,
+              repo,
+              state: "open",
+              per_page: 100
+            });
+            for (const pr of prs) {
+              // Skip draft PRs — author may still be actively working toward compliance
+              if (pr.draft) continue;
+              const labels = pr.labels.map(l => l.name);
+              if (!labels.includes("pr-requirements-warning")) continue;
+              const gracePeriod = 24 * 60 * 60 * 1000;
+              const lastUpdated = new Date(pr.created_at);
+              const now = new Date();
+              if (now - lastUpdated < gracePeriod) {
+                console.log(`Skipping PR #${pr.number} — still within grace period`);
+                continue;
+              }
+              const prNumber = pr.number;
+              const prAuthor = pr.user.login;
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: prNumber,
+                body: `Closing PR because the contribution requirements were not resolved within the 24-hour grace period.
+                If this was closed in error, feel free to reopen the PR after fixing the requirements.`
+              });
+              await github.rest.pulls.update({
+                owner,
+                repo,
+                pull_number: prNumber,
+                state: "closed"
+              });
+              console.log(`Closed PR #${prNumber} by ${prAuthor} (PR requirements were not met)`);
+            }

.github/workflows/pr-requirements.yml

@@ -43,9 +43,10 @@ jobs:
             console.log(`  Found issue references: ${issueNumbers.length > 0 ? issueNumbers.join(', ') : 'none'}`);
 
             if (issueNumbers.length === 0) {
-              const message = `## PR Closed - Requirements Not Met
+              const message = `## PR Requirements Warning
 
-            This PR has been automatically closed because it doesn't meet the requirements.
+            This PR does not meet the contribution requirements.
+            If the issue is not fixed within ~24 hours, it may be automatically closed.
 
             **Missing:** No linked issue found.
 
@@ -67,14 +68,15 @@ jobs:
 
             **Why is this required?** See #472 for details.`;
 
-              const comments = await github.rest.issues.listComments({
+              const comments = await github.paginate(github.rest.issues.listComments, {
                 owner: context.repo.owner,
                 repo: context.repo.repo,
                 issue_number: prNumber,
+                per_page: 100,
               });
 
-              const botComment = comments.data.find(
-                (c) => c.user.type === 'Bot' && c.body.includes('PR Closed - Requirements Not Met')
+              const botComment = comments.find(
+                (c) => c.user.type === 'Bot' && c.body.includes('PR Requirements Warning')
               );
 
               if (!botComment) {
@@ -86,11 +88,11 @@ jobs:
                 });
               }
 
-              await github.rest.pulls.update({
+              await github.rest.issues.addLabels({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                pull_number: prNumber,
-                state: 'closed',
+                issue_number: prNumber,
+                labels: ['pr-requirements-warning'],
               });
 
               core.setFailed('PR must reference an issue');
@@ -132,9 +134,10 @@ jobs:
                 `#${i.number} (assignees: ${i.assignees.length > 0 ? i.assignees.join(', ') : 'none'})`
               ).join(', ');
 
-              const message = `## PR Closed - Requirements Not Met
+              const message = `## PR Requirements Warning
 
-            This PR has been automatically closed because it doesn't meet the requirements.
+            This PR does not meet the contribution requirements.
+            If the issue is not fixed within ~24 hours, it may be automatically closed.
 
             **PR Author:** @${prAuthor}
             **Found issues:** ${issueList}
@@ -157,14 +160,15 @@ jobs:
 
             **Why is this required?** See #472 for details.`;
 
-              const comments = await github.rest.issues.listComments({
+              const comments = await github.paginate(github.rest.issues.listComments, {
                 owner: context.repo.owner,
                 repo: context.repo.repo,
                 issue_number: prNumber,
+                per_page: 100,
               });
 
-              const botComment = comments.data.find(
-                (c) => c.user.type === 'Bot' && c.body.includes('PR Closed - Requirements Not Met')
+              const botComment = comments.find(
+                (c) => c.user.type === 'Bot' && c.body.includes('PR Requirements Warning')
               );
 
               if (!botComment) {
@@ -176,14 +180,24 @@ jobs:
                 });
               }
 
-              await github.rest.pulls.update({
+              await github.rest.issues.addLabels({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
-                pull_number: prNumber,
-                state: 'closed',
+                issue_number: prNumber,
+                labels: ['pr-requirements-warning'],
               });
 
               core.setFailed('PR author must be assigned to the linked issue');
             } else {
               console.log(`PR requirements met! Issue #${issueWithAuthorAssigned} has ${prAuthor} as assignee.`);
-            }
+              try {
+                await github.rest.issues.removeLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: prNumber,
+                  name: "pr-requirements-warning"
+                });
+              }catch (error){
+                //ignore if label doesn't exist
+              }
+            }

.github/workflows/weekly-leaderboard.yml

@@ -0,0 +1,40 @@
+name: Weekly bounty leaderboard
+description: Posts the integration bounty leaderboard to Discord every Monday
+
+on:
+  schedule:
+    # Every Monday at 9:00 UTC
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+    inputs:
+      since_date:
+        description: "Only count PRs merged after this date (YYYY-MM-DD). Leave empty for all-time."
+        required: false
+
+jobs:
+  leaderboard:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Post leaderboard to Discord
+        run: bun run scripts/bounty-tracker.ts leaderboard
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}
+          GITHUB_REPOSITORY_NAME: ${{ github.event.repository.name }}
+          DISCORD_WEBHOOK_URL: ${{ secrets.DISCORD_BOUNTY_WEBHOOK_URL }}
+          LURKR_API_KEY: ${{ secrets.LURKR_API_KEY }}
+          LURKR_GUILD_ID: ${{ secrets.LURKR_GUILD_ID }}
+          SINCE_DATE: ${{ github.event.inputs.since_date || '' }}

.gitignore

@@ -46,6 +46,7 @@ coverage/
 
 # TypeScript
 *.tsbuildinfo
+vite.config.d.ts
 
 # Python
 __pycache__/
@@ -54,7 +55,6 @@ __pycache__/
 *.egg-info/
 .eggs/
 *.egg
-uv.lock
 
 # Generated runtime data
 core/data/
@@ -67,11 +67,14 @@ temp/
 
 exports/*
 
-.agent-builder-sessions/*
-
 .claude/settings.local.json
+.claude/skills/ship-it/
 
 .venv
 
 docs/github-issues/*
 core/tests/*dumps/*
+
+screenshots/*
+
+.gemini/*

.mcp.json

@@ -1,14 +1,3 @@
 {
-  "mcpServers": {
-    "agent-builder": {
-      "command": "uv",
-      "args": ["run", "-m", "framework.mcp.agent_builder_server"],
-      "cwd": "core"
-    },
-    "tools": {
-      "command": "uv",
-      "args": ["run", "mcp_server.py", "--stdio"],
-      "cwd": "tools"
-    }
-  }
+  "mcpServers": {}
 }

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.8.6
+    rev: v0.15.0
     hooks:
       - id: ruff
         name: ruff lint (core)

.vscode/extensions.json

@@ -1,7 +0,0 @@
-{
-  "recommendations": [
-    "charliermarsh.ruff",
-    "editorconfig.editorconfig",
-    "ms-python.python"
-  ]
-}

AGENTS.md

@@ -0,0 +1,34 @@
+# Repository Guidelines
+
+Shared agent instructions for this workspace.
+
+## Deprecations
+
+- **TUI is deprecated.** The terminal UI (`hive tui`) is no longer maintained. Use the browser-based interface (`hive open`) instead.
+
+## Coding Agent Notes
+
+- 
+- When working on a GitHub Issue or PR, print the full URL at the end of the task.
+- When answering questions, respond with high-confidence answers only: verify in code; do not guess.
+- Do not update dependencies casually. Version bumps, patched dependencies, overrides, or vendored dependency changes require explicit approval.
+- Add brief comments for tricky logic. Keep files reasonably small when practical; split or refactor large files instead of growing them indefinitely.
+- If shared guardrails are available locally, review them; otherwise follow this repo's guidance.
+- Use `uv` for Python execution and package management. Do not use `python` or `python3` directly unless the user explicitly asks for it.
+- Prefer `uv run` for scripts and tests, and `uv pip` for package operations.
+
+
+## Multi-Agent Safety
+
+- Do not create, apply, or drop `git stash` entries unless explicitly requested.
+- Do not create, remove, or modify `git worktree` checkouts unless explicitly requested.
+- Do not switch branches or check out a different branch unless explicitly requested.
+- When the user says `push`, you may `git pull --rebase` to integrate latest changes, but never discard other in-progress work.
+- When the user says `commit`, commit only your changes. When the user says `commit all`, commit everything in grouped chunks.
+- When you see unrecognized files or unrelated changes, keep going and focus on your scoped changes.
+
+## Change Hygiene
+
+- If staged and unstaged diffs are formatting-only, resolve them without asking.
+- If a commit or push was already requested, include formatting-only follow-up changes in that same commit when practical.
+- Only stop to ask for confirmation when changes are semantic and may alter behavior.

CHANGELOG.md

@@ -1,41 +1,207 @@
-# Changelog
+# Release Notes
 
-All notable changes to this project will be documented in this file.
+**Release Date:** February 18, 2026
+**Tag:** v0.5.1
 
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## The Hive Gets a Brain
 
-## [Unreleased]
+v0.5.1 is our most ambitious release yet. Hive agents can now **build other agents** -- the new Hive Coder meta-agent writes, tests, and fixes agent packages from natural language. The runtime grows multi-graph support so one session can orchestrate multiple agents simultaneously. The TUI gets a complete overhaul with an in-app agent picker, live streaming, and seamless escalation to the Coder. And we're now provider-agnostic: Claude Code subscriptions, OpenAI-compatible endpoints, and any LiteLLM-supported model work out of the box.
 
-### Added
-- Initial project structure
-- React frontend (honeycomb) with Vite and TypeScript
-- Node.js backend (hive) with Express and TypeScript
-- Docker Compose configuration for local development
-- Configuration system via `config.yaml`
-- GitHub Actions CI/CD workflows
-- Comprehensive documentation
+---
 
-### Changed
-- N/A
+## Highlights
 
-### Deprecated
-- N/A
+### Hive Coder -- The Agent That Builds Agents
 
-### Removed
-- N/A
+A native meta-agent that lives inside the framework at `core/framework/agents/hive_coder/`. Give it a natural-language specification and it produces a complete agent package -- goal definition, node prompts, edge routing, MCP tool wiring, tests, and all boilerplate files.
 
+```bash
+# Launch the Coder directly
+hive code
 
-### Fixed
-- tools: Fixed web_scrape tool attempting to parse non-HTML content (PDF, JSON) as HTML (#487)
+# Or escalate from any running agent (TUI)
+Ctrl+E  # or /coder in chat
+```
 
-### Security
-- N/A
+The Coder ships with:
 
-## [0.1.0] - 2025-01-13
+- **Reference documentation** -- anti-patterns, construction guide, and design patterns baked into its system prompt
+- **Guardian watchdog** -- an event-driven monitor that catches agent failures and triggers automatic remediation
+- **Coder Tools MCP server** -- file I/O, fuzzy-match editing, git snapshots, and sandboxed shell execution (`tools/coder_tools_server.py`)
+- **Test generation** -- structural tests for forever-alive agents that don't hang on `runner.run()`
 
-### Added
-- Initial release
+### Multi-Graph Agent Runtime
 
-[Unreleased]: https://github.com/adenhq/hive/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/adenhq/hive/releases/tag/v0.1.0
+`AgentRuntime` now supports loading, managing, and switching between multiple agent graphs within a single session. Six new lifecycle tools give agents (and the TUI) full control:
+
+```python
+# Load a second agent into the runtime
+await runtime.add_graph("exports/deep_research_agent")
+
+# Tools available to agents:
+# load_agent, unload_agent, start_agent, restart_agent, list_agents, get_user_presence
+```
+
+The Hive Coder uses multi-graph internally -- when you escalate from a worker agent, the Coder loads as a separate graph while the worker stays alive in the background.
+
+### TUI Revamp
+
+The Terminal UI gets a ground-up rebuild with five major additions:
+
+- **Agent Picker** (Ctrl+A) -- tabbed modal screen for browsing Your Agents, Framework agents, and Examples with metadata badges (node count, tool count, session count, tags)
+- **Runtime-optional startup** -- TUI launches without a pre-loaded agent, showing the picker on first open
+- **Live streaming pane** -- dedicated RichLog widget shows LLM tokens as they arrive, replacing the old one-token-per-line display
+- **PDF attachments** -- `/attach` and `/detach` commands with native OS file dialog (macOS, Linux, Windows)
+- **Multi-graph commands** -- `/graphs`, `/graph <id>`, `/load <path>`, `/unload <id>` for managing agent graphs in-session
+
+### Provider-Agnostic LLM Support
+
+Hive is no longer Anthropic-only. v0.5.1 adds first-class support for:
+
+- **Claude Code subscriptions** -- `use_claude_code_subscription: true` in `~/.hive/configuration.json` reads OAuth tokens from `~/.claude/.credentials.json` with automatic refresh
+- **OpenAI-compatible endpoints** -- `api_base` config routes traffic through any compatible API (Azure OpenAI, vLLM, Ollama, etc.)
+- **Any LiteLLM model** -- `RuntimeConfig` now passes `api_key`, `api_base`, and `extra_kwargs` through to LiteLLM
+
+The quickstart script auto-detects Claude Code subscriptions and ZAI Code installations.
+
+---
+
+## What's New
+
+### Architecture & Runtime
+
+- **Hive Coder meta-agent** -- Natural-language agent builder with reference docs, guardian watchdog, and `hive code` CLI command. (@TimothyZhang7)
+- **Multi-graph agent sessions** -- `add_graph`/`remove_graph` on AgentRuntime with 6 lifecycle tools (`load_agent`, `unload_agent`, `start_agent`, `restart_agent`, `list_agents`, `get_user_presence`). (@TimothyZhang7)
+- **Claude Code subscription support** -- OAuth token refresh via `use_claude_code_subscription` config, auto-detection in quickstart, LiteLLM header patching. (@TimothyZhang7)
+- **OpenAI-compatible endpoint support** -- `api_base` and `extra_kwargs` in `RuntimeConfig` for any OpenAI-compatible API. (@TimothyZhang7)
+- **Remove deprecated node types** -- Delete `FlexibleGraphExecutor`, `WorkerNode`, `HybridJudge`, `CodeSandbox`, `Plan`, `FunctionNode`, `LLMNode`, `RouterNode`. Deprecated types (`llm_tool_use`, `llm_generate`, `function`, `router`, `human_input`) now raise `RuntimeError` with migration guidance. (@TimothyZhang7)
+- **Interactive credential setup** -- Guided `CredentialSetupSession` with health checks and encrypted storage, accessible via `hive setup-credentials` or automatic prompting on credential errors. (@RichardTang-Aden)
+- **Pre-start confirmation prompt** -- Interactive prompt before agent execution allowing credential updates or abort. (@RichardTang-Aden)
+- **Event bus multi-graph support** -- `graph_id` on events, `filter_graph` on subscriptions, `ESCALATION_REQUESTED` event type, `exclude_own_graph` filter. (@TimothyZhang7)
+
+### TUI Improvements
+
+- **In-app agent picker** (Ctrl+A) -- Tabbed modal for browsing agents with metadata badges (nodes, tools, sessions, tags). (@TimothyZhang7)
+- **Runtime-optional TUI startup** -- Launches without a pre-loaded agent, shows agent picker on startup. (@TimothyZhang7)
+- **Hive Coder escalation** (Ctrl+E) -- Escalate to Hive Coder and return; also available via `/coder` and `/back` chat commands. (@TimothyZhang7)
+- **PDF attachment support** -- `/attach` and `/detach` commands with native OS file dialog. (@TimothyZhang7)
+- **Streaming output pane** -- Dedicated RichLog widget for live LLM token streaming. (@TimothyZhang7)
+- **Multi-graph TUI commands** -- `/graphs`, `/graph <id>`, `/load <path>`, `/unload <id>`. (@TimothyZhang7)
+- **Agent Guardian watchdog** -- Event-driven monitor that catches secondary agent failures and triggers automatic remediation, with `--no-guardian` CLI flag. (@TimothyZhang7)
+
+### New Tool Integrations
+
+| Tool                   | Description                                                                                                                                                            | Contributor        |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
+| **Discord**            | 4 MCP tools (`discord_list_guilds`, `discord_list_channels`, `discord_send_message`, `discord_get_messages`) with rate-limit retry and channel filtering               | @mishrapravin114   |
+| **Exa Search API**     | 4 AI-powered search tools (`exa_search`, `exa_find_similar`, `exa_get_contents`, `exa_answer`) with neural/keyword search, domain filters, and citation-backed answers | @JeetKaria06       |
+| **Razorpay**           | 6 payment processing tools for payments, invoices, payment links, and refunds with HTTP Basic Auth                                                                     | @shivamshahi07     |
+| **Google Docs**        | Document creation, reading, and editing with OAuth credential support                                                                                                  | @haliaeetusvocifer |
+| **Gmail enhancements** | Expanded mail operations for inbox management                                                                                                                          | @bryanadenhq       |
+
+### Infrastructure
+
+- **Default node type → `event_loop`** -- `NodeSpec.node_type` defaults to `"event_loop"` instead of `"llm_tool_use"`. (@TimothyZhang7)
+- **Default `max_node_visits` → 0 (unlimited)** -- Nodes default to unlimited visits, reducing friction for feedback loops and forever-alive agents. (@TimothyZhang7)
+- **Remove `function` field from NodeSpec** -- Follows deprecation of `FunctionNode`. (@TimothyZhang7)
+- **LiteLLM OAuth patch** -- Correct header construction for OAuth tokens (remove `x-api-key` when Bearer token is present). (@TimothyZhang7)
+- **Orchestrator config centralization** -- Reads `api_key`, `api_base`, `extra_kwargs` from centralized `~/.hive/configuration.json`. (@TimothyZhang7)
+- **System prompt datetime injection** -- All system prompts now include current date/time for time-aware agent behavior. (@TimothyZhang7)
+- **Utils module exports** -- Proper `__init__.py` exports for the utils module. (@Siddharth2624)
+- **Increased default max_tokens** -- Opus 4.6 defaults to 32768, Sonnet 4.5 to 16384 (up from 8192). (@TimothyZhang7)
+
+---
+
+## Bug Fixes
+
+- Flush WIP accumulator outputs on cancel/failure so edge conditions see correct values on resume
+- Stall detection state preserved across resume (no more resets on checkpoint restore)
+- Skip client-facing blocking for event-triggered executions (timer/webhook)
+- Executor retry override scoped to actual EventLoopNode instances only
+- Add `_awaiting_input` flag to EventLoopNode to prevent input injection race conditions
+- Fix TUI streaming display (tokens no longer appear one-per-line)
+- Fix `_return_from_escalation` crash when ChatRepl widgets not yet mounted
+- Fix tools registration problems for Google Docs credentials (@RichardTang-Aden)
+- Fix email agent version conflicts (@RichardTang-Aden)
+- Fix coder tool timeouts (120s for tests, 300s cap for commands)
+
+## Documentation
+
+- Clarify installation and prevent root pip install misuse (@paarths-collab)
+
+---
+
+## Agent Updates
+
+- **Email Inbox Management** -- Consolidate `gmail_inbox_guardian` and `inbox_management` into a single unified agent with updated prompts and config. (@RichardTang-Aden, @bryanadenhq)
+- **Job Hunter** -- Updated node prompts, config, and agent metadata; added PDF resume selection. (@bryanadenhq)
+- **Deep Research Agent** -- Revised node implementations with updated prompts and output handling.
+- **Tech News Reporter** -- Revised node prompts for improved output quality.
+- **Vulnerability Assessment** -- Expanded prompts with more detailed assessment instructions. (@bryanadenhq)
+
+---
+
+## Breaking Changes
+
+- **Deprecated node types raise `RuntimeError`** -- `llm_tool_use`, `llm_generate`, `function`, `router`, `human_input` now fail instead of warning. Migrate to `event_loop`.
+- **`NodeSpec.node_type` defaults to `"event_loop"`** (was `"llm_tool_use"`)
+- **`NodeSpec.max_node_visits` defaults to `0` / unlimited** (was `1`)
+- **`NodeSpec.function` field removed** -- `FunctionNode` is deleted; use event_loop nodes with tools instead.
+
+---
+
+## Community Contributors
+
+A huge thank you to everyone who contributed to this release:
+
+- **Richard Tang** (@RichardTang-Aden) -- Interactive credential setup, pre-start confirmation, email agent consolidation, tool registration fixes, lint and formatting
+- **Pravin Mishra** (@mishrapravin114) -- Discord integration with 4 MCP tools
+- **Jeet Karia** (@JeetKaria06) -- Exa Search API integration with 4 AI-powered search tools
+- **Shivam Shahi** (@shivamshahi07) -- Razorpay payment processing integration
+- **Siddharth Varshney** (@Siddharth2624) -- Utils module exports
+- **@haliaeetusvocifer** -- Google Docs integration with OAuth support
+- **Bryan** (@bryanadenhq) -- PDF selection, inbox agent fixes, Job Hunter and Vulnerability Assessment updates
+- **@paarths-collab** -- Documentation improvements
+
+---
+
+## Upgrading
+
+```bash
+git pull origin main
+uv sync
+```
+
+### Migration Guide
+
+If your agents use deprecated node types, update them:
+
+```python
+# Before (v0.5.0) -- these now raise RuntimeError
+NodeSpec(node_type="llm_tool_use", ...)
+NodeSpec(node_type="function", function=my_func, ...)
+
+# After (v0.5.1) -- use event_loop for everything
+NodeSpec(node_type="event_loop", ...)  # or just omit node_type (it's the default now)
+```
+
+If your agents set `max_node_visits=1` explicitly, they'll still work. The only change is the _default_ -- new agents without an explicit value now get unlimited visits.
+
+To try the new Hive Coder:
+
+```bash
+# Launch Coder directly
+hive code
+
+# Or from TUI -- press Ctrl+E to escalate
+hive tui
+```
+
+---
+
+## What's Next
+
+- **Agent-to-agent communication** -- one agent's output triggers another agent's entry point
+- **Cost visibility** -- detailed runtime log of LLM costs per node and per session
+- **Persistent webhook subscriptions** -- survive agent restarts without re-registering
+- **Remote agent deployment** -- run agents as long-lived services with HTTP APIs

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -1,10 +1,10 @@
 # Contributing to Aden Agent Framework
 
-Thank you for your interest in contributing to the Aden Agent Framework! This document provides guidelines and information for contributors. We’re especially looking for help building tools, integrations([check #2805](https://github.com/adenhq/hive/issues/2805)), and example agents for the framework. If you’re interested in extending its functionality, this is the perfect place to start. 
+Thank you for your interest in contributing to the Aden Agent Framework! This document provides guidelines and information for contributors. We’re especially looking for help building tools, integrations ([check #2805](https://github.com/adenhq/hive/issues/2805)), and example agents for the framework. If you’re interested in extending its functionality, this is the perfect place to start. 
 
 ## Code of Conduct
 
-By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+By participating in this project, you agree to abide by our [Code of Conduct](docs/CODE_OF_CONDUCT.md).
 
 ## Issue Assignment Policy
 
@@ -35,15 +35,22 @@ You may submit PRs without prior assignment for:
 
 1. Fork the repository
 2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/hive.git`
-3. Create a feature branch: `git checkout -b feature/your-feature-name`
-4. Make your changes
-5. Run checks and tests:
+3. Add the upstream repository: `git remote add upstream https://github.com/adenhq/hive.git`
+4. Sync with upstream to ensure you're starting from the latest code:
+   ```bash
+   git fetch upstream
+   git checkout main
+   git merge upstream/main
+   ```
+5. Create a feature branch: `git checkout -b feature/your-feature-name`
+6. Make your changes
+7. Run checks and tests:
    ```bash
    make check    # Lint and format checks (ruff check + ruff format --check on core/ and tools/)
    make test     # Core tests (cd core && pytest tests/ -v)
    ```
-6. Commit your changes following our commit conventions
-7. Push to your fork and submit a Pull Request
+8. Commit your changes following our commit conventions
+9. Push to your fork and submit a Pull Request
 
 ## Development Setup
 
@@ -58,6 +65,52 @@ You may submit PRs without prior assignment for:
 
 > **Tip:** Installing Claude Code skills is optional for running existing agents, but required if you plan to **build new agents**.
 
+## Troubleshooting Setup Issues
+
+If you encounter issues while setting up the development environment, the following steps may help:
+
+### `make: command not found`
+Install `make` using:
+
+```bash
+sudo apt install make
+
+uv: command not found
+
+Install uv using:
+
+curl -LsSf https://astral.sh/uv/install.sh | sh
+source ~/.bashrc
+
+ruff: not found
+
+If linting fails due to a missing ruff command, install it with:
+
+uv tool install ruff
+
+WSL Path Recommendation
+
+When using WSL, it is recommended to clone the repository inside your Linux home directory (e.g., ~/hive) instead of under /mnt/c/... to avoid potential performance and permission issues.
+
+
+---
+
+# ✅ Why This Is Good
+
+- Clear
+- Professional tone
+- No unnecessary explanation
+- Under micro-fix size
+- Based on real contributor experience
+- Won’t annoy maintainers
+
+---
+
+Now:
+
+```bash
+git checkout -b docs/setup-troubleshooting
+
 ## Commit Convention
 
 We follow [Conventional Commits](https://www.conventionalcommits.org/):
@@ -92,8 +145,7 @@ docs(readme): update installation instructions
 2. Update documentation if needed
 3. Add tests for new functionality
 4. Ensure `make check` and `make test` pass
-5. Update the CHANGELOG.md if applicable
-6. Request review from maintainers
+5. Request review from maintainers
 
 ### PR Title Format
 
@@ -120,12 +172,14 @@ feat(component): add new feature description
 - Use meaningful variable and function names
 - Keep functions focused and small
 
+For linting and formatting (Ruff, pre-commit hooks), see [Linting & Formatting Setup](docs/contributing-lint-setup.md).
+
 ## Testing
 
 > **Note:** When testing agents in `exports/`, always set PYTHONPATH:
 >
 > ```bash
-> PYTHONPATH=core:exports python -m agent_name test
+> PYTHONPATH=exports uv run python -m agent_name test
 > ```
 
 ```bash
@@ -138,8 +192,11 @@ make test
 # Or run tests directly
 cd core && pytest tests/ -v
 
+# Run tools package tests (when contributing to tools/)
+cd tools && uv run pytest tests/ -v
+
 # Run tests for a specific agent
-PYTHONPATH=core:exports python -m agent_name test
+PYTHONPATH=exports uv run python -m agent_name test
 ```
 
 > **CI also validates** that all exported agent JSON files (`exports/*/agent.json`) are well-formed JSON. Ensure your agent exports are valid before submitting.
@@ -152,4 +209,4 @@ By submitting a Pull Request, you agree that your contributions will be licensed
 
 Feel free to open an issue for questions or join our [Discord community](https://discord.com/invite/MXE49hrKDk).
 
-Thank you for contributing!
+Thank you for contributing!

Makefile

@@ -1,12 +1,14 @@
-.PHONY: lint format check test install-hooks help
+.PHONY: lint format check test install-hooks help frontend-install frontend-dev frontend-build
 
 help: ## Show this help
 	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
 		awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2}'
 
-lint: ## Run ruff linter (with auto-fix)
+lint: ## Run ruff linter and formatter (with auto-fix)
 	cd core && ruff check --fix .
 	cd tools && ruff check --fix .
+	cd core && ruff format .
+	cd tools && ruff format .
 
 format: ## Run ruff formatter
 	cd core && ruff format .
@@ -18,9 +20,30 @@ check: ## Run all checks without modifying files (CI-safe)
 	cd core && ruff format --check .
 	cd tools && ruff format --check .
 
-test: ## Run all tests
-	cd core && python -m pytest tests/ -v
+test: ## Run all tests (core + tools, excludes live)
+	cd core && uv run python -m pytest tests/ -v
+	cd tools && uv run python -m pytest -v
+
+test-tools: ## Run tool tests only (mocked, no credentials needed)
+	cd tools && uv run python -m pytest -v
+
+test-live: ## Run live integration tests (requires real API credentials)
+	cd tools && uv run python -m pytest -m live -s -o "addopts=" --log-cli-level=INFO
+
+test-all: ## Run everything including live tests
+	cd core && uv run python -m pytest tests/ -v
+	cd tools && uv run python -m pytest -v
+	cd tools && uv run python -m pytest -m live -s -o "addopts=" --log-cli-level=INFO
 
 install-hooks: ## Install pre-commit hooks
-	pip install pre-commit
+	uv pip install pre-commit
 	pre-commit install
+
+frontend-install: ## Install frontend npm packages
+	cd core/frontend && npm install
+
+frontend-dev: ## Start frontend dev server
+	cd core/frontend && npm run dev
+
+frontend-build: ## Build frontend for production
+	cd core/frontend && npm run build

PR.md

@@ -1,51 +0,0 @@
-## Summary
-- **Added HubSpot integration** — new HubSpot MCP tool with search, get, create, and update operations for contacts, companies, and deals. Includes OAuth2 provider for HubSpot credentials and credential store adapter for the tools layer.
-- **Replaced web_scrape tool with Playwright + stealth** — swapped httpx/BeautifulSoup for a headless Chromium browser using `playwright` (async API) and `playwright-stealth`, enabling JS-rendered page scraping and bot detection evasion
-- **Added empty response retry logic** — LLM provider now detects empty responses (e.g. Gemini returning 200 with no content on rate limit) and retries with exponential backoff, preventing hallucinated output from the cleanup LLM
-- **Added context-aware input compaction** — LLM nodes now estimate input token count before calling the model and progressively truncate the largest values if they exceed the context window budget
-- **Increased rate limit retries to 10** with verbose `[retry]` and `[compaction]` logging that includes model name, finish reason, and attempt count
-- **Updated setup scripts** — `scripts/setup-python.sh` now installs Playwright Chromium browser automatically for web scraping support
-- **Interactive quickstart onboarding** — `quickstart.sh` rewritten as bee-themed interactive wizard that detects existing API keys (including Claude Code subscription), lets user pick ONE default LLM provider, and saves configuration to `~/.hive/configuration.json`
-- **Fixed lint errors** across `hubspot_tool.py` (line length) and `agent_builder_server.py` (unused variable)
-
-## Changed files
-
-### HubSpot Integration
-- `tools/src/aden_tools/tools/hubspot_tool/` — New MCP tool: contacts, companies, and deals CRUD
-- `tools/src/aden_tools/tools/__init__.py` — Registered HubSpot tools
-- `tools/src/aden_tools/credentials/integrations.py` — HubSpot credential integration
-- `tools/src/aden_tools/credentials/__init__.py` — Updated credential exports
-- `core/framework/credentials/oauth2/hubspot_provider.py` — HubSpot OAuth2 provider
-- `core/framework/credentials/oauth2/__init__.py` — Registered HubSpot OAuth2 provider
-- `core/framework/runner/runner.py` — Updated runner for credential support
-
-### Web Scrape Rewrite
-- `tools/src/aden_tools/tools/web_scrape_tool/web_scrape_tool.py` — Playwright async rewrite
-- `tools/src/aden_tools/tools/web_scrape_tool/README.md` — Updated docs
-- `tools/pyproject.toml` — Added `playwright`, `playwright-stealth` deps
-- `tools/Dockerfile` — Added `playwright install chromium --with-deps`
-- `scripts/setup-python.sh` — Added Playwright Chromium browser install step
-
-### LLM Reliability
-- `core/framework/llm/litellm.py` — Empty response retry + max retries 10 + verbose logging
-- `core/framework/graph/node.py` — Input compaction via `_compact_inputs()`, `_estimate_tokens()`, `_get_context_limit()`
-
-### Quickstart & Setup
-- `quickstart.sh` — Interactive bee-themed onboarding wizard with single provider selection
-- `~/.hive/configuration.json` — New user config file for default LLM provider/model
-
-### Fixes
-- `core/framework/mcp/agent_builder_server.py` — Removed unused variable
-- `tools/src/aden_tools/tools/hubspot_tool/hubspot_tool.py` — Fixed E501 line length violations
-
-## Test plan
-- [ ] Run `make lint` — passes clean
-- [ ] Run `./quickstart.sh` and verify interactive flow works, config saved to `~/.hive/configuration.json`
-- [ ] Run `./scripts/setup-python.sh` and verify Playwright Chromium installs
-- [ ] Run `pytest tests/tools/test_web_scrape_tool.py -v`
-- [ ] Run agent against a JS-heavy site and verify `web_scrape` returns rendered content
-- [ ] Set `HUBSPOT_ACCESS_TOKEN` and verify HubSpot tool CRUD operations work
-- [ ] Trigger rate limit and verify `[retry]` logs appear with correct attempt counts
-- [ ] Run agent with large inputs and verify `[compaction]` logs show truncation
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img width="100%" alt="Hive Banner" src="https://storage.googleapis.com/aden-prod-assets/website/aden-title-card.png" />
+  <img width="100%" alt="Hive Banner" src="https://github.com/user-attachments/assets/a027429b-5d3c-4d34-88e4-0feaeaabbab3" />
 </p>
 
 <p align="center">
@@ -13,16 +13,19 @@
   <a href="docs/i18n/ko.md">한국어</a>
 </p>
 
-[![Apache 2.0 License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/adenhq/hive/blob/main/LICENSE)
-[![Y Combinator](https://img.shields.io/badge/Y%20Combinator-Aden-orange)](https://www.ycombinator.com/companies/aden)
-[![Discord](https://img.shields.io/discord/1172610340073242735?logo=discord&labelColor=%235462eb&logoColor=%23f5f5f5&color=%235462eb)](https://discord.com/invite/MXE49hrKDk)
-[![Twitter Follow](https://img.shields.io/twitter/follow/teamaden?logo=X&color=%23f5f5f5)](https://x.com/aden_hq)
-[![LinkedIn](https://custom-icon-badges.demolab.com/badge/LinkedIn-0A66C2?logo=linkedin-white&logoColor=fff)](https://www.linkedin.com/company/teamaden/)
+<p align="center">
+  <a href="https://github.com/aden-hive/hive/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="Apache 2.0 License" /></a>
+  <a href="https://www.ycombinator.com/companies/aden"><img src="https://img.shields.io/badge/Y%20Combinator-Aden-orange" alt="Y Combinator" /></a>
+  <a href="https://discord.com/invite/MXE49hrKDk"><img src="https://img.shields.io/discord/1172610340073242735?logo=discord&labelColor=%235462eb&logoColor=%23f5f5f5&color=%235462eb" alt="Discord" /></a>
+  <a href="https://x.com/aden_hq"><img src="https://img.shields.io/twitter/follow/teamaden?logo=X&color=%23f5f5f5" alt="Twitter Follow" /></a>
+  <a href="https://www.linkedin.com/company/teamaden/"><img src="https://custom-icon-badges.demolab.com/badge/LinkedIn-0A66C2?logo=linkedin-white&logoColor=fff" alt="LinkedIn" /></a>
+  <img src="https://img.shields.io/badge/MCP-102_Tools-00ADD8?style=flat-square" alt="MCP" />
+</p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/AI_Agents-Self--Improving-brightgreen?style=flat-square" alt="AI Agents" />
   <img src="https://img.shields.io/badge/Multi--Agent-Systems-blue?style=flat-square" alt="Multi-Agent" />
-  <img src="https://img.shields.io/badge/Goal--Driven-Development-purple?style=flat-square" alt="Goal-Driven" />
+  <img src="https://img.shields.io/badge/Headless-Development-purple?style=flat-square" alt="Headless" />
   <img src="https://img.shields.io/badge/Human--in--the--Loop-orange?style=flat-square" alt="HITL" />
   <img src="https://img.shields.io/badge/Production--Ready-red?style=flat-square" alt="Production" />
 </p>
@@ -30,15 +33,16 @@
   <img src="https://img.shields.io/badge/OpenAI-supported-412991?style=flat-square&logo=openai" alt="OpenAI" />
   <img src="https://img.shields.io/badge/Anthropic-supported-d4a574?style=flat-square" alt="Anthropic" />
   <img src="https://img.shields.io/badge/Google_Gemini-supported-4285F4?style=flat-square&logo=google" alt="Gemini" />
-  <img src="https://img.shields.io/badge/MCP-19_Tools-00ADD8?style=flat-square" alt="MCP" />
 </p>
 
 ## Overview
 
-Build reliable, self-improving AI agents without hardcoding workflows. Define your goal through conversation with a coding agent, and the framework generates a node graph with dynamically created connection code. When things break, the framework captures failure data, evolves the agent through the coding agent, and redeploys. Built-in human-in-the-loop nodes, credential management, and real-time monitoring give you control without sacrificing adaptability.
+Build autonomous, reliable, self-improving AI agents without hardcoding workflows. Define your goal through conversation with hive coding agent(queen), and the framework generates a node graph with dynamically created connection code. When things break, the framework captures failure data, evolves the agent through the coding agent, and redeploys. Built-in human-in-the-loop nodes, credential management, and real-time monitoring give you control without sacrificing adaptability.
 
 Visit [adenhq.com](https://adenhq.com) for complete documentation, examples, and guides.
 
+[![Hive Demo](https://img.youtube.com/vi/XDOG9fOaLjU/maxresdefault.jpg)](https://www.youtube.com/watch?v=XDOG9fOaLjU)
+
 ## Who Is Hive For?
 
 Hive is designed for developers and teams who want to build **production-grade AI agents** without manually wiring complex workflows.
@@ -46,7 +50,7 @@ Hive is designed for developers and teams who want to build **production-grade A
 Hive is a good fit if you:
 
 - Want AI agents that **execute real business processes**, not demos
-- Prefer **goal-driven development** over hardcoded workflows
+- Need **fast or high volume agent execution** over open workflow
 - Need **self-healing and adaptive agents** that improve over time
 - Require **human-in-the-loop control**, observability, and cost limits
 - Plan to run agents in **production environments**
@@ -58,94 +62,97 @@ Hive may not be the best fit if you’re only experimenting with simple agent ch
 Use Hive when you need:
 
 - Long-running, autonomous agents
-- Multi-agent coordination
+- Strong guardrails, process, and controls
 - Continuous improvement based on failures
-- Strong monitoring, safety, and budget controls
+- Multi-agent coordination
 - A framework that evolves with your goals
 
-
-## What is Aden
-
-<p align="center">
-  <img width="100%" alt="Aden Architecture" src="docs/assets/aden-architecture-diagram.jpg" />
-</p>
-
-Aden is a platform for building, deploying, operating, and adapting AI agents:
-
-- **Build** - A Coding Agent generates specialized Worker Agents (Sales, Marketing, Ops) from natural language goals
-- **Deploy** - Headless deployment with CI/CD integration and full API lifecycle management
-- **Operate** - Real-time monitoring, observability, and runtime guardrails keep agents reliable
-- **Adapt** - Continuous evaluation, supervision, and adaptation ensure agents improve over time
-- **Infra** - Shared memory, LLM integrations, tools, and skills power every agent
-
 ## Quick Links
 
 - **[Documentation](https://docs.adenhq.com/)** - Complete guides and API reference
 - **[Self-Hosting Guide](https://docs.adenhq.com/getting-started/quickstart)** - Deploy Hive on your infrastructure
-- **[Changelog](https://github.com/adenhq/hive/releases)** - Latest updates and releases
-<!-- - **[Roadmap](https://adenhq.com/roadmap)** - Upcoming features and plans -->
+- **[Changelog](https://github.com/aden-hive/hive/releases)** - Latest updates and releases
+- **[Roadmap](docs/roadmap.md)** - Upcoming features and plans
 - **[Report Issues](https://github.com/adenhq/hive/issues)** - Bug reports and feature requests
+- **[Contributing](CONTRIBUTING.md)** - How to contribute and submit PRs
 
 ## Quick Start
 
-## Prerequisites
+### Prerequisites
 
 - Python 3.11+ for agent development
-- Claude Code or Cursor for utilizing agent skills
+- An LLM provider that powers the agents
+- **ripgrep (optional, recommended on Windows):** The `search_files` tool uses ripgrep for faster file search. If not installed, a Python fallback is used. On Windows: `winget install BurntSushi.ripgrep` or `scoop install ripgrep`
 
 > **Note for Windows Users:** It is strongly recommended to use **WSL (Windows Subsystem for Linux)** or **Git Bash** to run this framework. Some core automation scripts may not execute correctly in standard Command Prompt or PowerShell.
 
 ### Installation
 
+> **Note**
+> Hive uses a `uv` workspace layout and is not installed with `pip install`.
+> Running `pip install -e .` from the repository root will create a placeholder package and Hive will not function correctly.
+> Please use the quickstart script below to set up the environment.
+
 ```bash
 # Clone the repository
-git clone https://github.com/adenhq/hive.git
+git clone https://github.com/aden-hive/hive.git
 cd hive
 
+
 # Run quickstart setup
 ./quickstart.sh
 ```
 
 This sets up:
+
 - **framework** - Core agent runtime and graph executor (in `core/.venv`)
 - **aden_tools** - MCP tools for agent capabilities (in `tools/.venv`)
-- All required Python dependencies
+- **credential store** - Encrypted API key storage (`~/.hive/credentials`)
+- **LLM provider** - Interactive default model configuration
+- All required Python dependencies with `uv`
+
+- At last, it will initiate the open hive interface in your browser
+
+> **Tip:** To reopen the dashboard later, run `hive open` from the project directory.
+
+<img width="2500" height="1214" alt="home-screen" src="https://github.com/user-attachments/assets/134d897f-5e75-4874-b00b-e0505f6b45c4" />
 
 ### Build Your First Agent
 
-```bash
-# Build an agent using Claude Code
-claude> /building-agents-construction
+Type the agent you want to build in the home input box
 
-# Test your agent
-claude> /testing-agent
+<img width="2500" height="1214" alt="Image" src="https://github.com/user-attachments/assets/1ce19141-a78b-46f5-8d64-dbf987e048f4" />
 
-# Run your agent
-PYTHONPATH=core:exports python -m your_agent_name run --input '{...}'
-```
+### Use Template Agents
 
-**[📖 Complete Setup Guide](ENVIRONMENT_SETUP.md)** - Detailed instructions for agent development
+Click "Try a sample agent" and check the templates. You can run a templates directly or choose to build your version on top of the existing template.
 
-### Cursor IDE Support
+### Run Agents
 
-Skills are also available in Cursor. To enable:
+Now you can run an agent by selectiing the agent (either an existing agent or example agent). You can click the Run button on the top left, or talk to the queen agent and it can run the agent for you.
 
-1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
-2. Run `MCP: Enable` to enable MCP servers
-3. Restart Cursor to load the MCP servers from `.cursor/mcp.json`
-4. Type `/` in Agent chat and search for skills (e.g., `/building-agents-construction`)
+<img width="2500" height="1214" alt="Image" src="https://github.com/user-attachments/assets/71c38206-2ad5-49aa-bde8-6698d0bc55f5" />
 
 ## Features
 
-- **Goal-Driven Development** - Define objectives in natural language; the coding agent generates the agent graph and connection code to achieve them
-- **Adaptiveness** - Framework captures failures, calibrates according to the objectives, and evolves the agent graph
-- **Dynamic Node Connections** - No predefined edges; connection code is generated by any capable LLM based on your goals
+- **Browser-Use** - Control the browser on your computer to achieve hard tasks
+- **Parallel Execution** - Execute the generated graph in parallel. This way you can have multiple agent compelteing the jobs for you
+- **[Goal-Driven Generation](docs/key_concepts/goals_outcome.md)** - Define objectives in natural language; the coding agent generates the agent graph and connection code to achieve them
+- **[Adaptiveness](docs/key_concepts/evolution.md)** - Framework captures failures, calibrates according to the objectives, and evolves the agent graph
+- **[Dynamic Node Connections](docs/key_concepts/graph.md)** - No predefined edges; connection code is generated by any capable LLM based on your goals
 - **SDK-Wrapped Nodes** - Every node gets shared memory, local RLM memory, monitoring, tools, and LLM access out of the box
-- **Human-in-the-Loop** - Intervention nodes that pause execution for human input with configurable timeouts and escalation
+- **[Human-in-the-Loop](docs/key_concepts/graph.md#human-in-the-loop)** - Intervention nodes that pause execution for human input with configurable timeouts and escalation
 - **Real-time Observability** - WebSocket streaming for live monitoring of agent execution, decisions, and node-to-node communication
-- **Cost & Budget Control** - Set spending limits, throttles, and automatic model degradation policies
 - **Production-Ready** - Self-hostable, built for scale and reliability
 
+## Integration
+
+<a href="https://github.com/aden-hive/hive/tree/main/tools/src/aden_tools/tools"><img width="100%" alt="Integration" src="https://github.com/user-attachments/assets/a1573f93-cf02-4bb8-b3d5-b305b05b1e51" /></a>
+Hive is built to be model-agnostic and system-agnostic.
+
+- **LLM flexibility** - Hive Framework is designed to support various types of LLMs, including hosted and local models through LiteLLM-compatible providers.
+- **Business system connectivity** - Hive Framework is designed to connect to all kinds of business systems as tools, such as CRM, support, messaging, data, file, and internal APIs via MCP.
+
 ## Why Aden
 
 Hive focuses on generating agents that run real business processes rather than generic agents. Instead of requiring you to manually design workflows, define agent interactions, and handle failures reactively, Hive flips the paradigm: **you describe outcomes, and the system builds itself**—delivering an outcome-driven, adaptive experience with an easy-to-use set of tools and integrations.
@@ -182,161 +189,161 @@ flowchart LR
     style V6 fill:#fff,stroke:#ed8c00,stroke-width:1px,color:#cc5d00
 ```
 
-### The Aden Advantage
+### The Hive Advantage
 
-| Traditional Frameworks     | Aden                                   |
+| Traditional Frameworks     | Hive                                   |
 | -------------------------- | -------------------------------------- |
 | Hardcode agent workflows   | Describe goals in natural language     |
 | Manual graph definition    | Auto-generated agent graphs            |
-| Reactive error handling    | Outcome-evaluation and adaptiveness               |
+| Reactive error handling    | Outcome-evaluation and adaptiveness    |
 | Static tool configurations | Dynamic SDK-wrapped nodes              |
 | Separate monitoring setup  | Built-in real-time observability       |
 | DIY budget management      | Integrated cost controls & degradation |
 
 ### How It Works
 
-1. **Define Your Goal** → Describe what you want to achieve in plain English
-2. **Coding Agent Generates** → Creates the agent graph, connection code, and test cases
-3. **Workers Execute** → SDK-wrapped nodes run with full observability and tool access
+1. **[Define Your Goal](docs/key_concepts/goals_outcome.md)** → Describe what you want to achieve in plain English
+2. **Coding Agent Generates** → Creates the [agent graph](docs/key_concepts/graph.md), connection code, and test cases
+3. **[Workers Execute](docs/key_concepts/worker_agent.md)** → SDK-wrapped nodes run with full observability and tool access
 4. **Control Plane Monitors** → Real-time metrics, budget enforcement, policy management
-5. **Adaptiveness** → On failure, the system evolves the graph and redeploys automatically
-
-## Run pre-built Agents (Coming Soon)
-
-### Run a sample agent
-Aden Hive provides a list of featured agents that you can use and build on top of.
-
-### Run an agent shared by others
-Put the agent in `exports/` and run `PYTHONPATH=core:exports python -m your_agent_name run --input '{...}'`
-
-
-For building and running goal-driven agents with the framework:
-
-```bash
-# One-time setup
-./quickstart.sh
-
-# This sets up:
-# - framework package (core runtime)
-# - aden_tools package (MCP tools)
-# - All Python dependencies
-
-# Build new agents using Claude Code skills
-claude> /building-agents-construction
-
-# Test agents
-claude> /testing-agent
-
-# Run agents
-PYTHONPATH=core:exports python -m agent_name run --input '{...}'
-```
-
-See [ENVIRONMENT_SETUP.md](ENVIRONMENT_SETUP.md) for complete setup instructions.
+5. **[Adaptiveness](docs/key_concepts/evolution.md)** → On failure, the system evolves the graph and redeploys automatically
 
 ## Documentation
 
-- **[Developer Guide](DEVELOPER.md)** - Comprehensive guide for developers
+- **[Developer Guide](docs/developer-guide.md)** - Comprehensive guide for developers
 - [Getting Started](docs/getting-started.md) - Quick setup instructions
 - [Configuration Guide](docs/configuration.md) - All configuration options
 - [Architecture Overview](docs/architecture/README.md) - System design and structure
 
 ## Roadmap
 
-Aden Hive Agent Framework aims to help developers build outcome-oriented, self-adaptive agents. See [ROADMAP.md](ROADMAP.md) for details.
+Aden Hive Agent Framework aims to help developers build outcome-oriented, self-adaptive agents. See [roadmap.md](docs/roadmap.md) for details.
 
 ```mermaid
-flowchart TD
-subgraph Foundation
-    direction LR
-    subgraph arch["Architecture"]
-        a1["Node-Based Architecture"]:::done
-        a2["Python SDK"]:::done
-        a3["LLM Integration"]:::done
-        a4["Communication Protocol"]:::done
-    end
-    subgraph ca["Coding Agent"]
-        b1["Goal Creation Session"]:::done
-        b2["Worker Agent Creation"]
-        b3["MCP Tools"]:::done
-    end
-    subgraph wa["Worker Agent"]
-        c1["Human-in-the-Loop"]:::done
-        c2["Callback Handlers"]:::done
-        c3["Intervention Points"]:::done
-        c4["Streaming Interface"]
-    end
-    subgraph cred["Credentials"]
-        d1["Setup Process"]:::done
-        d2["Pluggable Sources"]:::done
-        d3["Enterprise Secrets"]
-        d4["Integration Tools"]:::done
-    end
-    subgraph tools["Tools"]
-        e1["File Use"]:::done
-        e2["Memory STM/LTM"]:::done
-        e3["Web Search/Scraper"]:::done
-        e4["CSV/PDF"]:::done
-        e5["Excel/Email"]
-    end
-    subgraph core["Core"]
-        f1["Eval System"]
-        f2["Pydantic Validation"]:::done
-        f3["Documentation"]:::done
-        f4["Adaptiveness"]
-        f5["Sample Agents"]
-    end
-end
+flowchart TB
+    %% Main Entity
+    User([User])
 
-subgraph Expansion
-    direction LR
-    subgraph intel["Intelligence"]
-        g1["Guardrails"]
-        g2["Streaming Mode"]
-        g3["Image Generation"]
-        g4["Semantic Search"]
+    %% =========================================
+    %% EXTERNAL EVENT SOURCES
+    %% =========================================
+    subgraph ExtEventSource [External Event Source]
+        E_Sch["Schedulers"]
+        E_WH["Webhook"]
+        E_SSE["SSE"]
     end
-    subgraph mem["Memory Iteration"]
-        h1["Message Model & Sessions"]
-        h2["Storage Migration"]
-        h3["Context Building"]
-        h4["Proactive Compaction"]
-        h5["Token Tracking"]
-    end
-    subgraph evt["Event System"]
-        i1["Event Bus for Nodes"]
-    end
-    subgraph cas["Coding Agent Support"]
-        j1["Claude Code"]
-        j2["Cursor"]
-        j3["Opencode"]
-        j4["Antigravity"]
-    end
-    subgraph plat["Platform"]
-        k1["JavaScript/TypeScript SDK"]
-        k2["Custom Tool Integrator"]
-        k3["Windows Support"]
-    end
-    subgraph dep["Deployment"]
-        l1["Self-Hosted"]
-        l2["Cloud Services"]
-        l3["CI/CD Pipeline"]
-    end
-    subgraph tmpl["Templates"]
-        m1["Sales Agent"]
-        m2["Marketing Agent"]
-        m3["Analytics Agent"]
-        m4["Training Agent"]
-        m5["Smart Form Agent"]
-    end
-end
 
-classDef done fill:#9e9e9e,color:#fff,stroke:#757575
+    %% =========================================
+    %% SYSTEM NODES
+    %% =========================================
+    subgraph WorkerBees [Worker Bees]
+        WB_C["Conversation"]
+        WB_SP["System prompt"]
+
+        subgraph Graph [Graph]
+            direction TB
+            N1["Node"] --> N2["Node"] --> N3["Node"]
+            N1 -.-> AN["Active Node"]
+            N2 -.-> AN
+            N3 -.-> AN
+
+            %% Nested Event Loop Node
+            subgraph EventLoopNode [Event Loop Node]
+                ELN_L["listener"]
+                ELN_SP["System Prompt<br/>(Task)"]
+                ELN_EL["Event loop"]
+                ELN_C["Conversation"]
+            end
+        end
+    end
+
+    subgraph JudgeNode [Judge]
+        J_C["Criteria"]
+        J_P["Principles"]
+        J_EL["Event loop"] <--> J_S["Scheduler"]
+    end
+
+    subgraph QueenBee [Queen Bee]
+        QB_SP["System prompt"]
+        QB_EL["Event loop"]
+        QB_C["Conversation"]
+    end
+
+    subgraph Infra [Infra]
+        SA["Sub Agent"]
+        TR["Tool Registry"]
+        WTM["Write through Conversation Memory<br/>(Logs/RAM/Harddrive)"]
+        SM["Shared Memory<br/>(State/Harddrive)"]
+        EB["Event Bus<br/>(RAM)"]
+        CS["Credential Store<br/>(Harddrive/Cloud)"]
+    end
+
+    subgraph PC [PC]
+        B["Browser"]
+        CB["Codebase<br/>v 0.0.x ... v n.n.n"]
+    end
+
+    %% =========================================
+    %% CONNECTIONS & DATA FLOW
+    %% =========================================
+
+    %% External Event Routing
+    E_Sch --> ELN_L
+    E_WH --> ELN_L
+    E_SSE --> ELN_L
+    ELN_L -->|"triggers"| ELN_EL
+
+    %% User Interactions
+    User -->|"Talk"| WB_C
+    User -->|"Talk"| QB_C
+    User -->|"Read/Write Access"| CS
+
+    %% Inter-System Logic
+    ELN_C <-->|"Mirror"| WB_C
+    WB_C -->|"Focus"| AN
+
+    WorkerBees -->|"Inquire"| JudgeNode
+    JudgeNode -->|"Approve"| WorkerBees
+
+    %% Judge Alignments
+    J_C <-.->|"aligns"| WB_SP
+    J_P <-.->|"aligns"| QB_SP
+
+    %% Escalate path
+    J_EL -->|"Report (Escalate)"| QB_EL
+
+    %% Pub/Sub Logic
+    AN -->|"publish"| EB
+    EB -->|"subscribe"| QB_C
+
+    %% Infra and Process Spawning
+    ELN_EL -->|"Spawn"| SA
+    SA -->|"Inform"| ELN_EL
+    SA -->|"Starts"| B
+    B -->|"Report"| ELN_EL
+    TR -->|"Assigned"| ELN_EL
+    CB -->|"Modify Worker Bee"| WB_C
+
+    %% =========================================
+    %% SHARED MEMORY & LOGS ACCESS
+    %% =========================================
+
+    %% Worker Bees Access (link to node inside Graph subgraph)
+    AN <-->|"Read/Write"| WTM
+    AN <-->|"Read/Write"| SM
+
+    %% Queen Bee Access
+    QB_C <-->|"Read/Write"| WTM
+    QB_EL <-->|"Read/Write"| SM
+
+    %% Credentials Access
+    CS -->|"Read Access"| QB_C
 ```
+
 ## Contributing
+We welcome contributions from the community! We’re especially looking for help building tools, integrations, and example agents for the framework ([check #2805](https://github.com/aden-hive/hive/issues/2805)). If you’re interested in extending its functionality, this is the perfect place to start. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
-We welcome contributions from the community! We’re especially looking for help building tools, integrations, and example agents for the framework ([check #2805](https://github.com/adenhq/hive/issues/2805)). If you’re interested in extending its functionality, this is the perfect place to start. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
-
-**Important:** Please get assigned to an issue before submitting a PR. Comment on an issue to claim it, and a maintainer will assign you. Issues with reproducible steps and proposals are prioritized. This helps prevent duplicate work. 
+**Important:** Please get assigned to an issue before submitting a PR. Comment on an issue to claim it, and a maintainer will assign you. Issues with reproducible steps and proposals are prioritized. This helps prevent duplicate work.
 
 1. Find or create an issue and get assigned
 2. Fork the repository
@@ -369,13 +376,9 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS
 
 ## Frequently Asked Questions (FAQ)
 
-**Q: Does Hive depend on LangChain or other agent frameworks?**
-
-No. Hive is built from the ground up with no dependencies on LangChain, CrewAI, or other agent frameworks. The framework is designed to be lean and flexible, generating agent graphs dynamically rather than relying on predefined components.
-
 **Q: What LLM providers does Hive support?**
 
-Hive supports 100+ LLM providers through LiteLLM integration, including OpenAI (GPT-4, GPT-4o), Anthropic (Claude models), Google Gemini, DeepSeek, Mistral, Groq, and many more. Simply set the appropriate API key environment variable and specify the model name.
+Hive supports 100+ LLM providers through LiteLLM integration, including OpenAI (GPT-4, GPT-4o), Anthropic (Claude models), Google Gemini, DeepSeek, Mistral, Groq, and many more. Simply set the appropriate API key environment variable and specify the model name. We recommend using Claude, GLM and Gemini as they have the best performance.
 
 **Q: Can I use Hive with local AI models like Ollama?**
 
@@ -383,37 +386,25 @@ Yes! Hive supports local models through LiteLLM. Simply use the model name forma
 
 **Q: What makes Hive different from other agent frameworks?**
 
-Hive generates your entire agent system from natural language goals using a coding agent—you don't hardcode workflows or manually define graphs. When agents fail, the framework automatically captures failure data, evolves the agent graph, and redeploys. This self-improving loop is unique to Aden.
+Hive generates your entire agent system from natural language goals using a coding agent—you don't hardcode workflows or manually define graphs. When agents fail, the framework automatically captures failure data, [evolves the agent graph](docs/key_concepts/evolution.md), and redeploys. This self-improving loop is unique to Aden.
 
 **Q: Is Hive open-source?**
 
 Yes, Hive is fully open-source under the Apache License 2.0. We actively encourage community contributions and collaboration.
 
-**Q: Does Hive collect data from users?**
-
-Hive collects telemetry data for monitoring and observability purposes, including token usage, latency metrics, and cost tracking. Content capture (prompts and responses) is configurable and stored with team-scoped data isolation. All data stays within your infrastructure when self-hosted.
-
-**Q: What deployment options does Hive support?**
-
-Hive supports self-hosted deployments via Python packages. See the [Environment Setup Guide](ENVIRONMENT_SETUP.md) for installation instructions. Cloud deployment options and Kubernetes-ready configurations are on the roadmap.
-
 **Q: Can Hive handle complex, production-scale use cases?**
 
 Yes. Hive is explicitly designed for production environments with features like automatic failure recovery, real-time observability, cost controls, and horizontal scaling support. The framework handles both simple automations and complex multi-agent workflows.
 
 **Q: Does Hive support human-in-the-loop workflows?**
 
-Yes, Hive fully supports human-in-the-loop workflows through intervention nodes that pause execution for human input. These include configurable timeouts and escalation policies, allowing seamless collaboration between human experts and AI agents.
-
-**Q: What monitoring and debugging tools does Hive provide?**
-
-Hive includes comprehensive observability features: real-time WebSocket streaming for live agent execution monitoring, TimescaleDB-powered analytics for cost and performance metrics, health check endpoints for Kubernetes integration, and MCP tools for agent execution, including file operations, web search, data processing, and more.
+Yes, Hive fully supports [human-in-the-loop](docs/key_concepts/graph.md#human-in-the-loop) workflows through intervention nodes that pause execution for human input. These include configurable timeouts and escalation policies, allowing seamless collaboration between human experts and AI agents.
 
 **Q: What programming languages does Hive support?**
 
 The Hive framework is built in Python. A JavaScript/TypeScript SDK is on the roadmap.
 
-**Q: Can Aden agents interact with external tools and APIs?**
+**Q: Can Hive agents interact with external tools and APIs?**
 
 Yes. Aden's SDK-wrapped nodes provide built-in tool access, and the framework supports flexible tool ecosystems. Agents can integrate with external APIs, databases, and services through the node architecture.
 
@@ -423,24 +414,12 @@ Hive provides granular budget controls including spending limits, throttles, and
 
 **Q: Where can I find examples and documentation?**
 
-Visit [docs.adenhq.com](https://docs.adenhq.com/) for complete guides, API reference, and getting started tutorials. The repository also includes documentation in the `docs/` folder and a comprehensive [DEVELOPER.md](DEVELOPER.md) guide.
+Visit [docs.adenhq.com](https://docs.adenhq.com/) for complete guides, API reference, and getting started tutorials. The repository also includes documentation in the `docs/` folder and a comprehensive [developer guide](docs/developer-guide.md).
 
 **Q: How can I contribute to Aden?**
 
 Contributions are welcome! Fork the repository, create your feature branch, implement your changes, and submit a pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 
-**Q: When will my team start seeing results from Aden's adaptive agents?**
-
-Aden's adaptation loop begins working from the first execution. When an agent fails, the framework captures the failure data, helping developers evolve the agent graph through the coding agent. How quickly this translates to measurable results depends on the complexity of your use case, the quality of your goal definitions, and the volume of executions generating feedback.
-
-**Q: How does Hive compare to other agent frameworks?**
-
-Hive focuses on generating agents that run real business processes, rather than generic agents. This vision emphasizes outcome-driven design, adaptability, and an easy-to-use set of tools and integrations.
-
-**Q: Does Aden offer enterprise support?**
-
-For enterprise inquiries, contact the Aden team through [adenhq.com](https://adenhq.com) or join our [Discord community](https://discord.com/invite/MXE49hrKDk) for support and discussions.
-
 ---
 
 <p align="center">

ROADMAP.md

@@ -1,299 +0,0 @@
-# Product Roadmap
-
-Aden Agent Framework aims to help developers build outcome oriented, self-adaptive agents. Please find our roadmap here
-
-```mermaid
-flowchart TD
-subgraph Foundation
-    direction LR
-    subgraph arch["Architecture"]
-        a1["Node-Based Architecture"]:::done
-        a2["Python SDK"]:::done
-        a3["LLM Integration"]:::done
-        a4["Communication Protocol"]:::done
-    end
-    subgraph ca["Coding Agent"]
-        b1["Goal Creation Session"]:::done
-        b2["Worker Agent Creation"]
-        b3["MCP Tools"]:::done
-    end
-    subgraph wa["Worker Agent"]
-        c1["Human-in-the-Loop"]:::done
-        c2["Callback Handlers"]:::done
-        c3["Intervention Points"]:::done
-        c4["Streaming Interface"]
-    end
-    subgraph cred["Credentials"]
-        d1["Setup Process"]:::done
-        d2["Pluggable Sources"]:::done
-        d3["Enterprise Secrets"]
-        d4["Integration Tools"]:::done
-    end
-    subgraph tools["Tools"]
-        e1["File Use"]:::done
-        e2["Memory STM/LTM"]:::done
-        e3["Web Search/Scraper"]:::done
-        e4["CSV/PDF"]:::done
-        e5["Excel/Email"]
-    end
-    subgraph core["Core"]
-        f1["Eval System"]
-        f2["Pydantic Validation"]:::done
-        f3["Documentation"]:::done
-        f4["Adaptiveness"]
-        f5["Sample Agents"]
-    end
-end
-
-subgraph Expansion
-    direction LR
-    subgraph intel["Intelligence"]
-        g1["Guardrails"]
-        g2["Streaming Mode"]
-        g3["Image Generation"]
-        g4["Semantic Search"]
-    end
-    subgraph mem["Memory Iteration"]
-        h1["Message Model & Sessions"]
-        h2["Storage Migration"]
-        h3["Context Building"]
-        h4["Proactive Compaction"]
-        h5["Token Tracking"]
-    end
-    subgraph evt["Event System"]
-        i1["Event Bus for Nodes"]
-    end
-    subgraph cas["Coding Agent Support"]
-        j1["Claude Code"]
-        j2["Cursor"]
-        j3["Opencode"]
-        j4["Antigravity"]
-    end
-    subgraph plat["Platform"]
-        k1["JavaScript/TypeScript SDK"]
-        k2["Custom Tool Integrator"]
-        k3["Windows Support"]
-    end
-    subgraph dep["Deployment"]
-        l1["Self-Hosted"]
-        l2["Cloud Services"]
-        l3["CI/CD Pipeline"]
-    end
-    subgraph tmpl["Templates"]
-        m1["Sales Agent"]
-        m2["Marketing Agent"]
-        m3["Analytics Agent"]
-        m4["Training Agent"]
-        m5["Smart Form Agent"]
-    end
-end
-
-classDef done fill:#9e9e9e,color:#fff,stroke:#757575
-```
-
----
-
-## Phase 1: Foundation
-
-### Backbone Architecture
-- [ ] **Node-Based Architecture (Agent as a node)**
-    - [x] Object schema definition
-    - [x] Node wrapper SDK
-    - [x] Shared memory access
-    - [ ] Default monitoring hooks
-    - [x] Tool access layer
-    - [x] LLM integration layer (Natively supports all mainstream LLMs through LiteLLM)
-        - [x] Anthropic
-        - [x] OpenAI
-        - [x] Google
-- [x] **Communication protocol between nodes**
-- [x] **[Coding Agent] Goal Creation Session** (separate from coding session)
-    - [x] Instruction back and forth
-    - [x] Goal Object schema definition
-    - [x] Being able to generate the test cases
-    - [x] Test case validation for worker agent (Outcome driven)
-- [ ] **[Coding Agent] Worker Agent Creation**
-    - [x] Coding Agent tools
-    - [ ] Use Template Agent as a start
-    - [x] Use our MCP tools
-- [ ] **[Worker Agent] Human-in-the-Loop**
-    - [x] Worker Agents request with questions and options
-    - [x] Callback Handler System to receive events throughout execution
-    - [x] Tool-Based Intervention Points (tool to pause execution and request human input)
-    - [x] Multiple entrypoint for different event source (e.g. Human input, webhook)
-    - [ ] Streaming Interface for Real-time Monitoring
-    - [x] Request State Management
-
-### Credential Management
-- [x] **Credentials Setup Process**
-    - [x] Install Credential MCP
-- [x] **Pluggable Credential Sources**
-    - [x] **Abstraction & Local Sources**
-        - [x] Introduce `CredentialSource` base class
-        - [x] Refactor existing logic into `EnvVarSource`
-        - [x] Implementation of Source Priority Chain mechanism
-        - [ ] Foundation unit tests
-    - [ ] **Enterprise Secret Managers**
-        - [x] `VaultSource` (HashiCorp Vault)
-        - [ ] `AWSSecretsSource` (AWS Secrets Manager)
-        - [ ] `AzureKeyVaultSource` (Azure Key Vault)
-        - [ ] Management of optional provider dependencies
-    - [ ] **Advanced Features**
-        - [x] Credential expiration and auto-refresh
-        - [ ] Audit logging for compliance/tracking
-        - [ ] Per-environment configuration support
-    - [ ] **Documentation & DX**
-        - [ ] Comprehensive source documentation
-        - [ ] Example configurations for all providers
-    - [x] **Integration as tools coverage**
-        - [x] Gsuite Tools
-        - [x] Social Media
-            - [ ] Twitter(X)
-            - [x] Github
-            - [ ] Instagram
-        - [ ] SAAS
-            - [ ] Hubspot
-            - [ ] Slack
-            - [ ] Teams
-            - [ ] Zoom
-            - [ ] Stripe
-            - [ ] Salesforce
-
-> [!IMPORTANT]
-> **Community Contribution Wanted**: We appreciate help from the community to expand the "Integration as tools" capability. Leave an issue of the integration you want to support via Hive!
-
-### Essential Tools
-- [x] **File Use Tool Kit**
-- [X] **Memory Tools**
-    - [x] STM Layer Tool (state-based short-term memory)
-    - [x] LTM Layer Tool (RLM - long-term memory)
-- [ ] **Infrastructure Tools**
-    - [x] Runtime Log Tool (logs for coding agent)
-    - [x] Web Search
-    - [x] Web Scraper
-    - [x] CSV tools
-    - [x] PDF tools
-    - [ ] Excel tools
-    - [ ] Email Tools
-    - [ ] Recipe for "Add your own tools"
-
-### Memory & File System
-- [x] DB for long-term persistent memory (Filesystem as durable scratchpad pattern)
-- [x] Session Local memory isolation
-
-### Eval System (Basic)
-- [x] Test Driven - Run test case for all agent iteration
-- [ ] Failure recording mechanism
-- [ ] SDK for defining failure conditions
-- [ ] Basic observability hooks
-- [ ] User-driven log analysis (OSS approach)
-
-### Data Validation
-- [x] Natively Support data validation of LLMs output with Pydantic
-
-### Developer Experience
-- [ ] **MVP Features**
-    - [ ] Debugging mode
-    - [ ] CLI tools for memory management
-    - [ ] CLI tools for credential management
-- [ ] **MVP Resources & Documentation**
-    - [x] Quick start guide
-    - [x] Goal creation guide
-    - [x] Agent creation guide
-    - [x] GitHub Page setup
-    - [x] README with examples
-    - [x] Contributing guidelines
-    - [ ] Introduction Video
-
-### Adaptiveness
-- [ ] Runtime data feedback loop
-- [ ] Instant Developer Feedback for improvement
-
-### Sample Agents
-- [ ] Knowledge Agent
-- [ ] Blog Writer Agent
-- [ ] SDR Agent
-
----
-
-## Phase 2: Expansion
-
-### Basic Guardrails
-- [ ] Support Basic Monitoring from Agent node SDK
-- [ ] SDK guardrail implementation (in node)
-- [ ] Guardrail type support (Determined Condition as Guardrails)
-
-### Agent Capability
-- [ ] Streaming mode support
-- [ ] Image Generation support
-- [ ] Take end user input Image and flatfile understand capability
-
-### Event-loop For Nodes (Opencode-style)
-- [ ] **Event bus**
-
-### Memory System Iteration
-- [ ] **Message Model & Session Management**
-    - [ ] Introduce `Message` class with structured content types
-    - [ ] Implement `Session` classes for conversation state
-- [ ] **Storage Migration**
-    - [ ] Implement granular per-message file persistence (`/message/[agentID]/...`)
-    - [ ] Migrate from monolithic run storage
-- [ ] **Context Building & Conversation Loop**
-    - [ ] Implement `Message.stream(sessionID)`
-    - [ ] Update `LLMNode.execute()` for full context building
-    - [ ] Implement `Message.toModelMessages()` conversion
-- [ ] **Proactive Compaction**
-    - [ ] Implement proactive overflow detection
-    - [ ] Develop backward-scanning pruning strategy (e.g., clearing old tool outputs)
-- [ ] **Enhanced Token Tracking**
-    - [ ] Extend `LLMResponse` to track reasoning and cache tokens
-    - [ ] Integrate granular token metrics into compaction logic
-
-### Coding Agent Support
-- [ ] Claude Code
-- [ ] Cursor
-- [ ] Opencode
-- [ ] Antigravity
-
-### File System Enhancement
-- [ ] Semantic Search integration
-- [ ] Interactive File System in product (frontend integration)
-
-### More Worker Tools
-- [ ] Custom Tool Integrator
-- [ ] Integration as a tool (Credential Store & Support)
-- [ ] **Core Agent Tools**
-    - [ ] Node Discovery Tool (find other agents in the graph)
-    - [ ] HITL Tool (pause execution for human approval)
-    - [ ] Wake-up Tool (resume agent tasks)
-
-### Deployment (Self-Hosted)
-- [ ] Workder agent docker container standardization
-- [ ] Headless backend execution
-- [ ] Exposed API for frontend attachment
-- [ ] Local monitoring & observability
-- [ ] Basic lifecycle APIs (Start, Stop, Pause, Resume)
-
-### Deployment (Cloud)
-- [ ] Cloud Service Options
-- [ ] Support deployment to 3rd-party platforms
-- [ ] Self-deploy + orchestrator connection
-- [ ] **CI/CD Pipeline**
-    - [ ] Automated test execution
-    - [ ] Agent version control
-    - [ ] All tests must pass for deployment
-
-### Developer Experience Enhancement
-- [ ] Tool usage documentation
-- [ ] Discord Support Channel
-
-### More Agent Templates
-- [ ] GTM Sales Agent (workflow)
-- [ ] GTM Marketing Agent (workflow)
-- [ ] Analytics Agent
-- [ ] Training Agent
-- [ ] Smart Entry / Form Agent (self-evolution emphasis)
-
-### Cross-Platform
-- [ ] JavaScript / TypeScript Version SDK
-- [ ] Better windows support

commit_message.txt

@@ -0,0 +1,31 @@
+perf: reduce subprocess spawning in quickstart scripts (#4427)
+
+## Problem
+Windows process creation (CreateProcess) is 10-100x slower than Linux fork/exec.
+The quickstart scripts were spawning 4+ separate `uv run python -c "import X"` 
+processes to verify imports, adding ~600ms overhead on Windows.
+
+## Solution
+Consolidated all import checks into a single batch script that checks multiple 
+modules in one subprocess call, reducing spawn overhead by ~75%.
+
+## Changes
+- **New**: `scripts/check_requirements.py` - Batched import checker
+- **New**: `scripts/test_check_requirements.py` - Test suite  
+- **New**: `scripts/benchmark_quickstart.ps1` - Performance benchmark tool
+- **Modified**: `quickstart.ps1` - Updated import verification (2 sections)
+- **Modified**: `quickstart.sh` - Updated import verification
+
+## Performance Impact
+**Benchmark results on Windows:**
+- Before: ~19.8 seconds for import checks
+- After: ~4.9 seconds for import checks
+- **Improvement: 14.9 seconds saved (75.2% faster)**
+
+## Testing
+- ✅ All functional tests pass (`scripts/test_check_requirements.py`)
+- ✅ Quickstart scripts work correctly on Windows
+- ✅ Error handling verified (invalid imports reported correctly)
+- ✅ Performance benchmark confirms 75%+ improvement
+
+Fixes #4427

contributors.yml

@@ -0,0 +1,27 @@
+# Identity mapping: GitHub username -> Discord ID
+#
+# This file links GitHub accounts to Discord accounts for the
+# Integration Bounty Program. When a bounty PR is merged, the
+# GitHub Action uses this file to ping the contributor on Discord.
+#
+# HOW TO ADD YOURSELF:
+# Open a "Link Discord Account" issue:
+# https://github.com/aden-hive/hive/issues/new?template=link-discord.yml
+# A GitHub Action will automatically add your entry here.
+#
+# To find your Discord ID:
+# 1. Open Discord Settings > Advanced > Enable Developer Mode
+# 2. Right-click your name > Copy User ID
+#
+# Format:
+#   - github: your-github-username
+#     discord: "your-discord-id"  # quotes required (it's a number)
+#     name: Your Display Name      # optional
+
+contributors:
+  # - github: example-user
+  #   discord: "123456789012345678"
+  #   name: Example User
+  - github: TimothyZhang7
+    discord: "408460790061072384"
+    name: Timothy@Aden

core/.mcp.json

@@ -1,10 +1,5 @@
 {
   "mcpServers": {
-    "agent-builder": {
-      "command": "python",
-      "args": ["-m", "framework.mcp.agent_builder_server"],
-      "cwd": "core"
-    },
     "tools": {
       "command": "python",
       "args": ["-m", "aden_tools.mcp_server", "--stdio"],

core/MCP_BUILDER_TOOLS_GUIDE.md

@@ -82,7 +82,7 @@ Register an MCP server as a tool source for your agent.
     "example_tool"
   ],
   "total_mcp_servers": 1,
-  "note": "MCP server 'tools' registered with 6 tools. These tools can now be used in llm_tool_use nodes."
+  "note": "MCP server 'tools' registered with 6 tools. These tools can now be used in event_loop nodes."
 }
 ```
 
@@ -149,7 +149,7 @@ List tools available from registered MCP servers.
     ]
   },
   "total_tools": 6,
-  "note": "Use these tool names in the 'tools' parameter when adding llm_tool_use nodes"
+  "note": "Use these tool names in the 'tools' parameter when adding event_loop nodes"
 }
 ```
 
@@ -246,7 +246,7 @@ Here's a complete workflow for building an agent with MCP tools:
     "node_id": "web-searcher",
     "name": "Web Search",
     "description": "Search the web for information",
-    "node_type": "llm_tool_use",
+    "node_type": "event_loop",
     "input_keys": "[\"query\"]",
     "output_keys": "[\"search_results\"]",
     "system_prompt": "Search for {query} using the web_search tool",

core/MCP_INTEGRATION_GUIDE.md

@@ -119,7 +119,7 @@ builder = WorkflowBuilder()
 builder.add_node(
     node_id="researcher",
     name="Web Researcher",
-    node_type="llm_tool_use",
+    node_type="event_loop",
     system_prompt="Research the topic using web_search",
     tools=["web_search"],  # Tool from tools MCP server
     input_keys=["topic"],
@@ -137,7 +137,7 @@ Tools from MCP servers can be referenced in your agent.json just like built-in t
     {
       "id": "searcher",
       "name": "Web Searcher",
-      "node_type": "llm_tool_use",
+      "node_type": "event_loop",
       "system_prompt": "Search for information about {topic}",
       "tools": ["web_search", "web_scrape"],
       "input_keys": ["topic"],

core/MCP_SERVER_GUIDE.md

@@ -1,17 +1,16 @@
-# MCP Server Guide - Agent Builder
+# MCP Server Guide - Agent Building Tools
 
-This guide covers the MCP (Model Context Protocol) server for building goal-driven agents.
+> **Note:** The standalone `agent-builder` MCP server (`framework.mcp.agent_builder_server`) has been replaced. Agent building is now done via the `coder-tools` server's `initialize_and_build_agent` tool, with underlying logic in `tools/coder_tools_server.py`.
+
+This guide covers the MCP tools available for building goal-driven agents.
 
 ## Setup
 
 ### Quick Setup
 
 ```bash
-# Using the setup script (recommended)
-python setup_mcp.py
-
-# Or using bash
-./setup_mcp.sh
+# Run the quickstart script (recommended)
+./quickstart.sh
 ```
 
 ### Manual Configuration
@@ -21,10 +20,10 @@ Add to your MCP client configuration (e.g., Claude Desktop):
 ```json
 {
   "mcpServers": {
-    "agent-builder": {
-      "command": "python",
-      "args": ["-m", "framework.mcp.agent_builder_server"],
-      "cwd": "/path/to/goal-agent"
+    "coder-tools": {
+      "command": "uv",
+      "args": ["run", "coder_tools_server.py", "--stdio"],
+      "cwd": "/path/to/hive/tools"
     }
   }
 }
@@ -103,31 +102,20 @@ Add a processing node to the agent graph.
 - `node_id` (string, required): Unique node identifier
 - `name` (string, required): Human-readable name
 - `description` (string, required): What this node does
-- `node_type` (string, required): One of: `llm_generate`, `llm_tool_use`, `router`, `function`
+- `node_type` (string, required): Must be `event_loop` (the only valid type)
 - `input_keys` (string, required): JSON array of input variable names
 - `output_keys` (string, required): JSON array of output variable names
-- `system_prompt` (string, optional): System prompt for LLM nodes
-- `tools` (string, optional): JSON array of tool names for tool_use nodes
-- `routes` (string, optional): JSON object of route mappings for router nodes
+- `system_prompt` (string, optional): System prompt for the LLM
+- `tools` (string, optional): JSON array of tool names
+- `client_facing` (boolean, optional): Set to true for human-in-the-loop interaction
 
-**Node Types:**
+**Node Type:**
 
-1. **llm_generate**: Uses LLM to generate output from inputs
-   - Requires: `system_prompt`
-   - Tools: Not used
-
-2. **llm_tool_use**: Uses LLM with tools to accomplish tasks
-   - Requires: `system_prompt`, `tools`
-   - Tools: Array of tool names (e.g., `["web_search", "web_fetch"]`)
-
-3. **router**: LLM-powered routing to different paths
-   - Requires: `system_prompt`, `routes`
-   - Routes: Object mapping route names to target node IDs
-   - Example: `{"pass": "success_node", "fail": "retry_node"}`
-
-4. **function**: Executes a pre-defined function
-   - System prompt describes the function behavior
-   - No LLM calls, pure computation
+**event_loop**: LLM-powered node with self-correction loop
+- Requires: `system_prompt`
+- Optional: `tools` (array of tool names, e.g., `["web_search", "web_fetch"]`)
+- Optional: `client_facing` (set to true for HITL / user interaction)
+- Supports: iterative refinement, judge-based evaluation, tool use, streaming
 
 **Example:**
 ```json
@@ -135,7 +123,7 @@ Add a processing node to the agent graph.
   "node_id": "search_sources",
   "name": "Search Sources",
   "description": "Searches for relevant sources on the topic",
-  "node_type": "llm_tool_use",
+  "node_type": "event_loop",
   "input_keys": "[\"topic\", \"search_queries\"]",
   "output_keys": "[\"sources\", \"source_count\"]",
   "system_prompt": "Search for sources using the provided queries...",
@@ -198,7 +186,7 @@ Export the validated graph as an agent specification.
 
 **What it does:**
 1. Validates the graph
-2. Auto-generates missing edges from router routes
+2. Validates edge connectivity
 3. Writes files to disk:
    - `exports/{agent-name}/agent.json` - Full agent specification
    - `exports/{agent-name}/README.md` - Auto-generated documentation
@@ -252,47 +240,6 @@ Test the complete agent graph with sample inputs.
 
 ---
 
-### Evaluation Rules
-
-#### `add_evaluation_rule`
-Add a rule for the HybridJudge to evaluate node outputs.
-
-**Parameters:**
-- `rule_id` (string, required): Unique rule identifier
-- `description` (string, required): What this rule checks
-- `condition` (string, required): Python expression to evaluate
-- `action` (string, required): Action to take: `accept`, `retry`, `escalate`
-- `priority` (integer, optional): Rule priority (default: 0)
-- `feedback_template` (string, optional): Feedback message template
-
-**Condition Examples:**
-- `'result.get("success") == True'` - Check for success flag
-- `'result.get("error_type") == "timeout"'` - Check error type
-- `'len(result.get("data", [])) > 0'` - Check for non-empty data
-
-**Example:**
-```json
-{
-  "rule_id": "timeout_retry",
-  "description": "Retry on timeout errors",
-  "condition": "result.get('error_type') == 'timeout'",
-  "action": "retry",
-  "priority": 10,
-  "feedback_template": "Timeout occurred, retrying..."
-}
-```
-
-#### `list_evaluation_rules`
-List all configured evaluation rules.
-
-#### `remove_evaluation_rule`
-Remove an evaluation rule.
-
-**Parameters:**
-- `rule_id` (string, required): Rule to remove
-
----
-
 ## Example Workflow
 
 Here's a complete workflow for building a research agent:
@@ -320,7 +267,7 @@ add_node(
     node_id="planner",
     name="Research Planner",
     description="Creates research strategy",
-    node_type="llm_generate",
+    node_type="event_loop",
     input_keys='["topic"]',
     output_keys='["strategy", "queries"]',
     system_prompt="Analyze topic and create research plan..."
@@ -330,7 +277,7 @@ add_node(
     node_id="searcher",
     name="Search Sources",
     description="Find relevant sources",
-    node_type="llm_tool_use",
+    node_type="event_loop",
     input_keys='["queries"]',
     output_keys='["sources"]',
     system_prompt="Search for sources...",
@@ -359,10 +306,9 @@ The exported agent will be saved to `exports/research-agent/`.
 
 1. **Start with the goal**: Define clear success criteria before building nodes
 2. **Test nodes individually**: Use `test_node` to verify each node works
-3. **Use router nodes for branching**: Don't create edges manually for routers - define routes and they'll be auto-generated
-4. **Add evaluation rules**: Help the judge evaluate outputs deterministically
-5. **Validate early, validate often**: Run `validate_graph` after adding nodes/edges
-6. **Check exports**: Review the generated README.md to verify your agent structure
+3. **Use conditional edges for branching**: Define condition_expr on edges for decision points
+4. **Validate early, validate often**: Run `validate_graph` after adding nodes/edges
+5. **Check exports**: Review the generated README.md to verify your agent structure
 
 ---
 

core/README.md

@@ -14,69 +14,14 @@ Framework provides a runtime framework that captures **decisions**, not just act
 ## Installation
 
 ```bash
-pip install -e .
+uv pip install -e .
 ```
 
-## MCP Server Setup
+## Agent Building
 
-The framework includes an MCP (Model Context Protocol) server for building agents. To set up the MCP server:
+Agent scaffolding is handled by the `coder-tools` MCP server (in `tools/coder_tools_server.py`), which provides the `initialize_and_build_agent` tool and related utilities. The package generation logic lives directly in `tools/coder_tools_server.py`.
 
-### Automated Setup
-
-**Using bash (Linux/macOS):**
-```bash
-./setup_mcp.sh
-```
-
-**Using Python (cross-platform):**
-```bash
-python setup_mcp.py
-```
-
-The setup script will:
-1. Install the framework package
-2. Install MCP dependencies (mcp, fastmcp)
-3. Create/verify `.mcp.json` configuration
-4. Test the MCP server module
-
-### Manual Setup
-
-If you prefer manual setup:
-
-```bash
-# Install framework
-pip install -e .
-
-# Install MCP dependencies
-pip install mcp fastmcp
-
-# Test the server
-python -m framework.mcp.agent_builder_server
-```
-
-### Using with MCP Clients
-
-To use the agent builder with Claude Desktop or other MCP clients, add this to your MCP client configuration:
-
-```json
-{
-  "mcpServers": {
-    "agent-builder": {
-      "command": "python",
-      "args": ["-m", "framework.mcp.agent_builder_server"],
-      "cwd": "/path/to/goal-agent"
-    }
-  }
-}
-```
-
-The MCP server provides tools for:
-- Creating agent building sessions
-- Defining goals with success criteria
-- Adding nodes (llm_generate, llm_tool_use, router, function)
-- Connecting nodes with edges
-- Validating and exporting agent graphs
-- Testing nodes and full agent graphs
+See the [Getting Started Guide](../docs/getting-started.md) for building agents.
 
 ## Quick Start
 
@@ -85,14 +30,14 @@ The MCP server provides tools for:
 Run an LLM-powered calculator:
 
 ```bash
-# Single calculation
-python -m framework calculate "2 + 3 * 4"
+# Run an exported agent
+uv run python -m framework run exports/calculator --input '{"expression": "2 + 3 * 4"}'
 
-# Interactive mode
-python -m framework interactive
+# Interactive shell session
+uv run python -m framework shell exports/calculator
 
-# Analyze runs with Builder
-python -m framework analyze calculator
+# Show agent info
+uv run python -m framework info exports/calculator
 ```
 
 ### Using the Runtime
@@ -136,16 +81,16 @@ Tests are generated using MCP tools (`generate_constraint_tests`, `generate_succ
 
 ```bash
 # Run tests against an agent
-python -m framework test-run <agent_path> --goal <goal_id> --parallel 4
+uv run python -m framework test-run <agent_path> --goal <goal_id> --parallel 4
 
 # Debug failed tests
-python -m framework test-debug <agent_path> <test_name>
+uv run python -m framework test-debug <agent_path> <test_name>
 
-# List tests for a goal
-python -m framework test-list <goal_id>
+# List tests for an agent
+uv run python -m framework test-list <agent_path>
 ```
 
-For detailed testing workflows, see the [testing-agent skill](../.claude/skills/testing-agent/SKILL.md).
+For detailed testing workflows, see [developer-guide.md](../docs/developer-guide.md).
 
 ### Analyzing Agent Behavior with Builder
 

core/codex_oauth.py

@@ -0,0 +1,387 @@
+"""OpenAI Codex OAuth PKCE login flow.
+
+Runs the full browser-based OAuth flow so users can authenticate with their
+ChatGPT Plus/Pro subscription without needing the Codex CLI installed.
+
+Usage (from quickstart.sh):
+    uv run python codex_oauth.py
+
+Exit codes:
+    0 - success (credentials saved to ~/.codex/auth.json)
+    1 - failure (user cancelled, timeout, or token exchange error)
+"""
+
+import base64
+import hashlib
+import http.server
+import json
+import os
+import platform
+import secrets
+import subprocess
+import sys
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import UTC, datetime
+from pathlib import Path
+
+# OAuth constants (from the Codex CLI binary)
+CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
+AUTHORIZE_URL = "https://auth.openai.com/oauth/authorize"
+TOKEN_URL = "https://auth.openai.com/oauth/token"
+REDIRECT_URI = "http://localhost:1455/auth/callback"
+SCOPE = "openid profile email offline_access"
+CALLBACK_PORT = 1455
+
+# Where to save credentials (same location the Codex CLI uses)
+CODEX_AUTH_FILE = Path.home() / ".codex" / "auth.json"
+
+# JWT claim path for account_id
+JWT_CLAIM_PATH = "https://api.openai.com/auth"
+
+
+def _base64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def generate_pkce() -> tuple[str, str]:
+    """Generate PKCE code_verifier and code_challenge (S256)."""
+    verifier_bytes = secrets.token_bytes(32)
+    verifier = _base64url(verifier_bytes)
+    challenge = _base64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return verifier, challenge
+
+
+def build_authorize_url(state: str, challenge: str) -> str:
+    """Build the OpenAI OAuth authorize URL with PKCE."""
+    params = urllib.parse.urlencode(
+        {
+            "response_type": "code",
+            "client_id": CLIENT_ID,
+            "redirect_uri": REDIRECT_URI,
+            "scope": SCOPE,
+            "code_challenge": challenge,
+            "code_challenge_method": "S256",
+            "state": state,
+            "id_token_add_organizations": "true",
+            "codex_cli_simplified_flow": "true",
+            "originator": "hive",
+        }
+    )
+    return f"{AUTHORIZE_URL}?{params}"
+
+
+def exchange_code_for_tokens(code: str, verifier: str) -> dict | None:
+    """Exchange the authorization code for tokens."""
+    data = urllib.parse.urlencode(
+        {
+            "grant_type": "authorization_code",
+            "client_id": CLIENT_ID,
+            "code": code,
+            "code_verifier": verifier,
+            "redirect_uri": REDIRECT_URI,
+        }
+    ).encode("utf-8")
+
+    req = urllib.request.Request(
+        TOKEN_URL,
+        data=data,
+        headers={"Content-Type": "application/x-www-form-urlencoded"},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            token_data = json.loads(resp.read())
+    except (urllib.error.URLError, json.JSONDecodeError, TimeoutError, OSError) as exc:
+        print(f"\033[0;31mToken exchange failed: {exc}\033[0m", file=sys.stderr)
+        return None
+
+    if not token_data.get("access_token") or not token_data.get("refresh_token"):
+        print("\033[0;31mToken response missing required fields\033[0m", file=sys.stderr)
+        return None
+
+    return token_data
+
+
+def decode_jwt_payload(token: str) -> dict | None:
+    """Decode the payload of a JWT (no signature verification)."""
+    try:
+        parts = token.split(".")
+        if len(parts) != 3:
+            return None
+        payload = parts[1]
+        # Add padding
+        padding = 4 - len(payload) % 4
+        if padding != 4:
+            payload += "=" * padding
+        decoded = base64.urlsafe_b64decode(payload)
+        return json.loads(decoded)
+    except Exception:
+        return None
+
+
+def get_account_id(access_token: str) -> str | None:
+    """Extract the ChatGPT account_id from the access token JWT."""
+    payload = decode_jwt_payload(access_token)
+    if not payload:
+        return None
+    auth = payload.get(JWT_CLAIM_PATH)
+    if isinstance(auth, dict):
+        account_id = auth.get("chatgpt_account_id")
+        if isinstance(account_id, str) and account_id:
+            return account_id
+    return None
+
+
+def save_credentials(token_data: dict, account_id: str) -> None:
+    """Save credentials to ~/.codex/auth.json in the same format the Codex CLI uses."""
+    auth_data = {
+        "tokens": {
+            "access_token": token_data["access_token"],
+            "refresh_token": token_data["refresh_token"],
+            "account_id": account_id,
+        },
+        "auth_mode": "chatgpt",
+        "last_refresh": datetime.now(UTC).isoformat(),
+    }
+    if "id_token" in token_data:
+        auth_data["tokens"]["id_token"] = token_data["id_token"]
+
+    CODEX_AUTH_FILE.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd = os.open(CODEX_AUTH_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        json.dump(auth_data, f, indent=2)
+
+
+def open_browser(url: str) -> bool:
+    """Open the URL in the user's default browser."""
+    system = platform.system()
+    try:
+        devnull = subprocess.DEVNULL
+        if system == "Darwin":
+            subprocess.Popen(["open", url], stdout=devnull, stderr=devnull)
+        elif system == "Windows":
+            subprocess.Popen(["cmd", "/c", "start", url], stdout=devnull, stderr=devnull)
+        else:
+            subprocess.Popen(["xdg-open", url], stdout=devnull, stderr=devnull)
+        return True
+    except OSError:
+        return False
+
+
+class OAuthCallbackHandler(http.server.BaseHTTPRequestHandler):
+    """HTTP handler that captures the OAuth callback."""
+
+    auth_code: str | None = None
+    received_state: str | None = None
+
+    def do_GET(self) -> None:
+        parsed = urllib.parse.urlparse(self.path)
+        if parsed.path != "/auth/callback":
+            self.send_response(404)
+            self.end_headers()
+            self.wfile.write(b"Not found")
+            return
+
+        params = urllib.parse.parse_qs(parsed.query)
+        code = params.get("code", [None])[0]
+        state = params.get("state", [None])[0]
+
+        if not code:
+            self.send_response(400)
+            self.end_headers()
+            self.wfile.write(b"Missing authorization code")
+            return
+
+        OAuthCallbackHandler.auth_code = code
+        OAuthCallbackHandler.received_state = state
+
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.end_headers()
+        self.wfile.write(
+            b"<!doctype html><html><head><meta charset='utf-8'/></head>"
+            b"<body><h2>Authentication successful</h2>"
+            b"<p>Return to your terminal to continue.</p></body></html>"
+        )
+
+    def log_message(self, format: str, *args: object) -> None:
+        # Suppress request logging
+        pass
+
+
+def wait_for_callback(state: str, timeout_secs: int = 120) -> str | None:
+    """Start a local HTTP server and wait for the OAuth callback.
+
+    Returns the authorization code on success, None on timeout.
+    """
+    OAuthCallbackHandler.auth_code = None
+    OAuthCallbackHandler.received_state = None
+
+    server = http.server.HTTPServer(("127.0.0.1", CALLBACK_PORT), OAuthCallbackHandler)
+    server.timeout = 1
+
+    deadline = time.time() + timeout_secs
+    server_thread = threading.Thread(target=_serve_until_done, args=(server, deadline, state))
+    server_thread.daemon = True
+    server_thread.start()
+    server_thread.join(timeout=timeout_secs + 2)
+
+    server.server_close()
+
+    if OAuthCallbackHandler.auth_code and OAuthCallbackHandler.received_state == state:
+        return OAuthCallbackHandler.auth_code
+    return None
+
+
+def _serve_until_done(server: http.server.HTTPServer, deadline: float, state: str) -> None:
+    while time.time() < deadline:
+        server.handle_request()
+        if OAuthCallbackHandler.auth_code and OAuthCallbackHandler.received_state == state:
+            return
+
+
+def parse_manual_input(value: str, expected_state: str) -> str | None:
+    """Parse user-pasted redirect URL or auth code."""
+    value = value.strip()
+    if not value:
+        return None
+    try:
+        parsed = urllib.parse.urlparse(value)
+        params = urllib.parse.parse_qs(parsed.query)
+        code = params.get("code", [None])[0]
+        state = params.get("state", [None])[0]
+        if state and state != expected_state:
+            return None
+        return code
+    except Exception:
+        pass
+    # Maybe it's just the raw code
+    if len(value) > 10 and " " not in value:
+        return value
+    return None
+
+
+def main() -> int:
+    # Generate PKCE and state
+    verifier, challenge = generate_pkce()
+    state = secrets.token_hex(16)
+
+    # Build URL
+    auth_url = build_authorize_url(state, challenge)
+
+    print()
+    print("\033[1mOpenAI Codex OAuth Login\033[0m")
+    print()
+
+    # Try to start the local callback server first
+    try:
+        server_available = True
+        # Quick test that port is free
+        import socket
+
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(1)
+        result = sock.connect_ex(("127.0.0.1", CALLBACK_PORT))
+        sock.close()
+        if result == 0:
+            print(f"\033[1;33mPort {CALLBACK_PORT} is in use. Using manual paste mode.\033[0m")
+            server_available = False
+    except Exception:
+        server_available = True
+
+    # Open browser
+    browser_opened = open_browser(auth_url)
+    if browser_opened:
+        print("  Browser opened for OpenAI sign-in...")
+    else:
+        print("  Could not open browser automatically.")
+
+    print()
+    print("  If the browser didn't open, visit this URL:")
+    print(f"  \033[0;36m{auth_url}\033[0m")
+    print()
+
+    code = None
+
+    if server_available:
+        print("  Waiting for authentication (up to 2 minutes)...")
+        print("  \033[2mOr paste the redirect URL below if the callback didn't work:\033[0m")
+        print()
+
+        # Start callback server in background
+        callback_result: list[str | None] = [None]
+
+        def run_server() -> None:
+            callback_result[0] = wait_for_callback(state, timeout_secs=120)
+
+        server_thread = threading.Thread(target=run_server)
+        server_thread.daemon = True
+        server_thread.start()
+
+        # Also accept manual input in parallel
+        # We poll for both the server result and stdin
+        try:
+            import select
+
+            while server_thread.is_alive():
+                # Check if stdin has data (non-blocking on unix)
+                if hasattr(select, "select"):
+                    ready, _, _ = select.select([sys.stdin], [], [], 0.5)
+                    if ready:
+                        manual = sys.stdin.readline()
+                        if manual.strip():
+                            code = parse_manual_input(manual, state)
+                            if code:
+                                break
+                else:
+                    time.sleep(0.5)
+
+                if callback_result[0]:
+                    code = callback_result[0]
+                    break
+        except (KeyboardInterrupt, EOFError):
+            print("\n\033[0;31mCancelled.\033[0m")
+            return 1
+
+        if not code:
+            code = callback_result[0]
+    else:
+        # Manual paste mode
+        try:
+            manual = input("  Paste the redirect URL: ").strip()
+            code = parse_manual_input(manual, state)
+        except (KeyboardInterrupt, EOFError):
+            print("\n\033[0;31mCancelled.\033[0m")
+            return 1
+
+    if not code:
+        print("\n\033[0;31mAuthentication timed out or failed.\033[0m")
+        return 1
+
+    # Exchange code for tokens
+    print()
+    print("  Exchanging authorization code for tokens...")
+    token_data = exchange_code_for_tokens(code, verifier)
+    if not token_data:
+        return 1
+
+    # Extract account_id from JWT
+    account_id = get_account_id(token_data["access_token"])
+    if not account_id:
+        print("\033[0;31mFailed to extract account ID from token.\033[0m", file=sys.stderr)
+        return 1
+
+    # Save credentials
+    save_credentials(token_data, account_id)
+    print("  \033[0;32mAuthentication successful!\033[0m")
+    print(f"  Credentials saved to {CODEX_AUTH_FILE}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

core/demos/github_outreach_demo.py

@@ -68,7 +68,7 @@ from framework.graph.event_loop_node import (  # noqa: E402
 )
 from framework.graph.executor import GraphExecutor  # noqa: E402
 from framework.graph.goal import Goal  # noqa: E402
-from framework.graph.node import NodeSpec  # noqa: E402
+from framework.graph.node import NodeContext, NodeProtocol, NodeResult, NodeSpec  # noqa: E402
 from framework.llm.litellm import LiteLLMProvider  # noqa: E402
 from framework.runner.tool_registry import ToolRegistry  # noqa: E402
 from framework.runtime.core import Runtime  # noqa: E402
@@ -654,7 +654,7 @@ NODE_SPECS = {
         id="sender",
         name="Sender",
         description="Send approved campaign emails",
-        node_type="function",
+        node_type="event_loop",
         input_keys=["approved_emails"],
         output_keys=["send_results"],
     ),
@@ -823,11 +823,20 @@ def _send_email_via_resend(
         return {"error": f"Network error: {e}"}
 
 
+class SenderNode(NodeProtocol):
+    """Node wrapper for send_emails function."""
+
+    async def execute(self, ctx: NodeContext) -> NodeResult:
+        approved = ctx.input_data.get("approved_emails", "")
+        result_str = send_emails(approved_emails=approved)
+        ctx.memory.write("send_results", result_str)
+        return NodeResult(success=True, output={"send_results": result_str})
+
+
 def send_emails(approved_emails: str = "") -> str:
     """Send approved campaign emails via Resend, or log if unconfigured.
 
-    Called by FunctionNode which unpacks input_keys as kwargs.
-    Returns a JSON string (FunctionNode wraps it in NodeResult).
+    Returns a JSON string.
     """
     approved = approved_emails
     if not approved:
@@ -1759,7 +1768,7 @@ async def _run_pipeline(websocket, initial_message: str):
             judge=judge,
             config=LoopConfig(
                 max_iterations=30,
-                max_tool_calls_per_turn=15,
+                max_tool_calls_per_turn=30,
                 max_history_tokens=64000,
                 max_tool_result_chars=8_000,
                 spillover_dir=str(_DATA_DIR),
@@ -1780,7 +1789,7 @@ async def _run_pipeline(websocket, initial_message: str):
     )
     for nid, impl in nodes.items():
         executor.register_node(nid, impl)
-    executor.register_function("sender", send_emails)
+    executor.register_node("sender", SenderNode())
 
     # --- Event forwarding: bus → WebSocket ---
 

core/demos/handoff_demo.py

@@ -751,7 +751,7 @@ async def _run_pipeline(websocket, topic: str):
         judge=None,  # implicit judge: accept when output_keys filled
         config=LoopConfig(
             max_iterations=20,
-            max_tool_calls_per_turn=10,
+            max_tool_calls_per_turn=30,
             max_history_tokens=32_000,
         ),
         conversation_store=store_a,
@@ -849,7 +849,7 @@ async def _run_pipeline(websocket, topic: str):
         judge=None,  # implicit judge
         config=LoopConfig(
             max_iterations=10,
-            max_tool_calls_per_turn=5,
+            max_tool_calls_per_turn=30,
             max_history_tokens=32_000,
         ),
         conversation_store=store_b,

core/demos/org_demo.py

@@ -1257,7 +1257,7 @@ async def _run_org_pipeline(websocket, topic: str):
             judge=judge,
             config=LoopConfig(
                 max_iterations=30,
-                max_tool_calls_per_turn=25,
+                max_tool_calls_per_turn=30,
                 max_history_tokens=32_000,
             ),
             conversation_store=store,

core/examples/manual_agent.py

@@ -4,34 +4,45 @@ Minimal Manual Agent Example
 This example demonstrates how to build and run an agent programmatically
 without using the Claude Code CLI or external LLM APIs.
 
-It uses 'function' nodes to define logic in pure Python, making it perfect
-for understanding the core runtime loop:
+It uses custom NodeProtocol implementations to define logic in pure Python,
+making it perfect for understanding the core runtime loop:
 Setup -> Graph definition -> Execution -> Result
 
 Run with:
-    PYTHONPATH=core python core/examples/manual_agent.py
+    uv run python core/examples/manual_agent.py
 """
 
 import asyncio
 
 from framework.graph import EdgeCondition, EdgeSpec, Goal, GraphSpec, NodeSpec
 from framework.graph.executor import GraphExecutor
+from framework.graph.node import NodeContext, NodeProtocol, NodeResult
 from framework.runtime.core import Runtime
 
 
-# 1. Define Node Logic (Pure Python Functions)
-def greet(name: str) -> str:
+# 1. Define Node Logic (Custom NodeProtocol implementations)
+class GreeterNode(NodeProtocol):
     """Generate a simple greeting."""
-    return f"Hello, {name}!"
+
+    async def execute(self, ctx: NodeContext) -> NodeResult:
+        name = ctx.input_data.get("name", "World")
+        greeting = f"Hello, {name}!"
+        ctx.memory.write("greeting", greeting)
+        return NodeResult(success=True, output={"greeting": greeting})
 
 
-def uppercase(greeting: str) -> str:
+class UppercaserNode(NodeProtocol):
     """Convert text to uppercase."""
-    return greeting.upper()
+
+    async def execute(self, ctx: NodeContext) -> NodeResult:
+        greeting = ctx.input_data.get("greeting") or ctx.memory.read("greeting") or ""
+        result = greeting.upper()
+        ctx.memory.write("final_greeting", result)
+        return NodeResult(success=True, output={"final_greeting": result})
 
 
 async def main():
-    print("🚀 Setting up Manual Agent...")
+    print("Setting up Manual Agent...")
 
     # 2. Define the Goal
     # Every agent needs a goal with success criteria
@@ -55,8 +66,7 @@ async def main():
         id="greeter",
         name="Greeter",
         description="Generates a simple greeting",
-        node_type="function",
-        function="greet",  # Matches the registered function name
+        node_type="event_loop",
         input_keys=["name"],
         output_keys=["greeting"],
     )
@@ -65,8 +75,7 @@ async def main():
         id="uppercaser",
         name="Uppercaser",
         description="Converts greeting to uppercase",
-        node_type="function",
-        function="uppercase",
+        node_type="event_loop",
         input_keys=["greeting"],
         output_keys=["final_greeting"],
     )
@@ -98,23 +107,23 @@ async def main():
     runtime = Runtime(storage_path=Path("./agent_logs"))
     executor = GraphExecutor(runtime=runtime)
 
-    # 7. Register Function Implementations
-    # Connect string names in NodeSpecs to actual Python functions
-    executor.register_function("greeter", greet)
-    executor.register_function("uppercaser", uppercase)
+    # 7. Register Node Implementations
+    # Connect node IDs in the graph to actual Python implementations
+    executor.register_node("greeter", GreeterNode())
+    executor.register_node("uppercaser", UppercaserNode())
 
     # 8. Execute Agent
-    print("▶ Executing agent with input: name='Alice'...")
+    print("Executing agent with input: name='Alice'...")
 
     result = await executor.execute(graph=graph, goal=goal, input_data={"name": "Alice"})
 
     # 9. Verify Results
     if result.success:
-        print("\n✅ Success!")
+        print("\nSuccess!")
         print(f"Path taken: {' -> '.join(result.path)}")
         print(f"Final output: {result.output.get('final_greeting')}")
     else:
-        print(f"\n❌ Failed: {result.error}")
+        print(f"\nFailed: {result.error}")
 
 
 if __name__ == "__main__":

core/examples/mcp_integration_example.py

@@ -95,81 +95,6 @@ async def example_3_config_file():
     (test_agent_path / "mcp_servers.json").unlink()
 
 
-async def example_4_custom_agent_with_mcp_tools():
-    """Example 4: Build custom agent that uses MCP tools"""
-    print("\n=== Example 4: Custom Agent with MCP Tools ===\n")
-
-    from framework.builder.workflow import GraphBuilder
-
-    # Create a workflow builder
-    builder = GraphBuilder()
-
-    # Define goal
-    builder.set_goal(
-        goal_id="web-researcher",
-        name="Web Research Agent",
-        description="Search the web and summarize findings",
-    )
-
-    # Add success criteria
-    builder.add_success_criterion(
-        "search-results", "Successfully retrieve at least 3 web search results"
-    )
-    builder.add_success_criterion("summary", "Provide a clear, concise summary of the findings")
-
-    # Add nodes that will use MCP tools
-    builder.add_node(
-        node_id="web-searcher",
-        name="Web Search",
-        description="Search the web for information",
-        node_type="llm_tool_use",
-        system_prompt="Search for {query} and return the top results. Use the web_search tool.",
-        tools=["web_search"],  # This tool comes from tools MCP server
-        input_keys=["query"],
-        output_keys=["search_results"],
-    )
-
-    builder.add_node(
-        node_id="summarizer",
-        name="Summarize Results",
-        description="Summarize the search results",
-        node_type="llm_generate",
-        system_prompt="Summarize the following search results in 2-3 sentences: {search_results}",
-        input_keys=["search_results"],
-        output_keys=["summary"],
-    )
-
-    # Connect nodes
-    builder.add_edge("web-searcher", "summarizer")
-
-    # Set entry point
-    builder.set_entry("web-searcher")
-    builder.set_terminal("summarizer")
-
-    # Export the agent
-    export_path = Path("exports/web-research-agent")
-    export_path.mkdir(parents=True, exist_ok=True)
-    builder.export(export_path)
-
-    # Load and register MCP server
-    runner = AgentRunner.load(export_path)
-    runner.register_mcp_server(
-        name="tools",
-        transport="stdio",
-        command="python",
-        args=["-m", "aden_tools.mcp_server", "--stdio"],
-        cwd="../tools",
-    )
-
-    # Run the agent
-    result = await runner.run({"query": "latest AI breakthroughs 2026"})
-
-    print(f"\nAgent completed with result:\n{result}")
-
-    # Cleanup
-    runner.cleanup()
-
-
 async def main():
     """Run all examples"""
     print("=" * 60)

core/examples/mcp_servers.json

@@ -4,8 +4,8 @@
       "name": "tools",
       "description": "Aden tools including web search, file operations, and PDF reading",
       "transport": "stdio",
-      "command": "python",
-      "args": ["mcp_server.py", "--stdio"],
+      "command": "uv",
+      "args": ["run", "python", "mcp_server.py", "--stdio"],
       "cwd": "../tools",
       "env": {
         "BRAVE_SEARCH_API_KEY": "${BRAVE_SEARCH_API_KEY}"

core/framework/agents/__init__.py

@@ -0,0 +1,13 @@
+"""Framework-provided agents."""
+
+from pathlib import Path
+
+FRAMEWORK_AGENTS_DIR = Path(__file__).parent
+
+
+def list_framework_agents() -> list[Path]:
+    """List all framework agent directories."""
+    return sorted(
+        [p for p in FRAMEWORK_AGENTS_DIR.iterdir() if p.is_dir() and (p / "agent.py").exists()],
+        key=lambda p: p.name,
+    )

core/framework/agents/credential_tester/__init__.py

@@ -0,0 +1,55 @@
+"""
+Credential Tester — verify credentials (Aden OAuth + local API keys) via live API calls.
+
+Interactive agent that lists all testable accounts, lets the user pick one,
+loads the provider's tools, and runs a chat session to test the credential.
+"""
+
+from .agent import (
+    CredentialTesterAgent,
+    _list_aden_accounts,
+    _list_env_fallback_accounts,
+    _list_local_accounts,
+    configure_for_account,
+    conversation_mode,
+    edges,
+    entry_node,
+    entry_points,
+    get_tools_for_provider,
+    goal,
+    identity_prompt,
+    list_connected_accounts,
+    loop_config,
+    nodes,
+    pause_nodes,
+    requires_account_selection,
+    skip_credential_validation,
+    terminal_nodes,
+)
+from .config import default_config
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "CredentialTesterAgent",
+    "configure_for_account",
+    "conversation_mode",
+    "default_config",
+    "edges",
+    "entry_node",
+    "entry_points",
+    "get_tools_for_provider",
+    "goal",
+    "identity_prompt",
+    "list_connected_accounts",
+    "loop_config",
+    "nodes",
+    "pause_nodes",
+    "requires_account_selection",
+    "skip_credential_validation",
+    "terminal_nodes",
+    # Internal list helpers (exposed for testing)
+    "_list_aden_accounts",
+    "_list_local_accounts",
+    "_list_env_fallback_accounts",
+]

core/framework/agents/credential_tester/__main__.py

@@ -0,0 +1,148 @@
+"""CLI entry point for Credential Tester agent."""
+
+import asyncio
+import logging
+import sys
+
+import click
+
+from .agent import CredentialTesterAgent
+
+
+def setup_logging(verbose=False, debug=False):
+    if debug:
+        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+    elif verbose:
+        level, fmt = logging.INFO, "%(message)s"
+    else:
+        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+
+
+def pick_account(agent: CredentialTesterAgent) -> dict | None:
+    """Interactive account picker. Returns selected account dict or None."""
+    accounts = agent.list_accounts()
+    if not accounts:
+        click.echo("No connected accounts found.")
+        click.echo("Set ADEN_API_KEY and connect accounts at https://app.adenhq.com")
+        return None
+
+    click.echo("\nConnected accounts:\n")
+    for i, acct in enumerate(accounts, 1):
+        provider = acct.get("provider", "?")
+        alias = acct.get("alias", "?")
+        identity = acct.get("identity", {})
+        detail_parts = [f"{k}: {v}" for k, v in identity.items() if v]
+        detail = f"  ({', '.join(detail_parts)})" if detail_parts else ""
+        click.echo(f"  {i}. {provider}/{alias}{detail}")
+
+    click.echo()
+    while True:
+        choice = click.prompt("Pick an account to test", type=int, default=1)
+        if 1 <= choice <= len(accounts):
+            return accounts[choice - 1]
+        click.echo(f"Invalid choice. Enter 1-{len(accounts)}.")
+
+
+@click.group()
+@click.version_option(version="1.0.0")
+def cli():
+    """Credential Tester — verify synced credentials via live API calls."""
+    pass
+
+
+@cli.command()
+@click.option("--verbose", "-v", is_flag=True)
+@click.option("--debug", is_flag=True)
+def tui(verbose, debug):
+    """Launch TUI to test a credential interactively."""
+    setup_logging(verbose=verbose, debug=debug)
+
+    try:
+        from framework.tui.app import AdenTUI
+    except ImportError:
+        click.echo("TUI requires 'textual'. Install with: pip install textual")
+        sys.exit(1)
+
+    agent = CredentialTesterAgent()
+    account = pick_account(agent)
+    if account is None:
+        sys.exit(1)
+
+    agent.select_account(account)
+    provider = account.get("provider", "?")
+    alias = account.get("alias", "?")
+    click.echo(f"\nTesting {provider}/{alias}...\n")
+
+    async def run_tui():
+        agent._setup()
+        runtime = agent._agent_runtime
+        await runtime.start()
+        try:
+            app = AdenTUI(runtime)
+            await app.run_async()
+        finally:
+            await runtime.stop()
+
+    asyncio.run(run_tui())
+
+
+@cli.command()
+@click.option("--verbose", "-v", is_flag=True)
+@click.option("--debug", is_flag=True)
+def shell(verbose, debug):
+    """Interactive CLI session to test a credential."""
+    setup_logging(verbose=verbose, debug=debug)
+    asyncio.run(_interactive_shell(verbose))
+
+
+async def _interactive_shell(verbose=False):
+    agent = CredentialTesterAgent()
+    account = pick_account(agent)
+    if account is None:
+        return
+
+    agent.select_account(account)
+    provider = account.get("provider", "?")
+    alias = account.get("alias", "?")
+
+    click.echo(f"\nTesting {provider}/{alias}")
+    click.echo("Type your requests or 'quit' to exit.\n")
+
+    await agent.start()
+
+    try:
+        result = await agent._agent_runtime.trigger_and_wait(
+            entry_point_id="start",
+            input_data={},
+        )
+        if result:
+            click.echo(f"\nSession ended: {'success' if result.success else result.error}")
+    except KeyboardInterrupt:
+        click.echo("\nGoodbye!")
+    finally:
+        await agent.stop()
+
+
+@cli.command(name="list")
+def list_accounts():
+    """List all connected accounts."""
+    agent = CredentialTesterAgent()
+    accounts = agent.list_accounts()
+
+    if not accounts:
+        click.echo("No connected accounts found.")
+        return
+
+    click.echo("\nConnected accounts:\n")
+    for acct in accounts:
+        provider = acct.get("provider", "?")
+        alias = acct.get("alias", "?")
+        identity = acct.get("identity", {})
+        detail_parts = [f"{k}: {v}" for k, v in identity.items() if v]
+        detail = f"  ({', '.join(detail_parts)})" if detail_parts else ""
+        click.echo(f"  {provider}/{alias}{detail}")
+
+
+if __name__ == "__main__":
+    cli()

core/framework/agents/credential_tester/agent.py

@@ -0,0 +1,622 @@
+"""Credential Tester agent — verify credentials via live API calls.
+
+Supports both Aden OAuth2-synced accounts AND locally-stored API key accounts.
+Aden accounts use account="alias" routing; local accounts inject the key into
+the session environment so tools read it without an account= parameter.
+
+When loaded via AgentRunner.load() (TUI picker, ``hive run``), the module-level
+``nodes`` / ``edges`` variables provide a static graph.  The TUI detects
+``requires_account_selection`` and shows an account picker *before* starting
+the agent.  ``configure_for_account()`` then scopes the node's tools to the
+selected provider.
+
+When used directly (``CredentialTesterAgent``), the graph is built dynamically
+after the user picks an account programmatically.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from framework.graph import Goal, NodeSpec, SuccessCriterion
+from framework.graph.checkpoint_config import CheckpointConfig
+from framework.graph.edge import GraphSpec
+from framework.graph.executor import ExecutionResult
+from framework.llm import LiteLLMProvider
+from framework.runner.tool_registry import ToolRegistry
+from framework.runtime.agent_runtime import AgentRuntime, create_agent_runtime
+from framework.runtime.execution_stream import EntryPointSpec
+
+from .config import default_config
+from .nodes import build_tester_node
+
+if TYPE_CHECKING:
+    from framework.runner import AgentRunner
+
+# ---------------------------------------------------------------------------
+# Goal
+# ---------------------------------------------------------------------------
+
+goal = Goal(
+    id="credential-tester",
+    name="Credential Tester",
+    description="Verify that a credential can make real API calls.",
+    success_criteria=[
+        SuccessCriterion(
+            id="api-call-success",
+            description="At least one API call succeeds using the credential",
+            metric="api_call_success",
+            target="true",
+            weight=1.0,
+        ),
+    ],
+    constraints=[],
+)
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def get_tools_for_provider(provider_name: str) -> list[str]:
+    """Collect tool names for a credential by credential_id OR credential_group.
+
+    Matches on both ``credential_id`` (e.g. "google" → Gmail tools) and
+    ``credential_group`` (e.g. "google_custom_search" → all google search tools).
+    """
+    from aden_tools.credentials import CREDENTIAL_SPECS
+
+    tools: list[str] = []
+    for spec in CREDENTIAL_SPECS.values():
+        if spec.credential_id == provider_name or spec.credential_group == provider_name:
+            tools.extend(spec.tools)
+    return sorted(set(tools))
+
+
+def _list_aden_accounts() -> list[dict]:
+    """List active accounts from the Aden platform (requires ADEN_API_KEY)."""
+    import os
+
+    api_key = os.environ.get("ADEN_API_KEY")
+    if not api_key:
+        return []
+
+    try:
+        from framework.credentials.aden.client import AdenClientConfig, AdenCredentialClient
+
+        client = AdenCredentialClient(
+            AdenClientConfig(
+                base_url=os.environ.get("ADEN_API_URL", "https://api.adenhq.com"),
+            )
+        )
+        try:
+            integrations = client.list_integrations()
+        finally:
+            client.close()
+
+        return [
+            {
+                "provider": c.provider,
+                "alias": c.alias,
+                "identity": {"email": c.email} if c.email else {},
+                "integration_id": c.integration_id,
+                "source": "aden",
+            }
+            for c in integrations
+            if c.status == "active"
+        ]
+    except Exception:
+        return []
+
+
+def _list_local_accounts() -> list[dict]:
+    """List named local API key accounts from LocalCredentialRegistry."""
+    try:
+        from framework.credentials.local.registry import LocalCredentialRegistry
+
+        return [
+            info.to_account_dict() for info in LocalCredentialRegistry.default().list_accounts()
+        ]
+    except Exception:
+        return []
+
+
+def _list_env_fallback_accounts() -> list[dict]:
+    """Surface configured-but-unregistered credentials as testable entries.
+
+    Detects credentials available via env vars OR stored in the encrypted
+    store in the old flat format (e.g. ``brave_search`` with no alias).
+    These are users who haven't yet run ``save_account()`` but have a working key.
+    Shows with alias="default" and status="unknown".
+    """
+    import os
+
+    from aden_tools.credentials import CREDENTIAL_SPECS
+
+    # Collect IDs in encrypted store (includes old flat entries like "brave_search")
+    try:
+        from framework.credentials.storage import EncryptedFileStorage
+
+        encrypted_ids: set[str] = set(EncryptedFileStorage().list_all())
+    except Exception:
+        encrypted_ids = set()
+
+    def _is_configured(cred_name: str, spec) -> bool:
+        # 1. Env var present
+        if os.environ.get(spec.env_var):
+            return True
+        # 2. Old flat encrypted entry (no slash — new entries have {x}/{y})
+        if cred_name in encrypted_ids:
+            return True
+        return False
+
+    seen_groups: set[str] = set()
+    accounts: list[dict] = []
+
+    for cred_name, spec in CREDENTIAL_SPECS.items():
+        if not spec.direct_api_key_supported or not spec.tools:
+            continue
+
+        if spec.credential_group:
+            if spec.credential_group in seen_groups:
+                continue
+            group_available = all(
+                _is_configured(n, s)
+                for n, s in CREDENTIAL_SPECS.items()
+                if s.credential_group == spec.credential_group
+            )
+            if not group_available:
+                continue
+            seen_groups.add(spec.credential_group)
+            provider = spec.credential_group
+        else:
+            if not _is_configured(cred_name, spec):
+                continue
+            provider = cred_name
+
+        accounts.append(
+            {
+                "provider": provider,
+                "alias": "default",
+                "identity": {},
+                "integration_id": None,
+                "source": "local",
+                "status": "unknown",
+            }
+        )
+
+    return accounts
+
+
+def list_connected_accounts() -> list[dict]:
+    """List all testable accounts: Aden-synced + named local + env-var fallbacks."""
+    aden = _list_aden_accounts()
+    local = _list_local_accounts()
+
+    # Show env-var fallbacks only for credentials not already in the named registry
+    local_providers = {a["provider"] for a in local}
+    env_fallbacks = [
+        a for a in _list_env_fallback_accounts() if a["provider"] not in local_providers
+    ]
+
+    return aden + local + env_fallbacks
+
+
+# ---------------------------------------------------------------------------
+# Module-level hooks (read by AgentRunner.load / TUI)
+# ---------------------------------------------------------------------------
+
+skip_credential_validation = True
+"""Don't validate credentials at load time — we don't know which provider yet."""
+
+requires_account_selection = True
+"""Signal TUI to show account picker before starting the agent."""
+
+
+def configure_for_account(runner: AgentRunner, account: dict) -> None:
+    """Scope the tester node's tools to the selected provider.
+
+    Handles both Aden accounts (account= routing) and local accounts
+    (session-level env var injection, no account= parameter in prompt).
+    """
+    provider = account["provider"]
+    source = account.get("source", "aden")
+    alias = account.get("alias", "unknown")
+    identity = account.get("identity", {})
+    tools = get_tools_for_provider(provider)
+
+    if source == "aden":
+        tools.append("get_account_info")
+        email = identity.get("email", "")
+        detail = f" (email: {email})" if email else ""
+        _configure_aden_node(runner, provider, alias, detail, tools)
+    else:
+        status = account.get("status", "unknown")
+        _activate_local_account(provider, alias)
+        _configure_local_node(runner, provider, alias, identity, tools, status)
+
+
+def _activate_local_account(credential_id: str, alias: str) -> None:
+    """Inject a named local account's key into the session environment.
+
+    Handles three cases:
+    1. Named account in LocalCredentialRegistry (new format: {credential_id}/{alias})
+    2. Old flat credential in EncryptedFileStorage (id == credential_id, no alias)
+    3. Env var already set — skip injection (nothing to do)
+    """
+    import os
+
+    from aden_tools.credentials import CREDENTIAL_SPECS
+
+    # Collect specs for this credential (handles grouped credentials too)
+    group_specs = [
+        (cred_name, spec)
+        for cred_name, spec in CREDENTIAL_SPECS.items()
+        if spec.credential_group == credential_id
+        or spec.credential_id == credential_id
+        or cred_name == credential_id
+    ]
+    # Deduplicate — credential_id and credential_group may both match the same spec
+    seen_env_vars: set[str] = set()
+
+    try:
+        from framework.credentials.local.registry import LocalCredentialRegistry
+        from framework.credentials.storage import EncryptedFileStorage
+
+        registry = LocalCredentialRegistry.default()
+        flat_storage = EncryptedFileStorage()
+
+        for _cred_name, spec in group_specs:
+            if spec.env_var in seen_env_vars:
+                continue
+            # If env var is already set, nothing to do for this one
+            if os.environ.get(spec.env_var):
+                seen_env_vars.add(spec.env_var)
+                continue
+
+            seen_env_vars.add(spec.env_var)
+
+            # Determine key name based on spec
+            key_name = "api_key"
+            if spec.credential_group and "cse" in spec.env_var.lower():
+                key_name = "cse_id"
+
+            key: str | None = None
+
+            # 1. Try named account in registry (new format)
+            if alias != "default":
+                key = registry.get_key(credential_id, alias, key_name)
+            else:
+                # For "default" alias, check registry first, then fall back to flat store
+                key = registry.get_key(credential_id, "default", key_name)
+
+            # 2. Fall back to old flat encrypted entry (id == credential_id, no alias)
+            if key is None:
+                flat_cred = flat_storage.load(credential_id)
+                if flat_cred is not None:
+                    key = flat_cred.get_key(key_name) or flat_cred.get_default_key()
+
+            if key:
+                os.environ[spec.env_var] = key
+    except Exception:
+        pass
+
+
+def _configure_aden_node(
+    runner: AgentRunner,
+    provider: str,
+    alias: str,
+    detail: str,
+    tools: list[str],
+) -> None:
+    for node in runner.graph.nodes:
+        if node.id == "tester":
+            node.tools = sorted(set(tools))
+            node.system_prompt = f"""\
+You are a credential tester for the account: {provider}/{alias}{detail}
+
+# Instructions
+
+1. Suggest a simple read-only API call to verify the credential works \
+(e.g. list messages, list channels, list contacts).
+2. Execute the call when the user agrees.
+3. Report the result: success (with sample data) or failure (with error).
+4. Let the user request additional API calls to further test the credential.
+
+# Account routing
+
+IMPORTANT: Always pass `account="{alias}"` when calling any tool. \
+This routes the API call to the correct credential. Never use the email \
+or any other identifier — always use the alias exactly as shown.
+
+# Rules
+
+- Start with read-only operations (list, get) before write operations.
+- Always confirm with the user before performing write operations.
+- If a call fails, report the exact error — this helps diagnose credential issues.
+- Be concise. No emojis.
+"""
+            break
+
+    runner.intro_message = (
+        f"Testing {provider}/{alias}{detail} — "
+        f"{len(tools)} tools loaded. "
+        "I'll suggest a read-only API call to verify the credential works."
+    )
+
+
+def _configure_local_node(
+    runner: AgentRunner,
+    provider: str,
+    alias: str,
+    identity: dict,
+    tools: list[str],
+    status: str,
+) -> None:
+    identity_parts = [f"{k}: {v}" for k, v in identity.items() if v]
+    detail = f" ({', '.join(identity_parts)})" if identity_parts else ""
+    status_note = " [key not yet validated]" if status == "unknown" else ""
+
+    for node in runner.graph.nodes:
+        if node.id == "tester":
+            node.tools = sorted(set(tools))
+            node.system_prompt = f"""\
+You are a credential tester for the local API key: {provider}/{alias}{detail}{status_note}
+
+# Instructions
+
+1. Suggest a simple test call to verify the credential works \
+(e.g. search for "test", list items, get profile info).
+2. Execute the call when the user agrees.
+3. Report the result: success (with sample data) or failure (with error).
+4. Let the user request additional API calls to further test the credential.
+
+# Rules
+
+- Do NOT pass an `account` parameter — this credential is injected \
+directly into the session environment and tools read it automatically.
+- Start with read-only operations before write operations.
+- Always confirm with the user before performing write operations.
+- If a call fails, report the exact error — this helps diagnose credential issues.
+- Be concise. No emojis.
+"""
+            break
+
+    runner.intro_message = (
+        f"Testing {provider}/{alias}{detail} — "
+        f"{len(tools)} tools loaded. "
+        "I'll suggest a test API call to verify the credential works."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Module-level graph variables (read by AgentRunner.load)
+# ---------------------------------------------------------------------------
+
+nodes = [
+    NodeSpec(
+        id="tester",
+        name="Credential Tester",
+        description=(
+            "Interactive credential testing — lets the user pick an account "
+            "and verify it via API calls."
+        ),
+        node_type="event_loop",
+        client_facing=True,
+        max_node_visits=0,
+        input_keys=[],
+        output_keys=["test_result"],
+        nullable_output_keys=["test_result"],
+        tools=["get_account_info"],
+        system_prompt="""\
+You are a credential tester. Your job is to help the user verify that their \
+connected accounts and API keys can make real API calls.
+
+# Startup
+
+1. Call ``get_account_info`` to list the user's connected accounts.
+2. Present the list and ask the user which account to test.
+3. Once they pick one, note the account's **alias** (e.g. "Timothy", "work-slack").
+4. Suggest a simple read-only API call to verify the credential works \
+(e.g. list messages, list channels, list contacts).
+5. Execute the call when the user agrees.
+6. Report the result: success (with sample data) or failure (with error).
+7. Let the user request additional API calls to further test the credential.
+
+# Account routing (Aden accounts only)
+
+IMPORTANT: For Aden-synced accounts, always pass the account's **alias** as the \
+``account`` parameter when calling any tool. For local API key accounts, do NOT \
+pass an account parameter — they are pre-injected into the session.
+
+# Rules
+
+- Start with read-only operations (list, get) before write operations.
+- Always confirm with the user before performing write operations.
+- If a call fails, report the exact error — this helps diagnose credential issues.
+- Be concise. No emojis.
+""",
+    ),
+]
+
+edges = []
+
+entry_node = "tester"
+entry_points = {"start": "tester"}
+pause_nodes = []
+terminal_nodes = ["tester"]  # Tester node can terminate
+
+conversation_mode = "continuous"
+identity_prompt = (
+    "You are a credential tester that verifies connected accounts and API keys "
+    "can make real API calls."
+)
+loop_config = {
+    "max_iterations": 50,
+    "max_tool_calls_per_turn": 30,
+    "max_history_tokens": 32000,
+}
+
+# ---------------------------------------------------------------------------
+# Programmatic agent class (used by __main__.py CLI)
+# ---------------------------------------------------------------------------
+
+
+class CredentialTesterAgent:
+    """Interactive agent that tests a specific credential via API calls.
+
+    Usage:
+        agent = CredentialTesterAgent()
+        accounts = agent.list_accounts()
+        agent.select_account(accounts[0])
+        await agent.start()
+        await agent.stop()
+    """
+
+    def __init__(self, config=None):
+        self.config = config or default_config
+        self._selected_account: dict | None = None
+        self._agent_runtime: AgentRuntime | None = None
+        self._tool_registry: ToolRegistry | None = None
+        self._storage_path: Path | None = None
+
+    def list_accounts(self) -> list[dict]:
+        """List all testable accounts (Aden + local named + env-var fallbacks)."""
+        return list_connected_accounts()
+
+    def select_account(self, account: dict) -> None:
+        """Select an account to test.
+
+        Args:
+            account: Account dict from list_accounts() with
+                     provider, alias, identity, source keys.
+        """
+        self._selected_account = account
+
+    @property
+    def selected_provider(self) -> str:
+        if self._selected_account is None:
+            raise RuntimeError("No account selected. Call select_account() first.")
+        return self._selected_account["provider"]
+
+    @property
+    def selected_alias(self) -> str:
+        if self._selected_account is None:
+            raise RuntimeError("No account selected. Call select_account() first.")
+        return self._selected_account.get("alias", "unknown")
+
+    def _build_graph(self) -> GraphSpec:
+        provider = self.selected_provider
+        alias = self.selected_alias
+        source = self._selected_account.get("source", "aden")
+        identity = self._selected_account.get("identity", {})
+        tools = get_tools_for_provider(provider)
+
+        if source == "local":
+            _activate_local_account(provider, alias)
+        elif source == "aden":
+            tools.append("get_account_info")
+
+        tester_node = build_tester_node(
+            provider=provider,
+            alias=alias,
+            tools=tools,
+            identity=identity,
+            source=source,
+        )
+
+        return GraphSpec(
+            id="credential-tester-graph",
+            goal_id=goal.id,
+            version="1.0.0",
+            entry_node="tester",
+            entry_points={"start": "tester"},
+            terminal_nodes=["tester"],  # Tester node can terminate
+            pause_nodes=[],
+            nodes=[tester_node],
+            edges=[],
+            default_model=self.config.model,
+            max_tokens=self.config.max_tokens,
+            loop_config={
+                "max_iterations": 50,
+                "max_tool_calls_per_turn": 30,
+                "max_history_tokens": 32000,
+            },
+            conversation_mode="continuous",
+            identity_prompt=(
+                f"You are testing the {provider}/{alias} credential. "
+                "Help the user verify it works by making real API calls."
+            ),
+        )
+
+    def _setup(self) -> None:
+        if self._selected_account is None:
+            raise RuntimeError("No account selected. Call select_account() first.")
+
+        self._storage_path = Path.home() / ".hive" / "agents" / "credential_tester"
+        self._storage_path.mkdir(parents=True, exist_ok=True)
+
+        self._tool_registry = ToolRegistry()
+
+        mcp_config_path = Path(__file__).parent / "mcp_servers.json"
+        if mcp_config_path.exists():
+            self._tool_registry.load_mcp_config(mcp_config_path)
+
+        extra_kwargs = getattr(self.config, "extra_kwargs", {}) or {}
+        llm = LiteLLMProvider(
+            model=self.config.model,
+            api_key=self.config.api_key,
+            api_base=self.config.api_base,
+            **extra_kwargs,
+        )
+
+        tool_executor = self._tool_registry.get_executor()
+        tools = list(self._tool_registry.get_tools().values())
+
+        graph = self._build_graph()
+
+        self._agent_runtime = create_agent_runtime(
+            graph=graph,
+            goal=goal,
+            storage_path=self._storage_path,
+            entry_points=[
+                EntryPointSpec(
+                    id="start",
+                    name="Test Credential",
+                    entry_node="tester",
+                    trigger_type="manual",
+                    isolation_level="isolated",
+                ),
+            ],
+            llm=llm,
+            tools=tools,
+            tool_executor=tool_executor,
+            checkpoint_config=CheckpointConfig(enabled=False),
+            graph_id="credential_tester",
+        )
+
+    async def start(self) -> None:
+        """Set up and start the agent runtime."""
+        if self._agent_runtime is None:
+            self._setup()
+        if not self._agent_runtime.is_running:
+            await self._agent_runtime.start()
+
+    async def stop(self) -> None:
+        """Stop the agent runtime."""
+        if self._agent_runtime and self._agent_runtime.is_running:
+            await self._agent_runtime.stop()
+        self._agent_runtime = None
+
+    async def run(self) -> ExecutionResult:
+        """Run the agent (convenience for single execution)."""
+        await self.start()
+        try:
+            result = await self._agent_runtime.trigger_and_wait(
+                entry_point_id="start",
+                input_data={},
+            )
+            return result or ExecutionResult(success=False, error="Execution timeout")
+        finally:
+            await self.stop()

core/framework/agents/credential_tester/config.py

@@ -0,0 +1,19 @@
+"""Runtime configuration for Credential Tester agent."""
+
+from dataclasses import dataclass
+
+from framework.config import RuntimeConfig
+
+
+@dataclass
+class AgentMetadata:
+    name: str = "Credential Tester"
+    version: str = "1.0.0"
+    description: str = (
+        "Test connected accounts by making real API calls. "
+        "Pick an account, verify credentials work, and explore available tools."
+    )
+
+
+metadata = AgentMetadata()
+default_config = RuntimeConfig(temperature=0.3)

core/framework/agents/credential_tester/mcp_servers.json

@@ -0,0 +1,9 @@
+{
+  "hive-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "mcp_server.py", "--stdio"],
+    "cwd": "../../../../tools",
+    "description": "Hive tools MCP server with provider-specific tools"
+  }
+}

core/framework/agents/credential_tester/nodes/__init__.py

@@ -0,0 +1,85 @@
+"""Node definitions for Credential Tester agent."""
+
+from framework.graph import NodeSpec
+
+
+def build_tester_node(
+    provider: str,
+    alias: str,
+    tools: list[str],
+    identity: dict[str, str],
+    source: str = "aden",
+) -> NodeSpec:
+    """Build the tester node dynamically for the selected account.
+
+    Args:
+        provider: Provider / credential name (e.g. "google", "brave_search").
+        alias: User-set alias (e.g. "Timothy", "work").
+        tools: Tool names available for this provider.
+        identity: Identity dict (email, workspace, etc.) for context.
+        source: "aden" or "local" — controls routing instructions in the prompt.
+    """
+    detail_parts = [f"{k}: {v}" for k, v in identity.items() if v]
+    detail = f" ({', '.join(detail_parts)})" if detail_parts else ""
+
+    if source == "aden":
+        routing_section = f"""\
+# Account routing
+
+IMPORTANT: Always pass `account="{alias}"` when calling any tool. \
+This routes the API call to the correct credential. Never use the email \
+or any other identifier — always use the alias exactly as shown.
+"""
+    else:
+        routing_section = """\
+# Credential routing
+
+This is a local API key credential — do NOT pass an `account` parameter. \
+The key is pre-injected into the session environment and tools read it automatically.
+"""
+
+    account_label = "account" if source == "aden" else "local API key"
+
+    return NodeSpec(
+        id="tester",
+        name="Credential Tester",
+        description=(
+            f"Interactive testing node for {provider}/{alias}. "
+            f"Has access to all {provider} tools to verify the credential works."
+        ),
+        node_type="event_loop",
+        client_facing=True,
+        max_node_visits=0,
+        input_keys=[],
+        output_keys=["test_result"],
+        nullable_output_keys=["test_result"],
+        tools=tools,
+        system_prompt=f"""\
+You are a credential tester for the {account_label}: {provider}/{alias}{detail}
+
+Your job is to help the user verify that this credential works by making \
+real API calls using the available tools.
+
+{routing_section}
+# Instructions
+
+1. Start by greeting the user and confirming which account you're testing.
+2. Suggest a simple, safe, read-only API call to verify the credential works \
+(e.g. list messages, list channels, list contacts, search for "test").
+3. Execute the call when the user agrees.
+4. Report the result clearly: success (with sample data) or failure (with error).
+5. Let the user request additional API calls to further test the credential.
+
+# Available tools
+
+You have access to {len(tools)} tools for {provider}:
+{chr(10).join(f"- {t}" for t in tools)}
+
+# Rules
+
+- Start with read-only operations (list, get) before write operations (create, update, delete).
+- Always confirm with the user before performing write operations.
+- If a call fails, report the exact error — this helps diagnose credential issues.
+- Be concise. No emojis.
+""",
+    )

core/framework/agents/queen/__init__.py

@@ -0,0 +1,21 @@
+"""
+Queen — Native agent builder for the Hive framework.
+
+Deeply understands the agent framework and produces complete Python packages
+with goals, nodes, edges, system prompts, MCP configuration, and tests
+from natural language specifications.
+"""
+
+from .agent import queen_goal, queen_graph
+from .config import AgentMetadata, RuntimeConfig, default_config, metadata
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "queen_goal",
+    "queen_graph",
+    "RuntimeConfig",
+    "AgentMetadata",
+    "default_config",
+    "metadata",
+]

core/framework/agents/queen/agent.py

@@ -0,0 +1,40 @@
+"""Queen graph definition."""
+
+from framework.graph import Goal
+from framework.graph.edge import GraphSpec
+
+from .nodes import queen_node
+
+# ---------------------------------------------------------------------------
+# Queen graph — the primary persistent conversation.
+# Loaded by queen_orchestrator.create_queen(), NOT by AgentRunner.
+# ---------------------------------------------------------------------------
+
+queen_goal = Goal(
+    id="queen-manager",
+    name="Queen Manager",
+    description=(
+        "Manage the worker agent lifecycle and serve as the user's primary "
+        "interactive interface. Triage health escalations from the judge."
+    ),
+    success_criteria=[],
+    constraints=[],
+)
+
+queen_graph = GraphSpec(
+    id="queen-graph",
+    goal_id=queen_goal.id,
+    version="1.0.0",
+    entry_node="queen",
+    entry_points={"start": "queen"},
+    terminal_nodes=[],
+    pause_nodes=[],
+    nodes=[queen_node],
+    edges=[],
+    conversation_mode="continuous",
+    loop_config={
+        "max_iterations": 999_999,
+        "max_tool_calls_per_turn": 30,
+        "max_history_tokens": 32000,
+    },
+)

core/framework/agents/queen/config.py

@@ -0,0 +1,51 @@
+"""Runtime configuration for Queen agent."""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _load_preferred_model() -> str:
+    """Load preferred model from ~/.hive/configuration.json."""
+    config_path = Path.home() / ".hive" / "configuration.json"
+    if config_path.exists():
+        try:
+            with open(config_path, encoding="utf-8") as f:
+                config = json.load(f)
+            llm = config.get("llm", {})
+            if llm.get("provider") and llm.get("model"):
+                return f"{llm['provider']}/{llm['model']}"
+        except Exception:
+            pass
+    return "anthropic/claude-sonnet-4-20250514"
+
+
+@dataclass
+class RuntimeConfig:
+    model: str = field(default_factory=_load_preferred_model)
+    temperature: float = 0.7
+    max_tokens: int = 8000
+    api_key: str | None = None
+    api_base: str | None = None
+
+
+default_config = RuntimeConfig()
+
+
+@dataclass
+class AgentMetadata:
+    name: str = "Queen"
+    version: str = "1.0.0"
+    description: str = (
+        "Native coding agent that builds production-ready Hive agent packages "
+        "from natural language specifications. Deeply understands the agent framework "
+        "and produces complete Python packages with goals, nodes, edges, system prompts, "
+        "MCP configuration, and tests."
+    )
+    intro_message: str = (
+        "I'm Queen — I build Hive agents. Describe what kind of agent "
+        "you want to create and I'll design, implement, and validate it for you."
+    )
+
+
+metadata = AgentMetadata()

core/framework/agents/queen/mcp_servers.json

@@ -0,0 +1,9 @@
+{
+  "coder-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "coder_tools_server.py", "--stdio"],
+    "cwd": "../../../../tools",
+    "description": "Unsandboxed file system tools for code generation and validation"
+  }
+}

core/framework/agents/queen/nodes/thinking_hook.py

@@ -0,0 +1,80 @@
+"""Queen thinking hook — HR persona classifier.
+
+Fires once when the queen enters building mode at session start.
+Makes a single non-streaming LLM call (acting as an HR Director) to select
+the best-fit expert persona for the user's request, then returns a persona
+prefix string that replaces the queen's default "Solution Architect" identity.
+
+This is designed to activate the model's latent domain expertise — a CFO
+persona on a financial question, a Lawyer on a legal question, etc.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from framework.llm.provider import LLMProvider
+
+logger = logging.getLogger(__name__)
+
+_HR_SYSTEM_PROMPT = """\
+You are an expert HR Director and talent consultant at a world-class firm.
+A new request has arrived and you must identify which professional's expertise
+would produce the highest-quality response.
+
+Reply with ONLY a valid JSON object — no markdown, no prose, no explanation:
+{"role": "<job title>", "persona": "<2-3 sentence first-person identity statement>"}
+
+Rules:
+- Choose from any real professional role: CFO, CEO, CTO, Lawyer, Data Scientist,
+  Product Manager, Security Engineer, DevOps Engineer, Software Architect,
+  HR Director, Marketing Director, Business Analyst, UX Designer,
+  Financial Analyst, Operations Director, Legal Counsel, etc.
+- The persona statement must be written in first person ("I am..." or "I have...").
+- Select the role whose domain knowledge most directly applies to solving the request.
+- If the request is clearly about coding or building software systems, pick Software Architect.
+- "Queen" is your internal alias — do not include it in the persona.
+"""
+
+
+async def select_expert_persona(user_message: str, llm: LLMProvider) -> str:
+    """Run the HR classifier and return a persona prefix string.
+
+    Makes a single non-streaming acomplete() call with the session LLM.
+    Returns an empty string on any failure so the queen falls back
+    gracefully to its default "Solution Architect" identity.
+
+    Args:
+        user_message: The user's opening message for the session.
+        llm: The session LLM provider.
+
+    Returns:
+        A persona prefix like "You are a CFO. I am a CFO with 20 years..."
+        or "" on failure.
+    """
+    if not user_message.strip():
+        return ""
+
+    try:
+        response = await llm.acomplete(
+            messages=[{"role": "user", "content": user_message}],
+            system=_HR_SYSTEM_PROMPT,
+            max_tokens=1024,
+            json_mode=True,
+        )
+        raw = response.content.strip()
+        parsed = json.loads(raw)
+        role = parsed.get("role", "").strip()
+        persona = parsed.get("persona", "").strip()
+        if not role or not persona:
+            logger.warning("Thinking hook: empty role/persona in response: %r", raw)
+            return ""
+        result = f"You are a {role}. {persona}"
+        logger.info("Thinking hook: selected persona — %s", role)
+        return result
+    except Exception:
+        logger.warning("Thinking hook: persona classification failed", exc_info=True)
+        return ""

core/framework/agents/queen/queen_memory.py

@@ -0,0 +1,371 @@
+"""Queen global cross-session memory.
+
+Three-tier memory architecture:
+  ~/.hive/queen/MEMORY.md                            — semantic (who, what, why)
+  ~/.hive/queen/memories/MEMORY-YYYY-MM-DD.md        — episodic (daily journals)
+  ~/.hive/queen/session/{id}/data/adapt.md           — working (session-scoped)
+
+Semantic and episodic files are injected at queen session start.
+
+Semantic memory (MEMORY.md) is updated automatically at session end via
+consolidate_queen_memory() — the queen never rewrites this herself.
+
+Episodic memory (MEMORY-date.md) can be written by the queen during a session
+via the write_to_diary tool, and is also appended to at session end by
+consolidate_queen_memory().
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import traceback
+from datetime import date, datetime
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def _queen_dir() -> Path:
+    return Path.home() / ".hive" / "queen"
+
+
+def semantic_memory_path() -> Path:
+    return _queen_dir() / "MEMORY.md"
+
+
+def episodic_memory_path(d: date | None = None) -> Path:
+    d = d or date.today()
+    return _queen_dir() / "memories" / f"MEMORY-{d.strftime('%Y-%m-%d')}.md"
+
+
+def read_semantic_memory() -> str:
+    path = semantic_memory_path()
+    return path.read_text(encoding="utf-8").strip() if path.exists() else ""
+
+
+def read_episodic_memory(d: date | None = None) -> str:
+    path = episodic_memory_path(d)
+    return path.read_text(encoding="utf-8").strip() if path.exists() else ""
+
+
+def format_for_injection() -> str:
+    """Format cross-session memory for system prompt injection.
+
+    Returns an empty string if no meaningful content exists yet (e.g. first
+    session with only the seed template).
+    """
+    semantic = read_semantic_memory()
+    episodic = read_episodic_memory()
+
+    # Suppress injection if semantic is still just the seed template
+    if semantic and semantic.startswith("# My Understanding of the User\n\n*No sessions"):
+        semantic = ""
+
+    parts: list[str] = []
+    if semantic:
+        parts.append(semantic)
+    if episodic:
+        today_str = date.today().strftime("%B %-d, %Y")
+        parts.append(f"## Today — {today_str}\n\n{episodic}")
+
+    if not parts:
+        return ""
+
+    body = "\n\n---\n\n".join(parts)
+    return "--- Your Cross-Session Memory ---\n\n" + body + "\n\n--- End Cross-Session Memory ---"
+
+
+_SEED_TEMPLATE = """\
+# My Understanding of the User
+
+*No sessions recorded yet.*
+
+## Who They Are
+
+## What They're Trying to Achieve
+
+## What's Working
+
+## What I've Learned
+"""
+
+
+def append_episodic_entry(content: str) -> None:
+    """Append a timestamped prose entry to today's episodic memory file.
+
+    Creates the file (with a date heading) if it doesn't exist yet.
+    Used both by the queen's diary tool and by the consolidation hook.
+    """
+    ep_path = episodic_memory_path()
+    ep_path.parent.mkdir(parents=True, exist_ok=True)
+    today_str = date.today().strftime("%B %-d, %Y")
+    timestamp = datetime.now().strftime("%H:%M")
+    if not ep_path.exists():
+        header = f"# {today_str}\n\n"
+        block = f"{header}### {timestamp}\n\n{content.strip()}\n"
+    else:
+        block = f"\n\n### {timestamp}\n\n{content.strip()}\n"
+    with ep_path.open("a", encoding="utf-8") as f:
+        f.write(block)
+
+
+def seed_if_missing() -> None:
+    """Create MEMORY.md with a blank template if it doesn't exist yet."""
+    path = semantic_memory_path()
+    if path.exists():
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(_SEED_TEMPLATE, encoding="utf-8")
+
+
+# ---------------------------------------------------------------------------
+# Consolidation prompt
+# ---------------------------------------------------------------------------
+
+_SEMANTIC_SYSTEM = """\
+You maintain the persistent cross-session memory of an AI assistant called the Queen.
+Review the session notes and rewrite MEMORY.md — the Queen's durable understanding of the
+person she works with across all sessions.
+
+Write entirely in the Queen's voice — first person, reflective, honest.
+Not a log of events, but genuine understanding of who this person is over time.
+
+Rules:
+- Update and synthesise: incorporate new understanding, update facts that have changed, remove
+  details that are stale, superseded, or no longer say anything meaningful about the person.
+- Keep it as structured markdown with named sections about the PERSON, not about today.
+- Do NOT include diary sections, daily logs, or session summaries. Those belong elsewhere.
+  MEMORY.md is about who they are, what they want, what works — not what happened today.
+- Reference dates only when noting a lasting milestone (e.g. "since March 8th they prefer X").
+- If the session had no meaningful new information about the person,
+  return the existing text unchanged.
+- Do not add fictional details. Only reflect what is evidenced in the notes.
+- Stay concise. Prune rather than accumulate. A lean, accurate file is more useful than a
+  dense one. If something was true once but has been resolved or superseded, remove it.
+- Output only the raw markdown content of MEMORY.md. No preamble, no code fences.
+"""
+
+_DIARY_SYSTEM = """\
+You maintain the daily episodic diary of an AI assistant called the Queen.
+You receive: (1) today's existing diary so far, and (2) notes from the latest session.
+
+Rewrite the complete diary for today as a single unified narrative —
+first person, reflective, honest.
+Merge and deduplicate: if the same story (e.g. a research agent stalling) recurred several times,
+describe it once with appropriate weight rather than retelling it. Weave in new developments from
+the session notes. Preserve important milestones, emotional texture, and session path references.
+
+If today's diary is empty, write the initial entry based on the session notes alone.
+
+Output only the full diary prose — no date heading, no timestamp headers,
+no preamble, no code fences.
+"""
+
+
+def read_session_context(session_dir: Path, max_messages: int = 80) -> str:
+    """Extract a readable transcript from conversation parts + adapt.md.
+
+    Reads the last ``max_messages`` conversation parts and the session's
+    adapt.md (working memory). Tool results are omitted — only user and
+    assistant turns (with tool-call names noted) are included.
+    """
+    parts: list[str] = []
+
+    # Working notes
+    adapt_path = session_dir / "data" / "adapt.md"
+    if adapt_path.exists():
+        text = adapt_path.read_text(encoding="utf-8").strip()
+        if text:
+            parts.append(f"## Session Working Notes (adapt.md)\n\n{text}")
+
+    # Conversation transcript
+    parts_dir = session_dir / "conversations" / "parts"
+    if parts_dir.exists():
+        part_files = sorted(parts_dir.glob("*.json"))[-max_messages:]
+        lines: list[str] = []
+        for pf in part_files:
+            try:
+                data = json.loads(pf.read_text(encoding="utf-8"))
+                role = data.get("role", "")
+                content = str(data.get("content", "")).strip()
+                tool_calls = data.get("tool_calls") or []
+                if role == "tool":
+                    continue  # skip verbose tool results
+                if role == "assistant" and tool_calls and not content:
+                    names = [tc.get("function", {}).get("name", "?") for tc in tool_calls]
+                    lines.append(f"[queen calls: {', '.join(names)}]")
+                elif content:
+                    label = "user" if role == "user" else "queen"
+                    lines.append(f"[{label}]: {content[:600]}")
+            except Exception:
+                continue
+        if lines:
+            parts.append("## Conversation\n\n" + "\n".join(lines))
+
+    return "\n\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Context compaction (binary-split LLM summarisation)
+# ---------------------------------------------------------------------------
+
+# If the raw session context exceeds this many characters, compact it first
+# before sending to the consolidation LLM. ~200 k chars ≈ 50 k tokens.
+_CTX_COMPACT_CHAR_LIMIT = 200_000
+_CTX_COMPACT_MAX_DEPTH = 8
+
+_COMPACT_SYSTEM = (
+    "Summarise this conversation segment. Preserve: user goals, key decisions, "
+    "what was built or changed, emotional tone, and important outcomes. "
+    "Write concisely in third person past tense. Omit routine tool invocations "
+    "unless the result matters."
+)
+
+
+async def _compact_context(text: str, llm: object, *, _depth: int = 0) -> str:
+    """Binary-split and LLM-summarise *text* until it fits within the char limit.
+
+    Mirrors the recursive binary-splitting strategy used by the main agent
+    compaction pipeline (EventLoopNode._llm_compact).
+    """
+    if len(text) <= _CTX_COMPACT_CHAR_LIMIT or _depth >= _CTX_COMPACT_MAX_DEPTH:
+        return text
+
+    # Split near the midpoint on a line boundary so we don't cut mid-message
+    mid = len(text) // 2
+    split_at = text.rfind("\n", 0, mid) + 1
+    if split_at <= 0:
+        split_at = mid
+
+    half1, half2 = text[:split_at], text[split_at:]
+
+    async def _summarise(chunk: str) -> str:
+        try:
+            resp = await llm.acomplete(
+                messages=[{"role": "user", "content": chunk}],
+                system=_COMPACT_SYSTEM,
+                max_tokens=2048,
+            )
+            return resp.content.strip()
+        except Exception:
+            logger.warning(
+                "queen_memory: context compaction LLM call failed (depth=%d), truncating",
+                _depth,
+            )
+            return chunk[: _CTX_COMPACT_CHAR_LIMIT // 4]
+
+    s1, s2 = await asyncio.gather(_summarise(half1), _summarise(half2))
+    combined = s1 + "\n\n" + s2
+    if len(combined) > _CTX_COMPACT_CHAR_LIMIT:
+        return await _compact_context(combined, llm, _depth=_depth + 1)
+    return combined
+
+
+async def consolidate_queen_memory(
+    session_id: str,
+    session_dir: Path,
+    llm: object,
+) -> None:
+    """Update MEMORY.md and append a diary entry based on the current session.
+
+    Reads conversation parts and adapt.md from session_dir. Called
+    periodically in the background and once at session end. Failures are
+    logged and silently swallowed so they never block teardown.
+
+    Args:
+        session_id: The session ID (used for the adapt.md path reference).
+        session_dir: Path to the session directory (~/.hive/queen/session/{id}).
+        llm: LLMProvider instance (must support acomplete()).
+    """
+    try:
+        session_context = read_session_context(session_dir)
+        if not session_context:
+            logger.debug("queen_memory: no session context, skipping consolidation")
+            return
+
+        logger.info("queen_memory: consolidating memory for session %s ...", session_id)
+
+        # If the transcript is very large, compact it with recursive binary LLM
+        # summarisation before sending to the consolidation model.
+        if len(session_context) > _CTX_COMPACT_CHAR_LIMIT:
+            logger.info(
+                "queen_memory: session context is %d chars — compacting first",
+                len(session_context),
+            )
+            session_context = await _compact_context(session_context, llm)
+            logger.info("queen_memory: compacted to %d chars", len(session_context))
+
+        existing_semantic = read_semantic_memory()
+        today_journal = read_episodic_memory()
+        today_str = date.today().strftime("%B %-d, %Y")
+        adapt_path = session_dir / "data" / "adapt.md"
+
+        user_msg = (
+            f"## Existing Semantic Memory (MEMORY.md)\n\n"
+            f"{existing_semantic or '(none yet)'}\n\n"
+            f"## Today's Diary So Far ({today_str})\n\n"
+            f"{today_journal or '(none yet)'}\n\n"
+            f"{session_context}\n\n"
+            f"## Session Reference\n\n"
+            f"Session ID: {session_id}\n"
+            f"Session path: {adapt_path}\n"
+        )
+
+        logger.debug(
+            "queen_memory: calling LLM (%d chars of context, ~%d tokens est.)",
+            len(user_msg),
+            len(user_msg) // 4,
+        )
+
+        from framework.agents.queen.config import default_config
+
+        semantic_resp, diary_resp = await asyncio.gather(
+            llm.acomplete(
+                messages=[{"role": "user", "content": user_msg}],
+                system=_SEMANTIC_SYSTEM,
+                max_tokens=default_config.max_tokens,
+            ),
+            llm.acomplete(
+                messages=[{"role": "user", "content": user_msg}],
+                system=_DIARY_SYSTEM,
+                max_tokens=default_config.max_tokens,
+            ),
+        )
+
+        new_semantic = semantic_resp.content.strip()
+        diary_entry = diary_resp.content.strip()
+
+        if new_semantic:
+            path = semantic_memory_path()
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(new_semantic, encoding="utf-8")
+            logger.info("queen_memory: semantic memory updated (%d chars)", len(new_semantic))
+
+        if diary_entry:
+            # Rewrite today's episodic file in-place — the LLM has merged and
+            # deduplicated the full day's content, so we replace rather than append.
+            ep_path = episodic_memory_path()
+            ep_path.parent.mkdir(parents=True, exist_ok=True)
+            heading = f"# {today_str}"
+            ep_path.write_text(f"{heading}\n\n{diary_entry}\n", encoding="utf-8")
+            logger.info(
+                "queen_memory: episodic diary rewritten for %s (%d chars)",
+                today_str,
+                len(diary_entry),
+            )
+
+    except Exception:
+        tb = traceback.format_exc()
+        logger.exception("queen_memory: consolidation failed")
+        # Write to file so the cause is findable regardless of log verbosity.
+        error_path = _queen_dir() / "consolidation_error.txt"
+        try:
+            error_path.parent.mkdir(parents=True, exist_ok=True)
+            error_path.write_text(
+                f"session: {session_id}\ntime: {datetime.now().isoformat()}\n\n{tb}",
+                encoding="utf-8",
+            )
+        except Exception:
+            pass

core/framework/agents/queen/reference/anti_patterns.md

@@ -0,0 +1,33 @@
+# Common Mistakes When Building Hive Agents
+
+## Critical Errors
+1. **Using tools that don't exist** — Always verify tools via `list_agent_tools()` before designing. Common hallucinations: `csv_read`, `csv_write`, `file_upload`, `database_query`, `bulk_fetch_emails`.
+2. **Wrong mcp_servers.json format** — Flat dict (no `"mcpServers"` wrapper). `cwd` must be `"../../tools"`. `command` must be `"uv"` with args `["run", "python", ...]`.
+3. **Missing module-level exports in `__init__.py`** — The runner reads `goal`, `nodes`, `edges`, `entry_node`, `entry_points`, `terminal_nodes`, `conversation_mode`, `identity_prompt`, `loop_config` via `getattr()`. ALL module-level variables from agent.py must be re-exported in `__init__.py`.
+
+## Value Errors
+4. **Fabricating tools** — Always verify via `list_agent_tools()` before designing and `validate_agent_package()` after building.
+
+## Design Errors
+5. **Adding framework gating for LLM behavior** — Don't add output rollback or premature rejection. Fix with better prompts or custom judges.
+6. **Calling set_output in same turn as tool calls** — Call set_output in a SEPARATE turn.
+
+## File Template Errors
+7. **Wrong import paths** — Use `from framework.graph import ...`, NOT `from core.framework.graph import ...`.
+8. **Missing storage path** — Agent class must set `self._storage_path = Path.home() / ".hive" / "agents" / "agent_name"`.
+9. **Missing mcp_servers.json** — Without this, the agent has no tools at runtime.
+10. **Bare `python` command** — Use `"command": "uv"` with args `["run", "python", ...]`.
+
+## Testing Errors
+11. **Using `runner.run()` on forever-alive agents** — `runner.run()` hangs forever because forever-alive agents have no terminal node. Write structural tests instead: validate graph structure, verify node specs, test `AgentRunner.load()` succeeds (no API key needed).
+12. **Stale tests after restructuring** — When changing nodes/edges, update tests to match. Tests referencing old node names will fail.
+13. **Running integration tests without API keys** — Use `pytest.skip()` when credentials are missing.
+14. **Forgetting sys.path setup in conftest.py** — Tests need `exports/` and `core/` on sys.path.
+
+## GCU Errors
+15. **Manually wiring browser tools on event_loop nodes** — Use `node_type="gcu"` which auto-includes browser tools. Do NOT manually list browser tool names.
+16. **Using GCU nodes as regular graph nodes** — GCU nodes are subagents only. They must ONLY appear in `sub_agents=["gcu-node-id"]` and be invoked via `delegate_to_sub_agent()`. Never connect via edges or use as entry/terminal nodes.
+
+## Worker Agent Errors
+17. **Adding client-facing intake node to workers** — The queen owns intake. Workers should start with an autonomous processing node. Client-facing nodes in workers are for mid-execution review/approval only.
+18. **Putting `escalate` or `set_output` in NodeSpec `tools=[]`** — These are synthetic framework tools, auto-injected at runtime. Only list MCP tools from `list_agent_tools()`.

core/framework/agents/queen/reference/file_templates.md

@@ -0,0 +1,619 @@
+# Agent File Templates
+
+Complete code templates for each file in a Hive agent package.
+
+## config.py
+
+```python
+"""Runtime configuration."""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def _load_preferred_model() -> str:
+    """Load preferred model from ~/.hive/configuration.json."""
+    config_path = Path.home() / ".hive" / "configuration.json"
+    if config_path.exists():
+        try:
+            with open(config_path) as f:
+                config = json.load(f)
+            llm = config.get("llm", {})
+            if llm.get("provider") and llm.get("model"):
+                return f"{llm['provider']}/{llm['model']}"
+        except Exception:
+            pass
+    return "anthropic/claude-sonnet-4-20250514"
+
+
+@dataclass
+class RuntimeConfig:
+    model: str = field(default_factory=_load_preferred_model)
+    temperature: float = 0.7
+    max_tokens: int = 40000
+    api_key: str | None = None
+    api_base: str | None = None
+
+
+default_config = RuntimeConfig()
+
+
+@dataclass
+class AgentMetadata:
+    name: str = "My Agent Name"
+    version: str = "1.0.0"
+    description: str = "What this agent does."
+    intro_message: str = "Welcome! What would you like me to do?"
+
+
+metadata = AgentMetadata()
+```
+
+## nodes/__init__.py
+
+```python
+"""Node definitions for My Agent."""
+
+from framework.graph import NodeSpec
+
+# Node 1: Process (autonomous entry node)
+# The queen handles intake and passes structured input via
+# run_agent_with_input(task). NO client-facing intake node.
+# The queen defines input_keys at build time and fills them at run time.
+process_node = NodeSpec(
+    id="process",
+    name="Process",
+    description="Execute the task using available tools",
+    node_type="event_loop",
+    max_node_visits=0,  # Unlimited for forever-alive
+    input_keys=["user_request", "feedback"],
+    output_keys=["results"],
+    nullable_output_keys=["feedback"],  # Only on feedback edge
+    success_criteria="Results are complete and accurate.",
+    system_prompt="""\
+You are a processing agent. Your task is in memory under "user_request". \
+If "feedback" is present, this is a revision — address the feedback.
+
+Work in phases:
+1. Use tools to gather/process data
+2. Analyze results
+3. Call set_output in a SEPARATE turn:
+   - set_output("results", "structured results")
+""",
+    tools=["web_search", "web_scrape", "save_data", "load_data", "list_data_files"],
+)
+
+# Node 2: Handoff (autonomous)
+handoff_node = NodeSpec(
+    id="handoff",
+    name="Handoff",
+    description="Prepare worker results for queen review",
+    node_type="event_loop",
+    client_facing=False,
+    max_node_visits=0,
+    input_keys=["results", "user_request"],
+    output_keys=["next_action", "feedback", "worker_summary"],
+    nullable_output_keys=["feedback", "worker_summary"],
+    success_criteria="Results are packaged for queen decision-making.",
+    system_prompt="""\
+Do NOT talk to the user directly. The queen is the only user interface.
+
+If blocked by tool failures, missing credentials, or unclear constraints, call:
+- escalate(reason, context)
+Then set:
+- set_output("next_action", "escalated")
+- set_output("feedback", "what help is needed")
+
+Otherwise summarize findings for queen and set:
+- set_output("worker_summary", "short summary for queen")
+- set_output("next_action", "done") or set_output("next_action", "revise")
+- set_output("feedback", "what to revise") only when revising
+""",
+    tools=[],
+)
+
+__all__ = ["process_node", "handoff_node"]
+```
+
+## agent.py
+
+```python
+"""Agent graph construction for My Agent."""
+
+from pathlib import Path
+
+from framework.graph import EdgeSpec, EdgeCondition, Goal, SuccessCriterion, Constraint
+from framework.graph.edge import GraphSpec
+from framework.graph.executor import ExecutionResult
+from framework.graph.checkpoint_config import CheckpointConfig
+from framework.llm import LiteLLMProvider
+from framework.runner.tool_registry import ToolRegistry
+from framework.runtime.agent_runtime import AgentRuntime, create_agent_runtime
+from framework.runtime.execution_stream import EntryPointSpec
+
+from .config import default_config, metadata
+from .nodes import process_node, handoff_node
+
+# Goal definition
+goal = Goal(
+    id="my-agent-goal",
+    name="My Agent Goal",
+    description="What this agent achieves.",
+    success_criteria=[
+        SuccessCriterion(id="sc-1", description="...", metric="...", target="...", weight=0.5),
+        SuccessCriterion(id="sc-2", description="...", metric="...", target="...", weight=0.5),
+    ],
+    constraints=[
+        Constraint(id="c-1", description="...", constraint_type="hard", category="quality"),
+    ],
+)
+
+# Node list
+nodes = [process_node, handoff_node]
+
+# Edge definitions
+edges = [
+    EdgeSpec(id="process-to-handoff", source="process", target="handoff",
+             condition=EdgeCondition.ON_SUCCESS, priority=1),
+    # Feedback loop — revise results
+    EdgeSpec(id="handoff-to-process", source="handoff", target="process",
+             condition=EdgeCondition.CONDITIONAL,
+             condition_expr="str(next_action).lower() == 'revise'", priority=2),
+    # Escalation loop — queen injects guidance and worker retries
+    EdgeSpec(id="handoff-escalated", source="handoff", target="process",
+             condition=EdgeCondition.CONDITIONAL,
+             condition_expr="str(next_action).lower() == 'escalated'", priority=3),
+    # Loop back for next task after queen decision
+    EdgeSpec(id="handoff-done", source="handoff", target="process",
+             condition=EdgeCondition.CONDITIONAL,
+             condition_expr="str(next_action).lower() == 'done'", priority=1),
+]
+
+# Graph configuration — entry is the autonomous process node
+# The queen handles intake and passes the task via run_agent_with_input(task)
+entry_node = "process"
+entry_points = {"start": "process"}
+pause_nodes = []
+terminal_nodes = []  # Forever-alive
+
+# Module-level vars read by AgentRunner.load()
+conversation_mode = "continuous"
+identity_prompt = "You are a helpful agent."
+loop_config = {"max_iterations": 100, "max_tool_calls_per_turn": 20, "max_history_tokens": 32000}
+
+
+class MyAgent:
+    def __init__(self, config=None):
+        self.config = config or default_config
+        self.goal = goal
+        self.nodes = nodes
+        self.edges = edges
+        self.entry_node = entry_node  # "process" — autonomous entry
+        self.entry_points = entry_points
+        self.pause_nodes = pause_nodes
+        self.terminal_nodes = terminal_nodes
+        self._graph = None
+        self._agent_runtime = None
+        self._tool_registry = None
+        self._storage_path = None
+
+    def _build_graph(self):
+        return GraphSpec(
+            id="my-agent-graph",
+            goal_id=self.goal.id,
+            version="1.0.0",
+            entry_node=self.entry_node,
+            entry_points=self.entry_points,
+            terminal_nodes=self.terminal_nodes,
+            pause_nodes=self.pause_nodes,
+            nodes=self.nodes,
+            edges=self.edges,
+            default_model=self.config.model,
+            max_tokens=self.config.max_tokens,
+            loop_config=loop_config,
+            conversation_mode=conversation_mode,
+            identity_prompt=identity_prompt,
+        )
+
+    def _setup(self):
+        self._storage_path = Path.home() / ".hive" / "agents" / "my_agent"
+        self._storage_path.mkdir(parents=True, exist_ok=True)
+        self._tool_registry = ToolRegistry()
+        mcp_config = Path(__file__).parent / "mcp_servers.json"
+        if mcp_config.exists():
+            self._tool_registry.load_mcp_config(mcp_config)
+        llm = LiteLLMProvider(model=self.config.model, api_key=self.config.api_key, api_base=self.config.api_base)
+        tools = list(self._tool_registry.get_tools().values())
+        tool_executor = self._tool_registry.get_executor()
+        self._graph = self._build_graph()
+        self._agent_runtime = create_agent_runtime(
+            graph=self._graph, goal=self.goal, storage_path=self._storage_path,
+            entry_points=[EntryPointSpec(id="default", name="Default", entry_node=self.entry_node,
+                                         trigger_type="manual", isolation_level="shared")],
+            llm=llm, tools=tools, tool_executor=tool_executor,
+            checkpoint_config=CheckpointConfig(enabled=True, checkpoint_on_node_complete=True,
+                                                checkpoint_max_age_days=7, async_checkpoint=True),
+        )
+
+    async def start(self):
+        if self._agent_runtime is None:
+            self._setup()
+        if not self._agent_runtime.is_running:
+            await self._agent_runtime.start()
+
+    async def stop(self):
+        if self._agent_runtime and self._agent_runtime.is_running:
+            await self._agent_runtime.stop()
+        self._agent_runtime = None
+
+    async def trigger_and_wait(self, entry_point="default", input_data=None, timeout=None, session_state=None):
+        if self._agent_runtime is None:
+            raise RuntimeError("Agent not started. Call start() first.")
+        return await self._agent_runtime.trigger_and_wait(
+            entry_point_id=entry_point, input_data=input_data or {}, session_state=session_state)
+
+    async def run(self, context, session_state=None):
+        await self.start()
+        try:
+            result = await self.trigger_and_wait("default", context, session_state=session_state)
+            return result or ExecutionResult(success=False, error="Execution timeout")
+        finally:
+            await self.stop()
+
+    def info(self):
+        return {
+            "name": metadata.name, "version": metadata.version, "description": metadata.description,
+            "goal": {"name": self.goal.name, "description": self.goal.description},
+            "nodes": [n.id for n in self.nodes], "edges": [e.id for e in self.edges],
+            "entry_node": self.entry_node, "entry_points": self.entry_points,
+            "terminal_nodes": self.terminal_nodes,
+            "client_facing_nodes": [n.id for n in self.nodes if n.client_facing],
+        }
+
+    def validate(self):
+        """Validate graph wiring and entry-point contract."""
+        errors, warnings = [], []
+        node_ids = {n.id for n in self.nodes}
+        for e in self.edges:
+            if e.source not in node_ids:
+                errors.append(f"Edge {e.id}: source '{e.source}' not found")
+            if e.target not in node_ids:
+                errors.append(f"Edge {e.id}: target '{e.target}' not found")
+        if self.entry_node not in node_ids:
+            errors.append(f"Entry node '{self.entry_node}' not found")
+        for t in self.terminal_nodes:
+            if t not in node_ids:
+                errors.append(f"Terminal node '{t}' not found")
+
+        if not isinstance(self.entry_points, dict):
+            errors.append(
+                "Invalid entry_points: expected dict[str, str] like "
+                "{'start': '<entry-node-id>'}. "
+                f"Got {type(self.entry_points).__name__}. "
+                "Fix agent.py: set entry_points = {'start': '<entry-node-id>'}."
+            )
+        else:
+            if "start" not in self.entry_points:
+                errors.append(
+                    "entry_points must include 'start' mapped to entry_node. "
+                    "Example: {'start': '<entry-node-id>'}."
+                )
+            else:
+                start_node = self.entry_points.get("start")
+                if start_node != self.entry_node:
+                    errors.append(
+                        f"entry_points['start'] points to '{start_node}' "
+                        f"but entry_node is '{self.entry_node}'. Keep these aligned."
+                    )
+
+            for ep_id, nid in self.entry_points.items():
+                if not isinstance(ep_id, str):
+                    errors.append(
+                        f"Invalid entry_points key {ep_id!r} "
+                        f"({type(ep_id).__name__}). Entry point names must be strings."
+                    )
+                    continue
+                if not isinstance(nid, str):
+                    errors.append(
+                        f"Invalid entry_points['{ep_id}']={nid!r} "
+                        f"({type(nid).__name__}). Node ids must be strings."
+                    )
+                    continue
+                if nid not in node_ids:
+                    errors.append(
+                        f"Entry point '{ep_id}' references unknown node '{nid}'. "
+                        f"Known nodes: {sorted(node_ids)}"
+                    )
+
+        return {"valid": len(errors) == 0, "errors": errors, "warnings": warnings}
+
+
+default_agent = MyAgent()
+```
+
+## agent.py — Async Entry Points Variant
+
+When an agent needs timers, webhooks, or event-driven triggers, add
+`async_entry_points` and optionally `runtime_config` as module-level variables.
+These are IN ADDITION to the standard variables above.
+
+```python
+# Additional imports for async entry points
+from framework.graph.edge import GraphSpec, AsyncEntryPointSpec
+from framework.runtime.agent_runtime import (
+    AgentRuntime, AgentRuntimeConfig, create_agent_runtime,
+)
+
+# ... (goal, nodes, edges, entry_node, entry_points, etc. as above) ...
+
+# Async entry points — event-driven triggers
+async_entry_points = [
+    # Timer with cron: daily at 9am
+    AsyncEntryPointSpec(
+        id="daily-check",
+        name="Daily Check",
+        entry_node="process-node",
+        trigger_type="timer",
+        trigger_config={"cron": "0 9 * * *"},
+        isolation_level="shared",
+        max_concurrent=1,
+    ),
+    # Timer with fixed interval: every 20 minutes
+    AsyncEntryPointSpec(
+        id="scheduled-check",
+        name="Scheduled Check",
+        entry_node="process-node",
+        trigger_type="timer",
+        trigger_config={"interval_minutes": 20, "run_immediately": False},
+        isolation_level="shared",
+        max_concurrent=1,
+    ),
+    # Event: reacts to webhook events
+    AsyncEntryPointSpec(
+        id="webhook-event",
+        name="Webhook Event Handler",
+        entry_node="process-node",
+        trigger_type="event",
+        trigger_config={"event_types": ["webhook_received"]},
+        isolation_level="shared",
+        max_concurrent=10,
+    ),
+]
+
+# Webhook server config (only needed if using webhooks)
+runtime_config = AgentRuntimeConfig(
+    webhook_host="127.0.0.1",
+    webhook_port=8080,
+    webhook_routes=[
+        {
+            "source_id": "my-source",
+            "path": "/webhooks/my-source",
+            "methods": ["POST"],
+        },
+    ],
+)
+```
+
+**Key rules for async entry points:**
+- `async_entry_points` is a list of `AsyncEntryPointSpec` (NOT `EntryPointSpec`)
+- `runtime_config` is `AgentRuntimeConfig` (NOT `RuntimeConfig` from config.py)
+- Valid trigger_types: `timer`, `event`, `webhook`, `manual`, `api`
+- Valid isolation_levels: `isolated`, `shared`, `synchronized`
+- Timer trigger_config (cron): `{"cron": "0 9 * * *"}` — standard 5-field cron expression
+- Timer trigger_config (interval): `{"interval_minutes": float, "run_immediately": bool}`
+- Event trigger_config: `{"event_types": ["webhook_received"], "filter_stream": "...", "filter_node": "..."}`
+- Use `isolation_level="shared"` for async entry points that need to read
+  the primary session's memory (e.g., user-configured rules)
+- The `_build_graph()` method passes `async_entry_points` to GraphSpec
+- Reference: `exports/gmail_inbox_guardian/agent.py`
+
+## __init__.py
+
+**CRITICAL:** The runner imports the package (`__init__.py`) and reads ALL module-level
+variables via `getattr()`. Every variable defined in `agent.py` that the runner needs
+MUST be re-exported here. Missing exports cause silent failures (variables default to
+`None` or `{}`), leading to "must define goal, nodes, edges" errors or graph validation
+failures like "node X is unreachable".
+
+```python
+"""My Agent — description."""
+
+from .agent import (
+    MyAgent,
+    default_agent,
+    goal,
+    nodes,
+    edges,
+    entry_node,
+    entry_points,
+    pause_nodes,
+    terminal_nodes,
+    conversation_mode,
+    identity_prompt,
+    loop_config,
+)
+from .config import default_config, metadata
+
+__all__ = [
+    "MyAgent",
+    "default_agent",
+    "goal",
+    "nodes",
+    "edges",
+    "entry_node",
+    "entry_points",
+    "pause_nodes",
+    "terminal_nodes",
+    "conversation_mode",
+    "identity_prompt",
+    "loop_config",
+    "default_config",
+    "metadata",
+]
+```
+
+**If the agent uses async entry points**, also import and export:
+```python
+from .agent import (
+    ...,
+    async_entry_points,
+    runtime_config,  # Only if using webhooks
+)
+
+__all__ = [
+    ...,
+    "async_entry_points",
+    "runtime_config",
+]
+```
+
+## __main__.py
+
+```python
+"""CLI entry point for My Agent."""
+
+import asyncio, json, logging, sys
+import click
+from .agent import default_agent, MyAgent
+
+
+def setup_logging(verbose=False, debug=False):
+    if debug: level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+    elif verbose: level, fmt = logging.INFO, "%(message)s"
+    else: level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+
+
+@click.group()
+@click.version_option(version="1.0.0")
+def cli():
+    """My Agent — description."""
+    pass
+
+
+@cli.command()
+@click.option("--topic", "-t", required=True)
+@click.option("--verbose", "-v", is_flag=True)
+def run(topic, verbose):
+    """Execute the agent."""
+    setup_logging(verbose=verbose)
+    result = asyncio.run(default_agent.run({"topic": topic}))
+    click.echo(json.dumps({"success": result.success, "output": result.output}, indent=2, default=str))
+    sys.exit(0 if result.success else 1)
+
+
+@cli.command()
+def tui():
+    """Launch TUI dashboard."""
+    from pathlib import Path
+    from framework.tui.app import AdenTUI
+    from framework.llm import LiteLLMProvider
+    from framework.runner.tool_registry import ToolRegistry
+    from framework.runtime.agent_runtime import create_agent_runtime
+    from framework.runtime.execution_stream import EntryPointSpec
+
+    async def run_tui():
+        agent = MyAgent()
+        agent._tool_registry = ToolRegistry()
+        storage = Path.home() / ".hive" / "agents" / "my_agent"
+        storage.mkdir(parents=True, exist_ok=True)
+        mcp_cfg = Path(__file__).parent / "mcp_servers.json"
+        if mcp_cfg.exists(): agent._tool_registry.load_mcp_config(mcp_cfg)
+        llm = LiteLLMProvider(model=agent.config.model, api_key=agent.config.api_key, api_base=agent.config.api_base)
+        runtime = create_agent_runtime(
+            graph=agent._build_graph(), goal=agent.goal, storage_path=storage,
+            entry_points=[EntryPointSpec(id="start", name="Start", entry_node="process", trigger_type="manual", isolation_level="isolated")],
+            llm=llm, tools=list(agent._tool_registry.get_tools().values()), tool_executor=agent._tool_registry.get_executor())
+        await runtime.start()
+        try:
+            app = AdenTUI(runtime)
+            await app.run_async()
+        finally:
+            await runtime.stop()
+    asyncio.run(run_tui())
+
+
+@cli.command()
+def info():
+    """Show agent info."""
+    data = default_agent.info()
+    click.echo(f"Agent: {data['name']}\nVersion: {data['version']}\nDescription: {data['description']}")
+    click.echo(f"Nodes: {', '.join(data['nodes'])}\nClient-facing: {', '.join(data['client_facing_nodes'])}")
+
+
+@cli.command()
+def validate():
+    """Validate agent structure."""
+    v = default_agent.validate()
+    if v["valid"]: click.echo("Agent is valid")
+    else:
+        click.echo("Errors:")
+        for e in v["errors"]: click.echo(f"  {e}")
+    sys.exit(0 if v["valid"] else 1)
+
+
+if __name__ == "__main__":
+    cli()
+```
+
+## mcp_servers.json
+
+> **Auto-generated.** `initialize_and_build_agent` creates this file with hive-tools
+> as the default. Only edit manually to add additional MCP servers.
+
+```json
+{
+  "hive-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "mcp_server.py", "--stdio"],
+    "cwd": "../../tools",
+    "description": "Hive tools MCP server"
+  }
+}
+```
+
+**CRITICAL FORMAT RULES:**
+- NO `"mcpServers"` wrapper (flat dict, not nested)
+- `cwd` MUST be `"../../tools"` (relative from `exports/AGENT_NAME/` to `tools/`)
+- `command` MUST be `"uv"` with `"args": ["run", "python", ...]` (NOT bare `"python"`)
+
+## tests/conftest.py
+
+```python
+"""Test fixtures."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+_repo_root = Path(__file__).resolve().parents[3]
+for _p in ["exports", "core"]:
+    _path = str(_repo_root / _p)
+    if _path not in sys.path:
+        sys.path.insert(0, _path)
+
+AGENT_PATH = str(Path(__file__).resolve().parents[1])
+
+
+@pytest.fixture(scope="session")
+def agent_module():
+    """Import the agent package for structural validation."""
+    import importlib
+    return importlib.import_module(Path(AGENT_PATH).name)
+
+
+@pytest.fixture(scope="session")
+def runner_loaded():
+    """Load the agent through AgentRunner (structural only, no LLM needed)."""
+    from framework.runner.runner import AgentRunner
+    return AgentRunner.load(AGENT_PATH)
+```
+
+## entry_points Format
+
+MUST be: `{"start": "first-node-id"}`
+NOT: `{"first-node-id": ["input_keys"]}` (WRONG)
+NOT: `{"first-node-id"}` (WRONG — this is a set)

core/framework/agents/queen/reference/framework_guide.md

@@ -0,0 +1,322 @@
+# Hive Agent Framework — Condensed Reference
+
+## Architecture
+
+Agents are Python packages in `exports/`:
+```
+exports/my_agent/
+├── __init__.py          # MUST re-export ALL module-level vars from agent.py
+├── __main__.py          # CLI (run, tui, info, validate, shell)
+├── agent.py             # Graph construction (goal, edges, agent class)
+├── config.py            # Runtime config
+├── nodes/__init__.py    # Node definitions (NodeSpec)
+├── mcp_servers.json     # MCP tool server config
+└── tests/               # pytest tests
+```
+
+## Agent Loading Contract
+
+`AgentRunner.load()` imports the package (`__init__.py`) and reads these
+module-level variables via `getattr()`:
+
+| Variable | Required | Default if missing | Consequence |
+|----------|----------|--------------------|-------------|
+| `goal` | YES | `None` | **FATAL** — "must define goal, nodes, edges" |
+| `nodes` | YES | `None` | **FATAL** — same error |
+| `edges` | YES | `None` | **FATAL** — same error |
+| `entry_node` | no | `nodes[0].id` | Probably wrong node |
+| `entry_points` | no | `{}` | **Nodes unreachable** — validation fails |
+| `terminal_nodes` | **YES** | `[]` | **FATAL** — graph must have at least one terminal node |
+| `pause_nodes` | no | `[]` | OK |
+| `conversation_mode` | no | not passed | Isolated mode (no context carryover) |
+| `identity_prompt` | no | not passed | No agent-level identity |
+| `loop_config` | no | `{}` | No iteration limits |
+| `async_entry_points` | no | `[]` | No async triggers (timers, webhooks, events) |
+| `runtime_config` | no | `None` | No webhook server |
+
+**CRITICAL:** `__init__.py` MUST import and re-export ALL of these from
+`agent.py`. Missing exports silently fall back to defaults, causing
+hard-to-debug failures.
+
+**Why `default_agent.validate()` is NOT sufficient:**
+`validate()` checks the agent CLASS's internal graph (self.nodes, self.edges).
+These are always correct because the constructor references agent.py's module
+vars directly. But `AgentRunner.load()` reads from the PACKAGE (`__init__.py`),
+not the class. So `validate()` passes while `AgentRunner.load()` fails.
+Always test with `AgentRunner.load("exports/{name}")` — this is the same
+code path the TUI and `hive run` use.
+
+## Goal
+
+Defines success criteria and constraints:
+```python
+goal = Goal(
+    id="kebab-case-id",
+    name="Display Name",
+    description="What the agent does",
+    success_criteria=[
+        SuccessCriterion(id="sc-id", description="...", metric="...", target="...", weight=0.25),
+    ],
+    constraints=[
+        Constraint(id="c-id", description="...", constraint_type="hard", category="quality"),
+    ],
+)
+```
+- 3-5 success criteria, weights sum to 1.0
+- 1-5 constraints (hard/soft, categories: quality, accuracy, interaction, functional)
+
+## NodeSpec Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| id | str | required | kebab-case identifier |
+| name | str | required | Display name |
+| description | str | required | What the node does |
+| node_type | str | required | `"event_loop"` or `"gcu"` (browser automation — see GCU Guide appendix) |
+| input_keys | list[str] | required | Memory keys this node reads |
+| output_keys | list[str] | required | Memory keys this node writes via set_output |
+| system_prompt | str | "" | LLM instructions |
+| tools | list[str] | [] | Tool names from MCP servers |
+| client_facing | bool | False | If True, streams to user and blocks for input |
+| nullable_output_keys | list[str] | [] | Keys that may remain unset |
+| max_node_visits | int | 0 | 0=unlimited (default); >1 for one-shot feedback loops |
+| max_retries | int | 3 | Retries on failure |
+| success_criteria | str | "" | Natural language for judge evaluation |
+
+## EdgeSpec Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| id | str | kebab-case identifier |
+| source | str | Source node ID |
+| target | str | Target node ID |
+| condition | EdgeCondition | ON_SUCCESS, ON_FAILURE, ALWAYS, CONDITIONAL |
+| condition_expr | str | Python expression evaluated against memory (for CONDITIONAL) |
+| priority | int | Positive=forward (evaluated first), negative=feedback (loop-back) |
+
+## Key Patterns
+
+### STEP 1/STEP 2 (Client-Facing Nodes)
+```
+**STEP 1 — Respond to the user (text only, NO tool calls):**
+[Present information, ask questions]
+
+**STEP 2 — After the user responds, call set_output:**
+- set_output("key", "value based on user response")
+```
+This prevents premature set_output before user interaction.
+
+### Fewer, Richer Nodes (CRITICAL)
+
+**Hard limit: 3-6 nodes for most agents.** Never exceed 6 unless the user
+explicitly requests a complex multi-phase pipeline.
+
+Each node boundary serializes outputs to shared memory and **destroys** all
+in-context information: tool call results, intermediate reasoning, conversation
+history. A research node that searches, fetches, and analyzes in ONE node keeps
+all source material in its conversation context. Split across 3 nodes, each
+downstream node only sees the serialized summary string.
+
+**Decision framework — merge unless ANY of these apply:**
+1. **Client-facing boundary** — Autonomous and client-facing work MUST be
+   separate nodes (different interaction models)
+2. **Disjoint tool sets** — If tools are fundamentally different (e.g., web
+   search vs database), separate nodes make sense
+3. **Parallel execution** — Fan-out branches must be separate nodes
+
+**Red flags that you have too many nodes:**
+- A node with 0 tools (pure LLM reasoning) → merge into predecessor/successor
+- A node that sets only 1 trivial output → collapse into predecessor
+- Multiple consecutive autonomous nodes → combine into one rich node
+- A "report" node that presents analysis → merge into the client-facing node
+- A "confirm" or "schedule" node that doesn't call any external service → remove
+
+**Typical agent structure (2 nodes):**
+```
+process (autonomous) ←→ review (client-facing)
+```
+The queen owns intake — she gathers requirements from the user, then
+passes structured input via `run_agent_with_input(task)`. When building
+the agent, design the entry node's `input_keys` to match what the queen
+will provide at run time. Worker agents should NOT have a client-facing
+intake node. Client-facing nodes are for mid-execution review/approval only.
+
+For simpler agents, just 1 autonomous node:
+```
+process (autonomous) — loops back to itself
+```
+
+### nullable_output_keys
+For inputs that only arrive on certain edges:
+```python
+research_node = NodeSpec(
+    input_keys=["brief", "feedback"],
+    nullable_output_keys=["feedback"],  # Only present on feedback edge
+    max_node_visits=3,
+)
+```
+
+### Mutually Exclusive Outputs
+For routing decisions:
+```python
+review_node = NodeSpec(
+    output_keys=["approved", "feedback"],
+    nullable_output_keys=["approved", "feedback"],  # Node sets one or the other
+)
+```
+
+### Continuous Loop Pattern
+Mark the primary event_loop node as terminal: `terminal_nodes=["process"]`.
+The node has `output_keys` and can complete when the agent finishes its work.
+Use `conversation_mode="continuous"` to preserve context across transitions.
+
+### set_output
+- Synthetic tool injected by framework
+- Call separately from real tool calls (separate turn)
+- `set_output("key", "value")` stores to shared memory
+
+## Edge Conditions
+
+| Condition | When |
+|-----------|------|
+| ON_SUCCESS | Node completed successfully |
+| ON_FAILURE | Node failed |
+| ALWAYS | Unconditional |
+| CONDITIONAL | condition_expr evaluates to True against memory |
+
+condition_expr examples:
+- `"needs_more_research == True"`
+- `"str(next_action).lower() == 'new_agent'"`
+- `"feedback is not None"`
+
+## Graph Lifecycle
+
+| Pattern | terminal_nodes | When |
+|---------|---------------|------|
+| **Continuous loop** | `["node-with-output-keys"]` | **DEFAULT for all agents** |
+| Linear | `["last-node"]` | One-shot/batch agents |
+
+**Every graph must have at least one terminal node.** Terminal nodes
+define where execution ends. For interactive agents that loop continuously,
+mark the primary event_loop node as terminal (it has `output_keys` and can
+complete at any point). The framework default for `max_node_visits` is 0
+(unbounded), so nodes work correctly in continuous loops without explicit
+override. Only set `max_node_visits > 0` in one-shot agents with feedback loops.
+Every node must have at least one outgoing edge — no dead ends.
+
+## Continuous Conversation Mode
+
+`conversation_mode` has ONLY two valid states:
+- `"continuous"` — recommended for interactive agents
+- Omit entirely — isolated per-node conversations (each node starts fresh)
+
+**INVALID values** (do NOT use): `"client_facing"`, `"interactive"`,
+`"adaptive"`, `"shared"`. These do not exist in the framework.
+
+When `conversation_mode="continuous"`:
+- Same conversation thread carries across node transitions
+- Layered system prompts: identity (agent-level) + narrative + focus (per-node)
+- Transition markers inserted at boundaries
+- Compaction happens opportunistically at phase transitions
+
+## loop_config
+
+Only three valid keys:
+```python
+loop_config = {
+    "max_iterations": 100,          # Max LLM turns per node visit
+    "max_tool_calls_per_turn": 20,  # Max tool calls per LLM response
+    "max_history_tokens": 32000,    # Triggers conversation compaction
+}
+```
+**INVALID keys** (do NOT use): `"strategy"`, `"mode"`, `"timeout"`,
+`"temperature"`. These are silently ignored or cause errors.
+
+## Data Tools (Spillover)
+
+For large data that exceeds context:
+- `save_data(filename, data)` — Write to session data dir
+- `load_data(filename, offset, limit)` — Read with pagination
+- `list_data_files()` — List files
+- `serve_file_to_user(filename, label)` — Clickable file:// URI
+
+`data_dir` is auto-injected by framework — LLM never sees it.
+
+## Fan-Out / Fan-In
+
+Multiple ON_SUCCESS edges from same source → parallel execution via asyncio.gather().
+- Parallel nodes must have disjoint output_keys
+- Only one branch may have client_facing nodes
+- Fan-in node gets all outputs in shared memory
+
+## Judge System
+
+- **Implicit** (default): ACCEPTs when LLM finishes with no tool calls and all required outputs set
+- **SchemaJudge**: Validates against Pydantic model
+- **Custom**: Implement `evaluate(context) -> JudgeVerdict`
+
+Judge is the SOLE acceptance mechanism — no ad-hoc framework gating.
+
+## Async Entry Points (Webhooks, Timers, Events)
+
+For agents that react to external events, use `AsyncEntryPointSpec`:
+
+```python
+from framework.graph.edge import AsyncEntryPointSpec
+from framework.runtime.agent_runtime import AgentRuntimeConfig
+
+# Timer trigger (cron or interval)
+async_entry_points = [
+    AsyncEntryPointSpec(
+        id="daily-check",
+        name="Daily Check",
+        entry_node="process",
+        trigger_type="timer",
+        trigger_config={"cron": "0 9 * * *"},  # daily at 9am
+        isolation_level="shared",
+    )
+]
+
+# Webhook server (optional)
+runtime_config = AgentRuntimeConfig(
+    webhook_host="127.0.0.1",
+    webhook_port=8080,
+    webhook_routes=[{"source_id": "gmail", "path": "/webhooks/gmail", "methods": ["POST"]}],
+)
+```
+
+### Key Fields
+- `trigger_type`: `"timer"`, `"event"`, `"webhook"`, `"manual"`
+- `trigger_config`: `{"cron": "0 9 * * *"}` or `{"interval_minutes": 20}`
+- `isolation_level`: `"shared"` (recommended), `"isolated"`, `"synchronized"`
+- `event_types`: For event triggers, e.g., `["webhook_received"]`
+
+### Exports Required
+Both `async_entry_points` and `runtime_config` must be exported from `__init__.py`.
+
+See `exports/gmail_inbox_guardian/agent.py` for complete example.
+
+## Tool Discovery
+
+Do NOT rely on a static tool list — it will be outdated. Always call
+`list_agent_tools()` with NO arguments first to see ALL available tools.
+Only use `group=` or `output_schema=` as follow-up calls after seeing the
+full list.
+
+```
+list_agent_tools()                            # ALWAYS call this first
+list_agent_tools(group="gmail", output_schema="full")  # then drill into a category
+list_agent_tools("exports/my_agent/mcp_servers.json")  # specific agent's tools
+```
+
+After building, run `validate_agent_package("{name}")` to check everything at once.
+
+Common tool categories (verify via list_agent_tools):
+- **Web**: search, scrape, PDF
+- **Data**: save/load/append/list data files, serve to user
+- **File**: view, write, replace, diff, list, grep
+- **Communication**: email, gmail, slack, telegram
+- **CRM**: hubspot, apollo, calcom
+- **GitHub**: stargazers, user profiles, repos
+- **Vision**: image analysis
+- **Time**: current time

core/framework/agents/queen/reference/gcu_guide.md

@@ -0,0 +1,119 @@
+# GCU Browser Automation Guide
+
+## When to Use GCU Nodes
+
+Use `node_type="gcu"` when:
+- The user's workflow requires **navigating real websites** (scraping, form-filling, social media interaction, testing web UIs)
+- The task involves **dynamic/JS-rendered pages** that `web_scrape` cannot handle (SPAs, infinite scroll, login-gated content)
+- The agent needs to **interact with a website** — clicking, typing, scrolling, selecting, uploading files
+
+Do NOT use GCU for:
+- Static content that `web_scrape` handles fine
+- API-accessible data (use the API directly)
+- PDF/file processing
+- Anything that doesn't require a browser UI
+
+## What GCU Nodes Are
+
+- `node_type="gcu"` — a declarative enhancement over `event_loop`
+- Framework auto-prepends browser best-practices system prompt
+- Framework auto-includes all 31 browser tools from `gcu-tools` MCP server
+- Same underlying `EventLoopNode` class — no new imports needed
+- `tools=[]` is correct — tools are auto-populated at runtime
+
+## GCU Architecture Pattern  
+
+GCU nodes are **subagents** — invoked via `delegate_to_sub_agent()`, not connected via edges.
+
+- Primary nodes (`event_loop`, client-facing) orchestrate; GCU nodes do browser work
+- Parent node declares `sub_agents=["gcu-node-id"]` and calls `delegate_to_sub_agent(agent_id="gcu-node-id", task="...")`
+- GCU nodes set `max_node_visits=1` (single execution per delegation), `client_facing=False`
+- GCU nodes use `output_keys=["result"]` and return structured JSON via `set_output("result", ...)`
+
+## GCU Node Definition Template
+
+```python
+gcu_browser_node = NodeSpec(
+    id="gcu-browser-worker",
+    name="Browser Worker",
+    description="Browser subagent that does X.",
+    node_type="gcu",
+    client_facing=False,
+    max_node_visits=1,
+    input_keys=[],
+    output_keys=["result"],
+    tools=[],  # Auto-populated with all browser tools
+    system_prompt="""\
+You are a browser agent. Your job: [specific task].
+
+## Workflow
+1. browser_start (only if no browser is running yet)
+2. browser_open(url=TARGET_URL) — note the returned targetId
+3. browser_snapshot to read the page
+4. [task-specific steps]
+5. set_output("result", JSON)
+
+## Output format
+set_output("result", JSON) with:
+- [field]: [type and description]
+""",
+)
+```
+
+## Parent Node Template (orchestrating GCU subagents)
+
+```python
+orchestrator_node = NodeSpec(
+    id="orchestrator",
+    ...
+    node_type="event_loop",
+    sub_agents=["gcu-browser-worker"],
+    system_prompt="""\
+...
+delegate_to_sub_agent(
+    agent_id="gcu-browser-worker",
+    task="Navigate to [URL]. Do [specific task]. Return JSON with [fields]."
+)
+...
+""",
+    tools=[],  # Orchestrator doesn't need browser tools
+)
+```
+
+## mcp_servers.json with GCU
+
+```json
+{
+  "hive-tools": { ... },
+  "gcu-tools": {
+    "transport": "stdio",
+    "command": "uv",
+    "args": ["run", "python", "-m", "gcu.server", "--stdio"],
+    "cwd": "../../tools",
+    "description": "GCU tools for browser automation"
+  }
+}
+```
+
+Note: `gcu-tools` is auto-added if any node uses `node_type="gcu"`, but including it explicitly is fine.
+
+## GCU System Prompt Best Practices
+
+Key rules to bake into GCU node prompts:
+
+- Prefer `browser_snapshot` over `browser_get_text("body")` — compact accessibility tree vs 100KB+ raw HTML
+- Always `browser_wait` after navigation
+- Use large scroll amounts (~2000-5000) for lazy-loaded content
+- For spillover files, use `run_command` with grep, not `read_file`
+- If auth wall detected, report immediately — don't attempt login
+- Keep tool calls per turn ≤10
+- Tab isolation: when browser is already running, use `browser_open(background=true)` and pass `target_id` to every call
+
+## GCU Anti-Patterns
+
+- Using `browser_screenshot` to read text (use `browser_snapshot`)
+- Re-navigating after scrolling (resets scroll position)
+- Attempting login on auth walls
+- Forgetting `target_id` in multi-tab scenarios
+- Putting browser tools directly on `event_loop` nodes instead of using GCU subagent pattern
+- Making GCU nodes `client_facing=True` (they should be autonomous subagents)

core/framework/agents/queen/reference/queen_memory.md

@@ -0,0 +1,63 @@
+# Queen Memory — File System Structure
+
+```
+~/.hive/
+├── queen/
+│   ├── MEMORY.md                          ← Semantic memory
+│   ├── memories/
+│   │   ├── MEMORY-2026-03-09.md           ← Episodic memory (today)
+│   │   ├── MEMORY-2026-03-08.md
+│   │   └── ...
+│   └── session/
+│       └── {session_id}/                  ← One dir per session (or resumed-from session)
+│           ├── conversations/
+│           │   ├── parts/
+│           │   │   ├── 00001.json         ← One file per message (role, content, tool_calls)
+│           │   │   ├── 00002.json
+│           │   │   └── ...
+│           │   └── spillover/
+│           │       ├── conversation_1.md  ← Compacted old conversation segments
+│           │       ├── conversation_2.md
+│           │       └── ...
+│           └── data/
+│               ├── adapt.md              ← Working memory (session-scoped)
+│               ├── web_search_1.txt      ← Spillover: large tool results
+│               ├── web_search_2.txt
+│               └── ...
+```
+
+---
+
+## The three memory tiers
+
+| File | Tier | Written by | Read at |
+|---|---|---|---|
+| `MEMORY.md` | Semantic | Consolidation LLM (auto, post-session) | Session start (injected into system prompt) |
+| `memories/MEMORY-YYYY-MM-DD.md` | Episodic | Queen via `write_to_diary` tool + consolidation LLM | Session start (today's file injected) |
+| `data/adapt.md` | Working | Queen via `update_session_notes` tool | Every turn (inlined in system prompt) |
+
+---
+
+## Session directory naming
+
+The session directory name is **`queen_resume_from`** when a cold-restore resumes an existing
+session, otherwise the new **`session_id`**. This means resumed sessions accumulate all messages
+in the original directory rather than fragmenting across multiple folders.
+
+---
+
+## Consolidation
+
+`consolidate_queen_memory()` runs every **5 minutes** in the background and once more at session
+end. It reads:
+
+1. `conversations/parts/*.json` — full message history (user + assistant turns; tool results skipped)
+2. `data/adapt.md` — current working notes
+
+It then makes two LLM writes:
+
+- Rewrites `MEMORY.md` in place (semantic memory — queen never touches this herself)
+- Appends a timestamped prose entry to today's `memories/MEMORY-YYYY-MM-DD.md`
+
+If the combined transcript exceeds ~200 K characters it is recursively binary-compacted via the
+LLM before being sent to the consolidation model (mirrors `EventLoopNode._llm_compact`).

core/framework/agents/queen/tests/conftest.py

@@ -0,0 +1,31 @@
+"""Test fixtures for Queen agent."""
+
+import sys
+from pathlib import Path
+
+import pytest
+import pytest_asyncio
+
+_repo_root = Path(__file__).resolve().parents[3]
+for _p in ["exports", "core"]:
+    _path = str(_repo_root / _p)
+    if _path not in sys.path:
+        sys.path.insert(0, _path)
+
+AGENT_PATH = str(Path(__file__).resolve().parents[1])
+
+
+@pytest.fixture(scope="session")
+def mock_mode():
+    return True
+
+
+@pytest_asyncio.fixture(scope="session")
+async def runner(tmp_path_factory, mock_mode):
+    from framework.runner.runner import AgentRunner
+
+    storage = tmp_path_factory.mktemp("agent_storage")
+    r = AgentRunner.load(AGENT_PATH, mock_mode=mock_mode, storage_path=storage)
+    r._setup()
+    yield r
+    await r.cleanup_async()

core/framework/agents/queen/ticket_receiver.py

@@ -0,0 +1,27 @@
+"""Queen's ticket receiver entry point.
+
+When the Worker Health Judge emits a WORKER_ESCALATION_TICKET event on the
+shared EventBus, this entry point fires and routes to the ``ticket_triage``
+node, where the Queen deliberates and decides whether to notify the operator.
+
+Isolation level is ``isolated`` — the queen's triage memory is kept separate
+from the worker's shared memory. Each ticket triage runs in its own context.
+"""
+
+from __future__ import annotations
+
+from framework.graph.edge import AsyncEntryPointSpec
+
+TICKET_RECEIVER_ENTRY_POINT = AsyncEntryPointSpec(
+    id="ticket_receiver",
+    name="Worker Escalation Ticket Receiver",
+    entry_node="ticket_triage",
+    trigger_type="event",
+    trigger_config={
+        "event_types": ["worker_escalation_ticket"],
+        # Do not fire on our own graph's events (prevents loops if queen
+        # somehow emits a worker_escalation_ticket for herself)
+        "exclude_own_graph": True,
+    },
+    isolation_level="isolated",
+)

core/framework/builder/__init__.py

@@ -1,21 +1,7 @@
 """Builder interface for analyzing and building agents."""
 
 from framework.builder.query import BuilderQuery
-from framework.builder.workflow import (
-    BuildPhase,
-    BuildSession,
-    GraphBuilder,
-    TestCase,
-    TestResult,
-    ValidationResult,
-)
 
 __all__ = [
     "BuilderQuery",
-    "GraphBuilder",
-    "BuildSession",
-    "BuildPhase",
-    "ValidationResult",
-    "TestCase",
-    "TestResult",
 ]

core/framework/builder/workflow.py

@@ -1,807 +0,0 @@
-"""
-GraphBuilder Workflow - Enforced incremental building with HITL approval.
-
-The build process:
-1. Define Goal → APPROVE
-2. Add Node → VALIDATE → TEST → APPROVE
-3. Add Edge → VALIDATE → TEST → APPROVE
-4. Repeat until graph is complete
-5. Final integration test → APPROVE
-6. Export
-
-Each step requires validation and human approval before proceeding.
-You cannot skip steps or bypass validation.
-"""
-
-from collections.abc import Callable
-from datetime import datetime
-from enum import StrEnum
-from pathlib import Path
-from typing import Any
-
-from pydantic import BaseModel, Field
-
-from framework.graph.edge import EdgeCondition, EdgeSpec, GraphSpec
-from framework.graph.goal import Goal
-from framework.graph.node import NodeSpec
-
-
-class BuildPhase(StrEnum):
-    """Current phase of the build process."""
-
-    INIT = "init"  # Just started
-    GOAL_DRAFT = "goal_draft"  # Drafting goal
-    GOAL_APPROVED = "goal_approved"  # Goal approved
-    ADDING_NODES = "adding_nodes"  # Adding nodes
-    ADDING_EDGES = "adding_edges"  # Adding edges
-    TESTING = "testing"  # Running tests
-    APPROVED = "approved"  # Fully approved
-    EXPORTED = "exported"  # Exported to file
-
-
-class ValidationResult(BaseModel):
-    """Result of a validation check."""
-
-    valid: bool
-    errors: list[str] = Field(default_factory=list)
-    warnings: list[str] = Field(default_factory=list)
-    suggestions: list[str] = Field(default_factory=list)
-
-
-class TestCase(BaseModel):
-    """A test case for validating agent behavior."""
-
-    id: str
-    description: str
-    input: dict[str, Any]
-    expected_output: Any = None  # None means just check it doesn't error
-    expected_contains: str | None = None
-
-
-class TestResult(BaseModel):
-    """Result of running a test case."""
-
-    test_id: str
-    passed: bool
-    actual_output: Any = None
-    error: str | None = None
-    execution_path: list[str] = Field(default_factory=list)
-
-
-class BuildSession(BaseModel):
-    """
-    Persistent build session state.
-
-    Saved after each approved step so you can resume later.
-    """
-
-    id: str
-    name: str
-    phase: BuildPhase = BuildPhase.INIT
-    created_at: datetime = Field(default_factory=datetime.now)
-    updated_at: datetime = Field(default_factory=datetime.now)
-
-    # The artifacts being built
-    goal: Goal | None = None
-    nodes: list[NodeSpec] = Field(default_factory=list)
-    edges: list[EdgeSpec] = Field(default_factory=list)
-
-    # Test cases
-    test_cases: list[TestCase] = Field(default_factory=list)
-    test_results: list[TestResult] = Field(default_factory=list)
-
-    # Approval history
-    approvals: list[dict[str, Any]] = Field(default_factory=list)
-
-    # Tools (stored as dicts for serialization)
-    tools: list[dict[str, Any]] = Field(default_factory=list)
-
-    model_config = {"extra": "allow"}
-
-
-class GraphBuilder:
-    """
-    Enforced incremental graph building with HITL approval.
-
-    Usage:
-        builder = GraphBuilder("my-agent")
-
-        # Step 1: Define and approve goal
-        builder.set_goal(goal)
-        builder.validate()  # Must pass
-        builder.approve("Goal looks good")  # Human approval required
-
-        # Step 2: Add nodes one by one
-        builder.add_node(node_spec)
-        builder.validate()  # Must pass
-        builder.test(test_case)  # Must pass
-        builder.approve("Node works")
-
-        # Step 3: Add edges
-        builder.add_edge(edge_spec)
-        builder.validate()
-        builder.approve("Edge correct")
-
-        # Step 4: Final approval
-        builder.run_all_tests()
-        builder.final_approve("Ready for production")
-
-        # Step 5: Export
-        graph = builder.export()
-    """
-
-    def __init__(
-        self,
-        name: str,
-        storage_path: Path | str | None = None,
-        session_id: str | None = None,
-    ):
-        self.storage_path = Path(storage_path) if storage_path else Path.home() / ".core" / "builds"
-        self.storage_path.mkdir(parents=True, exist_ok=True)
-
-        if session_id:
-            self.session = self._load_session(session_id)
-        else:
-            self.session = BuildSession(
-                id=f"build_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
-                name=name,
-            )
-
-        self._pending_validation: ValidationResult | None = None
-
-    # =========================================================================
-    # PHASE 1: GOAL
-    # =========================================================================
-
-    def set_goal(self, goal: Goal) -> ValidationResult:
-        """
-        Set the goal for this agent.
-
-        Returns validation result. Must call approve() after validation passes.
-        """
-        self._require_phase([BuildPhase.INIT, BuildPhase.GOAL_DRAFT])
-
-        self.session.goal = goal
-        self.session.phase = BuildPhase.GOAL_DRAFT
-
-        validation = self._validate_goal(goal)
-        self._pending_validation = validation
-        self._save_session()
-
-        return validation
-
-    def _validate_goal(self, goal: Goal) -> ValidationResult:
-        """Validate a goal definition."""
-        errors = []
-        warnings = []
-        suggestions = []
-
-        if not goal.id:
-            errors.append("Goal must have an id")
-        if not goal.name:
-            errors.append("Goal must have a name")
-        if not goal.description:
-            errors.append("Goal must have a description")
-
-        if not goal.success_criteria:
-            errors.append("Goal must have at least one success criterion")
-        else:
-            for sc in goal.success_criteria:
-                if not sc.description:
-                    errors.append(f"Success criterion '{sc.id}' needs a description")
-
-        if not goal.constraints:
-            warnings.append("Consider adding constraints to define boundaries")
-
-        if not goal.required_capabilities:
-            suggestions.append("Specify required_capabilities (e.g., ['llm', 'tools'])")
-
-        return ValidationResult(
-            valid=len(errors) == 0,
-            errors=errors,
-            warnings=warnings,
-            suggestions=suggestions,
-        )
-
-    # =========================================================================
-    # PHASE 2: NODES
-    # =========================================================================
-
-    def add_node(self, node: NodeSpec) -> ValidationResult:
-        """
-        Add a node to the graph.
-
-        Returns validation result. Must call approve() after validation passes.
-        """
-        self._require_phase([BuildPhase.GOAL_APPROVED, BuildPhase.ADDING_NODES])
-
-        # Check for duplicate
-        if any(n.id == node.id for n in self.session.nodes):
-            return ValidationResult(
-                valid=False,
-                errors=[f"Node with id '{node.id}' already exists"],
-            )
-
-        self.session.nodes.append(node)
-        self.session.phase = BuildPhase.ADDING_NODES
-
-        validation = self._validate_node(node)
-        self._pending_validation = validation
-        self._save_session()
-
-        return validation
-
-    def _validate_node(self, node: NodeSpec) -> ValidationResult:
-        """Validate a node definition."""
-        errors = []
-        warnings = []
-        suggestions = []
-
-        if not node.id:
-            errors.append("Node must have an id")
-        if not node.name:
-            errors.append("Node must have a name")
-        if not node.description:
-            warnings.append(f"Node '{node.id}' should have a description")
-
-        # Type-specific validation
-        if node.node_type == "llm_tool_use":
-            if not node.tools:
-                errors.append(f"LLM tool node '{node.id}' must specify tools")
-            if not node.system_prompt:
-                warnings.append(f"LLM node '{node.id}' should have a system_prompt")
-
-        if node.node_type == "router":
-            if not node.routes:
-                errors.append(f"Router node '{node.id}' must specify routes")
-
-        if node.node_type == "function":
-            if not node.function:
-                errors.append(f"Function node '{node.id}' must specify function name")
-
-        # Check input/output keys
-        if not node.input_keys:
-            suggestions.append(f"Consider specifying input_keys for '{node.id}'")
-        if not node.output_keys:
-            suggestions.append(f"Consider specifying output_keys for '{node.id}'")
-
-        return ValidationResult(
-            valid=len(errors) == 0,
-            errors=errors,
-            warnings=warnings,
-            suggestions=suggestions,
-        )
-
-    def update_node(self, node_id: str, **updates) -> ValidationResult:
-        """Update an existing node."""
-        self._require_phase([BuildPhase.ADDING_NODES])
-
-        for i, node in enumerate(self.session.nodes):
-            if node.id == node_id:
-                node_dict = node.model_dump()
-                node_dict.update(updates)
-                updated_node = NodeSpec(**node_dict)
-                self.session.nodes[i] = updated_node
-
-                validation = self._validate_node(updated_node)
-                self._pending_validation = validation
-                self._save_session()
-                return validation
-
-        return ValidationResult(valid=False, errors=[f"Node '{node_id}' not found"])
-
-    def remove_node(self, node_id: str) -> ValidationResult:
-        """Remove a node (only if no edges reference it)."""
-        self._require_phase([BuildPhase.ADDING_NODES])
-
-        # Check for edge references
-        for edge in self.session.edges:
-            if edge.source == node_id or edge.target == node_id:
-                return ValidationResult(
-                    valid=False,
-                    errors=[f"Cannot remove node '{node_id}': referenced by edge '{edge.id}'"],
-                )
-
-        self.session.nodes = [n for n in self.session.nodes if n.id != node_id]
-        self._save_session()
-
-        return ValidationResult(valid=True)
-
-    # =========================================================================
-    # PHASE 3: EDGES
-    # =========================================================================
-
-    def add_edge(self, edge: EdgeSpec) -> ValidationResult:
-        """
-        Add an edge to the graph.
-
-        Returns validation result. Must call approve() after validation passes.
-        """
-        self._require_phase([BuildPhase.ADDING_NODES, BuildPhase.ADDING_EDGES])
-
-        # Check for duplicate
-        if any(e.id == edge.id for e in self.session.edges):
-            return ValidationResult(
-                valid=False,
-                errors=[f"Edge with id '{edge.id}' already exists"],
-            )
-
-        self.session.edges.append(edge)
-        self.session.phase = BuildPhase.ADDING_EDGES
-
-        validation = self._validate_edge(edge)
-        self._pending_validation = validation
-        self._save_session()
-
-        return validation
-
-    def _validate_edge(self, edge: EdgeSpec) -> ValidationResult:
-        """Validate an edge definition."""
-        errors = []
-        warnings = []
-
-        if not edge.id:
-            errors.append("Edge must have an id")
-
-        # Check source exists
-        if not any(n.id == edge.source for n in self.session.nodes):
-            errors.append(f"Edge source '{edge.source}' not found in nodes")
-
-        # Check target exists
-        if not any(n.id == edge.target for n in self.session.nodes):
-            errors.append(f"Edge target '{edge.target}' not found in nodes")
-
-        # Warn about conditional edges without expressions
-        if edge.condition == EdgeCondition.CONDITIONAL and not edge.condition_expr:
-            warnings.append(f"Conditional edge '{edge.id}' has no condition_expr")
-
-        return ValidationResult(
-            valid=len(errors) == 0,
-            errors=errors,
-            warnings=warnings,
-        )
-
-    # =========================================================================
-    # VALIDATION & TESTING
-    # =========================================================================
-
-    def validate(self) -> ValidationResult:
-        """Validate the entire current graph state."""
-        errors = []
-        warnings = []
-
-        # Must have a goal
-        if not self.session.goal:
-            errors.append("No goal defined")
-            return ValidationResult(valid=False, errors=errors)
-
-        # Must have at least one node
-        if not self.session.nodes:
-            errors.append("No nodes defined")
-
-        # Check for entry node
-        entry_candidates = []
-        for node in self.session.nodes:
-            # A node is an entry candidate if no edges point to it
-            if not any(e.target == node.id for e in self.session.edges):
-                entry_candidates.append(node.id)
-
-        if len(entry_candidates) == 0 and self.session.nodes:
-            errors.append("No entry node found (all nodes have incoming edges)")
-        elif len(entry_candidates) > 1:
-            warnings.append(f"Multiple entry candidates: {entry_candidates}. Specify one.")
-
-        # Check for terminal nodes
-        terminal_candidates = []
-        for node in self.session.nodes:
-            if not any(e.source == node.id for e in self.session.edges):
-                terminal_candidates.append(node.id)
-
-        if not terminal_candidates and self.session.nodes:
-            warnings.append("No terminal nodes found (all nodes have outgoing edges)")
-
-        # Check reachability
-        if entry_candidates and self.session.nodes:
-            reachable = self._compute_reachable(entry_candidates[0])
-            unreachable = [n.id for n in self.session.nodes if n.id not in reachable]
-            if unreachable:
-                errors.append(f"Unreachable nodes: {unreachable}")
-
-        validation = ValidationResult(
-            valid=len(errors) == 0,
-            errors=errors,
-            warnings=warnings,
-        )
-        self._pending_validation = validation
-        return validation
-
-    def _compute_reachable(self, start: str) -> set[str]:
-        """Compute all nodes reachable from start."""
-        reachable = set()
-        to_visit = [start]
-
-        while to_visit:
-            current = to_visit.pop()
-            if current in reachable:
-                continue
-            reachable.add(current)
-
-            for edge in self.session.edges:
-                if edge.source == current:
-                    to_visit.append(edge.target)
-
-            # Also follow router routes
-            for node in self.session.nodes:
-                if node.id == current and node.routes:
-                    for target in node.routes.values():
-                        to_visit.append(target)
-
-        return reachable
-
-    def add_test(self, test: TestCase) -> None:
-        """Add a test case."""
-        self.session.test_cases.append(test)
-        self._save_session()
-
-    def run_test(
-        self,
-        test: TestCase,
-        executor_factory: Callable,
-    ) -> TestResult:
-        """
-        Run a single test case.
-
-        executor_factory should return a configured GraphExecutor.
-        """
-        self._require_phase([BuildPhase.ADDING_NODES, BuildPhase.ADDING_EDGES, BuildPhase.TESTING])
-        self.session.phase = BuildPhase.TESTING
-
-        try:
-            # Build temporary graph for testing
-            graph = self._build_graph()
-            executor = executor_factory()
-
-            # Run the test
-            import asyncio
-
-            result = asyncio.run(
-                executor.execute(
-                    graph=graph,
-                    goal=self.session.goal,
-                    input_data=test.input,
-                )
-            )
-
-            # Check result
-            passed = result.success
-            if test.expected_output is not None:
-                passed = passed and (result.output.get("result") == test.expected_output)
-            if test.expected_contains:
-                output_str = str(result.output)
-                passed = passed and (test.expected_contains in output_str)
-
-            test_result = TestResult(
-                test_id=test.id,
-                passed=passed,
-                actual_output=result.output,
-                execution_path=result.path,
-            )
-
-        except Exception as e:
-            test_result = TestResult(
-                test_id=test.id,
-                passed=False,
-                error=str(e),
-            )
-
-        self.session.test_results.append(test_result)
-        self._save_session()
-
-        return test_result
-
-    def run_all_tests(self, executor_factory: Callable) -> list[TestResult]:
-        """Run all test cases."""
-        results = []
-        for test in self.session.test_cases:
-            result = self.run_test(test, executor_factory)
-            results.append(result)
-        return results
-
-    # =========================================================================
-    # APPROVAL
-    # =========================================================================
-
-    def approve(self, comment: str) -> bool:
-        """
-        Approve the current pending change.
-
-        Must have a passing validation to approve.
-        Returns True if approved, False if validation failed.
-        """
-        if self._pending_validation is None:
-            raise RuntimeError("Nothing to approve. Run validation first.")
-
-        if not self._pending_validation.valid:
-            return False
-
-        self.session.approvals.append(
-            {
-                "phase": self.session.phase.value,
-                "comment": comment,
-                "timestamp": datetime.now().isoformat(),
-                "validation": self._pending_validation.model_dump(),
-            }
-        )
-
-        # Advance phase if appropriate
-        if self.session.phase == BuildPhase.GOAL_DRAFT:
-            self.session.phase = BuildPhase.GOAL_APPROVED
-
-        self._pending_validation = None
-        self._save_session()
-
-        return True
-
-    def final_approve(self, comment: str) -> bool:
-        """
-        Final approval for the complete graph.
-
-        Requires all tests to pass.
-        """
-        # Run final validation
-        validation = self.validate()
-        if not validation.valid:
-            self._pending_validation = validation
-            return False
-
-        # Check test results
-        if self.session.test_cases:
-            failed_tests = [t for t in self.session.test_results if not t.passed]
-            if failed_tests:
-                self._pending_validation = ValidationResult(
-                    valid=False,
-                    errors=[f"Failed tests: {[t.test_id for t in failed_tests]}"],
-                )
-                return False
-
-        self.session.phase = BuildPhase.APPROVED
-        self.session.approvals.append(
-            {
-                "phase": "final",
-                "comment": comment,
-                "timestamp": datetime.now().isoformat(),
-            }
-        )
-
-        self._save_session()
-        return True
-
-    # =========================================================================
-    # EXPORT
-    # =========================================================================
-
-    def export(self) -> GraphSpec:
-        """
-        Export the approved graph.
-
-        Requires final approval.
-        """
-        self._require_phase([BuildPhase.APPROVED])
-
-        graph = self._build_graph()
-
-        self.session.phase = BuildPhase.EXPORTED
-        self._save_session()
-
-        return graph
-
-    def _build_graph(self) -> GraphSpec:
-        """Build a GraphSpec from current session."""
-        # Determine entry node
-        entry_node = None
-        for node in self.session.nodes:
-            if not any(e.target == node.id for e in self.session.edges):
-                entry_node = node.id
-                break
-
-        # Determine terminal nodes
-        terminal_nodes = []
-        for node in self.session.nodes:
-            if not any(e.source == node.id for e in self.session.edges):
-                terminal_nodes.append(node.id)
-
-        # Collect all memory keys
-        memory_keys = set()
-        for node in self.session.nodes:
-            memory_keys.update(node.input_keys)
-            memory_keys.update(node.output_keys)
-
-        return GraphSpec(
-            id=f"{self.session.name}-graph",
-            goal_id=self.session.goal.id if self.session.goal else "",
-            entry_node=entry_node or "",
-            terminal_nodes=terminal_nodes,
-            nodes=self.session.nodes,
-            edges=self.session.edges,
-            memory_keys=list(memory_keys),
-        )
-
-    def export_to_file(self, path: Path | str) -> None:
-        """Export the graph to a Python file."""
-        self._require_phase([BuildPhase.APPROVED, BuildPhase.EXPORTED])
-
-        graph = self._build_graph()
-
-        # Generate Python code
-        code = self._generate_code(graph)
-
-        Path(path).write_text(code)
-        self.session.phase = BuildPhase.EXPORTED
-        self._save_session()
-
-    def _generate_code(self, graph: GraphSpec) -> str:
-        """Generate Python code for the graph."""
-        lines = [
-            '"""',
-            f"Generated agent: {self.session.name}",
-            f"Generated at: {datetime.now().isoformat()}",
-            '"""',
-            "",
-            "from framework.graph import (",
-            "    Goal, SuccessCriterion, Constraint,",
-            "    NodeSpec, EdgeSpec, EdgeCondition,",
-            ")",
-            "from framework.graph.edge import GraphSpec",
-            "from framework.graph.goal import GoalStatus",
-            "",
-            "",
-            "# Goal",
-        ]
-
-        if self.session.goal:
-            goal_json = self.session.goal.model_dump_json(indent=4)
-            lines.append("GOAL = Goal.model_validate_json('''")
-            lines.append(goal_json)
-            lines.append("''')")
-        else:
-            lines.append("GOAL = None")
-
-        lines.extend(
-            [
-                "",
-                "",
-                "# Nodes",
-                "NODES = [",
-            ]
-        )
-
-        for node in self.session.nodes:
-            node_json = node.model_dump_json(indent=4)
-            lines.append("    NodeSpec.model_validate_json('''")
-            lines.append(node_json)
-            lines.append("    '''),")
-
-        lines.extend(
-            [
-                "]",
-                "",
-                "",
-                "# Edges",
-                "EDGES = [",
-            ]
-        )
-
-        for edge in self.session.edges:
-            edge_json = edge.model_dump_json(indent=4)
-            lines.append("    EdgeSpec.model_validate_json('''")
-            lines.append(edge_json)
-            lines.append("    '''),")
-
-        lines.extend(
-            [
-                "]",
-                "",
-                "",
-                "# Graph",
-            ]
-        )
-
-        graph_json = graph.model_dump_json(indent=4)
-        lines.append("GRAPH = GraphSpec.model_validate_json('''")
-        lines.append(graph_json)
-        lines.append("''')")
-
-        return "\n".join(lines)
-
-    # =========================================================================
-    # SESSION MANAGEMENT
-    # =========================================================================
-
-    def _require_phase(self, allowed: list[BuildPhase]) -> None:
-        """Ensure we're in an allowed phase."""
-        if self.session.phase not in allowed:
-            raise RuntimeError(
-                f"Cannot perform this action in phase '{self.session.phase.value}'. "
-                f"Allowed phases: {[p.value for p in allowed]}"
-            )
-
-    def _save_session(self) -> None:
-        """Save session to disk."""
-        self.session.updated_at = datetime.now()
-        path = self.storage_path / f"{self.session.id}.json"
-        path.write_text(self.session.model_dump_json(indent=2))
-
-    def _load_session(self, session_id: str) -> BuildSession:
-        """Load session from disk."""
-        path = self.storage_path / f"{session_id}.json"
-        if not path.exists():
-            raise FileNotFoundError(f"Session not found: {session_id}")
-        return BuildSession.model_validate_json(path.read_text())
-
-    @classmethod
-    def list_sessions(cls, storage_path: Path | str | None = None) -> list[str]:
-        """List all saved sessions."""
-        path = Path(storage_path) if storage_path else Path.home() / ".core" / "builds"
-        if not path.exists():
-            return []
-        return [f.stem for f in path.glob("*.json")]
-
-    # =========================================================================
-    # STATUS
-    # =========================================================================
-
-    def status(self) -> dict[str, Any]:
-        """Get current build status."""
-        return {
-            "session_id": self.session.id,
-            "name": self.session.name,
-            "phase": self.session.phase.value,
-            "goal": self.session.goal.name if self.session.goal else None,
-            "nodes": len(self.session.nodes),
-            "edges": len(self.session.edges),
-            "tests": len(self.session.test_cases),
-            "tests_passed": sum(1 for t in self.session.test_results if t.passed),
-            "approvals": len(self.session.approvals),
-            "pending_validation": self._pending_validation.model_dump()
-            if self._pending_validation
-            else None,
-        }
-
-    def show(self) -> str:
-        """Show current graph as text."""
-        lines = [
-            f"=== Build: {self.session.name} ===",
-            f"Phase: {self.session.phase.value}",
-            "",
-        ]
-
-        if self.session.goal:
-            lines.extend(
-                [
-                    f"Goal: {self.session.goal.name}",
-                    f"  {self.session.goal.description}",
-                    "",
-                ]
-            )
-
-        if self.session.nodes:
-            lines.append("Nodes:")
-            for node in self.session.nodes:
-                lines.append(f"  [{node.id}] {node.name} ({node.node_type})")
-            lines.append("")
-
-        if self.session.edges:
-            lines.append("Edges:")
-            for edge in self.session.edges:
-                lines.append(f"  {edge.source} --{edge.condition.value}--> {edge.target}")
-            lines.append("")
-
-        if self._pending_validation:
-            lines.append("Pending Validation:")
-            lines.append(f"  Valid: {self._pending_validation.valid}")
-            for err in self._pending_validation.errors:
-                lines.append(f"  ERROR: {err}")
-            for warn in self._pending_validation.warnings:
-                lines.append(f"  WARN: {warn}")
-
-        return "\n".join(lines)

core/framework/cli.py

@@ -11,9 +11,9 @@ Usage:
 
 Testing commands:
     hive test-run <agent_path> --goal <goal_id>
-    hive test-debug <goal_id> <test_id>
-    hive test-list <goal_id>
-    hive test-stats <goal_id>
+    hive test-debug <agent_path> <test_name>
+    hive test-list <agent_path>
+    hive test-stats <agent_path>
 """
 
 import argparse
@@ -44,11 +44,25 @@ def _configure_paths():
         if exports_str not in sys.path:
             sys.path.insert(0, exports_str)
 
+    # Add examples/templates/ to sys.path so template agents are importable
+    templates_dir = project_root / "examples" / "templates"
+    if templates_dir.is_dir():
+        templates_str = str(templates_dir)
+        if templates_str not in sys.path:
+            sys.path.insert(0, templates_str)
+
     # Ensure core/ is also in sys.path (for non-editable-install scenarios)
     core_str = str(project_root / "core")
     if (project_root / "core").is_dir() and core_str not in sys.path:
         sys.path.insert(0, core_str)
 
+    # Add core/framework/agents/ so framework agents are importable as top-level packages
+    framework_agents_dir = project_root / "core" / "framework" / "agents"
+    if framework_agents_dir.is_dir():
+        fa_str = str(framework_agents_dir)
+        if fa_str not in sys.path:
+            sys.path.insert(0, fa_str)
+
 
 def main():
     _configure_paths()

core/framework/config.py

@@ -0,0 +1,169 @@
+"""Shared Hive configuration utilities.
+
+Centralises reading of ~/.hive/configuration.json so that the runner
+and every agent template share one implementation instead of copy-pasting
+helper functions.
+"""
+
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from framework.graph.edge import DEFAULT_MAX_TOKENS
+
+# ---------------------------------------------------------------------------
+# Low-level config file access
+# ---------------------------------------------------------------------------
+
+HIVE_CONFIG_FILE = Path.home() / ".hive" / "configuration.json"
+logger = logging.getLogger(__name__)
+
+
+def get_hive_config() -> dict[str, Any]:
+    """Load hive configuration from ~/.hive/configuration.json."""
+    if not HIVE_CONFIG_FILE.exists():
+        return {}
+    try:
+        with open(HIVE_CONFIG_FILE, encoding="utf-8-sig") as f:
+            return json.load(f)
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning(
+            "Failed to load Hive config %s: %s",
+            HIVE_CONFIG_FILE,
+            e,
+        )
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Derived helpers
+# ---------------------------------------------------------------------------
+
+
+def get_preferred_model() -> str:
+    """Return the user's preferred LLM model string (e.g. 'anthropic/claude-sonnet-4-20250514')."""
+    llm = get_hive_config().get("llm", {})
+    if llm.get("provider") and llm.get("model"):
+        return f"{llm['provider']}/{llm['model']}"
+    return "anthropic/claude-sonnet-4-20250514"
+
+
+def get_max_tokens() -> int:
+    """Return the configured max_tokens, falling back to DEFAULT_MAX_TOKENS."""
+    return get_hive_config().get("llm", {}).get("max_tokens", DEFAULT_MAX_TOKENS)
+
+
+def get_api_key() -> str | None:
+    """Return the API key, supporting env var, Claude Code subscription, Codex, and ZAI Code.
+
+    Priority:
+    1. Claude Code subscription (``use_claude_code_subscription: true``)
+       reads the OAuth token from ``~/.claude/.credentials.json``.
+    2. Codex subscription (``use_codex_subscription: true``)
+       reads the OAuth token from macOS Keychain or ``~/.codex/auth.json``.
+    3. Environment variable named in ``api_key_env_var``.
+    """
+    llm = get_hive_config().get("llm", {})
+
+    # Claude Code subscription: read OAuth token directly
+    if llm.get("use_claude_code_subscription"):
+        try:
+            from framework.runner.runner import get_claude_code_token
+
+            token = get_claude_code_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    # Codex subscription: read OAuth token from Keychain / auth.json
+    if llm.get("use_codex_subscription"):
+        try:
+            from framework.runner.runner import get_codex_token
+
+            token = get_codex_token()
+            if token:
+                return token
+        except ImportError:
+            pass
+
+    # Standard env-var path (covers ZAI Code and all API-key providers)
+    api_key_env_var = llm.get("api_key_env_var")
+    if api_key_env_var:
+        return os.environ.get(api_key_env_var)
+    return None
+
+
+def get_gcu_enabled() -> bool:
+    """Return whether GCU (browser automation) is enabled in user config."""
+    return get_hive_config().get("gcu_enabled", True)
+
+
+def get_api_base() -> str | None:
+    """Return the api_base URL for OpenAI-compatible endpoints, if configured."""
+    llm = get_hive_config().get("llm", {})
+    if llm.get("use_codex_subscription"):
+        # Codex subscription routes through the ChatGPT backend, not api.openai.com.
+        return "https://chatgpt.com/backend-api/codex"
+    return llm.get("api_base")
+
+
+def get_llm_extra_kwargs() -> dict[str, Any]:
+    """Return extra kwargs for LiteLLMProvider (e.g. OAuth headers).
+
+    When ``use_claude_code_subscription`` is enabled, returns
+    ``extra_headers`` with the OAuth Bearer token so that litellm's
+    built-in Anthropic OAuth handler adds the required beta headers.
+
+    When ``use_codex_subscription`` is enabled, returns
+    ``extra_headers`` with the Bearer token, ``ChatGPT-Account-Id``,
+    and ``store=False`` (required by the ChatGPT backend).
+    """
+    llm = get_hive_config().get("llm", {})
+    if llm.get("use_claude_code_subscription"):
+        api_key = get_api_key()
+        if api_key:
+            return {
+                "extra_headers": {"authorization": f"Bearer {api_key}"},
+            }
+    if llm.get("use_codex_subscription"):
+        api_key = get_api_key()
+        if api_key:
+            headers: dict[str, str] = {
+                "Authorization": f"Bearer {api_key}",
+                "User-Agent": "CodexBar",
+            }
+            try:
+                from framework.runner.runner import get_codex_account_id
+
+                account_id = get_codex_account_id()
+                if account_id:
+                    headers["ChatGPT-Account-Id"] = account_id
+            except ImportError:
+                pass
+            return {
+                "extra_headers": headers,
+                "store": False,
+                "allowed_openai_params": ["store"],
+            }
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# RuntimeConfig – shared across agent templates
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RuntimeConfig:
+    """Agent runtime configuration loaded from ~/.hive/configuration.json."""
+
+    model: str = field(default_factory=get_preferred_model)
+    temperature: float = 0.7
+    max_tokens: int = field(default_factory=get_max_tokens)
+    api_key: str | None = field(default_factory=get_api_key)
+    api_base: str | None = field(default_factory=get_api_base)
+    extra_kwargs: dict[str, Any] = field(default_factory=get_llm_extra_kwargs)

core/framework/credentials/__init__.py

@@ -42,6 +42,14 @@ For Vault integration:
     from core.framework.credentials.vault import HashiCorpVaultStorage
 """
 
+from .key_storage import (
+    delete_aden_api_key,
+    generate_and_save_credential_key,
+    load_aden_api_key,
+    load_credential_key,
+    save_aden_api_key,
+    save_credential_key,
+)
 from .models import (
     CredentialDecryptionError,
     CredentialError,
@@ -59,6 +67,13 @@ from .provider import (
     CredentialProvider,
     StaticProvider,
 )
+from .setup import (
+    CredentialSetupSession,
+    MissingCredential,
+    SetupResult,
+    load_agent_nodes,
+    run_credential_setup_cli,
+)
 from .storage import (
     CompositeStorage,
     CredentialStorage,
@@ -68,6 +83,12 @@ from .storage import (
 )
 from .store import CredentialStore
 from .template import TemplateResolver
+from .validation import (
+    CredentialStatus,
+    CredentialValidationResult,
+    ensure_credential_key_env,
+    validate_agent_credentials,
+)
 
 # Aden sync components (lazy import to avoid httpx dependency when not needed)
 # Usage: from core.framework.credentials.aden import AdenSyncProvider
@@ -84,6 +105,14 @@ try:
 except ImportError:
     _ADEN_AVAILABLE = False
 
+# Local credential registry (named API key accounts with identity metadata)
+try:
+    from .local import LocalAccountInfo, LocalCredentialRegistry
+
+    _LOCAL_AVAILABLE = True
+except ImportError:
+    _LOCAL_AVAILABLE = False
+
 __all__ = [
     # Main store
     "CredentialStore",
@@ -111,12 +140,34 @@ __all__ = [
     "CredentialRefreshError",
     "CredentialValidationError",
     "CredentialDecryptionError",
+    # Key storage (bootstrap credentials)
+    "load_credential_key",
+    "save_credential_key",
+    "generate_and_save_credential_key",
+    "load_aden_api_key",
+    "save_aden_api_key",
+    "delete_aden_api_key",
+    # Validation
+    "ensure_credential_key_env",
+    "validate_agent_credentials",
+    "CredentialStatus",
+    "CredentialValidationResult",
+    # Interactive setup
+    "CredentialSetupSession",
+    "MissingCredential",
+    "SetupResult",
+    "load_agent_nodes",
+    "run_credential_setup_cli",
     # Aden sync (optional - requires httpx)
     "AdenSyncProvider",
     "AdenCredentialClient",
     "AdenClientConfig",
     "AdenCachedStorage",
+    # Local credential registry (optional - requires cryptography)
+    "LocalCredentialRegistry",
+    "LocalAccountInfo",
 ]
 
 # Track Aden availability for runtime checks
 ADEN_AVAILABLE = _ADEN_AVAILABLE
+LOCAL_AVAILABLE = _LOCAL_AVAILABLE

core/framework/credentials/aden/client.py

@@ -1,33 +1,36 @@
 """
 Aden Credential Client.
 
-HTTP client for communicating with the Aden authentication server.
-The Aden server handles OAuth2 authorization flows and token management.
-This client fetches tokens and delegates refresh operations to Aden.
+HTTP client for the Aden authentication server.
+Aden holds all OAuth secrets; agents receive only short-lived access tokens.
+
+API (all endpoints authenticated with Bearer {api_key}):
+
+    GET  /v1/credentials                          — list integrations
+    GET  /v1/credentials/{integration_id}          — get access token (auto-refreshes)
+    POST /v1/credentials/{integration_id}/refresh  — force refresh
+    GET  /v1/credentials/{integration_id}/validate — check validity
+
+Integration IDs are base64-encoded hashes assigned by the Aden platform
+(e.g. "Z29vZ2xlOlRpbW90aHk6MTYwNjc6MTM2ODQ"), NOT provider names.
 
 Usage:
-    # API key loaded from ADEN_API_KEY environment variable by default
     client = AdenCredentialClient(AdenClientConfig(
         base_url="https://api.adenhq.com",
     ))
 
-    # Or explicitly provide the API key
-    client = AdenCredentialClient(AdenClientConfig(
-        base_url="https://api.adenhq.com",
-        api_key="your-api-key",
-    ))
+    # List what's connected
+    for info in client.list_integrations():
+        print(f"{info.provider}/{info.alias}: {info.status}")
 
-    # Fetch a credential
-    response = client.get_credential("hubspot")
-    if response:
-        print(f"Token expires at: {response.expires_at}")
-
-    # Request a refresh
-    refreshed = client.request_refresh("hubspot")
+    # Get an access token
+    cred = client.get_credential(info.integration_id)
+    print(cred.access_token)
 """
 
 from __future__ import annotations
 
+import json as _json
 import logging
 import os
 import time
@@ -88,8 +91,7 @@ class AdenClientConfig:
     """Base URL of the Aden server (e.g., 'https://api.adenhq.com')."""
 
     api_key: str | None = None
-    """Agent's API key for authenticating with Aden.
-    If not provided, loaded from ADEN_API_KEY environment variable."""
+    """Agent API key. Loaded from ADEN_API_KEY env var if not provided."""
 
     tenant_id: str | None = None
     """Optional tenant ID for multi-tenant deployments."""
@@ -104,7 +106,6 @@ class AdenClientConfig:
     """Base delay between retries in seconds (exponential backoff)."""
 
     def __post_init__(self) -> None:
-        """Load API key from environment if not provided."""
         if self.api_key is None:
             self.api_key = os.environ.get("ADEN_API_KEY")
             if not self.api_key:
@@ -115,71 +116,124 @@ class AdenClientConfig:
 
 
 @dataclass
-class AdenCredentialResponse:
-    """Response from Aden server containing credential data."""
+class AdenIntegrationInfo:
+    """An integration from GET /v1/credentials.
+
+    Example response item::
+
+        {
+            "integration_id": "Z29vZ2xlOlRpbW90aHk6MTYwNjc6MTM2ODQ",
+            "provider": "google",
+            "alias": "Timothy",
+            "status": "active",
+            "email": "timothy@acho.io",
+            "expires_at": "2026-02-20T21:46:04.863Z"
+        }
+    """
 
     integration_id: str
-    """Unique identifier for the integration (e.g., 'hubspot')."""
+    """Base64-encoded hash ID assigned by Aden."""
 
-    integration_type: str
-    """Type of integration (e.g., 'hubspot', 'github', 'slack')."""
+    provider: str
+    """Provider type (e.g. "google", "slack", "hubspot")."""
 
-    access_token: str
-    """The access token for API calls."""
+    alias: str
+    """User-set alias on the Aden platform."""
 
-    token_type: str = "Bearer"
-    """Token type (usually 'Bearer')."""
+    status: str
+    """Status: "active", "expired", "requires_reauth"."""
+
+    email: str = ""
+    """Email associated with this connection."""
 
     expires_at: datetime | None = None
-    """When the access token expires (UTC)."""
+    """When the current access token expires."""
 
-    scopes: list[str] = field(default_factory=list)
-    """OAuth2 scopes granted to this token."""
-
-    metadata: dict[str, Any] = field(default_factory=dict)
-    """Additional integration-specific metadata."""
+    # Backward compat — old code reads integration_type
+    @property
+    def integration_type(self) -> str:
+        return self.provider
 
     @classmethod
-    def from_dict(
-        cls, data: dict[str, Any], integration_id: str | None = None
-    ) -> AdenCredentialResponse:
-        """Create from API response dictionary."""
+    def from_dict(cls, data: dict[str, Any]) -> AdenIntegrationInfo:
         expires_at = None
         if data.get("expires_at"):
             expires_at = datetime.fromisoformat(data["expires_at"].replace("Z", "+00:00"))
 
         return cls(
-            integration_id=integration_id or data.get("alias", data.get("provider", "")),
-            integration_type=data.get("provider", ""),
-            access_token=data["access_token"],
-            token_type=data.get("token_type", "Bearer"),
+            integration_id=data.get("integration_id", ""),
+            provider=data.get("provider", ""),
+            alias=data.get("alias", ""),
+            status=data.get("status", "unknown"),
+            email=data.get("email", ""),
             expires_at=expires_at,
-            scopes=data.get("scopes", []),
-            metadata={"email": data.get("email")} if data.get("email") else {},
         )
 
 
 @dataclass
-class AdenIntegrationInfo:
-    """Information about an available integration."""
+class AdenCredentialResponse:
+    """Response from GET /v1/credentials/{integration_id}.
+
+    Example::
+
+        {
+            "access_token": "ya29.a0AfH6SM...",
+            "token_type": "Bearer",
+            "expires_at": "2026-02-20T12:00:00.000Z",
+            "provider": "google",
+            "alias": "Timothy",
+            "email": "timothy@acho.io"
+        }
+    """
 
     integration_id: str
-    integration_type: str
-    status: str  # "active", "requires_reauth", "expired"
+    """The integration_id used in the request."""
+
+    access_token: str
+    """Short-lived access token for API calls."""
+
+    token_type: str = "Bearer"
+
     expires_at: datetime | None = None
 
+    provider: str = ""
+    """Provider type (e.g. "google")."""
+
+    alias: str = ""
+    """User-set alias."""
+
+    email: str = ""
+    """Email associated with this connection."""
+
+    scopes: list[str] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # Backward compat
+    @property
+    def integration_type(self) -> str:
+        return self.provider
+
     @classmethod
-    def from_dict(cls, data: dict[str, Any]) -> AdenIntegrationInfo:
-        """Create from API response dictionary."""
+    def from_dict(cls, data: dict[str, Any], integration_id: str = "") -> AdenCredentialResponse:
         expires_at = None
         if data.get("expires_at"):
             expires_at = datetime.fromisoformat(data["expires_at"].replace("Z", "+00:00"))
 
+        # Build metadata from email if present
+        metadata = data.get("metadata") or {}
+        if not metadata and data.get("email"):
+            metadata = {"email": data["email"]}
+
         return cls(
-            integration_id=data["integration_id"],
-            integration_type=data.get("provider", data["integration_id"]),
-            status=data.get("status", "unknown"),
+            integration_id=integration_id or data.get("integration_id", ""),
+            access_token=data["access_token"],
+            token_type=data.get("token_type", "Bearer"),
             expires_at=expires_at,
+            provider=data.get("provider", ""),
+            alias=data.get("alias", ""),
+            email=data.get("email", ""),
+            scopes=data.get("scopes", []),
+            metadata=metadata,
         )
 
 
@@ -187,56 +241,38 @@ class AdenCredentialClient:
     """
     HTTP client for Aden credential server.
 
-    Handles communication with the Aden authentication server,
-    including fetching credentials, requesting refreshes, and
-    reporting usage statistics.
-
-    The client automatically handles:
-    - Retries with exponential backoff for transient failures
-    - Proper error classification (auth, not found, rate limit, etc.)
-    - Request headers for authentication and tenant isolation
-
     Usage:
-        # API key loaded from ADEN_API_KEY environment variable
-        config = AdenClientConfig(
+        client = AdenCredentialClient(AdenClientConfig(
             base_url="https://api.adenhq.com",
-        )
+        ))
 
-        client = AdenCredentialClient(config)
+        # List integrations
+        for info in client.list_integrations():
+            print(f"{info.provider}/{info.alias}: {info.status}")
 
-        # Fetch a credential
-        cred = client.get_credential("hubspot")
-        if cred:
-            headers = {"Authorization": f"Bearer {cred.access_token}"}
+        # Get access token (uses base64 integration_id, NOT provider name)
+        cred = client.get_credential(info.integration_id)
+        headers = {"Authorization": f"Bearer {cred.access_token}"}
 
-        # List all integrations
-        integrations = client.list_integrations()
-        for info in integrations:
-            print(f"{info.integration_id}: {info.status}")
-
-        # Clean up
         client.close()
     """
 
     def __init__(self, config: AdenClientConfig):
-        """
-        Initialize the Aden client.
-
-        Args:
-            config: Client configuration including base URL and API key.
-        """
         self.config = config
         self._client: httpx.Client | None = None
 
+    @staticmethod
+    def _parse_json(response: httpx.Response) -> Any:
+        """Parse JSON from response, tolerating UTF-8 BOM."""
+        return _json.loads(response.content.decode("utf-8-sig"))
+
     def _get_client(self) -> httpx.Client:
-        """Get or create the HTTP client."""
         if self._client is None:
             headers = {
                 "Authorization": f"Bearer {self.config.api_key}",
                 "Content-Type": "application/json",
                 "User-Agent": "hive-credential-store/1.0",
             }
-
             if self.config.tenant_id:
                 headers["X-Tenant-ID"] = self.config.tenant_id
 
@@ -245,7 +281,6 @@ class AdenCredentialClient:
                 timeout=self.config.timeout,
                 headers=headers,
             )
-
         return self._client
 
     def _request_with_retry(
@@ -262,10 +297,13 @@ class AdenCredentialClient:
             try:
                 response = client.request(method, path, **kwargs)
 
-                # Handle specific error codes
                 if response.status_code == 401:
                     raise AdenAuthenticationError("Agent API key is invalid or revoked")
 
+                if response.status_code == 403:
+                    data = self._parse_json(response)
+                    raise AdenClientError(data.get("message", "Forbidden"))
+
                 if response.status_code == 404:
                     raise AdenNotFoundError(f"Integration not found: {path}")
 
@@ -277,15 +315,16 @@ class AdenCredentialClient:
                     )
 
                 if response.status_code == 400:
-                    data = response.json()
-                    if data.get("error") == "refresh_failed":
+                    data = self._parse_json(response)
+                    msg = data.get("message", "Bad request")
+                    if data.get("error") == "refresh_failed" or "refresh" in msg.lower():
                         raise AdenRefreshError(
-                            data.get("message", "Token refresh failed"),
+                            msg,
                             requires_reauthorization=data.get("requires_reauthorization", False),
                             reauthorization_url=data.get("reauthorization_url"),
                         )
+                    raise AdenClientError(f"Bad request: {msg}")
 
-                # Success or other error
                 response.raise_for_status()
                 return response
 
@@ -306,161 +345,96 @@ class AdenCredentialClient:
                 AdenRefreshError,
                 AdenRateLimitError,
             ):
-                # Don't retry these errors
                 raise
 
-        # Should not reach here, but just in case
         raise AdenClientError(
             f"Request failed after {self.config.retry_attempts} attempts"
         ) from last_error
 
-    def get_credential(self, integration_id: str) -> AdenCredentialResponse | None:
+    def list_integrations(self) -> list[AdenIntegrationInfo]:
         """
-        Fetch the current credential for an integration.
+        List all integrations for this agent's team.
 
-        The Aden server may refresh the token internally if it's expired
-        before returning it.
-
-        Args:
-            integration_id: The integration identifier (e.g., 'hubspot').
+        GET /v1/credentials → {"integrations": [...]}
 
         Returns:
-            Credential response with access token, or None if not found.
+            List of AdenIntegrationInfo with integration_id, provider,
+            alias, status, email, expires_at.
+        """
+        response = self._request_with_retry("GET", "/v1/credentials")
+        data = self._parse_json(response)
+        return [AdenIntegrationInfo.from_dict(item) for item in data.get("integrations", [])]
 
-        Raises:
-            AdenAuthenticationError: If API key is invalid.
-            AdenClientError: For connection failures.
+    # Alias
+    list_connections = list_integrations
+
+    def get_credential(self, integration_id: str) -> AdenCredentialResponse | None:
+        """
+        Get access token for an integration. Auto-refreshes if near expiry.
+
+        GET /v1/credentials/{integration_id}
+
+        Args:
+            integration_id: Base64 hash ID from list_integrations().
+
+        Returns:
+            AdenCredentialResponse with access_token, or None if not found.
         """
         try:
             response = self._request_with_retry("GET", f"/v1/credentials/{integration_id}")
-            data = response.json()
+            data = self._parse_json(response)
             return AdenCredentialResponse.from_dict(data, integration_id=integration_id)
         except AdenNotFoundError:
             return None
 
     def request_refresh(self, integration_id: str) -> AdenCredentialResponse:
         """
-        Request the Aden server to refresh the token.
+        Force refresh the access token.
 
-        Use this when the local store detects an expired or near-expiry token.
-        The Aden server handles the actual OAuth2 refresh token flow.
+        POST /v1/credentials/{integration_id}/refresh
 
         Args:
-            integration_id: The integration identifier.
+            integration_id: Base64 hash ID.
 
         Returns:
-            Credential response with new access token.
-
-        Raises:
-            AdenRefreshError: If refresh fails (may require re-authorization).
-            AdenNotFoundError: If integration not found.
-            AdenAuthenticationError: If API key is invalid.
-            AdenRateLimitError: If rate limited.
+            AdenCredentialResponse with new access_token.
         """
         response = self._request_with_retry("POST", f"/v1/credentials/{integration_id}/refresh")
-        data = response.json()
+        data = self._parse_json(response)
         return AdenCredentialResponse.from_dict(data, integration_id=integration_id)
 
-    def list_integrations(self) -> list[AdenIntegrationInfo]:
-        """
-        List all integrations available for this agent/tenant.
-
-        Returns:
-            List of integration info objects.
-
-        Raises:
-            AdenAuthenticationError: If API key is invalid.
-            AdenClientError: For connection failures.
-        """
-        response = self._request_with_retry("GET", "/v1/credentials")
-        data = response.json()
-        return [AdenIntegrationInfo.from_dict(item) for item in data.get("integrations", [])]
-
     def validate_token(self, integration_id: str) -> dict[str, Any]:
         """
-        Check if a token is still valid without fetching it.
+        Check if an integration's OAuth connection is valid.
 
-        Args:
-            integration_id: The integration identifier.
+        GET /v1/credentials/{integration_id}/validate
 
         Returns:
-            Dict with 'valid' bool and optional 'expires_at', 'reason',
-            'requires_reauthorization', 'reauthorization_url'.
-
-        Raises:
-            AdenNotFoundError: If integration not found.
-            AdenAuthenticationError: If API key is invalid.
+            {"valid": bool, "status": str, "expires_at": str, "error": str|null}
         """
         response = self._request_with_retry("GET", f"/v1/credentials/{integration_id}/validate")
-        return response.json()
-
-    def report_usage(
-        self,
-        integration_id: str,
-        operation: str,
-        status: str = "success",
-        metadata: dict[str, Any] | None = None,
-    ) -> None:
-        """
-        Report credential usage statistics to Aden.
-
-        This is optional and used for analytics/billing.
-
-        Args:
-            integration_id: The integration identifier.
-            operation: Operation name (e.g., 'api_call').
-            status: Operation status ('success', 'error').
-            metadata: Additional operation metadata.
-        """
-        try:
-            self._request_with_retry(
-                "POST",
-                f"/v1/credentials/{integration_id}/usage",
-                json={
-                    "operation": operation,
-                    "status": status,
-                    "timestamp": datetime.utcnow().isoformat() + "Z",
-                    "metadata": metadata or {},
-                },
-            )
-        except Exception as e:
-            # Usage reporting is best-effort, don't fail on errors
-            logger.warning(f"Failed to report usage for '{integration_id}': {e}")
+        return self._parse_json(response)
 
     def health_check(self) -> dict[str, Any]:
-        """
-        Check Aden server health and connectivity.
-
-        Returns:
-            Dict with 'status', 'version', 'timestamp', and optionally 'error'.
-        """
+        """Check Aden server health."""
         try:
             client = self._get_client()
             response = client.get("/health")
             if response.status_code == 200:
-                data = response.json()
+                data = self._parse_json(response)
                 data["latency_ms"] = response.elapsed.total_seconds() * 1000
                 return data
-            return {
-                "status": "degraded",
-                "error": f"Unexpected status code: {response.status_code}",
-            }
+            return {"status": "degraded", "error": f"HTTP {response.status_code}"}
         except Exception as e:
-            return {
-                "status": "unhealthy",
-                "error": str(e),
-            }
+            return {"status": "unhealthy", "error": str(e)}
 
     def close(self) -> None:
-        """Close the HTTP client and release resources."""
         if self._client:
             self._client.close()
             self._client = None
 
     def __enter__(self) -> AdenCredentialClient:
-        """Context manager entry."""
         return self
 
     def __exit__(self, *args: Any) -> None:
-        """Context manager exit."""
         self.close()

core/framework/credentials/aden/provider.py

@@ -282,8 +282,8 @@ class AdenSyncProvider(CredentialProvider):
         """
         Sync all credentials from Aden server to local store.
 
-        Fetches the list of available integrations from Aden and
-        populates the local credential store with current tokens.
+        Calls GET /v1/credentials to list integrations, then fetches
+        access tokens for each active one.
 
         Args:
             store: The credential store to populate.
@@ -298,9 +298,7 @@ class AdenSyncProvider(CredentialProvider):
 
             for info in integrations:
                 if info.status != "active":
-                    logger.warning(
-                        f"Skipping integration '{info.integration_id}': status={info.status}"
-                    )
+                    logger.warning(f"Skipping connection '{info.alias}': status={info.status}")
                     continue
 
                 try:
@@ -308,9 +306,9 @@ class AdenSyncProvider(CredentialProvider):
                     if cred:
                         store.save_credential(cred)
                         synced += 1
-                        logger.info(f"Synced credential '{info.integration_id}' from Aden")
+                        logger.info(f"Synced credential '{info.alias}' from Aden")
                 except Exception as e:
-                    logger.warning(f"Failed to sync '{info.integration_id}': {e}")
+                    logger.warning(f"Failed to sync '{info.alias}': {e}")
 
         except AdenClientError as e:
             logger.error(f"Failed to list integrations from Aden: {e}")
@@ -373,6 +371,21 @@ class AdenSyncProvider(CredentialProvider):
             value=SecretStr(aden_response.integration_type),
         )
 
+        # Store alias (user-set name from Aden platform)
+        if aden_response.alias:
+            credential.keys["_alias"] = CredentialKey(
+                name="_alias",
+                value=SecretStr(aden_response.alias),
+            )
+
+        # Persist Aden metadata as identity keys
+        for meta_key, meta_value in (aden_response.metadata or {}).items():
+            if meta_value and isinstance(meta_value, str):
+                credential.keys[f"_identity_{meta_key}"] = CredentialKey(
+                    name=f"_identity_{meta_key}",
+                    value=SecretStr(meta_value),
+                )
+
         # Update timestamps
         credential.last_refreshed = datetime.now(UTC)
         credential.provider_id = self.provider_id
@@ -400,12 +413,27 @@ class AdenSyncProvider(CredentialProvider):
             ),
         }
 
+        # Store alias (user-set name from Aden platform)
+        if aden_response.alias:
+            keys["_alias"] = CredentialKey(
+                name="_alias",
+                value=SecretStr(aden_response.alias),
+            )
+
         if aden_response.scopes:
             keys["scope"] = CredentialKey(
                 name="scope",
                 value=SecretStr(" ".join(aden_response.scopes)),
             )
 
+        # Persist Aden metadata as identity keys
+        for meta_key, meta_value in (aden_response.metadata or {}).items():
+            if meta_value and isinstance(meta_value, str):
+                keys[f"_identity_{meta_key}"] = CredentialKey(
+                    name=f"_identity_{meta_key}",
+                    value=SecretStr(meta_value),
+                )
+
         return CredentialObject(
             id=aden_response.integration_id,
             credential_type=CredentialType.OAUTH2,

core/framework/credentials/aden/storage.py

@@ -26,7 +26,7 @@ Usage:
     storage = AdenCachedStorage(
         local_storage=EncryptedFileStorage(),
         aden_provider=provider,
-        cache_ttl_seconds=300,  # Re-check Aden every 5 minutes
+        cache_ttl_seconds=600,  # Re-check Aden every 5 minutes
     )
 
     # Create store
@@ -77,7 +77,7 @@ class AdenCachedStorage(CredentialStorage):
         storage = AdenCachedStorage(
             local_storage=EncryptedFileStorage(),
             aden_provider=provider,
-            cache_ttl_seconds=300,  # 5 minutes
+            cache_ttl_seconds=00,  # 5 minutes
         )
 
         store = CredentialStore(
@@ -114,8 +114,10 @@ class AdenCachedStorage(CredentialStorage):
         self._cache_ttl = timedelta(seconds=cache_ttl_seconds)
         self._prefer_local = prefer_local
         self._cache_timestamps: dict[str, datetime] = {}
-        # Index: provider name (e.g., "hubspot") -> credential hash ID
-        self._provider_index: dict[str, str] = {}
+        # Index: provider name (e.g., "hubspot") -> list of credential hash IDs
+        self._provider_index: dict[str, list[str]] = {}
+        # Index: "provider:alias" -> credential hash ID (for alias-based routing)
+        self._alias_index: dict[str, str] = {}
 
     def save(self, credential: CredentialObject) -> None:
         """
@@ -160,14 +162,16 @@ class AdenCachedStorage(CredentialStorage):
             CredentialObject if found, None otherwise.
         """
         # Check provider index first — Aden-synced credentials take priority
-        resolved_id = self._provider_index.get(credential_id)
-        if resolved_id and resolved_id != credential_id:
-            result = self._load_by_id(resolved_id)
-            if result is not None:
-                logger.info(
-                    f"Loaded credential '{credential_id}' via provider index (id='{resolved_id}')"
-                )
-                return result
+        resolved_ids = self._provider_index.get(credential_id)
+        if resolved_ids:
+            for rid in resolved_ids:
+                if rid != credential_id:
+                    result = self._load_by_id(rid)
+                    if result is not None:
+                        logger.info(
+                            f"Loaded credential '{credential_id}' via provider index (id='{rid}')"
+                        )
+                        return result
 
         # Direct lookup (exact credential_id match)
         return self._load_by_id(credential_id)
@@ -189,25 +193,42 @@ class AdenCachedStorage(CredentialStorage):
             logger.debug(f"Using cached credential '{credential_id}'")
             return local_cred
 
-        # Try to fetch from Aden
+        # If nothing local, there's nothing to refresh from Aden.
+        # sync_all() already fetched all available credentials — anything
+        # not in local storage doesn't exist on the Aden server.
+        if local_cred is None:
+            return None
+
+        # Try to refresh stale local credential from Aden
         try:
             aden_cred = self._aden_provider.fetch_from_aden(credential_id)
             if aden_cred:
-                # Update local cache
                 self.save(aden_cred)
                 logger.debug(f"Fetched credential '{credential_id}' from Aden")
                 return aden_cred
         except Exception as e:
             logger.warning(f"Failed to fetch '{credential_id}' from Aden: {e}")
+            logger.info(f"Using stale cached credential '{credential_id}'")
+            return local_cred
 
-            # Fall back to local cache if Aden fails
-            if local_cred:
-                logger.info(f"Using stale cached credential '{credential_id}'")
-                return local_cred
-
-        # Return local credential if it exists (may be None)
         return local_cred
 
+    def load_all_for_provider(self, provider_name: str) -> list[CredentialObject]:
+        """Load all credentials for a given provider type.
+
+        Args:
+            provider_name: Provider name (e.g. "google", "slack").
+
+        Returns:
+            List of CredentialObjects for all accounts of this provider.
+        """
+        results: list[CredentialObject] = []
+        for cid in self._provider_index.get(provider_name, []):
+            cred = self._load_by_id(cid)
+            if cred:
+                results.append(cred)
+        return results
+
     def delete(self, credential_id: str) -> bool:
         """
         Delete credential from local cache.
@@ -246,9 +267,11 @@ class AdenCachedStorage(CredentialStorage):
         if self._local.exists(credential_id):
             return True
         # Check provider index
-        resolved_id = self._provider_index.get(credential_id)
-        if resolved_id and resolved_id != credential_id:
-            return self._local.exists(resolved_id)
+        resolved_ids = self._provider_index.get(credential_id)
+        if resolved_ids:
+            for rid in resolved_ids:
+                if rid != credential_id and self._local.exists(rid):
+                    return True
         return False
 
     def _is_cache_fresh(self, credential_id: str) -> bool:
@@ -285,13 +308,15 @@ class AdenCachedStorage(CredentialStorage):
 
     def _index_provider(self, credential: CredentialObject) -> None:
         """
-        Index a credential by its provider/integration type.
+        Index a credential by its provider/integration type and alias.
 
         Aden credentials carry an ``_integration_type`` key whose value is
         the provider name (e.g., ``hubspot``).  This method maps that
         provider name to the credential's hash ID so that subsequent
         ``load("hubspot")`` calls resolve to the correct credential.
 
+        Also indexes by ``_alias`` for alias-based multi-account routing.
+
         Args:
             credential: The credential to index.
         """
@@ -300,19 +325,45 @@ class AdenCachedStorage(CredentialStorage):
             return
         provider_name = integration_type_key.value.get_secret_value()
         if provider_name:
-            self._provider_index[provider_name] = credential.id
+            if provider_name not in self._provider_index:
+                self._provider_index[provider_name] = []
+            if credential.id not in self._provider_index[provider_name]:
+                self._provider_index[provider_name].append(credential.id)
             logger.debug(f"Indexed provider '{provider_name}' -> '{credential.id}'")
 
+            # Index by alias for multi-account routing
+            alias_key = credential.keys.get("_alias")
+            if alias_key:
+                alias = alias_key.value.get_secret_value()
+                if alias:
+                    self._alias_index[f"{provider_name}:{alias}"] = credential.id
+
+    def load_by_alias(self, provider_name: str, alias: str) -> CredentialObject | None:
+        """Load a credential by provider name and alias.
+
+        Args:
+            provider_name: Provider type (e.g. "google", "slack").
+            alias: User-set alias from the Aden platform.
+
+        Returns:
+            CredentialObject if found, None otherwise.
+        """
+        cred_id = self._alias_index.get(f"{provider_name}:{alias}")
+        if cred_id:
+            return self._load_by_id(cred_id)
+        return None
+
     def rebuild_provider_index(self) -> int:
         """
-        Rebuild the provider index from all locally cached credentials.
+        Rebuild the provider and alias indexes from all locally cached credentials.
 
-        Useful after loading from disk when the in-memory index is empty.
+        Useful after loading from disk when the in-memory indexes are empty.
 
         Returns:
             Number of provider mappings indexed.
         """
         self._provider_index.clear()
+        self._alias_index.clear()
         indexed = 0
         for cred_id in self._local.list_all():
             cred = self._local.load(cred_id)
@@ -328,8 +379,8 @@ class AdenCachedStorage(CredentialStorage):
         """
         Sync all credentials from Aden server to local cache.
 
-        Fetches the list of available integrations from Aden and
-        updates the local cache with current tokens.
+        Calls GET /v1/credentials to list active integrations,
+        then fetches tokens for each.
 
         Returns:
             Number of credentials synced.
@@ -341,9 +392,7 @@ class AdenCachedStorage(CredentialStorage):
 
             for info in integrations:
                 if info.status != "active":
-                    logger.warning(
-                        f"Skipping integration '{info.integration_id}': status={info.status}"
-                    )
+                    logger.warning(f"Skipping integration '{info.alias}': status={info.status}")
                     continue
 
                 try:
@@ -351,9 +400,9 @@ class AdenCachedStorage(CredentialStorage):
                     if cred:
                         self.save(cred)
                         synced += 1
-                        logger.info(f"Synced credential '{info.integration_id}' from Aden")
+                        logger.info(f"Synced credential '{info.alias}' from Aden")
                 except Exception as e:
-                    logger.warning(f"Failed to sync '{info.integration_id}': {e}")
+                    logger.warning(f"Failed to sync '{info.alias}': {e}")
 
         except Exception as e:
             logger.error(f"Failed to list integrations from Aden: {e}")

core/framework/credentials/aden/tests/test_aden_sync.py

@@ -61,11 +61,13 @@ def mock_client(aden_config):
 def aden_response():
     """Create a sample Aden credential response."""
     return AdenCredentialResponse(
-        integration_id="hubspot",
-        integration_type="hubspot",
+        integration_id="aHVic3BvdDp0ZXN0OjEzNjExOjExNTI1",
         access_token="test-access-token",
         token_type="Bearer",
         expires_at=datetime.now(UTC) + timedelta(hours=1),
+        provider="hubspot",
+        alias="My HubSpot",
+        email="test@example.com",
         scopes=["crm.objects.contacts.read", "crm.objects.contacts.write"],
         metadata={"portal_id": "12345"},
     )
@@ -108,18 +110,20 @@ class TestAdenCredentialResponse:
     """Tests for AdenCredentialResponse dataclass."""
 
     def test_from_dict_basic(self):
-        """Test creating response from dict."""
+        """Test creating response from dict (real get-token format)."""
         data = {
-            "integration_id": "github",
-            "integration_type": "github",
             "access_token": "ghp_xxxxx",
+            "token_type": "Bearer",
+            "provider": "github",
+            "alias": "Work",
         }
 
-        response = AdenCredentialResponse.from_dict(data)
+        response = AdenCredentialResponse.from_dict(data, integration_id="Z2l0aHViOldvcms6MTIzNDU")
 
-        assert response.integration_id == "github"
-        assert response.integration_type == "github"
+        assert response.integration_id == "Z2l0aHViOldvcms6MTIzNDU"
         assert response.access_token == "ghp_xxxxx"
+        assert response.provider == "github"
+        assert response.integration_type == "github"  # backward compat property
         assert response.token_type == "Bearer"
         assert response.expires_at is None
         assert response.scopes == []
@@ -127,19 +131,23 @@ class TestAdenCredentialResponse:
     def test_from_dict_full(self):
         """Test creating response with all fields."""
         data = {
-            "integration_id": "hubspot",
-            "integration_type": "hubspot",
             "access_token": "token123",
             "token_type": "Bearer",
             "expires_at": "2026-01-28T15:30:00Z",
+            "provider": "hubspot",
+            "alias": "My HubSpot",
+            "email": "test@example.com",
             "scopes": ["read", "write"],
             "metadata": {"key": "value"},
         }
 
-        response = AdenCredentialResponse.from_dict(data)
+        response = AdenCredentialResponse.from_dict(data, integration_id="aHVic3BvdDp0ZXN0")
 
-        assert response.integration_id == "hubspot"
+        assert response.integration_id == "aHVic3BvdDp0ZXN0"
         assert response.access_token == "token123"
+        assert response.provider == "hubspot"
+        assert response.alias == "My HubSpot"
+        assert response.email == "test@example.com"
         assert response.expires_at is not None
         assert response.scopes == ["read", "write"]
         assert response.metadata == {"key": "value"}
@@ -149,21 +157,44 @@ class TestAdenIntegrationInfo:
     """Tests for AdenIntegrationInfo dataclass."""
 
     def test_from_dict(self):
-        """Test creating integration info from dict."""
+        """Test creating integration info from real API format."""
         data = {
-            "integration_id": "slack",
-            "integration_type": "slack",
+            "integration_id": "c2xhY2s6V29yayBTbGFjazoxMjM0NQ",
+            "provider": "slack",
+            "alias": "Work Slack",
             "status": "active",
-            "expires_at": "2026-02-01T00:00:00Z",
+            "email": "user@example.com",
+            "expires_at": "2026-02-20T21:46:04.863Z",
         }
 
         info = AdenIntegrationInfo.from_dict(data)
 
-        assert info.integration_id == "slack"
-        assert info.integration_type == "slack"
+        assert info.integration_id == "c2xhY2s6V29yayBTbGFjazoxMjM0NQ"
+        assert info.provider == "slack"
+        assert info.integration_type == "slack"  # backward compat property
+        assert info.alias == "Work Slack"
+        assert info.email == "user@example.com"
         assert info.status == "active"
         assert info.expires_at is not None
 
+    def test_from_dict_minimal(self):
+        """Test creating integration info with minimal fields."""
+        data = {
+            "integration_id": "Z29vZ2xlOlRpbW90aHk6MTYwNjc",
+            "provider": "google",
+            "alias": "Timothy",
+            "status": "requires_reauth",
+        }
+
+        info = AdenIntegrationInfo.from_dict(data)
+
+        assert info.integration_id == "Z29vZ2xlOlRpbW90aHk6MTYwNjc"
+        assert info.provider == "google"
+        assert info.alias == "Timothy"
+        assert info.status == "requires_reauth"
+        assert info.email == ""
+        assert info.expires_at is None
+
 
 # =============================================================================
 # AdenSyncProvider Tests
@@ -220,10 +251,11 @@ class TestAdenSyncProvider:
 
     def test_refresh_success(self, provider, mock_client, aden_response):
         """Test successful credential refresh."""
+        hash_id = "aHVic3BvdDp0ZXN0OjEzNjExOjExNTI1"
         mock_client.request_refresh.return_value = aden_response
 
         cred = CredentialObject(
-            id="hubspot",
+            id=hash_id,
             credential_type=CredentialType.OAUTH2,
             keys={
                 "access_token": CredentialKey(
@@ -239,7 +271,7 @@ class TestAdenSyncProvider:
         assert refreshed.keys["access_token"].value.get_secret_value() == "test-access-token"
         assert refreshed.keys["_aden_managed"].value.get_secret_value() == "true"
         assert refreshed.last_refreshed is not None
-        mock_client.request_refresh.assert_called_once_with("hubspot")
+        mock_client.request_refresh.assert_called_once_with(hash_id)
 
     def test_refresh_requires_reauth(self, provider, mock_client):
         """Test refresh that requires re-authorization."""
@@ -339,12 +371,13 @@ class TestAdenSyncProvider:
 
     def test_fetch_from_aden(self, provider, mock_client, aden_response):
         """Test fetching credential from Aden."""
+        hash_id = "aHVic3BvdDp0ZXN0OjEzNjExOjExNTI1"
         mock_client.get_credential.return_value = aden_response
 
-        cred = provider.fetch_from_aden("hubspot")
+        cred = provider.fetch_from_aden(hash_id)
 
         assert cred is not None
-        assert cred.id == "hubspot"
+        assert cred.id == hash_id
         assert cred.keys["access_token"].value.get_secret_value() == "test-access-token"
         assert cred.auto_refresh is True
 
@@ -360,13 +393,15 @@ class TestAdenSyncProvider:
         """Test syncing all credentials."""
         mock_client.list_integrations.return_value = [
             AdenIntegrationInfo(
-                integration_id="hubspot",
-                integration_type="hubspot",
+                integration_id="aHVic3BvdDp0ZXN0OjEzNjExOjExNTI1",
+                provider="hubspot",
+                alias="My HubSpot",
                 status="active",
             ),
             AdenIntegrationInfo(
-                integration_id="github",
-                integration_type="github",
+                integration_id="Z2l0aHViOnRlc3Q6OTk5",
+                provider="github",
+                alias="Work GitHub",
                 status="requires_reauth",  # Should be skipped
             ),
         ]
@@ -376,7 +411,7 @@ class TestAdenSyncProvider:
         synced = provider.sync_all(store)
 
         assert synced == 1  # Only active one was synced
-        assert store.get_credential("hubspot") is not None
+        assert store.get_credential("aHVic3BvdDp0ZXN0OjEzNjExOjExNTI1") is not None
 
     def test_validate_via_aden(self, provider, mock_client):
         """Test validation via Aden introspection."""
@@ -608,7 +643,7 @@ class TestAdenCachedStorage:
 
         cached_storage.save(cred)
 
-        assert cached_storage._provider_index["hubspot"] == "aHVic3BvdDp0ZXN0OjEzNjExOjExNTI1"
+        assert cached_storage._provider_index["hubspot"] == ["aHVic3BvdDp0ZXN0OjEzNjExOjExNTI1"]
 
     def test_load_by_provider_name(self, cached_storage):
         """Test load resolves provider name to hash-based credential ID."""
@@ -711,8 +746,8 @@ class TestAdenCachedStorage:
         indexed = cached_storage.rebuild_provider_index()
 
         assert indexed == 2
-        assert cached_storage._provider_index["hubspot"] == "hash_hub"
-        assert cached_storage._provider_index["slack"] == "hash_slack"
+        assert cached_storage._provider_index["hubspot"] == ["hash_hub"]
+        assert cached_storage._provider_index["slack"] == ["hash_slack"]
 
     def test_save_without_integration_type_no_index(self, cached_storage):
         """Test save does not index credentials without _integration_type key."""
@@ -743,19 +778,23 @@ class TestAdenIntegration:
 
     def test_full_workflow(self, mock_client, aden_response):
         """Test full workflow: sync, get, refresh."""
+        hash_id = "aHVic3BvdDp0ZXN0OjEzNjExOjExNTI1"
+
         # Setup
         mock_client.list_integrations.return_value = [
             AdenIntegrationInfo(
-                integration_id="hubspot",
-                integration_type="hubspot",
+                integration_id=hash_id,
+                provider="hubspot",
+                alias="My HubSpot",
                 status="active",
             ),
         ]
         mock_client.get_credential.return_value = aden_response
         mock_client.request_refresh.return_value = AdenCredentialResponse(
-            integration_id="hubspot",
-            integration_type="hubspot",
+            integration_id=hash_id,
             access_token="refreshed-token",
+            provider="hubspot",
+            alias="My HubSpot",
             expires_at=datetime.now(UTC) + timedelta(hours=2),
             scopes=[],
         )
@@ -772,8 +811,8 @@ class TestAdenIntegration:
         synced = provider.sync_all(store)
         assert synced == 1
 
-        # Get credential
-        cred = store.get_credential("hubspot")
+        # Get credential by hash ID
+        cred = store.get_credential(hash_id)
         assert cred is not None
         assert cred.keys["access_token"].value.get_secret_value() == "test-access-token"
 

core/framework/credentials/key_storage.py

@@ -0,0 +1,201 @@
+"""
+Dedicated file-based storage for bootstrap credentials.
+
+HIVE_CREDENTIAL_KEY -> ~/.hive/secrets/credential_key  (plain text, chmod 600)
+ADEN_API_KEY        -> ~/.hive/credentials/             (encrypted via EncryptedFileStorage)
+
+Boot order:
+  1. load_credential_key()   -- reads/generates the Fernet key, sets os.environ
+  2. load_aden_api_key()     -- uses the encrypted store (which needs the key from step 1)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import stat
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+CREDENTIAL_KEY_PATH = Path.home() / ".hive" / "secrets" / "credential_key"
+CREDENTIAL_KEY_ENV_VAR = "HIVE_CREDENTIAL_KEY"
+ADEN_CREDENTIAL_ID = "aden_api_key"
+ADEN_ENV_VAR = "ADEN_API_KEY"
+
+
+# ---------------------------------------------------------------------------
+# HIVE_CREDENTIAL_KEY
+# ---------------------------------------------------------------------------
+
+
+def load_credential_key() -> str | None:
+    """Load HIVE_CREDENTIAL_KEY with priority: env > file > shell config.
+
+    Sets ``os.environ["HIVE_CREDENTIAL_KEY"]`` as a side-effect when found.
+    Returns the key string, or ``None`` if unavailable everywhere.
+    """
+    # 1. Already in environment (set by parent process, CI, Windows Registry, etc.)
+    key = os.environ.get(CREDENTIAL_KEY_ENV_VAR)
+    if key:
+        return key
+
+    # 2. Dedicated secrets file
+    key = _read_credential_key_file()
+    if key:
+        os.environ[CREDENTIAL_KEY_ENV_VAR] = key
+        return key
+
+    # 3. Shell config fallback (backward compat for old installs)
+    key = _read_from_shell_config(CREDENTIAL_KEY_ENV_VAR)
+    if key:
+        os.environ[CREDENTIAL_KEY_ENV_VAR] = key
+        return key
+
+    return None
+
+
+def save_credential_key(key: str) -> Path:
+    """Save HIVE_CREDENTIAL_KEY to ``~/.hive/secrets/credential_key``.
+
+    Creates parent dirs with mode 700, writes the file with mode 600.
+    Also sets ``os.environ["HIVE_CREDENTIAL_KEY"]``.
+
+    Returns:
+        The path that was written.
+    """
+    path = CREDENTIAL_KEY_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    # Restrict the secrets directory itself
+    path.parent.chmod(stat.S_IRWXU)  # 0o700
+
+    path.write_text(key, encoding="utf-8")
+    path.chmod(stat.S_IRUSR | stat.S_IWUSR)  # 0o600
+
+    os.environ[CREDENTIAL_KEY_ENV_VAR] = key
+    return path
+
+
+def generate_and_save_credential_key() -> str:
+    """Generate a new Fernet key and persist it to ``~/.hive/secrets/credential_key``.
+
+    Returns:
+        The generated key string.
+    """
+    from cryptography.fernet import Fernet
+
+    key = Fernet.generate_key().decode()
+    save_credential_key(key)
+    return key
+
+
+# ---------------------------------------------------------------------------
+# ADEN_API_KEY
+# ---------------------------------------------------------------------------
+
+
+def load_aden_api_key() -> str | None:
+    """Load ADEN_API_KEY with priority: env > encrypted store > shell config.
+
+    **Must** be called after ``load_credential_key()`` because the encrypted
+    store depends on HIVE_CREDENTIAL_KEY.
+
+    Sets ``os.environ["ADEN_API_KEY"]`` as a side-effect when found.
+    Returns the key string, or ``None`` if unavailable everywhere.
+    """
+    # 1. Already in environment
+    key = os.environ.get(ADEN_ENV_VAR)
+    if key:
+        return key
+
+    # 2. Encrypted credential store
+    key = _read_aden_from_encrypted_store()
+    if key:
+        os.environ[ADEN_ENV_VAR] = key
+        return key
+
+    # 3. Shell config fallback (backward compat)
+    key = _read_from_shell_config(ADEN_ENV_VAR)
+    if key:
+        os.environ[ADEN_ENV_VAR] = key
+        return key
+
+    return None
+
+
+def save_aden_api_key(key: str) -> None:
+    """Save ADEN_API_KEY to the encrypted credential store.
+
+    Also sets ``os.environ["ADEN_API_KEY"]``.
+    """
+    from pydantic import SecretStr
+
+    from .models import CredentialKey, CredentialObject
+    from .storage import EncryptedFileStorage
+
+    storage = EncryptedFileStorage()
+    cred = CredentialObject(
+        id=ADEN_CREDENTIAL_ID,
+        keys={"api_key": CredentialKey(name="api_key", value=SecretStr(key))},
+    )
+    storage.save(cred)
+    os.environ[ADEN_ENV_VAR] = key
+
+
+def delete_aden_api_key() -> None:
+    """Remove ADEN_API_KEY from the encrypted store and ``os.environ``."""
+    try:
+        from .storage import EncryptedFileStorage
+
+        storage = EncryptedFileStorage()
+        storage.delete(ADEN_CREDENTIAL_ID)
+    except Exception:
+        logger.debug("Could not delete %s from encrypted store", ADEN_CREDENTIAL_ID)
+
+    os.environ.pop(ADEN_ENV_VAR, None)
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_credential_key_file() -> str | None:
+    """Read the credential key from ``~/.hive/secrets/credential_key``."""
+    try:
+        if CREDENTIAL_KEY_PATH.is_file():
+            value = CREDENTIAL_KEY_PATH.read_text(encoding="utf-8").strip()
+            if value:
+                return value
+    except Exception:
+        logger.debug("Could not read %s", CREDENTIAL_KEY_PATH)
+    return None
+
+
+def _read_from_shell_config(env_var: str) -> str | None:
+    """Fallback: read an env var from ~/.zshrc or ~/.bashrc."""
+    try:
+        from aden_tools.credentials.shell_config import check_env_var_in_shell_config
+
+        found, value = check_env_var_in_shell_config(env_var)
+        if found and value:
+            return value
+    except ImportError:
+        pass
+    return None
+
+
+def _read_aden_from_encrypted_store() -> str | None:
+    """Try to load ADEN_API_KEY from the encrypted credential store."""
+    if not os.environ.get(CREDENTIAL_KEY_ENV_VAR):
+        return None
+    try:
+        from .storage import EncryptedFileStorage
+
+        storage = EncryptedFileStorage()
+        cred = storage.load(ADEN_CREDENTIAL_ID)
+        if cred:
+            return cred.get_key("api_key")
+    except Exception:
+        logger.debug("Could not load %s from encrypted store", ADEN_CREDENTIAL_ID)
+    return None

core/framework/credentials/local/__init__.py

@@ -0,0 +1,31 @@
+"""
+Local credential registry — named API key accounts with identity metadata.
+
+Provides feature parity with Aden OAuth credentials for locally-stored API keys:
+aliases, identity metadata, status tracking, CRUD, and health validation.
+
+Usage:
+    from framework.credentials.local import LocalCredentialRegistry, LocalAccountInfo
+
+    registry = LocalCredentialRegistry.default()
+
+    # Add a named account
+    info, health = registry.save_account("brave_search", "work", "BSA-xxx")
+
+    # List all stored local accounts
+    for account in registry.list_accounts():
+        print(f"{account.credential_id}/{account.alias}: {account.status}")
+        if account.identity.is_known:
+            print(f"  Identity: {account.identity.label}")
+
+    # Re-validate a stored account
+    result = registry.validate_account("github", "personal")
+"""
+
+from .models import LocalAccountInfo
+from .registry import LocalCredentialRegistry
+
+__all__ = [
+    "LocalAccountInfo",
+    "LocalCredentialRegistry",
+]

core/framework/credentials/local/models.py

@@ -0,0 +1,58 @@
+"""
+Data models for the local credential registry.
+
+LocalAccountInfo mirrors AdenIntegrationInfo, giving local API key credentials
+the same identity/status metadata as Aden OAuth credentials.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from framework.credentials.models import CredentialIdentity
+
+
+@dataclass
+class LocalAccountInfo:
+    """
+    A locally-stored named credential account.
+
+    Mirrors AdenIntegrationInfo so local and Aden accounts can be treated
+    uniformly in the credential tester and account selection UI.
+
+    Attributes:
+        credential_id: The logical credential name (e.g. "brave_search", "github")
+        alias: User-provided name for this account (e.g. "work", "personal")
+        status: "active" | "failed" | "unknown"
+        identity: Email, username, workspace, or account_id extracted from health check
+        last_validated: When the key was last verified against the live API
+        created_at: When this account was first stored
+    """
+
+    credential_id: str
+    alias: str
+    status: str = "unknown"
+    identity: CredentialIdentity = field(default_factory=CredentialIdentity)
+    last_validated: datetime | None = None
+    created_at: datetime = field(default_factory=datetime.utcnow)
+
+    @property
+    def storage_id(self) -> str:
+        """The key used in EncryptedFileStorage: '{credential_id}/{alias}'."""
+        return f"{self.credential_id}/{self.alias}"
+
+    def to_account_dict(self) -> dict:
+        """
+        Format compatible with AccountSelectionScreen and configure_for_account().
+
+        Same shape as Aden account dicts, with source='local' added.
+        """
+        return {
+            "provider": self.credential_id,
+            "alias": self.alias,
+            "identity": self.identity.to_dict(),
+            "integration_id": None,
+            "source": "local",
+            "status": self.status,
+        }

core/framework/credentials/local/registry.py

@@ -0,0 +1,326 @@
+"""
+Local Credential Registry.
+
+Manages named local API key accounts stored in EncryptedFileStorage.
+Mirrors the Aden integration model so local credentials have feature parity:
+aliases, identity metadata, status tracking, CRUD, and health validation.
+
+Storage convention:
+    {credential_id}/{alias}  →  CredentialObject
+    e.g. "brave_search/work" →  { api_key: "BSA-xxx", _alias: "work",
+                                   _integration_type: "brave_search",
+                                   _status: "active",
+                                   _identity_username: "acme", ... }
+
+Usage:
+    registry = LocalCredentialRegistry.default()
+
+    # Add a new account
+    info, health = registry.save_account("brave_search", "work", "BSA-xxx")
+    print(info.status, info.identity.label)
+
+    # List all accounts
+    for account in registry.list_accounts():
+        print(f"{account.credential_id}/{account.alias}: {account.status}")
+
+    # Get the raw API key for a specific account
+    key = registry.get_key("github", "personal")
+
+    # Re-validate a stored account
+    result = registry.validate_account("github", "personal")
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from framework.credentials.models import CredentialIdentity, CredentialObject
+from framework.credentials.storage import EncryptedFileStorage
+
+from .models import LocalAccountInfo
+
+if TYPE_CHECKING:
+    from aden_tools.credentials.health_check import HealthCheckResult
+
+logger = logging.getLogger(__name__)
+
+_SEPARATOR = "/"
+
+
+class LocalCredentialRegistry:
+    """
+    Named local API key account store backed by EncryptedFileStorage.
+
+    Provides the same list/save/get/delete/validate surface as the Aden
+    client, but for locally-stored API keys.
+    """
+
+    def __init__(self, storage: EncryptedFileStorage) -> None:
+        self._storage = storage
+
+    # ------------------------------------------------------------------
+    # Listing
+    # ------------------------------------------------------------------
+
+    def list_accounts(self, credential_id: str | None = None) -> list[LocalAccountInfo]:
+        """
+        List all stored local accounts.
+
+        Args:
+            credential_id: If given, filter to this credential type only.
+
+        Returns:
+            List of LocalAccountInfo sorted by credential_id then alias.
+        """
+        all_ids = self._storage.list_all()
+        accounts: list[LocalAccountInfo] = []
+
+        for storage_id in all_ids:
+            if _SEPARATOR not in storage_id:
+                continue  # Skip legacy un-aliased entries
+
+            try:
+                cred_obj = self._storage.load(storage_id)
+            except Exception as exc:
+                logger.debug("Skipping unreadable credential %s: %s", storage_id, exc)
+                continue
+
+            if cred_obj is None:
+                continue
+
+            info = self._to_account_info(cred_obj)
+            if info is None:
+                continue
+
+            if credential_id and info.credential_id != credential_id:
+                continue
+
+            accounts.append(info)
+
+        return sorted(accounts, key=lambda a: (a.credential_id, a.alias))
+
+    # ------------------------------------------------------------------
+    # Save / add
+    # ------------------------------------------------------------------
+
+    def save_account(
+        self,
+        credential_id: str,
+        alias: str,
+        api_key: str,
+        run_health_check: bool = True,
+        extra_keys: dict[str, str] | None = None,
+    ) -> tuple[LocalAccountInfo, HealthCheckResult | None]:
+        """
+        Store a named account, optionally validating it first.
+
+        Args:
+            credential_id: Logical credential name (e.g. "brave_search").
+            alias: User-chosen name (e.g. "work"). Defaults to "default".
+            api_key: The raw API key / token value.
+            run_health_check: If True, verify the key against the live API
+                and extract identity metadata. Failure still saves with
+                status="failed" so the user can re-validate later.
+            extra_keys: Additional key/value pairs to store (e.g.
+                cse_id for google_custom_search).
+
+        Returns:
+            (LocalAccountInfo, HealthCheckResult | None)
+        """
+        alias = alias or "default"
+        health_result: HealthCheckResult | None = None
+        identity: dict[str, str] = {}
+        status = "active"
+
+        if run_health_check:
+            try:
+                from aden_tools.credentials.health_check import check_credential_health
+
+                kwargs: dict[str, Any] = {}
+                if extra_keys and "cse_id" in extra_keys:
+                    kwargs["cse_id"] = extra_keys["cse_id"]
+
+                health_result = check_credential_health(credential_id, api_key, **kwargs)
+                status = "active" if health_result.valid else "failed"
+                identity = health_result.details.get("identity", {})
+            except Exception as exc:
+                logger.warning("Health check failed for %s/%s: %s", credential_id, alias, exc)
+                status = "unknown"
+
+        storage_id = f"{credential_id}{_SEPARATOR}{alias}"
+        now = datetime.now(UTC)
+
+        cred_obj = CredentialObject(id=storage_id)
+        cred_obj.set_key("api_key", api_key)
+        cred_obj.set_key("_alias", alias)
+        cred_obj.set_key("_integration_type", credential_id)
+        cred_obj.set_key("_status", status)
+
+        if extra_keys:
+            for k, v in extra_keys.items():
+                cred_obj.set_key(k, v)
+
+        if identity:
+            valid_fields = set(CredentialIdentity.model_fields)
+            filtered = {k: v for k, v in identity.items() if k in valid_fields}
+            if filtered:
+                cred_obj.set_identity(**filtered)
+
+        cred_obj.last_refreshed = now if run_health_check else None
+        self._storage.save(cred_obj)
+
+        account_info = LocalAccountInfo(
+            credential_id=credential_id,
+            alias=alias,
+            status=status,
+            identity=cred_obj.identity,
+            last_validated=cred_obj.last_refreshed,
+            created_at=cred_obj.created_at,
+        )
+        return account_info, health_result
+
+    # ------------------------------------------------------------------
+    # Get
+    # ------------------------------------------------------------------
+
+    def get_account(self, credential_id: str, alias: str) -> CredentialObject | None:
+        """Load the raw CredentialObject for a specific account."""
+        return self._storage.load(f"{credential_id}{_SEPARATOR}{alias}")
+
+    def get_key(self, credential_id: str, alias: str, key_name: str = "api_key") -> str | None:
+        """
+        Return the stored secret value for a specific account.
+
+        Args:
+            credential_id: Logical credential name (e.g. "brave_search").
+            alias: Account alias (e.g. "work").
+            key_name: Key within the credential (default "api_key").
+
+        Returns:
+            The secret value, or None if not found.
+        """
+        cred = self.get_account(credential_id, alias)
+        if cred is None:
+            return None
+        return cred.get_key(key_name)
+
+    def get_account_info(self, credential_id: str, alias: str) -> LocalAccountInfo | None:
+        """Load a LocalAccountInfo for a specific account."""
+        cred = self.get_account(credential_id, alias)
+        if cred is None:
+            return None
+        return self._to_account_info(cred)
+
+    # ------------------------------------------------------------------
+    # Delete
+    # ------------------------------------------------------------------
+
+    def delete_account(self, credential_id: str, alias: str) -> bool:
+        """
+        Remove a stored account.
+
+        Returns:
+            True if the account existed and was deleted, False otherwise.
+        """
+        return self._storage.delete(f"{credential_id}{_SEPARATOR}{alias}")
+
+    # ------------------------------------------------------------------
+    # Validate
+    # ------------------------------------------------------------------
+
+    def validate_account(self, credential_id: str, alias: str) -> HealthCheckResult:
+        """
+        Re-run health check for a stored account and update its status.
+
+        Args:
+            credential_id: Logical credential name.
+            alias: Account alias.
+
+        Returns:
+            HealthCheckResult from the live API check.
+
+        Raises:
+            KeyError: If the account doesn't exist.
+        """
+        from aden_tools.credentials.health_check import HealthCheckResult, check_credential_health
+
+        cred = self.get_account(credential_id, alias)
+        if cred is None:
+            raise KeyError(f"No local account found: {credential_id}/{alias}")
+
+        api_key = cred.get_key("api_key")
+        if not api_key:
+            return HealthCheckResult(valid=False, message="No api_key stored for this account")
+
+        try:
+            kwargs: dict[str, Any] = {}
+            cse_id = cred.get_key("cse_id")
+            if cse_id:
+                kwargs["cse_id"] = cse_id
+
+            result = check_credential_health(credential_id, api_key, **kwargs)
+        except Exception as exc:
+            result = HealthCheckResult(
+                valid=False,
+                message=f"Health check error: {exc}",
+                details={"error": str(exc)},
+            )
+
+        # Update status and timestamp in-place
+        new_status = "active" if result.valid else "failed"
+        cred.set_key("_status", new_status)
+        cred.last_refreshed = datetime.now(UTC)
+
+        # Re-extract identity if available
+        identity = result.details.get("identity", {})
+        if identity:
+            valid_fields = set(CredentialIdentity.model_fields)
+            filtered = {k: v for k, v in identity.items() if k in valid_fields}
+            if filtered:
+                cred.set_identity(**filtered)
+
+        self._storage.save(cred)
+        return result
+
+    # ------------------------------------------------------------------
+    # Factory
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def default(cls) -> LocalCredentialRegistry:
+        """Create a registry using the default encrypted storage at ~/.hive/credentials."""
+        return cls(EncryptedFileStorage())
+
+    @classmethod
+    def at_path(cls, path: str | Path) -> LocalCredentialRegistry:
+        """Create a registry using a custom storage path."""
+        return cls(EncryptedFileStorage(base_path=path))
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _to_account_info(self, cred_obj: CredentialObject) -> LocalAccountInfo | None:
+        """Build LocalAccountInfo from a CredentialObject."""
+        cred_type_key = cred_obj.keys.get("_integration_type")
+        if cred_type_key is None:
+            return None
+        cred_id = cred_type_key.get_secret_value()
+
+        alias_key = cred_obj.keys.get("_alias")
+        alias = alias_key.get_secret_value() if alias_key else cred_obj.id.split(_SEPARATOR, 1)[-1]
+
+        status_key = cred_obj.keys.get("_status")
+        status = status_key.get_secret_value() if status_key else "unknown"
+
+        return LocalAccountInfo(
+            credential_id=cred_id,
+            alias=alias,
+            status=status,
+            identity=cred_obj.identity,
+            last_validated=cred_obj.last_refreshed,
+            created_at=cred_obj.created_at,
+        )

core/framework/credentials/models.py

@@ -70,6 +70,29 @@ class CredentialKey(BaseModel):
         return self.value.get_secret_value()
 
 
+class CredentialIdentity(BaseModel):
+    """Identity information for a credential (whose account is this?)."""
+
+    email: str | None = None
+    username: str | None = None
+    workspace: str | None = None
+    account_id: str | None = None
+
+    @property
+    def label(self) -> str:
+        """Best human-readable identifier for display."""
+        return self.email or self.username or self.workspace or self.account_id or "unknown"
+
+    @property
+    def is_known(self) -> bool:
+        """Whether any identity field is populated."""
+        return bool(self.email or self.username or self.workspace or self.account_id)
+
+    def to_dict(self) -> dict[str, str]:
+        """Return only non-None identity fields."""
+        return {k: v for k, v in self.model_dump().items() if v is not None}
+
+
 class CredentialObject(BaseModel):
     """
     A credential object containing one or more keys.
@@ -202,6 +225,35 @@ class CredentialObject(BaseModel):
 
         return None
 
+    @property
+    def identity(self) -> CredentialIdentity:
+        """Extract identity from ``_identity_*`` keys in the vault."""
+        fields = {}
+        for key_name, key_obj in self.keys.items():
+            if key_name.startswith("_identity_"):
+                field_name = key_name[len("_identity_") :]
+                if field_name in CredentialIdentity.model_fields:
+                    fields[field_name] = key_obj.value.get_secret_value()
+        return CredentialIdentity(**fields)
+
+    @property
+    def provider_type(self) -> str | None:
+        """Return the integration/provider type (e.g. 'google', 'slack')."""
+        key = self.keys.get("_integration_type")
+        return key.value.get_secret_value() if key else None
+
+    @property
+    def alias(self) -> str | None:
+        """Return the user-set alias from the Aden platform."""
+        key = self.keys.get("_alias")
+        return key.value.get_secret_value() if key else None
+
+    def set_identity(self, **fields: str) -> None:
+        """Persist identity fields as ``_identity_*`` keys."""
+        for field_name, value in fields.items():
+            if value:
+                self.set_key(f"_identity_{field_name}", value)
+
 
 class CredentialUsageSpec(BaseModel):
     """

core/framework/credentials/oauth2/__init__.py

@@ -73,6 +73,7 @@ from .provider import (
     TokenExpiredError,
     TokenPlacement,
 )
+from .zoho_provider import ZohoOAuth2Provider
 
 __all__ = [
     # Types
@@ -82,6 +83,7 @@ __all__ = [
     # Providers
     "BaseOAuth2Provider",
     "HubSpotOAuth2Provider",
+    "ZohoOAuth2Provider",
     # Lifecycle
     "TokenLifecycleManager",
     "TokenRefreshResult",

core/framework/credentials/oauth2/base_provider.py

@@ -96,7 +96,7 @@ class BaseOAuth2Provider(CredentialProvider):
                 self._client = httpx.Client(timeout=self.config.request_timeout)
             except ImportError as e:
                 raise ImportError(
-                    "OAuth2 provider requires 'httpx'. Install with: pip install httpx"
+                    "OAuth2 provider requires 'httpx'. Install with: uv pip install httpx"
                 ) from e
         return self._client
 

core/framework/credentials/oauth2/zoho_provider.py

@@ -0,0 +1,198 @@
+"""
+Zoho CRM-specific OAuth2 provider.
+
+Pre-configured for Zoho's OAuth2 endpoints and CRM scopes.
+Extends BaseOAuth2Provider for Zoho-specific behavior.
+
+Usage:
+    provider = ZohoOAuth2Provider(
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+        accounts_domain="https://accounts.zoho.com",  # or .in, .eu, etc.
+    )
+
+    # Use with credential store
+    store = CredentialStore(
+        storage=EncryptedFileStorage(),
+        providers=[provider],
+    )
+
+See: https://www.zoho.com/crm/developer/docs/api/v2/access-refresh.html
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from ..models import CredentialObject, CredentialRefreshError, CredentialType
+from .base_provider import BaseOAuth2Provider
+from .provider import OAuth2Config, OAuth2Token, TokenPlacement
+
+logger = logging.getLogger(__name__)
+
+# Default CRM scopes for Phase 1 (Leads, Contacts, Accounts, Deals, Notes)
+ZOHO_DEFAULT_SCOPES = [
+    "ZohoCRM.modules.leads.ALL",
+    "ZohoCRM.modules.contacts.ALL",
+    "ZohoCRM.modules.accounts.ALL",
+    "ZohoCRM.modules.deals.ALL",
+    "ZohoCRM.modules.notes.CREATE",
+]
+
+
+class ZohoOAuth2Provider(BaseOAuth2Provider):
+    """
+    Zoho CRM OAuth2 provider with pre-configured endpoints.
+
+    Handles Zoho-specific OAuth2 behavior:
+    - Pre-configured token and authorization URLs (region-aware)
+    - Default CRM scopes for Leads, Contacts, Accounts, Deals, Notes
+    - Token validation via Zoho CRM API
+    - Authorization header format: "Authorization: Zoho-oauthtoken {token}"
+
+    Example:
+        provider = ZohoOAuth2Provider(
+            client_id="your-zoho-client-id",
+            client_secret="your-zoho-client-secret",
+            accounts_domain="https://accounts.zoho.com",  # US
+            # or "https://accounts.zoho.in" for India
+            # or "https://accounts.zoho.eu" for EU
+        )
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        accounts_domain: str = "https://accounts.zoho.com",
+        api_domain: str | None = None,
+        scopes: list[str] | None = None,
+    ):
+        """
+        Initialize Zoho OAuth2 provider.
+
+        Args:
+            client_id: Zoho OAuth2 client ID
+            client_secret: Zoho OAuth2 client secret
+            accounts_domain: Zoho accounts domain (region-specific)
+                - US: https://accounts.zoho.com
+                - India: https://accounts.zoho.in
+                - EU: https://accounts.zoho.eu
+                - etc.
+            api_domain: Zoho API domain for CRM calls (used in validate).
+                Defaults to ZOHO_API_DOMAIN env or https://www.zohoapis.com
+            scopes: Override default scopes if needed
+        """
+        base = accounts_domain.rstrip("/")
+        token_url = f"{base}/oauth/v2/token"
+        auth_url = f"{base}/oauth/v2/auth"
+
+        config = OAuth2Config(
+            token_url=token_url,
+            authorization_url=auth_url,
+            client_id=client_id,
+            client_secret=client_secret,
+            default_scopes=scopes or ZOHO_DEFAULT_SCOPES,
+            token_placement=TokenPlacement.HEADER_CUSTOM,
+            custom_header_name="Authorization",
+        )
+        super().__init__(config, provider_id="zoho_crm_oauth2")
+        self._accounts_domain = base
+        self._api_domain = (
+            api_domain or os.getenv("ZOHO_API_DOMAIN", "https://www.zohoapis.com")
+        ).rstrip("/")
+
+    @property
+    def supported_types(self) -> list[CredentialType]:
+        return [CredentialType.OAUTH2]
+
+    def format_for_request(self, token: OAuth2Token) -> dict[str, Any]:
+        """
+        Format token for Zoho CRM API requests.
+
+        Zoho uses Authorization header: "Zoho-oauthtoken {access_token}"
+        (not Bearer).
+        """
+        return {
+            "headers": {
+                "Authorization": f"Zoho-oauthtoken {token.access_token}",
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+        }
+
+    def validate(self, credential: CredentialObject) -> bool:
+        """
+        Validate Zoho credential by making a lightweight API call.
+
+        Uses GET /crm/v2/users?type=CurrentUser (doesn't require module access).
+        Treats 429 as valid-but-rate-limited.
+        """
+        access_token = credential.get_key("access_token")
+        if not access_token:
+            return False
+
+        try:
+            client = self._get_client()
+            response = client.get(
+                f"{self._api_domain}/crm/v2/users?type=CurrentUser",
+                headers={
+                    "Authorization": f"Zoho-oauthtoken {access_token}",
+                    "Accept": "application/json",
+                },
+                timeout=self.config.request_timeout,
+            )
+            return response.status_code in (200, 429)
+        except Exception as e:
+            logger.debug("Zoho credential validation failed: %s", e)
+            return False
+
+    def _parse_token_response(self, response_data: dict[str, Any]) -> OAuth2Token:
+        """
+        Parse Zoho token response.
+
+        Zoho returns:
+        {
+            "access_token": "...",
+            "refresh_token": "...",
+            "expires_in": 3600,
+            "api_domain": "https://www.zohoapis.com",
+            "token_type": "Bearer"
+        }
+        """
+        token = OAuth2Token.from_token_response(response_data)
+        if "api_domain" in response_data:
+            token.raw_response["api_domain"] = response_data["api_domain"]
+        return token
+
+    def refresh(self, credential: CredentialObject) -> CredentialObject:
+        """Refresh Zoho OAuth2 credential and persist DC metadata."""
+        refresh_tok = credential.get_key("refresh_token")
+        if not refresh_tok:
+            raise CredentialRefreshError(f"Credential '{credential.id}' has no refresh_token")
+
+        try:
+            new_token = self.refresh_access_token(refresh_tok)
+        except Exception as e:
+            raise CredentialRefreshError(f"Failed to refresh '{credential.id}': {e}") from e
+
+        credential.set_key("access_token", new_token.access_token, expires_at=new_token.expires_at)
+
+        if new_token.refresh_token and new_token.refresh_token != refresh_tok:
+            credential.set_key("refresh_token", new_token.refresh_token)
+
+        api_domain = new_token.raw_response.get("api_domain")
+        if isinstance(api_domain, str) and api_domain:
+            credential.set_key("api_domain", api_domain.rstrip("/"))
+
+        accounts_server = new_token.raw_response.get("accounts-server")
+        if isinstance(accounts_server, str) and accounts_server:
+            credential.set_key("accounts_domain", accounts_server.rstrip("/"))
+
+        location = new_token.raw_response.get("location")
+        if isinstance(location, str) and location:
+            credential.set_key("location", location.strip().lower())
+
+        return credential

core/framework/credentials/setup.py

@@ -0,0 +1,618 @@
+"""
+Interactive credential setup for CLI applications.
+
+Provides a modular, reusable credential setup flow that can be triggered
+when validate_agent_credentials() fails. Works with both TUI and headless CLIs.
+
+Usage:
+    from framework.credentials.setup import CredentialSetupSession
+
+    # From agent path
+    session = CredentialSetupSession.from_agent_path("exports/my-agent")
+    result = session.run_interactive()
+
+    # From nodes directly
+    session = CredentialSetupSession.from_nodes(nodes)
+    result = session.run_interactive()
+
+    # With custom I/O (for integration with other UIs)
+    session = CredentialSetupSession(
+        missing=missing_creds,
+        input_fn=my_input,
+        print_fn=my_print,
+    )
+"""
+
+from __future__ import annotations
+
+import getpass
+import json
+import os
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from framework.graph import NodeSpec
+
+
+# ANSI colors for terminal output
+class Colors:
+    RED = "\033[0;31m"
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    BLUE = "\033[0;34m"
+    CYAN = "\033[0;36m"
+    BOLD = "\033[1m"
+    DIM = "\033[2m"
+    NC = "\033[0m"  # No Color
+
+    @classmethod
+    def disable(cls):
+        """Disable colors (for non-TTY output)."""
+        cls.RED = cls.GREEN = cls.YELLOW = cls.BLUE = ""
+        cls.CYAN = cls.BOLD = cls.DIM = cls.NC = ""
+
+
+@dataclass
+class MissingCredential:
+    """A credential that needs to be configured."""
+
+    credential_name: str
+    """Internal credential name (e.g., 'brave_search')"""
+
+    env_var: str
+    """Environment variable name (e.g., 'BRAVE_SEARCH_API_KEY')"""
+
+    description: str
+    """Human-readable description"""
+
+    help_url: str
+    """URL where user can obtain credential"""
+
+    api_key_instructions: str
+    """Step-by-step instructions for getting API key"""
+
+    tools: list[str] = field(default_factory=list)
+    """Tools that require this credential"""
+
+    node_types: list[str] = field(default_factory=list)
+    """Node types that require this credential"""
+
+    aden_supported: bool = False
+    """Whether Aden OAuth flow is supported"""
+
+    direct_api_key_supported: bool = True
+    """Whether direct API key entry is supported"""
+
+    credential_id: str = ""
+    """Credential store ID"""
+
+    credential_key: str = "api_key"
+    """Key name within the credential"""
+
+
+@dataclass
+class SetupResult:
+    """Result of credential setup session."""
+
+    success: bool
+    """Whether all required credentials were configured"""
+
+    configured: list[str] = field(default_factory=list)
+    """Credentials that were successfully set up"""
+
+    skipped: list[str] = field(default_factory=list)
+    """Credentials user chose to skip"""
+
+    errors: list[str] = field(default_factory=list)
+    """Any errors encountered"""
+
+
+class CredentialSetupSession:
+    """
+    Interactive credential setup session.
+
+    Can be used by any CLI (runner, coding agent, etc.) to guide users
+    through credential configuration when validation fails.
+
+    Example:
+        from framework.credentials.setup import CredentialSetupSession
+        from framework.credentials.models import CredentialError
+
+        try:
+            validate_agent_credentials(nodes)
+        except CredentialError:
+            session = CredentialSetupSession.from_nodes(nodes)
+            result = session.run_interactive()
+            if result.success:
+                # Retry - credentials are now configured
+                validate_agent_credentials(nodes)
+    """
+
+    def __init__(
+        self,
+        missing: list[MissingCredential],
+        input_fn: Callable[[str], str] | None = None,
+        print_fn: Callable[[str], None] | None = None,
+        password_fn: Callable[[str], str] | None = None,
+    ):
+        """
+        Initialize the setup session.
+
+        Args:
+            missing: List of credentials that need setup
+            input_fn: Custom input function (default: built-in input)
+            print_fn: Custom print function (default: built-in print)
+            password_fn: Custom password input function (default: getpass.getpass)
+        """
+        self.missing = missing
+        self.input_fn = input_fn or input
+        self.print_fn = print_fn or print
+        self.password_fn = password_fn or getpass.getpass
+
+        # Disable colors if not a TTY
+        if not sys.stdout.isatty():
+            Colors.disable()
+
+    @classmethod
+    def from_nodes(cls, nodes: list[NodeSpec]) -> CredentialSetupSession:
+        """Create a setup session by detecting missing credentials from nodes."""
+        from framework.credentials.validation import _status_to_missing, validate_agent_credentials
+
+        result = validate_agent_credentials(nodes, verify=False, raise_on_error=False)
+        missing = [_status_to_missing(c) for c in result.credentials if not c.available]
+        return cls(missing)
+
+    @classmethod
+    def from_agent_path(
+        cls,
+        agent_path: str | Path,
+        *,
+        missing_only: bool = True,
+    ) -> CredentialSetupSession:
+        """Create a setup session for an agent by path.
+
+        Args:
+            agent_path: Path to agent folder.
+            missing_only: If True (default), only include credentials that
+                are NOT yet available. If False, include all required
+                credentials regardless of availability.
+        """
+        from framework.credentials.validation import _status_to_missing, validate_agent_credentials
+
+        nodes = load_agent_nodes(agent_path)
+        result = validate_agent_credentials(nodes, verify=False, raise_on_error=False)
+        if missing_only:
+            missing = [_status_to_missing(c) for c in result.credentials if not c.available]
+        else:
+            missing = [_status_to_missing(c) for c in result.credentials]
+        return cls(missing)
+
+    def run_interactive(self) -> SetupResult:
+        """Run the interactive setup flow."""
+        configured: list[str] = []
+        skipped: list[str] = []
+        errors: list[str] = []
+
+        if not self.missing:
+            self._print(f"\n{Colors.GREEN}✓ All credentials are already configured!{Colors.NC}\n")
+            return SetupResult(success=True)
+
+        self._print_header()
+
+        # Ensure HIVE_CREDENTIAL_KEY is set before storing anything
+        if not self._ensure_credential_key():
+            return SetupResult(
+                success=False,
+                errors=["Failed to initialize credential store encryption key"],
+            )
+
+        for cred in self.missing:
+            try:
+                result = self._setup_single_credential(cred)
+                if result:
+                    configured.append(cred.credential_name)
+                else:
+                    skipped.append(cred.credential_name)
+            except KeyboardInterrupt:
+                self._print(f"\n{Colors.YELLOW}Setup interrupted.{Colors.NC}")
+                skipped.append(cred.credential_name)
+                break
+            except Exception as e:
+                errors.append(f"{cred.credential_name}: {e}")
+
+        self._print_summary(configured, skipped, errors)
+
+        return SetupResult(
+            success=len(errors) == 0 and len(skipped) == 0,
+            configured=configured,
+            skipped=skipped,
+            errors=errors,
+        )
+
+    def _print(self, msg: str) -> None:
+        """Print a message."""
+        self.print_fn(msg)
+
+    def _input(self, prompt: str) -> str:
+        """Get input from user."""
+        return self.input_fn(prompt)
+
+    def _print_header(self) -> None:
+        """Print the setup header."""
+        self._print("")
+        self._print(f"{Colors.YELLOW}{'=' * 60}{Colors.NC}")
+        self._print(f"{Colors.BOLD}  CREDENTIAL SETUP{Colors.NC}")
+        self._print(f"{Colors.YELLOW}{'=' * 60}{Colors.NC}")
+        self._print("")
+        self._print(f"  {len(self.missing)} credential(s) need to be configured:")
+        for cred in self.missing:
+            affected = cred.tools or cred.node_types
+            self._print(f"    • {cred.env_var} ({', '.join(affected)})")
+        self._print("")
+
+    def _ensure_credential_key(self) -> bool:
+        """Ensure HIVE_CREDENTIAL_KEY is available for encrypted storage."""
+        from .key_storage import generate_and_save_credential_key, load_credential_key
+
+        if load_credential_key():
+            return True
+
+        # Generate a new key
+        self._print(f"{Colors.YELLOW}Initializing credential store...{Colors.NC}")
+        try:
+            generate_and_save_credential_key()
+            self._print(
+                f"{Colors.GREEN}✓ Encryption key saved to ~/.hive/secrets/credential_key{Colors.NC}"
+            )
+            return True
+        except Exception as e:
+            self._print(f"{Colors.RED}Failed to initialize credential store: {e}{Colors.NC}")
+            return False
+
+    def _setup_single_credential(self, cred: MissingCredential) -> bool:
+        """Set up a single credential. Returns True if configured."""
+        self._print(f"\n{Colors.CYAN}{'─' * 60}{Colors.NC}")
+        self._print(f"{Colors.BOLD}Setting up: {cred.credential_name}{Colors.NC}")
+        affected = cred.tools or cred.node_types
+        self._print(f"{Colors.DIM}Required for: {', '.join(affected)}{Colors.NC}")
+        if cred.description:
+            self._print(f"{Colors.DIM}{cred.description}{Colors.NC}")
+        self._print(f"{Colors.CYAN}{'─' * 60}{Colors.NC}")
+
+        # Show auth options
+        options = self._get_auth_options(cred)
+        choice = self._prompt_choice(options)
+
+        if choice == "skip":
+            return False
+        elif choice == "aden":
+            return self._setup_via_aden(cred)
+        elif choice == "direct":
+            return self._setup_direct_api_key(cred)
+
+        return False
+
+    def _get_auth_options(self, cred: MissingCredential) -> list[tuple[str, str, str]]:
+        """Get available auth options as (key, label, description) tuples."""
+        options = []
+
+        if cred.direct_api_key_supported:
+            options.append(
+                (
+                    "direct",
+                    "Enter API key directly",
+                    "Paste your API key from the provider's dashboard",
+                )
+            )
+
+        if cred.aden_supported:
+            options.append(
+                (
+                    "aden",
+                    "Use Aden Platform (OAuth)",
+                    "Secure OAuth2 flow via hive.adenhq.com",
+                )
+            )
+
+        options.append(
+            (
+                "skip",
+                "Skip for now",
+                "Configure this credential later",
+            )
+        )
+
+        return options
+
+    def _prompt_choice(self, options: list[tuple[str, str, str]]) -> str:
+        """Prompt user to choose from options."""
+        self._print("")
+        for i, (key, label, desc) in enumerate(options, 1):
+            if key == "skip":
+                self._print(f"  {Colors.DIM}{i}) {label}{Colors.NC}")
+            else:
+                self._print(f"  {Colors.CYAN}{i}){Colors.NC} {label}")
+                self._print(f"     {Colors.DIM}{desc}{Colors.NC}")
+        self._print("")
+
+        while True:
+            try:
+                choice_str = self._input(f"Select option (1-{len(options)}): ").strip()
+                if not choice_str:
+                    continue
+                choice_num = int(choice_str)
+                if 1 <= choice_num <= len(options):
+                    return options[choice_num - 1][0]
+            except ValueError:
+                pass
+            self._print(f"{Colors.RED}Invalid choice. Enter 1-{len(options)}{Colors.NC}")
+
+    def _setup_direct_api_key(self, cred: MissingCredential) -> bool:
+        """Guide user through direct API key setup."""
+        # Show instructions
+        if cred.api_key_instructions:
+            self._print(f"\n{Colors.BOLD}Setup Instructions:{Colors.NC}")
+            self._print(cred.api_key_instructions)
+
+        if cred.help_url:
+            self._print(f"\n{Colors.CYAN}Get your API key at:{Colors.NC} {cred.help_url}")
+
+        # Collect key (use password input to hide the value)
+        self._print("")
+        try:
+            api_key = self.password_fn(f"Paste your {cred.env_var}: ").strip()
+        except Exception:
+            # Fallback to regular input if password input fails
+            api_key = self._input(f"Paste your {cred.env_var}: ").strip()
+
+        if not api_key:
+            self._print(f"{Colors.YELLOW}No value entered. Skipping.{Colors.NC}")
+            return False
+
+        # Health check
+        health_result = self._run_health_check(cred, api_key)
+        if health_result is not None:
+            if health_result["valid"]:
+                self._print(f"{Colors.GREEN}✓ {health_result['message']}{Colors.NC}")
+            else:
+                self._print(f"{Colors.YELLOW}⚠ {health_result['message']}{Colors.NC}")
+                confirm = self._input("Continue anyway? [y/N]: ").strip().lower()
+                if confirm != "y":
+                    return False
+
+        # Store credential
+        self._store_credential(cred, api_key)
+        return True
+
+    def _setup_via_aden(self, cred: MissingCredential) -> bool:
+        """Guide user through Aden OAuth flow."""
+        self._print(f"\n{Colors.BOLD}Aden Platform Setup{Colors.NC}")
+        self._print("This will sync credentials from your Aden account.")
+        self._print("")
+
+        # Check for ADEN_API_KEY
+        aden_key = os.environ.get("ADEN_API_KEY")
+        if not aden_key:
+            self._print("You need an Aden API key to use this method.")
+            self._print(f"{Colors.CYAN}Get one at:{Colors.NC} https://hive.adenhq.com")
+            self._print("")
+
+            try:
+                aden_key = self.password_fn("Paste your ADEN_API_KEY: ").strip()
+            except Exception:
+                aden_key = self._input("Paste your ADEN_API_KEY: ").strip()
+
+            if not aden_key:
+                self._print(f"{Colors.YELLOW}No key entered. Skipping.{Colors.NC}")
+                return False
+
+            # Persist to encrypted store and set os.environ
+            from .key_storage import save_aden_api_key
+
+            save_aden_api_key(aden_key)
+
+        # Sync from Aden
+        try:
+            from framework.credentials import CredentialStore
+
+            store = CredentialStore.with_aden_sync(
+                base_url="https://api.adenhq.com",
+                auto_sync=True,
+            )
+
+            # Check if the credential was synced
+            cred_id = cred.credential_id or cred.credential_name
+            if store.is_available(cred_id):
+                self._print(f"{Colors.GREEN}✓ {cred.credential_name} synced from Aden{Colors.NC}")
+                # Export to current session
+                try:
+                    value = store.get_key(cred_id, cred.credential_key)
+                    if value:
+                        os.environ[cred.env_var] = value
+                except Exception:
+                    pass
+                return True
+            else:
+                self._print(
+                    f"{Colors.YELLOW}⚠ {cred.credential_name} not found in Aden account.{Colors.NC}"
+                )
+                self._print("Please connect this integration on https://hive.adenhq.com first.")
+                return False
+        except Exception as e:
+            self._print(f"{Colors.RED}Failed to sync from Aden: {e}{Colors.NC}")
+            return False
+
+    def _run_health_check(self, cred: MissingCredential, value: str) -> dict[str, Any] | None:
+        """Run health check on credential value."""
+        try:
+            from aden_tools.credentials import check_credential_health
+
+            result = check_credential_health(cred.credential_name, value)
+            return {
+                "valid": result.valid,
+                "message": result.message,
+                "details": result.details,
+            }
+        except Exception:
+            # No health checker available
+            return None
+
+    def _store_credential(self, cred: MissingCredential, value: str) -> None:
+        """Store credential in encrypted store and export to env."""
+        from pydantic import SecretStr
+
+        from framework.credentials import CredentialKey, CredentialObject, CredentialStore
+
+        try:
+            store = CredentialStore.with_encrypted_storage()
+            cred_id = cred.credential_id or cred.credential_name
+            key_name = cred.credential_key or "api_key"
+
+            cred_obj = CredentialObject(
+                id=cred_id,
+                name=cred.description or cred.credential_name,
+                keys={key_name: CredentialKey(name=key_name, value=SecretStr(value))},
+            )
+            store.save_credential(cred_obj)
+            self._print(f"{Colors.GREEN}✓ Stored in ~/.hive/credentials/{Colors.NC}")
+        except Exception as e:
+            self._print(f"{Colors.YELLOW}⚠ Could not store in credential store: {e}{Colors.NC}")
+
+        # Export to current session
+        os.environ[cred.env_var] = value
+        self._print(f"{Colors.GREEN}✓ Exported to current session{Colors.NC}")
+
+    def _print_summary(self, configured: list[str], skipped: list[str], errors: list[str]) -> None:
+        """Print final summary."""
+        self._print("")
+        self._print(f"{Colors.YELLOW}{'=' * 60}{Colors.NC}")
+        self._print(f"{Colors.BOLD}  SETUP COMPLETE{Colors.NC}")
+        self._print(f"{Colors.YELLOW}{'=' * 60}{Colors.NC}")
+
+        if configured:
+            self._print(f"\n{Colors.GREEN}✓ Configured:{Colors.NC}")
+            for name in configured:
+                self._print(f"    • {name}")
+
+        if skipped:
+            self._print(f"\n{Colors.YELLOW}⏭ Skipped:{Colors.NC}")
+            for name in skipped:
+                self._print(f"    • {name}")
+
+        if errors:
+            self._print(f"\n{Colors.RED}✗ Errors:{Colors.NC}")
+            for err in errors:
+                self._print(f"    • {err}")
+
+        if not skipped and not errors:
+            self._print(f"\n{Colors.GREEN}All credentials configured successfully!{Colors.NC}")
+        elif skipped:
+            self._print(f"\n{Colors.YELLOW}Note: Skipped credentials must be configured ")
+            self._print(f"before running the agent.{Colors.NC}")
+
+        self._print("")
+
+
+def load_agent_nodes(agent_path: str | Path) -> list:
+    """Load NodeSpec list from an agent's agent.py or agent.json.
+
+    Args:
+        agent_path: Path to agent directory.
+
+    Returns:
+        List of NodeSpec objects (empty list if agent can't be loaded).
+    """
+    agent_path = Path(agent_path)
+    agent_py = agent_path / "agent.py"
+    agent_json = agent_path / "agent.json"
+
+    if agent_py.exists():
+        return _load_nodes_from_python_agent(agent_path)
+    elif agent_json.exists():
+        return _load_nodes_from_json_agent(agent_json)
+    return []
+
+
+def _load_nodes_from_python_agent(agent_path: Path) -> list:
+    """Load nodes from a Python-based agent."""
+    import importlib.util
+
+    agent_py = agent_path / "agent.py"
+    if not agent_py.exists():
+        return []
+
+    try:
+        # Add agent path and its parent to sys.path so imports work
+        paths_to_add = [str(agent_path), str(agent_path.parent)]
+        for p in paths_to_add:
+            if p not in sys.path:
+                sys.path.insert(0, p)
+
+        spec = importlib.util.spec_from_file_location(
+            f"{agent_path.name}.agent",
+            agent_py,
+            submodule_search_locations=[str(agent_path)],
+        )
+        module = importlib.util.module_from_spec(spec)
+        sys.modules[spec.name] = module
+        spec.loader.exec_module(module)
+        return getattr(module, "nodes", [])
+    except Exception:
+        return []
+
+
+def _load_nodes_from_json_agent(agent_json: Path) -> list:
+    """Load nodes from a JSON-based agent."""
+    try:
+        with open(agent_json, encoding="utf-8-sig") as f:
+            data = json.load(f)
+
+        from framework.graph import NodeSpec
+
+        nodes_data = data.get("graph", {}).get("nodes", [])
+        nodes = []
+        for node_data in nodes_data:
+            nodes.append(
+                NodeSpec(
+                    id=node_data.get("id", ""),
+                    name=node_data.get("name", ""),
+                    description=node_data.get("description", ""),
+                    node_type=node_data.get("node_type", ""),
+                    tools=node_data.get("tools", []),
+                    input_keys=node_data.get("input_keys", []),
+                    output_keys=node_data.get("output_keys", []),
+                )
+            )
+        return nodes
+    except Exception:
+        return []
+
+
+def run_credential_setup_cli(agent_path: str | Path | None = None) -> int:
+    """
+    Standalone CLI entry point for credential setup.
+
+    Can be called from:
+    - `hive setup-credentials <agent>`
+    - After CredentialError in runner CLI
+    - From coding agent CLI
+
+    Args:
+        agent_path: Optional path to agent directory
+
+    Returns:
+        Exit code (0 = success, 1 = failure/skipped)
+    """
+    if agent_path:
+        session = CredentialSetupSession.from_agent_path(agent_path)
+    else:
+        # No agent specified - detect from current context or show error
+        print("Usage: hive setup-credentials <agent_path>")
+        return 1
+
+    result = session.run_interactive()
+    return 0 if result.success else 1

core/framework/credentials/storage.py

@@ -136,7 +136,8 @@ class EncryptedFileStorage(CredentialStorage):
             from cryptography.fernet import Fernet
         except ImportError as e:
             raise ImportError(
-                "Encrypted storage requires 'cryptography'. Install with: pip install cryptography"
+                "Encrypted storage requires 'cryptography'. "
+                "Install with: uv pip install cryptography"
             ) from e
 
         self.base_path = Path(base_path or self.DEFAULT_PATH).expanduser()
@@ -202,7 +203,7 @@ class EncryptedFileStorage(CredentialStorage):
         # Decrypt
         try:
             json_bytes = self._fernet.decrypt(encrypted)
-            data = json.loads(json_bytes.decode())
+            data = json.loads(json_bytes.decode("utf-8-sig"))
         except Exception as e:
             raise CredentialDecryptionError(
                 f"Failed to decrypt credential '{credential_id}': {e}"
@@ -226,7 +227,7 @@ class EncryptedFileStorage(CredentialStorage):
         index_path = self.base_path / "metadata" / "index.json"
         if not index_path.exists():
             return []
-        with open(index_path) as f:
+        with open(index_path, encoding="utf-8-sig") as f:
             index = json.load(f)
         return list(index.get("credentials", {}).keys())
 
@@ -267,7 +268,7 @@ class EncryptedFileStorage(CredentialStorage):
         index_path = self.base_path / "metadata" / "index.json"
 
         if index_path.exists():
-            with open(index_path) as f:
+            with open(index_path, encoding="utf-8-sig") as f:
                 index = json.load(f)
         else:
             index = {"credentials": {}, "version": "1.0"}
@@ -282,7 +283,7 @@ class EncryptedFileStorage(CredentialStorage):
 
         index["last_modified"] = datetime.now(UTC).isoformat()
 
-        with open(index_path, "w") as f:
+        with open(index_path, "w", encoding="utf-8") as f:
             json.dump(index, f, indent=2)
 
 

core/framework/credentials/store.py

@@ -362,6 +362,59 @@ class CredentialStore:
         """
         return self._storage.list_all()
 
+    def list_accounts(self, provider_name: str) -> list[dict[str, Any]]:
+        """List all accounts for a provider type with their identities.
+
+        Args:
+            provider_name: Provider type name (e.g. "google", "slack").
+
+        Returns:
+            List of dicts with credential_id, provider, alias, identity, label.
+        """
+        if hasattr(self._storage, "load_all_for_provider"):
+            creds = self._storage.load_all_for_provider(provider_name)
+        else:
+            cred = self.get_credential(provider_name)
+            creds = [cred] if cred else []
+        return [
+            {
+                "credential_id": c.id,
+                "provider": provider_name,
+                "alias": c.alias,
+                "identity": c.identity.to_dict(),
+            }
+            for c in creds
+        ]
+
+    def get_credential_by_alias(self, provider_name: str, alias: str) -> CredentialObject | None:
+        """Find a credential by provider name and alias.
+
+        Args:
+            provider_name: Provider type name (e.g. "google").
+            alias: User-set alias from the Aden platform.
+
+        Returns:
+            CredentialObject if found, None otherwise.
+        """
+        # LLMs sometimes pass "provider/alias" as the alias (e.g. "google/wrok"
+        # instead of just "wrok").  Strip the provider prefix when present.
+        if alias.startswith(f"{provider_name}/"):
+            alias = alias[len(provider_name) + 1 :]
+
+        if hasattr(self._storage, "load_by_alias"):
+            return self._storage.load_by_alias(provider_name, alias)
+
+        # Scan fallback for storage backends without alias index
+        if hasattr(self._storage, "load_all_for_provider"):
+            for cred in self._storage.load_all_for_provider(provider_name):
+                if cred.alias == alias:
+                    return cred
+        return None
+
+    def get_credential_by_identity(self, provider_name: str, label: str) -> CredentialObject | None:
+        """Alias for get_credential_by_alias (backward compat)."""
+        return self.get_credential_by_alias(provider_name, label)
+
     def is_available(self, credential_id: str) -> bool:
         """
         Check if a credential is available.
@@ -374,6 +427,10 @@ class CredentialStore:
         """
         return self.get_credential(credential_id, refresh_if_needed=False) is not None
 
+    def exists(self, credential_id: str) -> bool:
+        """Check if a credential exists in storage without triggering provider fetches."""
+        return self._storage.exists(credential_id)
+
     # --- Validation ---
 
     def validate_for_usage(self, credential_id: str) -> list[str]:

core/framework/credentials/validation.py

@@ -0,0 +1,518 @@
+"""Credential validation utilities.
+
+Provides reusable credential validation for agents, whether run through
+the AgentRunner or directly via GraphExecutor.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+def ensure_credential_key_env() -> None:
+    """Load bootstrap credentials into ``os.environ``.
+
+    Priority chain for each credential:
+      1. ``os.environ`` (already set — nothing to do)
+      2. Dedicated file storage (``~/.hive/secrets/`` or encrypted store)
+      3. Shell config fallback (``~/.zshrc`` / ``~/.bashrc``) for backward compat
+
+    Boot order matters: HIVE_CREDENTIAL_KEY must load BEFORE ADEN_API_KEY
+    because the encrypted store depends on it.
+
+    Remaining LLM/tool API keys still load from shell config.
+    """
+    from .key_storage import load_aden_api_key, load_credential_key
+
+    # Step 1: HIVE_CREDENTIAL_KEY (must come first — encrypted store depends on it)
+    load_credential_key()
+
+    # Step 2: ADEN_API_KEY (uses encrypted store, then shell config fallback)
+    load_aden_api_key()
+
+    # Step 3: Load remaining LLM/tool API keys from shell config
+    try:
+        from aden_tools.credentials.shell_config import check_env_var_in_shell_config
+    except ImportError:
+        return
+
+    try:
+        from aden_tools.credentials import CREDENTIAL_SPECS
+
+        for spec in CREDENTIAL_SPECS.values():
+            var_name = spec.env_var
+            if var_name and var_name not in ("HIVE_CREDENTIAL_KEY", "ADEN_API_KEY"):
+                if not os.environ.get(var_name):
+                    found, value = check_env_var_in_shell_config(var_name)
+                    if found and value:
+                        os.environ[var_name] = value
+                        logger.debug("Loaded %s from shell config", var_name)
+    except ImportError:
+        pass
+
+
+@dataclass
+class CredentialStatus:
+    """Status of a single required credential after validation."""
+
+    credential_name: str
+    credential_id: str
+    env_var: str
+    description: str
+    help_url: str
+    api_key_instructions: str
+    tools: list[str]
+    node_types: list[str]
+    available: bool
+    valid: bool | None  # None = not checked
+    validation_message: str | None
+    aden_supported: bool
+    direct_api_key_supported: bool
+    credential_key: str
+    aden_not_connected: bool  # Aden-only cred, ADEN_API_KEY set, but integration missing
+    alternative_group: str | None = None  # non-None when multiple providers can satisfy a tool
+
+
+@dataclass
+class CredentialValidationResult:
+    """Result of validating all credentials required by an agent."""
+
+    credentials: list[CredentialStatus]
+    has_aden_key: bool
+
+    @property
+    def failed(self) -> list[CredentialStatus]:
+        """Credentials that are missing, invalid, or Aden-not-connected.
+
+        For alternative groups (multi-provider tools like send_email), the group
+        is satisfied if ANY member is available and valid — only report failures
+        when the entire group is unsatisfied.
+        """
+        # Check which alternative groups are satisfied
+        alt_satisfied: dict[str, bool] = {}
+        for c in self.credentials:
+            if not c.alternative_group:
+                continue
+            if c.alternative_group not in alt_satisfied:
+                alt_satisfied[c.alternative_group] = False
+            if c.available and c.valid is not False:
+                alt_satisfied[c.alternative_group] = True
+
+        result = []
+        for c in self.credentials:
+            if c.alternative_group:
+                # Skip if any alternative in the group is satisfied
+                if alt_satisfied.get(c.alternative_group, False):
+                    continue
+                if not c.available or c.valid is False:
+                    result.append(c)
+            else:
+                if not c.available or c.valid is False:
+                    result.append(c)
+        return result
+
+    @property
+    def has_errors(self) -> bool:
+        return bool(self.failed)
+
+    @property
+    def failed_cred_names(self) -> list[str]:
+        """Credential names that need (re-)collection, excluding Aden-not-connected."""
+        return [c.credential_name for c in self.failed if not c.aden_not_connected]
+
+    def format_error_message(self) -> str:
+        """Format a human-readable error message for CLI/runner output."""
+        missing = [c for c in self.credentials if not c.available and not c.aden_not_connected]
+        invalid = [c for c in self.credentials if c.available and c.valid is False]
+        aden_nc = [c for c in self.credentials if c.aden_not_connected]
+
+        lines: list[str] = []
+        if missing:
+            lines.append("Missing credentials:\n")
+            for c in missing:
+                entry = f"  {c.env_var} for {_label(c)}"
+                if c.help_url:
+                    entry += f"\n    Get it at: {c.help_url}"
+                lines.append(entry)
+        if invalid:
+            if missing:
+                lines.append("")
+            lines.append("Invalid or expired credentials:\n")
+            for c in invalid:
+                entry = f"  {c.env_var} for {_label(c)} — {c.validation_message}"
+                if c.help_url:
+                    entry += f"\n    Get a new key at: {c.help_url}"
+                lines.append(entry)
+        if aden_nc:
+            if missing or invalid:
+                lines.append("")
+            lines.append(
+                "Aden integrations not connected "
+                "(ADEN_API_KEY is set but OAuth tokens unavailable):\n"
+            )
+            for c in aden_nc:
+                lines.append(
+                    f"  {c.env_var} for {_label(c)}"
+                    f"\n    Connect this integration at hive.adenhq.com first."
+                )
+        lines.append("\nIf you've already set up credentials, restart your terminal to load them.")
+        return "\n".join(lines)
+
+
+def _label(c: CredentialStatus) -> str:
+    """Build a human-readable label from tools/node_types."""
+    if c.tools:
+        return ", ".join(c.tools)
+    if c.node_types:
+        return ", ".join(c.node_types) + " nodes"
+    return c.credential_name
+
+
+def _presync_aden_tokens(credential_specs: dict, *, force: bool = False) -> None:
+    """Sync Aden-backed OAuth tokens into env vars for validation.
+
+    When ADEN_API_KEY is available, fetches fresh OAuth tokens from the Aden
+    server and exports them to env vars.  This ensures validation sees real
+    tokens instead of stale or mis-stored values in the encrypted store.
+    Only touches credentials that are ``aden_supported`` AND whose env var
+    is not already set (so explicit user exports always win).
+
+    Args:
+        force: When True, overwrite env vars that are already set.  Used by
+            the credentials modal to pick up freshly reauthorized tokens
+            from Aden instead of reusing stale values from a prior sync.
+    """
+    from framework.credentials.store import CredentialStore
+
+    try:
+        aden_store = CredentialStore.with_aden_sync(auto_sync=True)
+    except Exception as e:
+        logger.warning("Aden pre-sync unavailable: %s", e)
+        return
+
+    for name, spec in credential_specs.items():
+        if not spec.aden_supported:
+            continue
+        if not force and os.environ.get(spec.env_var):
+            continue  # Already set — don't overwrite
+        cred_id = spec.credential_id or name
+        # sync_all() already fetched everything available from Aden.
+        # Skip credentials not in the store — they aren't connected,
+        # so fetching individually would fail with "Invalid integration ID".
+        if not aden_store.exists(cred_id):
+            continue
+        try:
+            value = aden_store.get_key(cred_id, spec.credential_key)
+            if value:
+                os.environ[spec.env_var] = value
+                logger.debug("Pre-synced %s from Aden", spec.env_var)
+            else:
+                logger.warning(
+                    "Pre-sync: %s (id=%s) available but key '%s' returned None",
+                    spec.env_var,
+                    cred_id,
+                    spec.credential_key,
+                )
+        except Exception as e:
+            logger.warning(
+                "Pre-sync failed for %s (id=%s): %s",
+                spec.env_var,
+                cred_id,
+                e,
+            )
+
+
+def validate_agent_credentials(
+    nodes: list,
+    quiet: bool = False,
+    verify: bool = True,
+    raise_on_error: bool = True,
+    force_refresh: bool = False,
+) -> CredentialValidationResult:
+    """Check that required credentials are available and valid before running an agent.
+
+    Two-phase validation:
+    1. **Presence** — is the credential set (env var, encrypted store, or Aden sync)?
+    2. **Health check** — does the credential actually work? Uses each tool's
+       registered ``check_credential_health`` endpoint (lightweight HTTP call).
+
+    Args:
+        nodes: List of NodeSpec objects from the agent graph.
+        quiet: If True, suppress the credential summary output.
+        verify: If True (default), run health checks on present credentials.
+        raise_on_error: If True (default), raise CredentialError when validation
+            fails.  Set to False to get the result without raising.
+        force_refresh: If True, force re-sync of Aden OAuth tokens even when
+            env vars are already set.  Used by the credentials modal after
+            reauthorization.
+
+    Returns:
+        CredentialValidationResult with status of ALL required credentials.
+    """
+    empty_result = CredentialValidationResult(credentials=[], has_aden_key=False)
+
+    # Collect required tools and node types
+    required_tools: set[str] = set()
+    node_types: set[str] = set()
+    for node in nodes:
+        if hasattr(node, "tools") and node.tools:
+            required_tools.update(node.tools)
+        if hasattr(node, "node_type"):
+            node_types.add(node.node_type)
+
+    try:
+        from aden_tools.credentials import CREDENTIAL_SPECS
+    except ImportError:
+        return empty_result  # aden_tools not installed, skip check
+
+    from framework.credentials.storage import CompositeStorage, EncryptedFileStorage, EnvVarStorage
+    from framework.credentials.store import CredentialStore
+
+    # Build credential store.
+    # Env vars take priority — if a user explicitly exports a fresh key it
+    # must win over a potentially stale value in the encrypted store.
+    #
+    # Pre-sync: when ADEN_API_KEY is available, sync OAuth tokens from Aden
+    # into env vars so validation sees fresh tokens instead of stale values
+    # in the encrypted store (e.g., a previously mis-stored google.enc).
+    if os.environ.get("ADEN_API_KEY"):
+        _presync_aden_tokens(CREDENTIAL_SPECS, force=force_refresh)
+
+    env_mapping = {
+        (spec.credential_id or name): spec.env_var for name, spec in CREDENTIAL_SPECS.items()
+    }
+    env_storage = EnvVarStorage(env_mapping=env_mapping)
+    if os.environ.get("HIVE_CREDENTIAL_KEY"):
+        storage = CompositeStorage(primary=env_storage, fallbacks=[EncryptedFileStorage()])
+    else:
+        storage = env_storage
+    store = CredentialStore(storage=storage)
+
+    # Build reverse mappings — 1:many for multi-provider tools (e.g. send_email → resend OR google)
+    tool_to_creds: dict[str, list[str]] = {}
+    node_type_to_cred: dict[str, str] = {}
+    for cred_name, spec in CREDENTIAL_SPECS.items():
+        for tool_name in spec.tools:
+            tool_to_creds.setdefault(tool_name, []).append(cred_name)
+        for nt in spec.node_types:
+            node_type_to_cred[nt] = cred_name
+
+    has_aden_key = bool(os.environ.get("ADEN_API_KEY"))
+    checked: set[str] = set()
+    all_credentials: list[CredentialStatus] = []
+    # Credentials that are present and should be health-checked
+    to_verify: list[int] = []  # indices into all_credentials
+
+    def _check_credential(
+        spec,
+        cred_name: str,
+        affected_tools: list[str],
+        affected_node_types: list[str],
+        alternative_group: str | None = None,
+    ) -> None:
+        cred_id = spec.credential_id or cred_name
+        available = store.is_available(cred_id)
+
+        # Aden-not-connected: ADEN_API_KEY set, Aden-only cred, but integration missing
+        is_aden_nc = (
+            not available
+            and has_aden_key
+            and spec.aden_supported
+            and not spec.direct_api_key_supported
+        )
+
+        status = CredentialStatus(
+            credential_name=cred_name,
+            credential_id=cred_id,
+            env_var=spec.env_var,
+            description=spec.description,
+            help_url=spec.help_url,
+            api_key_instructions=getattr(spec, "api_key_instructions", ""),
+            tools=affected_tools,
+            node_types=affected_node_types,
+            available=available,
+            valid=None,
+            validation_message=None,
+            aden_supported=spec.aden_supported,
+            direct_api_key_supported=spec.direct_api_key_supported,
+            credential_key=spec.credential_key,
+            aden_not_connected=is_aden_nc,
+            alternative_group=alternative_group,
+        )
+        all_credentials.append(status)
+
+        if available and verify and spec.health_check_endpoint:
+            to_verify.append(len(all_credentials) - 1)
+
+    # Check tool credentials
+    for tool_name in sorted(required_tools):
+        cred_names = tool_to_creds.get(tool_name)
+        if cred_names is None:
+            continue
+
+        # Filter to credentials we haven't already checked
+        unchecked = [cn for cn in cred_names if cn not in checked]
+        if not unchecked:
+            continue
+
+        # Single provider — existing behavior
+        if len(unchecked) == 1:
+            cred_name = unchecked[0]
+            checked.add(cred_name)
+            spec = CREDENTIAL_SPECS[cred_name]
+            if not spec.required:
+                continue
+            affected = sorted(t for t in required_tools if t in spec.tools)
+            _check_credential(spec, cred_name, affected_tools=affected, affected_node_types=[])
+            continue
+
+        # Multi-provider (e.g. send_email → resend OR google):
+        # satisfied if ANY provider credential is available.
+        available_cn = None
+        for cn in unchecked:
+            spec = CREDENTIAL_SPECS[cn]
+            cred_id = spec.credential_id or cn
+            if store.is_available(cred_id):
+                available_cn = cn
+                break
+
+        if available_cn is not None:
+            # Found an available provider — check (and health-check) it
+            checked.add(available_cn)
+            spec = CREDENTIAL_SPECS[available_cn]
+            affected = sorted(t for t in required_tools if t in spec.tools)
+            _check_credential(spec, available_cn, affected_tools=affected, affected_node_types=[])
+        else:
+            # None available — report ALL alternatives so the modal can show them
+            group_key = tool_name  # e.g. "send_email"
+            for cn in unchecked:
+                checked.add(cn)
+                spec = CREDENTIAL_SPECS[cn]
+                affected = sorted(t for t in required_tools if t in spec.tools)
+                _check_credential(
+                    spec,
+                    cn,
+                    affected_tools=affected,
+                    affected_node_types=[],
+                    alternative_group=group_key,
+                )
+
+    # Check node type credentials (e.g., ANTHROPIC_API_KEY for LLM nodes)
+    for nt in sorted(node_types):
+        cred_name = node_type_to_cred.get(nt)
+        if cred_name is None or cred_name in checked:
+            continue
+        checked.add(cred_name)
+        spec = CREDENTIAL_SPECS[cred_name]
+        if not spec.required:
+            continue
+        affected_types = sorted(t for t in node_types if t in spec.node_types)
+        _check_credential(spec, cred_name, affected_tools=[], affected_node_types=affected_types)
+
+    # Phase 2: health-check present credentials
+    if to_verify:
+        try:
+            from aden_tools.credentials import check_credential_health
+        except ImportError:
+            check_credential_health = None  # type: ignore[assignment]
+
+        if check_credential_health is not None:
+            for idx in to_verify:
+                status = all_credentials[idx]
+                spec = CREDENTIAL_SPECS[status.credential_name]
+                value = store.get(status.credential_id)
+                if not value:
+                    continue
+                try:
+                    result = check_credential_health(
+                        status.credential_name,
+                        value,
+                        health_check_endpoint=spec.health_check_endpoint,
+                        health_check_method=spec.health_check_method,
+                    )
+                    status.valid = result.valid
+                    status.validation_message = result.message
+                    if result.valid:
+                        # Persist identity from health check (best-effort)
+                        identity_data = result.details.get("identity")
+                        if identity_data and isinstance(identity_data, dict):
+                            try:
+                                cred_obj = store.get_credential(
+                                    status.credential_id, refresh_if_needed=False
+                                )
+                                if cred_obj:
+                                    cred_obj.set_identity(**identity_data)
+                                    store.save_credential(cred_obj)
+                            except Exception:
+                                pass  # Identity persistence is best-effort
+                except Exception as exc:
+                    logger.debug("Health check for %s failed: %s", status.credential_name, exc)
+
+    validation_result = CredentialValidationResult(
+        credentials=all_credentials,
+        has_aden_key=has_aden_key,
+    )
+
+    if raise_on_error and validation_result.has_errors:
+        from framework.credentials.models import CredentialError
+
+        exc = CredentialError(validation_result.format_error_message())
+        exc.validation_result = validation_result  # type: ignore[attr-defined]
+        exc.failed_cred_names = validation_result.failed_cred_names  # type: ignore[attr-defined]
+        raise exc
+
+    return validation_result
+
+
+def build_setup_session_from_error(
+    credential_error: Exception,
+    nodes: list | None = None,
+    agent_path: str | None = None,
+):
+    """Build a ``CredentialSetupSession`` that covers all failed credentials.
+
+    Uses the ``CredentialValidationResult`` attached to the ``CredentialError``
+    when available.  Falls back to re-detecting from nodes / agent_path.
+
+    Args:
+        credential_error: The ``CredentialError`` raised by validation.
+        nodes: Graph nodes (preferred — avoids re-loading from disk).
+        agent_path: Agent directory path (used when nodes aren't available).
+    """
+    from framework.credentials.setup import CredentialSetupSession
+
+    # Prefer the validation result attached to the exception
+    result: CredentialValidationResult | None = getattr(credential_error, "validation_result", None)
+    if result is not None:
+        missing = [_status_to_missing(c) for c in result.failed]
+        return CredentialSetupSession(missing)
+
+    # Fallback: re-detect from nodes or agent_path
+    if nodes is not None:
+        return CredentialSetupSession.from_nodes(nodes)
+    elif agent_path is not None:
+        return CredentialSetupSession.from_agent_path(agent_path)
+    return CredentialSetupSession(missing=[])
+
+
+def _status_to_missing(c: CredentialStatus):
+    """Convert a CredentialStatus to a MissingCredential for the setup flow."""
+    from framework.credentials.setup import MissingCredential
+
+    return MissingCredential(
+        credential_name=c.credential_name,
+        env_var=c.env_var,
+        description=c.description,
+        help_url=c.help_url,
+        api_key_instructions=c.api_key_instructions,
+        tools=c.tools,
+        node_types=c.node_types,
+        aden_supported=c.aden_supported,
+        direct_api_key_supported=c.direct_api_key_supported,
+        credential_id=c.credential_id,
+        credential_key=c.credential_key,
+    )

core/framework/credentials/vault/hashicorp.py

@@ -2,7 +2,7 @@
 HashiCorp Vault storage adapter.
 
 Provides integration with HashiCorp Vault for enterprise secret management.
-Requires the 'hvac' package: pip install hvac
+Requires the 'hvac' package: uv pip install hvac
 """
 
 from __future__ import annotations
@@ -66,7 +66,7 @@ class HashiCorpVaultStorage(CredentialStorage):
         - AWS IAM auth method
 
     Requirements:
-        pip install hvac
+        uv pip install hvac
     """
 
     def __init__(
@@ -97,7 +97,7 @@ class HashiCorpVaultStorage(CredentialStorage):
             import hvac
         except ImportError as e:
             raise ImportError(
-                "HashiCorp Vault support requires 'hvac'. Install with: pip install hvac"
+                "HashiCorp Vault support requires 'hvac'. Install with: uv pip install hvac"
             ) from e
 
         self._url = url

core/framework/graph/__init__.py

@@ -1,4 +1,4 @@
-"""Graph structures: Goals, Nodes, Edges, and Flexible Execution."""
+"""Graph structures: Goals, Nodes, Edges, and Execution."""
 
 from framework.graph.client_io import (
     ActiveNodeClientIO,
@@ -6,10 +6,9 @@ from framework.graph.client_io import (
     InertNodeClientIO,
     NodeClientIO,
 )
-from framework.graph.code_sandbox import CodeSandbox, safe_eval, safe_exec
 from framework.graph.context_handoff import ContextHandoff, HandoffContext
 from framework.graph.conversation import ConversationStore, Message, NodeConversation
-from framework.graph.edge import EdgeCondition, EdgeSpec, GraphSpec
+from framework.graph.edge import DEFAULT_MAX_TOKENS, EdgeCondition, EdgeSpec, GraphSpec
 from framework.graph.event_loop_node import (
     EventLoopNode,
     JudgeProtocol,
@@ -18,31 +17,9 @@ from framework.graph.event_loop_node import (
     OutputAccumulator,
 )
 from framework.graph.executor import GraphExecutor
-from framework.graph.flexible_executor import ExecutorConfig, FlexibleGraphExecutor
 from framework.graph.goal import Constraint, Goal, GoalStatus, SuccessCriterion
-from framework.graph.judge import HybridJudge, create_default_judge
 from framework.graph.node import NodeContext, NodeProtocol, NodeResult, NodeSpec
 
-# Flexible execution (Worker-Judge pattern)
-from framework.graph.plan import (
-    ActionSpec,
-    ActionType,
-    # HITL (Human-in-the-loop)
-    ApprovalDecision,
-    ApprovalRequest,
-    ApprovalResult,
-    EvaluationRule,
-    ExecutionStatus,
-    Judgment,
-    JudgmentAction,
-    Plan,
-    PlanExecutionResult,
-    PlanStep,
-    StepStatus,
-    load_export,
-)
-from framework.graph.worker_node import StepExecutionResult, WorkerNode
-
 __all__ = [
     # Goal
     "Goal",
@@ -58,35 +35,9 @@ __all__ = [
     "EdgeSpec",
     "EdgeCondition",
     "GraphSpec",
-    # Executor (fixed graph)
+    "DEFAULT_MAX_TOKENS",
+    # Executor
     "GraphExecutor",
-    # Plan (flexible execution)
-    "Plan",
-    "PlanStep",
-    "ActionSpec",
-    "ActionType",
-    "StepStatus",
-    "Judgment",
-    "JudgmentAction",
-    "EvaluationRule",
-    "PlanExecutionResult",
-    "ExecutionStatus",
-    "load_export",
-    # HITL (Human-in-the-loop)
-    "ApprovalDecision",
-    "ApprovalRequest",
-    "ApprovalResult",
-    # Worker-Judge
-    "HybridJudge",
-    "create_default_judge",
-    "WorkerNode",
-    "StepExecutionResult",
-    "FlexibleGraphExecutor",
-    "ExecutorConfig",
-    # Code Sandbox
-    "CodeSandbox",
-    "safe_exec",
-    "safe_eval",
     # Conversation
     "NodeConversation",
     "ConversationStore",

core/framework/graph/checkpoint_config.py

@@ -0,0 +1,85 @@
+"""
+Checkpoint Configuration - Controls checkpoint behavior during execution.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass
+class CheckpointConfig:
+    """
+    Configuration for checkpoint behavior during graph execution.
+
+    Controls when checkpoints are created, how they're stored,
+    and when they're pruned.
+    """
+
+    # Enable/disable checkpointing
+    enabled: bool = True
+
+    # When to checkpoint
+    checkpoint_on_node_start: bool = True
+    checkpoint_on_node_complete: bool = True
+
+    # Pruning (time-based)
+    checkpoint_max_age_days: int = 7  # Prune checkpoints older than 1 week
+    prune_every_n_nodes: int = 10  # Check for pruning every N nodes
+
+    # Performance
+    async_checkpoint: bool = True  # Don't block execution on checkpoint writes
+
+    # What to include in checkpoints
+    include_full_memory: bool = True
+    include_metrics: bool = True
+
+    def should_checkpoint_node_start(self) -> bool:
+        """Check if should checkpoint before node execution."""
+        return self.enabled and self.checkpoint_on_node_start
+
+    def should_checkpoint_node_complete(self) -> bool:
+        """Check if should checkpoint after node execution."""
+        return self.enabled and self.checkpoint_on_node_complete
+
+    def should_prune_checkpoints(self, nodes_executed: int) -> bool:
+        """
+        Check if should prune checkpoints based on execution progress.
+
+        Args:
+            nodes_executed: Number of nodes executed so far
+
+        Returns:
+            True if should check for old checkpoints and prune them
+        """
+        return (
+            self.enabled
+            and self.prune_every_n_nodes > 0
+            and nodes_executed % self.prune_every_n_nodes == 0
+        )
+
+
+# Default configuration for most agents
+DEFAULT_CHECKPOINT_CONFIG = CheckpointConfig(
+    enabled=True,
+    checkpoint_on_node_start=True,
+    checkpoint_on_node_complete=True,
+    checkpoint_max_age_days=7,
+    prune_every_n_nodes=10,
+    async_checkpoint=True,
+)
+
+
+# Minimal configuration (only checkpoint at node completion)
+MINIMAL_CHECKPOINT_CONFIG = CheckpointConfig(
+    enabled=True,
+    checkpoint_on_node_start=False,
+    checkpoint_on_node_complete=True,
+    checkpoint_max_age_days=7,
+    prune_every_n_nodes=20,
+    async_checkpoint=True,
+)
+
+
+# Disabled configuration (no checkpointing)
+DISABLED_CHECKPOINT_CONFIG = CheckpointConfig(
+    enabled=False,
+)

core/framework/graph/client_io.py

@@ -46,9 +46,11 @@ class ActiveNodeClientIO(NodeClientIO):
         self,
         node_id: str,
         event_bus: EventBus | None = None,
+        execution_id: str = "",
     ) -> None:
         self.node_id = node_id
         self._event_bus = event_bus
+        self._execution_id = execution_id
 
         self._output_queue: asyncio.Queue[str | None] = asyncio.Queue()
         self._output_snapshot = ""
@@ -66,6 +68,7 @@ class ActiveNodeClientIO(NodeClientIO):
                 node_id=self.node_id,
                 content=content,
                 snapshot=self._output_snapshot,
+                execution_id=self._execution_id or None,
             )
 
         if is_final:
@@ -83,6 +86,7 @@ class ActiveNodeClientIO(NodeClientIO):
                 stream_id=self.node_id,
                 node_id=self.node_id,
                 prompt=prompt,
+                execution_id=self._execution_id or None,
             )
 
         try:
@@ -158,11 +162,12 @@ class ClientIOGateway:
     def __init__(self, event_bus: EventBus | None = None) -> None:
         self._event_bus = event_bus
 
-    def create_io(self, node_id: str, client_facing: bool) -> NodeClientIO:
+    def create_io(self, node_id: str, client_facing: bool, execution_id: str = "") -> NodeClientIO:
         if client_facing:
             return ActiveNodeClientIO(
                 node_id=node_id,
                 event_bus=self._event_bus,
+                execution_id=execution_id,
             )
         return InertNodeClientIO(
             node_id=node_id,

core/framework/graph/code_sandbox.py

@@ -1,413 +0,0 @@
-"""
-Code Sandbox for Safe Execution of Dynamic Code.
-
-Provides a restricted execution environment for code generated by
-the external planner. This is critical for open-ended planning where
-the planner can create arbitrary code actions.
-
-Security measures:
-1. Restricted builtins (no file I/O, no imports of dangerous modules)
-2. Timeout enforcement
-3. Memory limits (via resource module on Unix)
-4. Namespace isolation
-"""
-
-import ast
-import signal
-import sys
-from contextlib import contextmanager
-from dataclasses import dataclass, field
-from typing import Any
-
-# Safe builtins whitelist
-SAFE_BUILTINS = {
-    # Basic types
-    "True": True,
-    "False": False,
-    "None": None,
-    # Type constructors
-    "bool": bool,
-    "int": int,
-    "float": float,
-    "str": str,
-    "list": list,
-    "dict": dict,
-    "set": set,
-    "tuple": tuple,
-    "frozenset": frozenset,
-    # Basic functions
-    "abs": abs,
-    "all": all,
-    "any": any,
-    "bin": bin,
-    "chr": chr,
-    "divmod": divmod,
-    "enumerate": enumerate,
-    "filter": filter,
-    "format": format,
-    "hex": hex,
-    "isinstance": isinstance,
-    "issubclass": issubclass,
-    "iter": iter,
-    "len": len,
-    "map": map,
-    "max": max,
-    "min": min,
-    "next": next,
-    "oct": oct,
-    "ord": ord,
-    "pow": pow,
-    "range": range,
-    "repr": repr,
-    "reversed": reversed,
-    "round": round,
-    "slice": slice,
-    "sorted": sorted,
-    "sum": sum,
-    "zip": zip,
-}
-
-# Modules that can be imported
-ALLOWED_MODULES = {
-    "math",
-    "json",
-    "re",
-    "datetime",
-    "collections",
-    "itertools",
-    "functools",
-    "operator",
-    "string",
-    "random",
-    "statistics",
-    "decimal",
-    "fractions",
-}
-
-# Dangerous AST nodes to block
-BLOCKED_AST_NODES = {
-    ast.Import,
-    ast.ImportFrom,
-    ast.Global,
-    ast.Nonlocal,
-}
-
-
-class CodeSandboxError(Exception):
-    """Error during sandboxed code execution."""
-
-    pass
-
-
-class TimeoutError(CodeSandboxError):
-    """Code execution timed out."""
-
-    pass
-
-
-class SecurityError(CodeSandboxError):
-    """Code contains potentially dangerous operations."""
-
-    pass
-
-
-@dataclass
-class SandboxResult:
-    """Result of sandboxed code execution."""
-
-    success: bool
-    result: Any = None
-    error: str | None = None
-    stdout: str = ""
-    variables: dict[str, Any] = field(default_factory=dict)
-    execution_time_ms: int = 0
-
-
-class RestrictedImporter:
-    """Custom importer that only allows whitelisted modules."""
-
-    def __init__(self, allowed_modules: set[str]):
-        self.allowed_modules = allowed_modules
-        self._cache: dict[str, Any] = {}
-
-    def __call__(self, name: str, *args, **kwargs):
-        if name not in self.allowed_modules:
-            raise SecurityError(f"Import of module '{name}' is not allowed")
-
-        if name not in self._cache:
-            import importlib
-
-            self._cache[name] = importlib.import_module(name)
-
-        return self._cache[name]
-
-
-class CodeValidator:
-    """Validates code for safety before execution."""
-
-    def __init__(self, blocked_nodes: set[type] | None = None):
-        self.blocked_nodes = blocked_nodes or BLOCKED_AST_NODES
-
-    def validate(self, code: str) -> list[str]:
-        """
-        Validate code and return list of issues.
-
-        Returns empty list if code is safe.
-        """
-        issues = []
-
-        try:
-            tree = ast.parse(code)
-        except SyntaxError as e:
-            return [f"Syntax error: {e}"]
-
-        for node in ast.walk(tree):
-            # Check for blocked node types
-            if type(node) in self.blocked_nodes:
-                lineno = getattr(node, "lineno", "?")
-                issues.append(f"Blocked operation: {type(node).__name__} at line {lineno}")
-
-            # Check for dangerous attribute access
-            if isinstance(node, ast.Attribute):
-                if node.attr.startswith("_"):
-                    issues.append(
-                        f"Access to private attribute '{node.attr}' at line {node.lineno}"
-                    )
-
-            # Check for exec/eval calls
-            if isinstance(node, ast.Call):
-                if isinstance(node.func, ast.Name):
-                    if node.func.id in ("exec", "eval", "compile", "__import__"):
-                        issues.append(
-                            f"Blocked function call: {node.func.id} at line {node.lineno}"
-                        )
-
-        return issues
-
-
-class CodeSandbox:
-    """
-    Sandboxed environment for executing dynamic code.
-
-    Usage:
-        sandbox = CodeSandbox(timeout_seconds=5)
-        result = sandbox.execute(
-            code="x = 1 + 2\\nresult = x * 3",
-            inputs={"multiplier": 2},
-        )
-        if result.success:
-            print(result.variables["result"])  # 6
-    """
-
-    def __init__(
-        self,
-        timeout_seconds: int = 10,
-        allowed_modules: set[str] | None = None,
-        safe_builtins: dict[str, Any] | None = None,
-    ):
-        self.timeout_seconds = timeout_seconds
-        self.allowed_modules = allowed_modules or ALLOWED_MODULES
-        self.safe_builtins = safe_builtins or SAFE_BUILTINS
-        self.validator = CodeValidator()
-        self.importer = RestrictedImporter(self.allowed_modules)
-
-    @contextmanager
-    def _timeout_context(self, seconds: int):
-        """Context manager for timeout enforcement."""
-
-        def handler(signum, frame):
-            raise TimeoutError(f"Code execution timed out after {seconds} seconds")
-
-        # Only works on Unix-like systems
-        if hasattr(signal, "SIGALRM"):
-            old_handler = signal.signal(signal.SIGALRM, handler)
-            signal.alarm(seconds)
-            try:
-                yield
-            finally:
-                signal.alarm(0)
-                signal.signal(signal.SIGALRM, old_handler)
-        else:
-            # Windows: no timeout support, just execute
-            yield
-
-    def _create_namespace(self, inputs: dict[str, Any]) -> dict[str, Any]:
-        """Create isolated namespace for code execution."""
-        namespace = {
-            "__builtins__": dict(self.safe_builtins),
-            "__import__": self.importer,
-        }
-
-        # Add input variables
-        namespace.update(inputs)
-
-        return namespace
-
-    def execute(
-        self,
-        code: str,
-        inputs: dict[str, Any] | None = None,
-        extract_vars: list[str] | None = None,
-    ) -> SandboxResult:
-        """
-        Execute code in sandbox.
-
-        Args:
-            code: Python code to execute
-            inputs: Variables to inject into namespace
-            extract_vars: Variable names to extract from namespace after execution
-
-        Returns:
-            SandboxResult with execution outcome
-        """
-        import time
-
-        inputs = inputs or {}
-        extract_vars = extract_vars or []
-
-        # Validate code first
-        issues = self.validator.validate(code)
-        if issues:
-            return SandboxResult(
-                success=False,
-                error=f"Code validation failed: {'; '.join(issues)}",
-            )
-
-        # Create isolated namespace
-        namespace = self._create_namespace(inputs)
-
-        # Capture stdout
-        import io
-
-        old_stdout = sys.stdout
-        sys.stdout = captured_stdout = io.StringIO()
-
-        start_time = time.time()
-
-        try:
-            with self._timeout_context(self.timeout_seconds):
-                # Compile and execute
-                compiled = compile(code, "<sandbox>", "exec")
-                exec(compiled, namespace)
-
-            execution_time_ms = int((time.time() - start_time) * 1000)
-
-            # Extract requested variables
-            extracted = {}
-            for var in extract_vars:
-                if var in namespace:
-                    extracted[var] = namespace[var]
-
-            # Also extract any new variables (not in inputs or builtins)
-            for key, value in namespace.items():
-                if key not in inputs and key not in self.safe_builtins and not key.startswith("_"):
-                    extracted[key] = value
-
-            return SandboxResult(
-                success=True,
-                result=namespace.get("result"),  # Convention: 'result' is the return value
-                stdout=captured_stdout.getvalue(),
-                variables=extracted,
-                execution_time_ms=execution_time_ms,
-            )
-
-        except TimeoutError as e:
-            return SandboxResult(
-                success=False,
-                error=str(e),
-                execution_time_ms=self.timeout_seconds * 1000,
-            )
-
-        except SecurityError as e:
-            return SandboxResult(
-                success=False,
-                error=f"Security violation: {e}",
-                execution_time_ms=int((time.time() - start_time) * 1000),
-            )
-
-        except Exception as e:
-            return SandboxResult(
-                success=False,
-                error=f"{type(e).__name__}: {e}",
-                stdout=captured_stdout.getvalue(),
-                execution_time_ms=int((time.time() - start_time) * 1000),
-            )
-
-        finally:
-            sys.stdout = old_stdout
-
-    def execute_expression(
-        self,
-        expression: str,
-        inputs: dict[str, Any] | None = None,
-    ) -> SandboxResult:
-        """
-        Execute a single expression and return its value.
-
-        Simpler than execute() - just evaluates one expression.
-        """
-        inputs = inputs or {}
-
-        # Validate
-        try:
-            ast.parse(expression, mode="eval")
-        except SyntaxError as e:
-            return SandboxResult(success=False, error=f"Syntax error: {e}")
-
-        namespace = self._create_namespace(inputs)
-
-        try:
-            with self._timeout_context(self.timeout_seconds):
-                result = eval(expression, namespace)
-
-            return SandboxResult(success=True, result=result)
-
-        except Exception as e:
-            return SandboxResult(
-                success=False,
-                error=f"{type(e).__name__}: {e}",
-            )
-
-
-# Singleton instance with default settings
-default_sandbox = CodeSandbox()
-
-
-def safe_exec(
-    code: str,
-    inputs: dict[str, Any] | None = None,
-    timeout_seconds: int = 10,
-) -> SandboxResult:
-    """
-    Convenience function for safe code execution.
-
-    Args:
-        code: Python code to execute
-        inputs: Variables to inject
-        timeout_seconds: Max execution time
-
-    Returns:
-        SandboxResult
-    """
-    sandbox = CodeSandbox(timeout_seconds=timeout_seconds)
-    return sandbox.execute(code, inputs)
-
-
-def safe_eval(
-    expression: str,
-    inputs: dict[str, Any] | None = None,
-    timeout_seconds: int = 5,
-) -> SandboxResult:
-    """
-    Convenience function for safe expression evaluation.
-
-    Args:
-        expression: Python expression to evaluate
-        inputs: Variables to inject
-        timeout_seconds: Max execution time
-
-    Returns:
-        SandboxResult
-    """
-    sandbox = CodeSandbox(timeout_seconds=timeout_seconds)
-    return sandbox.execute_expression(expression, inputs)